Tuple.h

// -*- C++ -*-
// CLASSDOC OFF
// $Id: Tuple.h,v 1.3 1998/07/15 11:34:46 evc Exp $
// ---------------------------------------------------------------------------
// CLASSDOC ON
//
// This file is a part of what might become CLHEP -
// a Class Library for High Energy Physics.
//
// HepTuple.h - C++ virtual base class for ntuples.
//
// .SS Usage
// The HepTuple model is of an ntuple that is stores data passed
// to it until told an entry is complete, when it dumps the data
// out and prepares for the next entry
//
// Typical use would be something like:
//
//     HepTuple myNt("The Title");
//     float x;
//     int ix;
//       :
//       :
//     myNt.column("A float number", x );
//     if (x > 5.0) 
//     {
//        myNt.column("An int", ix, -1.0);
//     }
//       :
//       :
//     if (goodEvent) 
//        myNt.dumpData();
//     else
//        myNt.clearData();
//
// The member function "column" provides the data for a column of the ntuple.
// The string is the label of the column as well as being a unique identifier
// of the column. The second argument provides the data (float or int) for
// one row in the column. Note that only one line of code is needed to
// define the column (if it has not been seen previously) and provide the
// data for each "event". 
//
// The third argument of "column()" provides the default value for that
// column (if it not provided, it defaults to 0.0). On a particular "event",
// if no call is made to "column" for a particular column, that column's
// default value is used when filling the ntuple. Therefore, the default
// value should be set to an "unphysical" number.
//
// At the end of an "event", a call should be made to either "dumpData()" or
// "clearData()". "dumpData()" dumps all the data it has stored internally
// into the ntuple and then calls "clearData()". "clearData()" sets all the
// internal column values to their defaults, without changing the real
// ntuple. Therefore, if you want to keep the data that is presently in an
// Tuple, call "dumpData()"; else, call "clearData()".
//
// .ft B
// The ntuple row is not saved in the ntuple unless dumpData() is called.
//
// .SS See Also
// TupleManager.h
// 
// .SS History
// 
// A generalization by Bob Jacobsen of HBTuple, written by Paul Rensing
//

#ifndef _Tuple_H_
#define _Tuple_H_

#ifdef GNUPRAGMA
#pragma interface
#endif

#include "CLHEP/config/CLHEP.h"
#include "CLHEP/String/Strings.h"

class HepTuple 
{
public:
   HepTuple(const char *title);
   // create a tuple with the given title

   virtual ~HepTuple();

   virtual void column(const char *label, float value, float defvalue=0.0)=0;
   // Specify the data for a column. The string is to the key to
   // the column, so it must be unique. If an existing column with the given
   // label is not found, a new one is created. The third, optional, argument
   // is the value to use if this column is not otherwise filled in for a
   // given row of the tuple.

   virtual void dumpData()=0;
   // Dump all the data into the ntuple and then clear
     
   virtual void clearData();
   // Set all the data to their default values
     
   HepString title() const;

   HepString label(int i) const;
   // label for a particular column

protected:
   virtual int setExistingColumn(const char *lbl, float val);
   // try to find the given label in the set of columns. If it is found,
   // set the column's value and return 1. Else return 0.

   virtual void newColumn(const char *lbl, float val, float defval);
   // Add a new column to the list of existing ones

   HepString _title;
     
   HepString **_labels;
   HepString **_nextLabel;
   float *_values;
   float *_defvalues;
   int _nColumns;

   
};

#ifdef HEP_SHORT_NAMES
#define Tuple HepTuple
#endif

#endif				// _HepTuple_H_