/// @file modeler.hpp
/// Base Modeler class
///
/// @remarks
/// This is the base class from which all modelers are derived.
///
/// @author mouser
/// @date   2003.07.29
//---------------------------------------------------------------------------

/// @defgroup Modelers Modelers
///
/// The Modeler class is for statistical compression methods.  It's job is
/// to continually maintain a probability distribution over the next symbol
/// to be parsed.  This probability information can be used by a coder
/// (like an arithmetic or huffman coder) to optimally code the parsed
/// symbol.

//---------------------------------------------------------------------------
// forward declarations
class OctaneModeler;
//---------------------------------------------------------------------------

//---------------------------------------------------------------------------
// recursive header protection
#ifndef ModelerH
#define ModelerH
//---------------------------------------------------------------------------

//---------------------------------------------------------------------------
// application includes
#include "symbolweightvector.hpp"
#include "../core/octaneclass.hpp"
#include "../parsers/parser.hpp"
#include "../coders/coder.hpp"
#include "../bitio/bitio.hpp"
// system includes
//---------------------------------------------------------------------------




//---------------------------------------------------------------------------
/// The Modeler class is for statistical compression methods.  It's job is
///  to continually maintain a probability distribution over the next symbol
///  to be parsed.  This probability information can be used by a coder
///  (like an arithmetic or huffman coder) to optimally code the parsed symbol.
///
/// @ingroup Modelers
///
class OctaneModeler : public OctaneClass
{
public:
	/// constructor
	OctaneModeler() {;}
	/// destructor
	virtual ~OctaneModeler() {;}
public:
	//---------------------------------------------------------------------------
	// OCTANE PUBLIC API - RTTI FUNCTIONS - these are supported by all derived classes
	virtual std::string GetName() {return "OctaneModeler";}
	virtual std::string GetDescription() {return "Base Modeler";}
	virtual std::string GetHelpInformation() {return "";}
	//---------------------------------------------------------------------------
public:
	//---------------------------------------------------------------------------
	// MODELLER PUBLIC API - STATE MAINTENANCE
	virtual void ResetState() {;};
	/// Are we ready to work? this is usually only true after the model has been trained.
	/// @return true if the modeler is ready to begin predicting probabilities.
	virtual bool IsReadyToModel() {return true;};
	virtual void SynchronizeStateForNewStream() {;};
	/// Build a model using a stream and a parser.
	/// @return true on success.
	virtual bool CreateModelUsingStream(OctaneParser *parserp, bitreader &from) {return true;};
	/// Build a model just using parser.
	/// This is called on startup, before any possible training, when a default parser exists.
	/// @note that no input (training) stream is provider; some modelers may ignore this.
	/// @return true on success
	virtual bool CreateModelUsingParser(OctaneParser *parserp) {return false;};
	/// Prepare for modeling mode given a trained parser.
	/// @return true on success
	virtual bool PrepareForModeling(OctaneParser *parserp) {return true;};
	/// Update our model after each symbol is received during compression and decompression.
	/// Modelers track symbols during parsing and update the probability distribution predictions
	///  for upcoming symbols.  This function should notify the coder of changes to probabilities.
	/// @see OctaneCoder::ReceiveNotification_ModelChange_AllSymbolWeights
	/// @see OctaneCoder::ReceiveNotification_ModelChange_SingleSymbolWeight
	/// @return true on success
	virtual bool UpdateModelAfterReceivingSymbol(int symbolnumber, OctaneCoder *coderp) {return true;};
	//---------------------------------------------------------------------------
public:
	//---------------------------------------------------------------------------
	// MODELLER PUBLIC API - ACCESSOR FOR CODING
	/// Return the number of symbols in the modeler (should be same as number of symbols in the parser); called by coder.
	virtual int GetSymbolCount() {return 0;};
	/// Return a pointer to the current weight vector for symbols (used by coder) [optional]
	/// This is provided as a shortcut function to avoid having to make numerous calls to GetWeightVectorItem() below.
	/// Not all modelers will maintain probabilities in the form of a SymbolWeightVector, and a modeler can return NULL in order to
	///  force the coder to get probabilities for each symbol individually.
	/// @see OctaneModeler::GetWeightVectorItem
	/// @return a pointer to a local SymbolWeightVector or NULL if it is not available.
	virtual SymbolWeightVector* GetWeightVectorp() {return NULL;};
	/// Return a specific weight index value; (used by coder).
	virtual TSymbolWeightVectorWeight GetWeightVectorItem(int symbolnum) {return 0;};
	//---------------------------------------------------------------------------
};
//---------------------------------------------------------------------------



//---------------------------------------------------------------------------
#endif
//---------------------------------------------------------------------------

