package hep.aida.bin;

/**
 * Abstract base class for all arbitrary-dimensional bins consumes <tt>double</tt> elements.
 * First see the <a href="package-summary.html">package summary</a> and javadoc <a href="package-tree.html">tree view</a> to get the broad picture.
 * <p>
 * This class is fully thread safe (all public methods are synchronized).
 * Thus, you can have one or more threads adding to the bin as well as one or more threads reading and viewing the statistics of the bin <i>while it is filled</i>.
 * For high performance, add data in large chunks (buffers) via method <tt>addAllOf</tt> rather than piecewise via method <tt>add</tt>.
 * 
 * @author wolfgang.hoschek@cern.ch
 * @version 0.9, 03-Jul-99
 */
public abstract class AbstractBin extends cern.colt.PersistentObject {
/**
 * Makes this class non instantiable, but still let's others inherit from it.
 */
protected AbstractBin() {
}
/**
 * Returns <tt>center(0)</tt>.
 */
public final double center() {
	return center(0); 
}
/**
 * Returns a custom definable "center" measure; override this method if necessary.
 * Returns the absolute or relative center of this bin.
 * For example, the center of gravity.
 * 
 * The <i>real</i> absolute center can be obtained as follow:
 * <tt>partition(i).min(j) * bin(j).offset() + bin(j).center(i)</tt>,
 * where <tt>i</tt> is the dimension.
 * and <tt>j</tt> is the index of this bin.
 *
 * <p>This default implementation always returns 0.5.
 *
 * @param dimension the dimension to be considered (zero based).
 */
public synchronized double center(int dimension) {
	return 0.5; 
}
/**
 * Removes all elements from the receiver.
 * The receiver will be empty after this call returns.
 */
public abstract void clear();
/**
 * Returns whether two objects are equal;
 * This default implementation returns true if the other object is a bin 
 * and has the same size, value, error and center.
 */
public boolean equals(Object otherObj) {
	if (! (otherObj instanceof AbstractBin)) return false;
	AbstractBin other = (AbstractBin) otherObj;
	return size()==other.size() && value()==other.value() && error()==other.error() && center()==other.center();
}
/**
 * Returns <tt>error(0)</tt>.
 */
public final double error() {
	return error(0);
}
/**
 * Returns a custom definable error measure; override this method if necessary.
 * This default implementation always returns <tt>0</tt>.
 *
 * @param dimension the dimension to be considered.
 */
public synchronized double error(int dimension) {
	return 0;
}
/**
 * Returns whether a client can obtain all elements added to the receiver.
 * In other words, tells whether the receiver internally preserves all added elements.
 * If the receiver is rebinnable, the elements can be obtained via <tt>elements()</tt> methods.
 */
public abstract boolean isRebinnable();
/**
 * Returns <tt>offset(0)</tt>.
 */
public final double offset() {
	return offset(0); 
}
/**
 * Returns the relative or absolute position for the center of the bin; override this method if necessary.
 * Returns 1.0 if a relative center is stored in the bin.
 * Returns 0.0 if an absolute center is stored in the bin.
 *
 * <p>This default implementation always returns 1.0 (relative).
 *
 * @param dimension the index of the considered dimension (zero based);
 */
public double offset(int dimension) {
	return 1.0; 
}
/**
 * Returns the number of elements contained.
 *
 * @returns the number of elements contained.
 */
public abstract int size();
/**
 * Returns a String representation of the receiver.
 */
public synchronized String toString() {
	StringBuffer buf = new StringBuffer();
	buf.append(getClass().getName());
	buf.append("\n-------------");
	/*
	buf.append("\nValue: "+value());
	buf.append("\nError: "+error());
	buf.append("\nRMS: "+rms()+"\n");
	*/
	buf.append("\n");
	return buf.toString();
}
/**
 * Trims the capacity of the receiver to be the receiver's current size.
 * Releases any superfluos internal memory.
 * An application can use this operation to minimize the storage of the receiver.
 *
 * This default implementation does nothing.
 */
public synchronized void trimToSize() {}
/**
 * Returns <tt>value(0)</tt>.
 */
public final double value() {
	return value(0);
}
/**
 * Returns a custom definable "value" measure; override this method if necessary.
 * <p>This default implementation always returns 0.0.
 *
 * @param dimension the dimension to be considered.
 */
public double value(int dimension) {
	return 0;
}
}