---

CdbBdbSTimeLineP.ddl

Go to the documentation of this file.

#ifndef CDBBDBSHARED_TIMELINE_P_HH
#define CDBBDBSHARED_TIMELINE_P_HH
// File and Version Information:
//      $Id: CdbBdbSTimeLineP.ddl,v 1.7 2004/08/06 05:54:25 bartoldu Exp $

#include "BdbUtil/Bdb.hh"

#include "CdbBase/CdbItr.hh"

#include "CdbBdbShared/CdbBdbSTimeLineInterval.hh"
#include "CdbBdbShared/CdbBdbSTimeLineNode.hh"
#include "CdbBdbShared/CdbBdbSPagedVarrayP.hh"
#include "CdbBdbShared/CdbBdbSBtreeP_InterVal_ULong.hh"

#include "BdbTime/BdbTime.hh"

/// Persistent TimeLine class.
/**
  * This is a persistent implementation for the timeline of intervals.
  */
template< class V >
class CdbBdbSTimeLineP : public BdbPersObj {

private:

    typedef CdbBdbSTimeLineNode< V > Node;

    typedef CdbBdbSInterValBte   BTreeEntry;
    typedef CdbBdbSInterValBtFCP BTreeEntryFCP;

public:

  /// Type definitions for the TimeLine's iterators
  /**
    * These types are being introduced here to facilitate more flexible
    * type parametrisation of the class's clients (including its
    * direct and indirect subclasses).
    */
    typedef CdbItr< CdbBdbSTimeLineInterval<V> > IteratorOfIntervals;

public:

  /// Default constructor
  /**
    * The timeline will be initialized with the value constructed according
    * the default constriuctor of the corresponding class.
    */
    CdbBdbSTimeLineP( );

  /// Normal constructor
  /**
    * This form of the constructor lets a client to specify the initial value
    * to be put into the timeline. This value will be covering the whole timeline
    * from the -Infinity to +Infinity.
    */
    CdbBdbSTimeLineP( const V& theInitialValue );

  // Destructor

    virtual ~CdbBdbSTimeLineP( );

  /// Insert an interval into the collection
  /**
    * This method will "cut in" the specified interval.
    */
    CdbStatus insert( const BdbTime& theBeginTime,  /**< the begin time of the interval */
                      const BdbTime& theEndTime,    /**< the end   time of the interval */
                      const V&       theValue       /**< the value associated with this interval */
                    );

  /// Insert an interval into the collection
  /**
    * This method will "cut in" the specified interval.
    */
    CdbStatus insert( const CdbBdbSTimeLineInterval<V>& theInterval     /**< the interval to insert */
                    );

  /// Find an interval in the TimeLine
  /**
    * This method will only return "true" if specified time macthes to
    * the begin time of an interval in the TimeLine.
    */
    bool findAtBegin( CdbBdbSTimeLineInterval<V>& theInterval,
                      const BdbTime&              theTime ) const;

  /// Find an interval in the TimeLine
  /**
    * This method if successfull (returned value is TRUE) will return the information
    * about the interval where the specified time falls into.
    */
    bool find( CdbBdbSTimeLineInterval<V>& theInterval,
               const BdbTime&              theTime ) const;

  /// Get the first interval in the TimeLine
  /**
    * Return CdbStatus::NotFound if there is no intervals in the collection.
    */
    CdbStatus first( CdbBdbSTimeLineInterval<V>& theInterval            /**< the value of the interval to be returned */
                   ) const;

  /// Get the last interval in the TimeLine
  /**
    * Return CdbStatus::NotFound if there is no intervals in the collection.
    */
    CdbStatus last( CdbBdbSTimeLineInterval<V>& theInterval             /**< the value of the interval to be returned */
                  ) const;

  /// Get an instance of an iterator for intervals
  /**
    * The intervals delivered via this iterator are sorted in
    * the TimeLIne dimension. The first interval in the list will include the specified
    * begin time.
    */
    IteratorOfIntervals iterator( const BdbTime& theBeginTime = BdbTime::minusInfinity ) const;

  /// Dump the contents of the collection
  /**
    * The range of the dumped interval is controlled by mean of two
    * optional parameters.
    */
    void dump( std::ostream&       o,                                        /**< the output stream */
               const BdbTime& theBeginTime = BdbTime::minusInfinity,    /**< the begin time of the interval */
               const BdbTime& theEndTime   = BdbTime::plusInfinity      /**< the end   time of the interval */
             );

  /// Clone the timeline object
  /**
    * An exact copy of the current object will be created
    * at specified location. If the default value for the hint is chosen
    * then an objects will be created next to the current one.
    *
    * This operation may return a error status in case of problems
    * during the cloning (memory management) or any inconsistency at the
    * internal structure of the current object.
    */
    CdbStatus clone( BdbRef(CdbBdbSTimeLineP<V>)& theRef,           /**< the reference onto created clone */
                     const BdbRefAny&             theHint = 0       /**< the location of the clone */
                   ) const;

private:

  /// Initialize the timeline
  /**
    * The timeline will be initialized with one interval covering the whole
    * timeline and carrying specified value.
    */
    void initialize( const V& theInitialValue );

  /// Remove specified visible interval and insert a new one
  /**
    * This method installs a new "visible" instead of the specified one.
    */
    void insertAndRemoveOne( d_ULong        begin,          /**< the interval to be removed */
                             const BdbTime& beginTime,      /**< the begin time of the new interval */
                             const BdbTime& endTime,        /**< the end   time of the new interval */
                             const V&       value           /**< the value to be set up */
                           );

  /// Remove a range of visible intervals and insert a new one
  /**
    * This method installs a new "visible" instead of a sequence of specofied ones.
    * The sequence is defined by the first and last interval, and includes any intervals
    * in between.
    */
    void insertAndRemoveMany( d_ULong        begin,         /**< the first interval to be removed */
                              d_ULong        end,           /**< the last  interval to be removed */
                              const BdbTime& beginTime,     /**< the begin time of the new interval */
                              const BdbTime& endTime,       /**< the end   time of the new interval */
                              const V&       value          /**< the value to be set up */
                            );

  /// Allocator
  /**
    * Allocate an element from a list of free ones. The method will return
    * an index of the allocated element.
    */
    d_ULong allocate( d_ULong next = 0 );

  /// Disposer
  /**
    * Return specified element back to the list of free ones.
    */
    void release( d_ULong element );

  /// Extend a list of free elements
  /**
    * This list is only extended if it's empty.
    */
    void extend_free_list( );

private:

  /// B-tree index of timeline intervals
  /**
    * This index is updated coherently with the list of intervals
    * defined below. Remember, that elements of this index are objects of
    * the above defined "B-tree Entry" class, each having the corresponding link
    * as an index in a paged v-array defined below) back to the interval.
    */
    Bdb2Ref( CdbBdbSBtreeP< BTreeEntry, BTreeEntryFCP > ) _indexRef;

  /// The actual storage for timeline intervals
  /**
    * The first element of the array (index = 0) is not used, because
    * this number is meant to simulate "null pointer".
    *
    * Initially spare elements begin from the index = 1.
    * This will also change as the tree will expand.
    */
    BdbRef( CdbBdbSPagedVarrayP< Node > ) _bufRef;

  /// An index of the first & last elements of the list

    d_ULong _first;
    d_ULong _last;

  /// An indx of the first spare element
  /**
    * These nodes form a linked list. So the first spare element is actually
    * the head of the list.
    */
    d_ULong _free;
};

/// Macros for the xplicit template instantiation.
/**
  * The macro will provide all the nessesary declarations for specified
  * type of elements (first paremeter). It will also introduce new type
  * as required by the second parameter.
  */
#define EXPLICIT_INSTANTIATE_CdbBdbSTimeLineP_1( V ) \
EXPLICIT_INSTANTIATE_CdbBdbSPagedVarrayP_1( CdbBdbSTimeLineNode< V > ); \
template class CdbBdbSTimeLineP< V >

// Template class implementation

#ifdef    BABAR_COMP_INST
#include "CdbBdbShared/CdbBdbSTimeLineP.cc"
#endif /* BABAR_COMP_INST */

#endif /* CDBBDBSHARED_TIMELINE_P_HH */

---