---

CdbNTuple.hh

Go to the documentation of this file.

#ifndef CDB_NTUPLE_HH
#define CDB_NTUPLE_HH

// File and Version Information:
//      $Id: CdbNTuple.hh,v 1.6 2004/04/02 07:41:27 gapon Exp $

//#include "CdbBase/CdbItr.hh"
#include "CdbBase/CdbCPtrBase.hh"

#include "CdbTable/CdbNTupleBase.hh"

// Forward declaration for the comparator interface used by the ::sort
// method of the n-tuple.

template < class T, unsigned int NCOL > class CdbNTupleIsLessComparator;

/// An abstract base class for n-tuples.
/**
  * This class provides a base interface of and common infrustructure for data
  * stored in this n-tuple facility.
  *
  * Specifically the roles of this class are:
  *
  * - It defines the base configuration of n-tuple, which includes a type of its
  *   elements and the width (the number of elements) of its rows.
  *
  * - It defines the behavior of n-tuple (finding elements, updating, replacing, etc.)
  *
  * - It provides metadata information about n-tuple through its base class CdbNTupleBase.
  *
  * Notes:
  *
  * - Since the width of n-tuple is specified through its template parameter
  *   then two n-tuples of the same element type but different width are NON-COMPATIBLE!!!
  *   That's a design decision to enforce proper use of n-tuples at compilation time.
  *
  * - The names of columns (either generated by default or explicitly passed to the corresponding
  *   constructor of n-tuple) can be used when doing queries on values of elements of the n-tuple.
  *
  * @see class CdbNTupleBase
  */
template < class T, unsigned int NCOL >
class CdbNTuple : public CdbNTupleBase {

friend class CdbCPtrBase< CdbNTuple<T,NCOL> >;  // to destroy objects of this class

public:

    typedef T element_type;

    enum { ncol = NCOL };

protected:

  /// The default constructor

    CdbNTuple( );

  /// The constructor
  /**
    * The constructor will also assign default names to the columns. These names will be
    * derived from relative locations of the corresponding columns in a row. For example,
    * for an n-tuple of the width of 4 we would have:
    *
    *   "#0" "#1" "#2" "#3"
    */
    CdbNTuple( const std::string& theName,
               const std::string& theDescription );

  /// The constructor
  /**
    * This constructor can be used to specify the names of columns. The vector of names
    * passed as the first parameter can be of any length, where it would be shorter or longer
    * than the width of n-tuple.
    *
    * Notes:
    *
    * - Names passed in the vector must be unique. The default names assigned by the default
    *   descructor (see above) should not be used. A run-time assertion will happen in case
    *   of violation of this rule.
    *
    * - If the vector is shorter then elements of the vector will be used to name the first
    *   the rest of names will be filled with names derived from relative position of
    *   the corresponding column in a row. See the default constructor's description for details.
    *
    * - If the vector is longer - then the rest of the vector will be simply ignored.
    */
    CdbNTuple( const std::vector<std::string>& theCollumnNames,
               const std::string&              theName,
               const std::string&              theDescription );

  /// The copy constructor
  /**
    * Copy the local context.
    */
    CdbNTuple( const CdbNTuple<T,NCOL>& theOther );

  /// The assignment operator
  /**
    * Copy the local context.
    */
    CdbNTuple<T,NCOL>& operator=( const CdbNTuple<T,NCOL>& theOther );

public:

  /// The destructor
  /**
    * Just to enforce the virtual destructor.
    */
    virtual ~CdbNTuple( );

  /// Make a ("deep") clone of a tuple
  /**
    * The method is defined here to cope with a hierarchy of possible
    * implementations of the current n-tuple interface.
    */
    virtual CdbNTuple<T,NCOL>* clone( ) const = 0;

  /// Get the current size (the number of rows) of n-tuple

    virtual unsigned int rows( ) const = 0;

  /// Resize the current size (the number of rows) of n-tuple
  /**
    * Notes:
    *
    * - if the new size is less than its current size then the rest of the n-tuple
    *   will be truncated and destructors for the removed elements will be called.
    *
    * - if the new size is more - then n-tuple will be extended and default constructors
    *   for new elements will be called.
    *
    * @return the completion status of the operation
    */
    virtual CdbStatus set_rows( unsigned int theNewSize ) = 0;

  /// Resize the current size (the number of rows) of n-tuple using a prototype
  /**
    * Unlike a previously defined method, this one would use a user defined value of
    * a prototype object to fill the new elements if new rows are to be created.
    */
    virtual CdbStatus set_rows( unsigned int theNewSize,
                                const T&     thePrototype ) = 0;

  /// Append a new row
  /**
    * A vector passed as the parameter would extend n-tuple's size by one.
    *
    * Notes:
    *
    * - the vector is allowed to be less or greater than the width of n-tuple.
    *
    * - if the vector is shorter then the remaining elements will be padded
    *   using the new ones created using the default constructor of the current
    *   elements type.
    *
    * - if the vector is longer - the rest of the vector will be simply ignored.
    */
    virtual CdbStatus append_row( const std::vector<T>& theRow ) = 0;

  /// Insert a whole row of elements after the specified one
  /**
    * @return the method will CdbStatus::NotFound if the row does not exist.
    */
    virtual CdbStatus insert_row( const std::vector<T>& theRow,
                                  unsigned int          theRowNumber ) = 0;

  /// Replace a whole row of elements at specified position
  /**
    * @return the method will CdbStatus::NotFound if the row does not exist.
    */
    virtual CdbStatus replace_row( const std::vector<T>& theRow,
                                   unsigned int          theRowNumber ) = 0;

  /// Get a whole row of elements

    virtual CdbStatus get_row( std::vector<T>& theRow,
                               unsigned int    theRowNumber ) const = 0;

  /// Get a whole column by its number

    virtual CdbStatus get_column( std::vector<T>& theColumn,
                                  unsigned int    theColumnNumber ) const = 0;

  /// Get a whole column by its name

    virtual CdbStatus get_column( std::vector<T>&    theColumn,
                                  const std::string& theColumnName ) const = 0;

  /// Read an element (specify column by its number)

    virtual CdbStatus get_element( T&           theValue,
                                   unsigned int theRowNumber,
                                   unsigned int theColumnNumber ) const = 0;

  /// Read an element (specify column by its name)

    virtual CdbStatus get_element( T&                 theValue,
                                   unsigned int       theRowNumber,
                                   const std::string& theColumnName ) const = 0;

  /// Update a single an element (specify column by its number)

    virtual CdbStatus set_element( const T&     theValue,
                                   unsigned int theRowNumber,
                                   unsigned int theColumnNumber ) = 0;

  /// Update a single an element (specify column by its name)

    virtual CdbStatus set_element( const T&           theValue,
                                   unsigned int       theRowNumber,
                                   const std::string& theColumnName ) = 0;

// TEMPORARY DISABLED DUE TO RTTI LINK PROBLEM ON SOLARIS
//
//  /// Find all rows whose elements at specified (by its number) column have this value
//  /**
//    * IMPORTANT NOTE: The current model of the iterator assumes that an n-tuple
//    *                 in question stays immutable while the iterator is in use.
//    *                 Otherwise the results may be unpredictable.
//    */
//    virtual CdbStatus find_row( CdbItr<unsigned int>& theIterator,
//                                unsigned int          theColumnNumber,
//                                const T&              theValue ) const = 0;
//
//  /// Find all rows whose elements at specified  (by its name) column have this value
//  /**
//    * See notes on the iterator in the previous method's description.
//    */
//    virtual CdbStatus find_row( CdbItr<unsigned int>& theIterator,
//                                const std::string&    theColumnName,
//                                const T&              theValue ) const = 0;

  /// Sort rows using specified comparator
  /**
    * @return the method will CdbStatus::Success in case of successfull completion.
    */
    virtual CdbStatus sort( const CdbNTupleIsLessComparator<T,NCOL>* theComparatorPtr ) = 0;
};

#ifdef     BABAR_COMP_INST
#include "CdbTable/CdbNTuple.cc"
#endif  // BABAR_COMP_INST

#endif // CDB_NTUPLE_HH

---