package edu.vt.marian.search;

import java.util.*;
import java.io.*;

import edu.vt.marian.common.*;


/**
 * Sequencers are an important component of Searchers.  The function of
 *	a Sequencer is to take several WtdObjSets and merge them into a
 *	single bag of weighted objects in non-increasing order.  The
 *	contents of this resulting sequence are the WtdObjs from the
 *	component sets in the same order as a WtdObjSet (highest weight to
 *	lowest) but with duplicates <I>not</I> removed.
 * <P>
 * <B>NOTE:</B>  Given the intended use of Sequencers, we can implement
 *	the result sequence as a succession of objects returned by a
 *	nextElement() method.  There are two ways to design this.  Either
 *	a Sequencer should return an Enumeration that provides nextElement()
 *	and hasMoreElements() methods, or it can itself *be* an Enumeration.
 *	I have chosen the second course here, since most sequencers only run
 *	through their sequence a single time (while loading the appropriate
 *	Table or Cache).  The exception is the "terminal" sequencers in Summative
 *	Union searchers, where many objects may share a single Searcher, each using
 *	their own Enumeration to step through a (partially pre-computed)
 *	sequence of results.  To enable this sharing, we will capture the
 *	Sequencer results in a Cache and provide Enumerations to the Cache.
 *
 * @author Robert France
 * @see java.util.Enumeration
 * @see	EnumCacheWtdObjSet
 * @see	EnumCacheWtdObjSetEnum
 */

public interface Sequencer extends Enumeration
{
	/**
	 * Return the expected number of <I>unique</I> elements in the result
	 *	sequence.
	 * <P>
	 * <B>NOTE:</B>  The statistics here are drawn from the hypergeometric
	 *	distribution.  Follow code and documentation in the C++ file
	 *	"search/woset_coll.cc."
	 * <P>
	 * To make the statistics work, we need to know the size of the
	 *	universe:  in this case, the class from which the objects in the
	 *	sets were drawn.  Since this is most likely to be known at
	 *	construction time, any constructor for a Sequencer should include
	 *	a parameter
	 * <BR>&nbsp;&nbsp;&nbsp;	long classSize.
	 *
	 */
	public int expectedNumElts();


	/**
	 * Return the maximum number of <I>unique</I> elements in the result
	 *	sequence. (This is usually just the sum of all the elements in
	 *	each component set.)
	 */
	public int maxNumElts();

	/**
		Return a human-readable string for this entire set (may be large).
	*/
	public String toString();

	/**
		Return a short human-readable string that quickly describes this set.
	*/
	public String profile();
}