#ifndef HEPHIST1DARRAY_H
#define HEPHIST1DARRAY_H

// ----------------------------------------------------------------------
//
// HepHist1DArray.h - class declaration for generic array of 1D histogram
//
//
// - Creators
//- - --------------
//
//An array form of each creator.  Say the manager has pointer m and the array 
//size
//is K.  The syntax for one hist1d is
//
//  HepHist1D h (m->hist1D( title , nbins, low, high, id ));
//
//The proposed array syntax is
//
//  HepHist1DArray h (m->hist1DArray ( K, title , nbins, low, high, id ));
//
//	Tempting would be to extend with a syntax like
//	  HepHist1D h[K] (m->hist1D( title , nbins, low, high, id ));
//		or 
//	  HepHist1Darray[K] h (m->hist1D( title , nbins, low, high, id ));
//	However, it is not clear how to implement that, and if we were to come 
//	up with some clever way, it would probably be too much black magic.
//
//The semantics of this would be as follows:
//
//1) At the manager level, K distinct hist1D would be formed.
//
//2) The titles of the hist1D's would be title000, title001, ... where
//   the number of digits is fixed by the number of digits in K-1.  That is,
//   for 100 hists, wyou have title00 thru title99.
//
//3) All binning data, in this case nbins, low and high, are identical for all
//   K of the hists.
//
//4) If id is 0 (default), the assigned id's are K CONSECUTIVE id's chosen so 
//   as not to conflict with existing id's.  If id is non-zero, K id's starting
//   from that id are used.  If there is a conflict, then the call will fail
//   in the same way that hist1D (... id) will fail if id is already assigned.

// 1.2 - Retrievors
// - - ----------------

// Alothough a given particular member of a hist array can be retrieved by its 
// title (eg title49) or id, the retrieve methods analogous to the creator
// methods are also present:

// retrieveHist1DArray   (K, title, id)
// retrieveHist2DArray   (K, title, id)
// retrieveHistProfArray (K, title, id)

// The semantics are:

// 1) The user is responsible for knowing what K is.  We propose to NOT provide
//    a method of determining K given the histogram array generic title.
// 	An alternative is to provide such a method, whcih merely looks for 
// 	a hist with the right title and sees how long a sequence of numbers
// 	exists.

// 2) The titles and ids are checked -- if the titles are not title000 thru 
//    whatever, or the id's are not consecutive, then the method fails, throwing
//    the same sort of ZMexception as when you try to retrieve a non-existant 
//    hist.

// We could with work provide the following, but we will not:
// 	Z) You could retrive fewer hists than were actually available by
// 		retrieveHist1DArray   (N, S, title, id)
// 		retrieveHist2DArray   (N, S, title, id)
// 		retrieveHistProfArray (N, S, title, id)
// 	meaning retrieve N starting at S.  For example, 
// 		retrieveHist1DArray (10, 25, peds, 0) would mean find peds00,
// 	and retrieve peds25 thru peds34.  The the value of J indexing which
// 	one of these you refer to (for accumulation etc.) would be 25 to 34;
// 	we would have to remember the offset in the histArray struct.  This
// 	complicates the concepts for not much benefit.

// 1.3 - ls behavior
// - - -----------------

// When ls is invoked on a manager that has an array of hists, the array is listed
// as K separate hists. 
// 	An alternative would be to detect the sequence and list like
// 	CAL[6] instead of CAL0 CAL1 CAL2 CAL3 CAL4 CAL5.  This is extra
// 	work, and also probably hurts the user by defeating tools honed to
// 	the actual hist name.


// 
// 2 - In HepHist1D and other Hist classes:
// - - ----------------------------------------
// - - ----------------------------------------

// The main issues involve how to accumulate and access data.  Hee, the concept of
// an index awhich we call J is key:  J runs from 0 to K-1 and is an extra first
// argument to the accumulate and retrieval methods.

// There is no reason for concern about signature confusion between the 
// histArray methods and the corresponding hist methods.  Nor is there 
// concern about ambiguity in the Histarray methods themselves, because 
// the histWhateverArray class is distinct from histWhatever.

// 2.1 Accumulating data / Retrieving histogram data
// - - ---------------------

// All members functions of individual can be accessed through
// the histArray[index] notation:

// hist1DArray[J].accumulate( x, weight )
// hist2DArray[j].accumulate( x, y, weight )
// histProfArray[j].accumulate( x, y, weight )

// Reset could be done on a all-histograms or individual basis; I can see uses
// for iether and I would supply both:

// hist1DArray.reset();    // Resets all K of the individual histograms.
// hist1DArray[j].reset(); // Just resets one.

// hist1DArray[J].bin(binNum) 
// hist1DArray[J].entries()
// hist1DArray[J].weight()
// hist1DArray[J].sum()
// hist1DArray[J].sum2()
// hist1DArray[J].mean()
// hist1DArray[J].variance()

// 	We might think about all-histogram versions, either returning
// 	an array of values, or some overall sum.  The former introduces
// 	technical questions -- for example, you would like h.entries() to
// 	return an array of floats containing h[J].entries(), but how to 
// 	do this:  You could make it an argument, return a float* (probably
// 	trapping users into memory leaks) or introduce std::vector's.
// 	The overall sum idea is cleaner but a lot less useful.  At any
// 	rate, our users are perfectly capable of looping over J when they
// 	need this sort of information, so we should not make our interface
// 	any heavier than it is for this benefit.

// 2.2 Accessing class information
// - - -------------------------------

// These are easy because the class info is identical across the whole array.

// dir() 		same as for non-arrays
// Manager() 	same as for non-arrays
// title() 	will return the base title
// id() 		the starting id
// type() 		ought to be the same as for non-arrays, 
// 		using the same typeID letter.
// errorMethod()	is "not yet implemented."  If nobody cares, it stays that way.

// nBinsX() 	The various range routines 
// minX()		can just call 
// maxX() 		their counterparts 
// nBinsY() 	for the first
// minY()		element of 
// maxY() 		element of the array.

// length()	We should add this method just for arrays; it returns K.

// 2.4 - Creating a new Hist array from a parent
// - - ---------------------------------------------

// These should be provided, and should work just like the non-array versions:

// makeClone()
// makeEmpty()

// However, use of these may be fairly rare!

// History:
//  02-APR-99 Philippe Canal initial Draft

#ifndef ZMENVIRONMENT_H
  #include "ZMutility/ZMenvironment.h"
#endif

#include <string>

#ifndef  HEPOBJ_H
  #include "HepTuple/HepObj.h"
#endif

#ifndef ISOCXX__ISOCXX
  #include <STLUtility/fwd_vector.h>
#endif

ZM_BEGIN_NAMESPACE( zmht )	/*  namespace zmht  {  */

class HepHist1D;

class HepHist1DArray  :  public HepObj  {

  friend class HepFileManager;

public:
  
  typedef std::STL_VECTOR(HepHist1D*) dataArray;

protected:

  HepHist1DArray(                            // constructor
    HepFileManager    * mgr
  , const std::string & title
  , const dataArray   & data
  );

  // Used for dummy construction ...
  // the object is then not valid ...
  HepHist1DArray( );                         // default constructor

public:
  
  virtual ~HepHist1DArray();                 // destructor

  virtual ZM_COVARIANT_TYPE(HepObj,HepHist1DArray) & makeClone(
       const std::string& title, const int  id = 0) const;

  virtual ZM_COVARIANT_TYPE(HepObj,HepHist1DArray) & makeEmpty(
       const std::string& title, const int  id = 0) const;

  virtual ZM_COVARIANT_TYPE(HepObj,HepHist1DArray) & makeClone(
       HepFileManager *manager, const std::string& title
       , const int  id = 0) const;

  virtual ZM_COVARIANT_TYPE(HepObj,HepHist1DArray) & makeEmpty(
       HepFileManager *manager, const std::string& title
       , const int  id = 0) const;

  virtual void reset();

  virtual int length() const;
  virtual HepHist1D& operator[](int pos) const;

  virtual int nBins() const;     // retrieve # of in-range bins
  virtual float min() const;     // retrieve low end of binned range
  virtual float max() const;     // retrieve high end of binned range

private:

  // forbidden operations, hence private
  HepHist1DArray( const HepHist1DArray & );              // copy constructor
  HepHist1DArray & operator=( const HepHist1DArray & );  // assignment
  
  dataArray data_;     // array of Hist1D pointers

  int   nBins_;                     // # of in-range bins
  float min_;                       // lowest in-range value
  float max_;                       // highest in-range value
};

ZM_END_NAMESPACE( zmht )	/*  }  // namespace zmht  */

#endif  // HEPHIST1DARRAY_H