---

CdbNTupleAlgorithms.hh

Go to the documentation of this file.

#ifndef CDB_NTUPLE_ALGORITHMS_HH
#define CDB_NTUPLE_ALGORITHMS_HH

// File and Version Information:
//      $Id: CdbNTupleAlgorithms.hh,v 1.4 2004/03/16 19:22:42 gapon Exp $

#include "CdbBase/CdbCPtr.hh"
#include "CdbTable/CdbNTuple.hh"

// Forward declaration for the comparator interface used by the CdbNTupleSort
// algorithm.

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

/**
  * DESCRIPTION:
  *
  *   This file contains declarations for a collection of algorithms
  *   dealing with n-tuple-es.
  *
  * DESIGN NOTES:
  *
  *   Strictly speaking we should have defined these algorithms as:
  *
  *     template < class T,
  *                unsigned int NCOL >
  *     CdbStatus
  *     CdbNTupleMerge(       CdbCPtr<CdbNTuple<T,NCOL> >& theOutputPtr,
  *                     const CdbCPtr<CdbNTuple<T,NCOL> >& thePrototypePtr,
  *                     const CdbCPtr<CdbNTuple<T,NCOL> >& theExtraPtr );
  *
  *     template < class T,
  *                unsigned int NCOL >
  *     CdbStatus
  *     CdbNTupleAppend(       CdbCPtr<CdbNTuple<T,NCOL> >& theOutputPtr,
  *                      const CdbCPtr<CdbNTuple<T,NCOL> >& theInputPtr );
  *
  *     template < class T,
  *                unsigned int NCOL >
  *     CdbStatus
  *     CdbNTupleCopy(       CdbCPtr<CdbNTuple<T,NCOL> >& theOutputPtr,
  *                    const CdbCPtr<CdbNTuple<T,NCOL> >& theInputPtr );
  *
  *   Unfortunatelly this trick does not work for those n-tuples are subclasses
  *   of CdbNTuple and which are passed directly (w/o downcasting) to this function.
  *
  *   The solution was to have less strict interfaces which expects smart pointers
  *   onto n-tuple-like objects, meaning that the corresponding classes should exhibit
  *   enough interface to perform the current action.
  *
  *   Another advantage of this approach is that these algorithm would be perfectly
  *   functional for any other classes which may not derive from CdbNTuple.
  *
  *   Things are even more complicated for the "glue" algorithm, which should have
  *   been defined as:
  *
  *     template < class T,
  *                unsigned int NCOL_LEFT,
  *                unsigned int NCOL_RIGHT >
  *     CdbStatus
  *     CdbNTupleGlue(       CdbCPtr<CdbNTuple< T, NCOL_LEFT + NCOL_RIGHT > >& theOutputPtr,
  *                    const CdbCPtr<CdbNTuple< T, NCOL_LEFT > >&              theLeftPtr,
  *                    const CdbCPtr<CdbNTuple< T, NCOL_RIGHT > >&             theRightPtr,
  *                    const bool                                              allowRenamingOfColumnsFlag = true );
  *
  *   See the documentation on the algorithm below for more explanation why.
  */

/// A "merge of rows" algorithm for n-tuples of the same type
/**
  * This algorithm will produce a _NEW_ "output" tuple with rows copied from
  * both input tables.
  *
  * The metadata of the "output" tuple will be copied from the "prototype" one.
  *
  * The order of rows won't change. All rows from the "prototype" tuple will
  * be copied first. Then all rows found in the "extra" tuple will be appended
  * by the end of the "ouput" tuple.
  *
  * MEMORY MODEL NOTES:
  *
  *   Note, that the parameters of these algorithms are _counted_smart_pointers_
  *   onto the actual tuples. Therefore, to avoid confusions in case when two or
  *   more parameters of the algorithm will point onto the same instance
  *   of a tuple, remember that:
  *
  *   (1) The "output" pointer will always be initialized with a _newely_ created
  *       tuple. Any initial tuple pointed by the "output" pointer won't be affected
  *       by the algorithm.
  *
  *       IMPORTANT: The actual type of the "output" tuple will be the same as
  *                  the one of the "protorype" tuple.
  *
  *   (2) The algorithm won't attempt to check if both "prototype" and "extra"
  *       pointers point onto the same tuple. If this is going to be the case
  *       then the resulting tuple will have a double set of rows.
  *
  *   (3) The "output" pointer may not be a valid (not pointing to any tuple)
  *       pointer when calling this algorithm.
  *
  *   (4) Both "prototype" and "extra" pointers must be valid pointers.
  *
  *   (5) If the algorithm will fail for some reason then the "output"
  *       pointer won't change.
  *
  * @see class CdbNTuple
  * @see class CdbCPtr
  */
template < class NTUPLE >
CdbStatus
CdbNTupleMerge(       CdbCPtr<NTUPLE>& theOutputPtr,
                const CdbCPtr<NTUPLE>& thePrototypePtr,
                const CdbCPtr<NTUPLE>& theExtraPtr );

/// An "append of rows" algorithm for n-tuples of the same type
/**
  * This algorithm will append all rows from the "input" tuple by
  * the "output" one.
  *
  * The metadata of the "output" tuple won't be affected.
  *
  * The order of rows won't change. All the original rows of the "output" tuple
  * won't be affected. All rows found in the "input" tuple will be appended
  * by the end of the "ouput" tuple.
  *
  * MEMORY MODEL NOTES:
  *
  *   Note, that the parameters of these algorithms are _counted_smart_pointers_
  *   onto the actual tuples. Therefore, to avoid confusions in case when two or
  *   more parameters of the algorithm will point onto the same instance
  *   of a tuple, remember that:
  *
  *   (1) Upon the completion of the algorithm, the "output" pointer will
  *       always be pointing onto the same tuple.
  *
  *   (2) If both "output" and "input" pointers point onto the same tuple then
  *       the resulting tuple will contain a duble set of rows after the completion
  *       of the algorithm.
  *
  *   (3) Both "output" and "input" pointers must be valid pointers.
  *
  *   (5) If the algorithm will fail for some reason then the "output"
  *       tuple may stay in the unpredicted state!!!. IN this case also
  *       keep in mind the rule (2) above.
  *
  * @see class CdbNTuple
  * @see class CdbCPtr
  */
template < class NTUPLE >
CdbStatus
CdbNTupleAppend(       CdbCPtr<NTUPLE>& theOutputPtr,
                 const CdbCPtr<NTUPLE>& theInputPtr );

/// A "copy" algorithm for n-tuples of the same type
/**
  * will produce a _NEW_ "output" tuple with an exact copy of the "input" one.
  *
  * The metadata of the "output" tuple will be replaced with the one taken
  * from the input
  *
  * The order of rows won't change. All the original rows of the "output" tuple
  * won't be affected. All rows found in the "input" tuple will be appended
  * by the end of the "ouput" tuple.
  *
  * MEMORY MODEL NOTES:
  *
  *   Note, that the parameters of these algorithms are _counted_smart_pointers_
  *   onto the actual tuples. Therefore, to avoid confusions in case when two or
  *   more parameters of the algorithm will point onto the same instance
  *   of a tuple, remember that:
  *
  *   (1) The "output" pointer will always be initialized with a _newely_ created
  *       tuple. Any initial tuple pointed by the "output" pointer won't be affected
  *       by the algorithm.
  *
  *       IMPORTANT: The actual type of the "output" tuple will be the same as
  *                  the one of the "input" tuple.
  *
  *   (2) The "output" pointer may not be a valid (not pointing to any tuple)
  *       pointer when calling this algorithm.
  *
  *   (3) The "input" pointer must be a valid pointer.
  *
  *   (4) If the algorithm will fail for some reason then the "output"
  *       pointer won't change.
  *
  * @see class CdbNTuple
  * @see class CdbCPtr
  */
template < class NTUPLE >
CdbStatus
CdbNTupleCopy(       CdbCPtr<NTUPLE>& theOutputPtr,
               const CdbCPtr<NTUPLE>& theInputPtr );

/// A "glue of columns" algorithm for n-tuples of the same type elements
/**
  * This algorithm will produce a _NEW_ "output" tuple, with a sum of columns
  * from both input tuples. The data from rows will be copied accordingly.
  *
  * The metadata of the "output" tuple will be copied from the "left" one.
  *
  * The algorithm will also make a best attempt to preserve the names of columns.
  * An optional parameter "allowRenamingOfColumnsFlag" of the algorithm would
  * control a resolution of potential conflicts. Here are the rules:
  *
  *   - if there is no conflict then all names from both tuples will be copied
  *     into the output tuple.
  *
  *   - in case of a conflict and if the flag is set to "false" then the algorithm
  *     will fail and return the "CdbStatus::ConflictOfParameters" error status.
  *
  *   - in case of a conflict and if the flag is set to "true" then the algorithm
  *     will preserve al names from the "left" tuple, it will also preserve
  *     all non-conflicting names from the "right" tuple, and it will replace
  *     all conflicting names from the "right" tuple with default names (see
  *     the description of the CdbNTupleBase class for details).
  *
  * The order of rows won't change. The rows with the same numbers from both
  * tuples will be "glued" into the corresponding rows of the "output" tuple.
  * Missing elements of a shortest tuple will be replaced using defaul constructor
  * of the elements type.
  *
  * MEMORY MODEL NOTES:
  *
  *   Note, that the parameters of these algorithms are _counted_smart_pointers_
  *   onto the actual tuples. Therefore, to avoid confusions in case when two or
  *   more parameters of the algorithm will point onto the same instance
  *   of a tuple, remember that:
  *
  *   (1) The "output" pointer will always be initialized with a _newely_ created
  *       tuple. Any initial tuple pointed by the "output" pointer won't be affected
  *       by the algorithm.
  *
  *       IMPORTANT: The actual type of the "output" tuple is implementation
  *                  (of the algorithm) specific.
  *
  *   (2) The algorithm won't attempt to check if both "left" and "right"
  *       pointers point onto the same tuple. If this is going to be the case
  *       then the resulting tuple will have a double set of columns.
  *
  *   (3) The "output" pointer may not be a valid (not pointing to any tuple)
  *       pointer when calling this algorithm.
  *
  *   (4) Both "left" and "right" pointers must be valid pointers.
  *
  *   (5) If the algorithm will fail for some reason then the "output"
  *       pointer won't change.
  *
  *
  * IMPLEMENTATION NOTE:
  *
  *   Due to a lack of full support for any expressions with non-class template parameters
  *   of template functions _and_ template methods in:
  *
  *     "Sun WorkShop 6 update 1 C++ 5.2 Patch 109508-03 2001/04/07"
  *
  *   this algorithm can't be made available through a normal template function
  *   with a signature like:
  *
  *     template < class T,
  *                unsigned int NCOL_LEFT,
  *                unsigned int NCOL_RIGHT >
  *     CdbStatus
  *     CdbNTupleGlue(       CdbCPtr<CdbNTuple< T, NCOL_LEFT + NCOL_RIGHT > >& theOutputPtr,
  *                    const CdbCPtr<CdbNTuple< T, NCOL_LEFT > >&              theLeftPtr,
  *                    const CdbCPtr<CdbNTuple< T, NCOL_RIGHT > >&             theRightPtr,
  *                    const bool                                              allowRenamingOfColumnsFlag = true );
  *
  *   One unfortunate problem of this solution is its weakness (compared to the original idea of
  *   the template function) in the compilation time type checking of arguments. The problem
  *   is that there is no simple way to check that the output tuple has the same width as
  *   a sum of both input tuples' widths. That's why this implementation will return
  *   a special error value to indicate this problem:
  *
  *     CdbStatus::ConflictOfParameters
  *
  * @see class CdbNTuple
  * @see class CdbCPtr
  */
template < class NTUPLE_OUT,
           class NTUPLE_LEFT,
           class NTUPLE_RIGHT >
CdbStatus
CdbNTupleGlue(       CdbCPtr<NTUPLE_OUT>&   theOutputPtr,
               const CdbCPtr<NTUPLE_LEFT>&  theLeftPtr,
               const CdbCPtr<NTUPLE_RIGHT>& theRightPtr,
               const bool                   allowRenamingOfColumnsFlag = true );

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

#endif // CDB_NTUPLE_ALGORITHMS_HH

---