user/wxLayout/kbList.h

   1 /*-*- c++ -*-********************************************************
   2  * kbList.h : a double linked list                                  *
   3  *                                                                  *
   4  * (C) 1998 by Karsten Ballüder (Ballueder@usa.net)                 *
   5  *                                                                  *
   6  * $Id$
   7  * $Log$
   8  * Revision 1.1  1998/06/29 12:44:36  KB
   9  * Added my wxWindows based layout engine to the repository.
  10  * It arranges text and graphics for display on a wxDC.
  11  * This code is licensed under the LGPL.
  12  *
  13  * Revision 1.6  1998/06/27 20:06:10  KB
  14  * Added my layout code.
  15  *
  16  *******************************************************************/
  17
  18 #ifndef   KBLIST_H
  19 #   define   KBLIST_H
  20
  21 #ifdef __GNUG__
  22 #   pragma interface "kbList.h"
  23 #endif
  24
  25 #ifndef   NULL
  26 #   define   NULL   0
  27 #endif
  28
  29 /**@name Double linked list implementation. */
  30 //@{
  31
  32 /** kbListNode is a class used by kbList. It represents a single
  33     element in the list. It is not intended for general use outside
  34     kbList functions.
  35 */
  36 struct kbListNode
  37 {
  38    /// pointer to next node or NULL
  39    struct kbListNode *next;
  40    /// pointer to previous node or NULL
  41    struct kbListNode *prev;
  42    /// pointer to the actual data
  43    void *element;
  44    /** Constructor - it automatically links the node into the list, if
  45        the iprev, inext parameters are given.
  46        @param ielement pointer to the data for this node (i.e. the data itself)
  47        @param iprev if not NULL, use this as previous element in list
  48        @param inext if not NULL, use this as next element in list
  49    */
  50    kbListNode( void *ielement,
  51                kbListNode *iprev = NULL,
  52                kbListNode *inext = NULL);
  53    /// Destructor.
  54    ~kbListNode();
  55 };
  56
  57 /** The main list class, handling void pointers as data.
  58   */
  59
  60 class kbList
  61 {
  62 public:
  63    /// An iterator class for kbList, just like for the STL classes.
  64    class iterator
  65    {
  66    protected:
  67       /// the node to which this iterator points
  68       kbListNode *node;
  69       friend class kbList;
  70          public:
  71       /** Constructor.
  72           @param n if not NULL, the node to which to point
  73       */
  74       iterator(kbListNode *n = NULL);
  75       /** Dereference operator.
  76           @return the data pointer of the node belonging to this
  77           iterator
  78       */
  79       void * operator*();
  80
  81       /** Increment operator - prefix, goes to next node in list.
  82           @return itself
  83       */
  84       iterator & operator++();
  85
  86       /** Decrement operator - prefix, goes to previous node in list.
  87           @return itself
  88       */
  89       iterator & operator--();
  90
  91       /** Increment operator - prefix, goes to next node in list.
  92           @return itself
  93       */
  94       iterator & operator++(int); //postfix
  95
  96       /** Decrement operator - prefix, goes to previous node in list.
  97           @return itself
  98       */
  99       iterator & operator--(int); //postfix
 100
 101       /** Comparison operator.
 102           @return true if not equal.
 103       */
 104       bool operator !=(iterator const &) const;
 105
 106       /* Comparison operator.
 107          @return true if equal
 108       */
 109       bool operator ==(iterator const &) const;
 110
 111       /** Returns a pointer to the node associated with this iterator.
 112           This function is not for general use and should be
 113           protected. However, if protected, it cannot be called from
 114           derived classes' iterators. (Is this a bug in gcc/egcs?)
 115           @return the node pointer
 116       */
 117       inline kbListNode * Node(void) const
 118          { return node; }
 119    };
 120
 121    /** Constructor.
 122        @param ownsEntriesFlag if true, the list owns the entries and
 123        will issue a delete on each of them when deleting them. If
 124        false, the entries themselves will not get deleted. Do not use
 125        this with array types!
 126    */
 127    kbList(bool ownsEntriesFlag = true);
 128
 129    /** Destructor.
 130        If entries are owned, they will all get deleted from here.
 131    */
 132    ~kbList();
 133
 134    /** Tell list whether it owns objects. If owned, they can be
 135        deleted by list. See the constructor for more details.
 136        @param ownsflag if true, list will own entries
 137    */
 138    void ownsObjects(bool ownsflag = true)
 139       { ownsEntries = ownsflag; }
 140
 141    /** Query whether list owns entries.
 142        @return true if list owns entries
 143    */
 144    bool ownsObjects(void)
 145       { return ownsEntries; }
 146
 147    /** Add an entry at the end of the list.
 148        @param element pointer to data
 149    */
 150    void push_back(void *element);
 151
 152    /** Add an entry at the head of the list.
 153        @param element pointer to data
 154    */
 155    void push_front(void *element);
 156
 157    /** Get element from end of the list and delete it.
 158        NOTE: In this case the element's data will not get deleted by
 159        the list. It is the responsibility of the caller to free it.
 160        @return the element data
 161    */
 162    void *pop_back(void);
 163
 164    /** Get element from head of the list and delete it.
 165        NOTE: In this case the element's data will not get deleted by
 166        the list. It is the responsibility of the caller to free it.
 167        @return the element data
 168    */
 169    void *pop_front(void);
 170
 171    /** Insert an element into the list.
 172        @param i an iterator pointing to the element, before which the new one should be inserted
 173        @param element the element data
 174    */
 175    void insert(iterator & i, void *element);
 176
 177    /** Erase an element, move iterator to following element.
 178        @param i iterator pointing to the element to be deleted
 179    */
 180    void erase(iterator & i);
 181
 182    /* Get head of list.
 183       @return iterator pointing to head of list
 184    */
 185    iterator begin(void) const;
 186
 187    /* Get end of list.
 188    @return iterator pointing after the end of the list. This is an
 189    invalid iterator which cannot be dereferenced or decremented. It is
 190    only of use in comparisons. NOTE: this is different from STL!
 191    @see tail
 192    */
 193    iterator end(void) const;
 194
 195    /* Get last element in list.
 196       @return iterator pointing to the last element in the list.
 197       @see end
 198    */
 199    iterator tail(void) const;
 200
 201    /* Get the number of elements in the list.
 202       @return number of elements in the list
 203    */
 204    unsigned size(void) const;
 205
 206    /* Query whether list is empty.
 207       @return true if list is empty
 208    */
 209    bool empty(void) const
 210       { return first == NULL ; }
 211
 212 private:
 213    /// if true, list owns entries
 214    bool        ownsEntries;
 215    /// pointer to first element in list
 216    kbListNode *first;
 217    /// pointer to last element in list
 218    kbListNode *last;
 219
 220    /// forbid copy construction
 221    kbList(kbList const &foo);
 222    /// forbid assignments
 223    kbList& operator=(const kbList& foo);
 224 };
 225
 226 /// just for backward compatibility, will be removed soon
 227 typedef kbList::iterator kbListIterator;
 228 /// cast an iterator to a pointer, compatibility only to be removed
 229 #define   kbListICast(type, iterator)   ((type *)*iterator)
 230 /// cast an iterator to a const pointer, compatibility only to be removed
 231 #define   kbListIcCast(type, iterator)   ((type const *)*iterator)
 232
 233 /** Macro to define a kbList with a given name, having elements of
 234     pointer to the given type. I.e. KBLIST_DEFINE(Int,int) would
 235     create a kbListInt type holding int pointers.
 236 */
 237 #define   KBLIST_DEFINE(name,type)   \
 238 class name : public kbList \
 239 { \
 240 public: \
 241    class iterator : public kbList::iterator \
 242    { \
 243    protected: \
 244       inline iterator(kbList::iterator const & i) \
 245          { node = i.Node(); } \
 246       friend class name; \
 247    public: \
 248       inline iterator(kbListNode *n = NULL) \
 249          : kbList::iterator(n) {} \
 250       inline type * operator*() \
 251          /* the cast is needed for MS VC++ 5.0 */ \
 252          { return (type *)((kbList::iterator *)this)->operator*() ; } \
 253    }; \
 254    inline name(bool ownsEntriesFlag = true) \
 255       : kbList(ownsEntriesFlag) {} \
 256    \
 257    inline void push_back(type *element) \
 258       { kbList::push_back((void *)element); } \
 259    \
 260    inline void push_front(type *element) \
 261       { kbList::push_front((void *)element); } \
 262    \
 263    inline type *pop_back(void) \
 264       { return (type *) kbList::pop_back(); } \
 265    \
 266    inline type *pop_front(void) \
 267       { return (type *) kbList::pop_front(); } \
 268    \
 269    inline void insert(iterator & i, type *element) \
 270       { kbList::insert(i, (void *) element); } \
 271    \
 272    void erase(iterator & i) \
 273       { kbList::erase(i); } \
 274    \
 275    inline iterator begin(void) const \
 276       { return kbList::begin(); } \
 277    \
 278    inline iterator end(void) const \
 279       { return kbList::end(); } \
 280    \
 281    inline iterator tail(void) const \
 282       { return kbList::tail(); } \
 283 }
 284
 285 #ifdef   MCONFIG_H
 286 /// define the most commonly used list type once:
 287 KBLIST_DEFINE(kbStringList, String);
 288 #endif
 289
 290 #endif // KBLIST_H