gov.sandia.cognition.math.RingAccumulator Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of cognitive-foundry Show documentation
A single jar with all the Cognitive Foundry components.
There is a newer version: 4.0.1
/*
 * File:                RingAccumulator.java
 * Authors:             Justin Basilico
 * Company:             Sandia National Laboratories
 * Project:             Cognitive Foundry
 *
 * Copyright February 22, 2006, Sandia Corporation.  Under the terms of Contract
 * DE-AC04-94AL85000, there is a non-exclusive license for use of this work by
 * or on behalf of the U.S. Government. Export of this program may require a
 * license from the United States Government. See CopyrightHistory.txt for
 * complete details.
 *
 */

package gov.sandia.cognition.math;

import gov.sandia.cognition.annotation.CodeReview;
import gov.sandia.cognition.annotation.CodeReviewResponse;
import gov.sandia.cognition.annotation.CodeReviews;

/**
 * The RingAccumulator class implements a simple object that
 * is used to accumulate objects that implement the Ring interface. This
 * provides an easy way to compute sums or means of Ring objects by simply
 * adding them to the accumulator.
 *
 * Note that if nothing is added to the accumulator, the results returned
 * will be null because it will not be given a default object to use to
 * start at "zero".
 *
 * @param  Type of Ring that this object can operate upon
 * @author Justin Basilico
 * @since  1.0
 */
@CodeReviews(
    reviews={
        @CodeReview(
            reviewer="Kevin R. Dixon",
            date="2008-02-26",
            changesNeeded=false,
            comments="Looks good."
        ),
        @CodeReview(
            reviewer="Jonathan McClain",
            date="2006-05-16",
            changesNeeded=true,
            comments="A few minor changes.",
            response=@CodeReviewResponse(
                respondent="Justin Basilico",
                date="2006-05-16",
                moreChangesNeeded=false,
                comments="Minor updates based on comments."
            )
        )
    }
)
public class RingAccumulator>
{

    /** The number of items added to the accumulator. */
    private int count;

    /** The sum of the items. This starts as null until one item is added. */
    private RingType sum;

    /**
     * Creates a new instance of RingAccumulator
     */
    public RingAccumulator()
    {
        super();
        this.clear();
    }

    /**
     * Creates a new instance of RingAccumulator, adding all of the given
     * items to start with.
     *
     * @param  items The initial set of items to add to the accumulator,
     *         throws NullPointerException if null
     */
    public RingAccumulator(
        Iterable items )
    {
        this();
        this.accumulate( items );
    }

    /**
     * Clears the accumulator. Resetting the count and sum.
     */
    public void clear()
    {
        this.setCount( 0 );
        this.setSum( null );
    }

    /**
     * Adds the given object to the accumulation.
     *
     * @param  item The object to add to the accumulation,
     *         throws NullPointerException if null.
     */
    public void accumulate(
        RingType item )
    {
        if (item == null)
        {
            // Error: Bad parameter.
            throw new NullPointerException( "Cannot add null." );
        }

        // We are adding an object so increment the count.
        this.setCount( this.getCount() + 1 );

        if (this.sum == null)
        {
            // This is the first object so copy it to get the initial
            // sum.
            this.setSum( item.clone() );
        }
        else
        {
            // Add the object to the sum.
            this.sum.plusEquals( item );
        }
    }

    /**
     * Adds all of the given set of objects onto the accumulation.
     *
     * @param  items The objects to add to the accumulation,
     *         throws NullPointerException if null
     */
    public void accumulate(
        Iterable items )
    {
        // Just call the accumulate method on each object.
        for (RingType item : items)
        {
            this.accumulate( item );
        }
    }

    /**
     * Returns the sum scaled by the given scale factor.
     *
     * @param  scaleFactor The amount to scale the sum by.
     * @return The sum scaled by the given amount or null if no sum
     *         has been defined.
     */
    public RingType scaleSum(
        double scaleFactor )
    {
        if (this.sum == null)
        {
            // There is no sum so just return null.
            return null;
        }
        else
        {
            // Scale the sum.
            return this.sum.scale( scaleFactor );
        }
    }

    /**
     * Computes the mean of the accumulated values.
     *
     * @return The mean of the accumulated values.
     */
    public RingType getMean()
    {
        if (this.getCount() <= 0)
        {
            // We return null because we do not have the default sum to
            // operate on.
            return null;
        }
        else
        {
            // Divide the sum by the count.
            return this.scaleSum( 1.0 / (double) this.count );
        }
    }

    /**
     * Returns the sum object underlying the accumulator.
     *
     * @return The sum of the accumulation.
     */
    public RingType getSum()
    {
        return this.sum;
    }

    /**
     * Gets the number of items that have been added to the accumulator.
     *
     * @return The number of items that have been added to the accumulator.
     */
    public int getCount()
    {
        return this.count;
    }

    /**
     * Sets the count.
     *
     * @param  count The new count.
     */
    private void setCount(
        int count )
    {
        this.count = count;
    }

    /** 
     * Sets the sum of items.
     *
     * @param  sum The new sum of items.
     */
    private void setSum(
        RingType sum )
    {
        this.sum = sum;
    }

}