GListT.hh

Go to the documentation of this file.

//======================================================================
/*! \file GListT.hh
 *
 *  Include file for GListT template class.
 */
//======================================================================

#ifndef G_LIST_T_HH
#define G_LIST_T_HH

#include "GCollectionT.hh"
#include "GListIterT.hh"

//======================================================================
/*! \class GListT
 *
 *  Template class to define list of objects.
 *
 *  For the list, \ref first_item and \ref last_item allow to keep a constant
 *  algorithm speed when navigating through the list.
 *
 *  The \b current_item is an index indicating current position in the list.
 *  This is the reference position to add, insert, remove elements...
 *
 *  The \ref first_item, \ref last_item and \b current_item are defined as
 *  pointers to iterators, so that their content can be changed even in
 *  constant list object (to allow to navigate in the list, which requires
 *  to change the index)
 *
 *  See \ref gcpp_templates for more information about the behaviour of
 *  collection template classes.
 *
 *
 *  \par Adding and removing objects
 *
 *  The functions Add, Insert, Append and Prepend insert objects (either by
 *  pointer or by reference, respectively after current position, before
 *  current position, at the end of the list, at the beginning of the list.
 *
 *  Default behaviour (if no other option is selected, see gcollection
 *  namespace) is the following:
 *  - if an object is added by pointer, it is adopted by the list, and
 *    deleted when removed from the list.
 *  - if an object is added by reference, it is not deleted when removed,
 *    and the calling program may ensure that the object lives as long as it
 *    used in the list.
 *
 *  The functions Remove does what the function name obviously mean.
 *  If the object was adopted by the list, it is deleted.
 *
 *  The Take functions take an object out of the list, but do not delete
 *  it if it was adopted.
 *
 *
 *  \par Internal functions
 *
 *  The internal functions are defined to adapt the behaviour of the
 *  list to the options.
 *  This behaviour may also be sophisticated in derived classes
 *  (see GSortListT and GNamedListT).
 *
 *
 *  \image html GListT.png
 *
 */
template <class T> class GListT : public GCollectionT<T>
{
  //------------------------------------------------------------
  /*! \object_doc */
  GObject(GListT<T>)
  //------------------------------------------------------------

  protected:
    GListIterT<T> ** first_item;    ///< Iterator on first object in the list
    GListIterT<T> ** last_item;     ///< Iterator on last object in the list
    GListIterT<T> ** current_item;  ///< Iterator on current object in the list

  public:
  //------------------------------------------------------------
  //  Constructor / Destructor / Affectation
    GListT ( u_int opts = 0 );
    GListT ( const GListT<T> & list );
    GListT ( const GListT<T> & list, u_int opts );

    GListT<T> & operator = ( const GListT<T> & list );

    virtual  ~GListT ( );

  //------------------------------------------------------------
  public:
    virtual GListIterT<T> Begin ( ) const;
    virtual GListIterT<T> End   ( ) const;
    static  GListIterT<T> Null  ( );

    virtual bool          Exist        ( const T * ptr ) const;
    virtual GListIterT<T> Find         ( const T * ptr ) const;
    virtual GListIterT<T> FindNext     ( const T * ptr ) const;
    virtual GListIterT<T> FindPrevious ( const T * ptr ) const;
    virtual GListIterT<T> FindFirst    ( const T * ptr ) const;
    virtual GListIterT<T> FindLast     ( const T * ptr ) const;

    GListIterT<T> Current  ( ) const;
    GListIterT<T> Previous ( ) const;
    GListIterT<T> Next     ( ) const;
    GListIterT<T> First    ( ) const;
    GListIterT<T> Last     ( ) const;

    GListIterT<T> Goto     ( u_int n = 0 ) const;
    T &           At       ( u_int n ) const;
    int           Index    ( ) const;

  //------------------------------------------------------------
    virtual int  Move       ( int n );
    virtual bool MoveUp     ( );
    virtual bool MoveDown   ( );
    virtual bool MoveTop    ( );
    virtual bool MoveBottom ( );

  //------------------------------------------------------------
    virtual GListIterT<T> Add     ( T * obj_ptr );
    virtual GListIterT<T> Insert  ( T * obj_ptr );
    virtual GListIterT<T> Append  ( T * obj_ptr );
    virtual GListIterT<T> Prepend ( T * obj_ptr );

    virtual GListIterT<T> Add     ( T & obj_ptr );
    virtual GListIterT<T> Insert  ( T & obj_ptr );
    virtual GListIterT<T> Append  ( T & obj_ptr );
    virtual GListIterT<T> Prepend ( T & obj_ptr );

    virtual T *   Take   ( );
    virtual T *   Take   ( const T * ptr );
    virtual bool  Remove ( );
    virtual bool  Remove ( const T * ptr, bool all = true );
    virtual void  Empty  ( );

  //------------------------------------------------------------
  // internal functions
  protected:
    virtual GListIterT<T> * __Exist  ( const T * ptr, GListIterT<T> * except = NULL ) const;
    virtual GListIterT<T> * __Find   ( const T * ptr, GListIterT<T> * except = NULL ) const;
    virtual GListIterT<T>   __Add    ( T * item );
    virtual GListIterT<T>   __Insert ( T * item );
    virtual T *             __Take   ( );
    virtual void            __Swap   ( GListIterT<T> * iter );
    virtual bool            __MoveUp   ( );
    virtual bool            __MoveDown ( );

  //------------------------------------------------------------

};

//----------------------------------------------------------------------
// Inline functions
#include "icc/GListT.icc"

//======================================================================
#endif