// Stanford JavaNLP support classes
// Copyright (c) 2004-2008 The Board of Trustees of
// The Leland Stanford Junior University. All Rights Reserved.
//
// This program is free software; you can redistribute it and/or
// modify it under the terms of the GNU General Public License
// as published by the Free Software Foundation; either version 2
// of the License, or (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with this program; if not, write to the Free Software
// Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
//
// For more information, bug reports, fixes, contact:
// Christopher Manning
// Dept of Computer Science, Gates 1A
// Stanford CA 94305-9010
// USA
// java-nlp-support@lists.stanford.edu
// http://nlp.stanford.edu/software/
package edu.stanford.nlp.stats;
import java.util.Collection;
import java.util.Map;
import java.util.Set;
import edu.stanford.nlp.util.Factory;
import edu.stanford.nlp.util.logging.PrettyLoggable;
/**
* An Object to double map used for keeping weights or counts for objects.
* Utility functions are contained in
* {@link Counters}. The class previously known as Counter has been
* renamed to {@link ClassicCounter}.
*
*
*
* <p>
* <i>Implementation note:</i> You shouldn't casually add further methods to
* this interface. Rather, they should be added to the {@link Counters} class.
*
* @author dramage
* @author cer
* @author pado
*/
public interface Counter<E> extends PrettyLoggable {
/**
* Returns a factory that can create new instances of this kind of Counter.
*
* @return A factory that can create new instances of this kind of Counter.
*/
Factory<Counter<E>> getFactory();
/**
* Sets the default return value. This value is returned when you get
* the value for keys that are not in the Counter. It is zero by
* default, but can sometimes usefully by set to other values like
* Double.NaN or Double.NEGATIVE_INFINITY.
*
* @param rv The default value
*/
void setDefaultReturnValue(double rv) ;
/**
* Returns the default return value.
*
* @return The default return value.
*/
double defaultReturnValue() ;
/**
* Returns the count for this key as a double. This is the
* defaultReturnValue (0.0, if it hasn't been set) if the key hasn't
* previously been seen.
*
* @param key The key
* @return The count
*/
double getCount(Object key);
/**
* Sets the count for the given key to be the given value.
* This will replace any existing count for the key.
* To add to a count instead of replacing it, use
* {@link #incrementCount(Object,double)}.
*
* @param key The key
* @param value The count
*/
void setCount(E key, double value);
/**
* Increments the count for the given key by the given value. If the key
* hasn't been seen before, it is assumed to have count 0.0, and thus this
* method will set its count to the given amount. <i>Note that this is
* true regardless of the setting of defaultReturnValue.</i>
* Negative increments are equivalent to calling <tt>decrementCount</tt>.
* To more conveniently increment the count by 1.0, use
* {@link #incrementCount(Object)}.
* To set a count to a specific value instead of incrementing it, use
* {@link #setCount(Object,double)}.
*
* @param key The key to increment
* @param value The amount to increment it by
* @return The value associated with they key, post-increment.
*/
double incrementCount(E key, double value);
/**
* Increments the count for this key by 1.0. If the key hasn't been seen
* before, it is assumed to have count 0.0, and thus this method will set
* its count to 1.0. <i>Note that this is
* true regardless of the setting of defaultReturnValue.</i>
* To increment the count by a value other than 1.0, use
* {@link #incrementCount(Object,double)}.
* To set a count to a specific value instead of incrementing it, use
* {@link #setCount(Object,double)}.
*
* @param key The key to increment by 1.0
* @return The value associated with they key, post-increment.
*/
double incrementCount(E key);
/**
* Decrements the count for this key by the given value.
* If the key hasn't been seen before, it is assumed to have count 0.0, and
* thus this method will set its count to the negative of the given amount.
* <i>Note that this is true regardless of the setting of defaultReturnValue.</i>
* Negative increments are equivalent to calling <code>incrementCount</code>.
* To more conveniently decrement the count by 1.0, use
* {@link #decrementCount(Object)}.
* To set a count to a specific value instead of decrementing it, use
* {@link #setCount(Object,double)}.
*
* @param key The key to decrement
* @param value The amount to decrement it by
* @return The value associated with they key, post-decrement.
*/
double decrementCount(E key, double value);
/**
* Decrements the count for this key by 1.0.
* If the key hasn't been seen before, it is assumed to have count 0.0,
* and thus this method will set its count to -1.0. <i>Note that this is
* true regardless of the setting of defaultReturnValue.</i>
* To decrement the count by a value other than 1.0, use
* {@link #decrementCount(Object,double)}.
* To set a count to a specific value instead of decrementing it, use
* {@link #setCount(Object,double)}.
*
* @param key The key to decrement by 1.0
* @return The value of associated with they key, post-decrement.
*/
double decrementCount(E key);
/**
* Increments the count stored in log space for this key by the given
* log-transformed value.
* If the current count for the key is v1, and you call
* logIncrementCount with a value of v2, then the new value will
* be log(e^v1 + e^v2). If the key
* hasn't been seen before, it is assumed to have count
* Double.NEGATIVE_INFINITY, and thus this
* method will set its count to the given amount. <i>Note that this is
* true regardless of the setting of defaultReturnValue.</i>
* To set a count to a specific value instead of incrementing it, you need
* to first take the log yourself and then to call
* {@link #setCount(Object,double)}.
*
* @param key The key to increment
* @param value The amount to increment it by, in log space
* @return The value associated with they key, post-increment, in log space
*/
double logIncrementCount(E key, double value);
/**
* Adds the counts in the given Counter to the counts in this Counter.
* This is identical in effect to calling Counters.addInPlace(this, counter).
*
* @param counter The Counter whose counts will be added. For each key in
* counter, if it is not in this, then it will be added with value
* <code>counter.getCount(key)</code>. Otherwise, it will have value
* <code>this.getCount(key) + counter.getCount(key)</code>.
*/
void addAll(Counter<E> counter);
/**
* Removes the given key and its associated value from this Counter.
* Its count will now be returned as the defaultReturnValue and it
* will no longer be considered previously seen. If a key not contained in
* the Counter is given, no action is performed on the Counter and the
* defaultValue is returned. This behavior echoes that of HashMap, but differs
* since a HashMap returns a Double (rather than double) and thus returns null
* if a key is not present. Any future revisions of Counter should preserve
* the ability to "remove" a key that is not present in the Counter.
*
* @param key The key
* @return The value removed from the map or the default value if no
* count was associated with that key.
*/
double remove(E key);
/** Returns whether a Counter contains a key.
*
* @param key The key
* @return true iff key is a key in this Counter.
*/
boolean containsKey(E key);
/**
* Returns the Set of keys in this counter.
*
* @return The Set of keys in this counter.
*/
Set<E> keySet();
/**
* Returns a copy of the values currently in this counter.
* (You should regard this Collection as read-only for forward
* compatibility; at present implementations differ on how they
* respond to attempts to change this Collection.)
*
* @return A copy of the values currently in this counter.
*/
Collection<Double> values();
/**
* Returns a view of the entries in this counter. The values
* can be safely modified with setValue().
*
* @return A view of the entries in this counter
*/
Set<Map.Entry<E,Double>> entrySet();
/**
* Removes all entries from the counter.
*/
void clear();
/**
* Returns the number of entries stored in this counter.
* @return The number of entries in this counter.
*/
int size();
/**
* Computes the total of all counts in this counter, and returns it
* as a double. (Existing implementations cache this value, so that this
* operation is cheap.)
*
* @return The total (arithmetic sum) of all counts in this counter.
*/
double totalCount();
}