gov.sandia.cognition.collection.ScalarMap Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of gov-sandia-cognition-common-core Show documentation
Base classes for the Cognitive Foundry including generally utilities and linear algebra.
There is a newer version: 4.0.1
Show newest version
/*
 * File:                ScalarMap.java
 * Authors:             Justin Basilico
 * Company:             Sandia National Laboratories
 * Project:             Incremental Learning Core
 * 
 * Copyright April 27, 2011, 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.
 * 
 */

package gov.sandia.cognition.collection;

import java.util.Map;
import java.util.Set;

/**
 * An interface for a mapping of objects to scalar values represented as
 * doubles.
 *
 * @param   
 *      The type of the key in the map.
 * @author  Justin Basilico
 * @since   3.3.1
 */
public interface ScalarMap
    extends NumericMap
{

    /**
     * Gets a {@code java.util.Map} that contains the same data as in this
     * scalar map.
     *
     * @return
     *      The {@code Map} version of this data structure.
     */
    public Map asMap();

    /**
     * Gets the value associated with a given key. If the key does not exist,
     * then 0.0 is returned.
     *
     * @param   key
     *      A key.
     * @return
     *      The value associated with the key or 0.0 if it does not exist.
     */
    public double get(
        final KeyType key);

    /**
     * Sets the value associated with a given key. In some cases if the value is
     * 0.0, the key may be removed from the map.
     *
     * @param   key
     *      A key.
     * @param   value
     *      The value to associate with the key.
     */
    public void set(
        final KeyType key,
        final double value);

    /**
     * Sets all the given keys to the given value.
     *
     * @param   keys
     *      A list of keys.
     * @param   value
     *      The value to associate with all the given keys.
     */
    public void setAll(
        final Iterable keys,
        final double value);

    /**
     * Increments the value associated with the given key by 1.0.
     *
     * @param   key
     *      A key.
     * @return
     *      The new value associated with the key.
     */
    public double increment(
        final KeyType key);

    /**
     * Increments the value associated with the given key by the given amount.
     *
     * @param   key
     *      A key.
     * @param value
     *      The amount to increment the value associated with the given key by.
     * @return
     *      The new value associated with the key.
     */
    public double increment(
        final KeyType key,
        final double value);

    /**
     * Increments the values associated all of the given keys by 1.0.
     *
     * @param   keys
     *      A list of keys.
     */
    public void incrementAll(
        final Iterable keys);

    /**
     * Increments all the keys in this map by the values in the other one.
     *
     * @param   other
     *      The other map.
     */
    public void incrementAll(
        final ScalarMap other);

    /**
     * Decrements the value associated with a given key by 1.0.
     *
     * @param   key
     *      A key.
     * @return
     *      The new value associated with the key.
     */
    public double decrement(
        final KeyType key);

    /**
     * Decrements the value associated with the given key by the given amount.
     *
     * @param   key
     *      A key.
     * @param value
     *      The amount to decrement the value associated with the given key by.
     * @return
     *      The new value associated with the key.
     */
    public double decrement(
        final KeyType key,
        final double value);

    /**
     * Decrements the values associated all of the given keys by 1.0.
     *
     * @param   keys
     *      A list of keys.
     */
    public void decrementAll(
        final Iterable keys);

    /**
     * Decrements all the keys in this map by the values in the other one.
     *
     * @param   other
     *      The other map.
     */
    public void decrementAll(
        final ScalarMap other);

    /**
     * The maximum value associated with any key in the map.
     *
     * @return
     *      The maximum value associated with any key in the map. If the map
     *      is empty, then Double.NEGATIVE_INFINITY is returned.
     */
    public double getMaxValue();

    /**
     * The minimum value associated with any key in the map.
     *
     * @return
     *      The minimum value associated with any key in the map. If the map
     *      is empty, then Double.POSITIVE_INFINITY is returned.
     */
    public double getMinValue();

    /**
     * Gets the set of entries in this scalar map.
     *
     * @return
     *      The set of entries in the scalar map.
     */
    public Set> entrySet();

    /**
     * An entry in a scalar map. Similar to a Map.Entry.
     *
     * @param   
     *      The type of key in the map.
     * @see     java.util.Map.Entry
     */
    public static interface Entry
    {
        
        /**
         * Gets the key.
         *
         * @return
         *      The key.
         */
        public KeyType getKey();

        /**
         * Gets the value associated with the key.
         *
         * @return
         *      The value.
         */
        public double getValue();

        /**
         * Sets the value associated with the key. Optional operation.
         *
         * @param   value
         *      The value.
         */
        public void setValue(
            final double value);
    }

}