Dogcows Code - chaz/yoink/blob - src/Moof/stlplus/safe_iterator.hpp

   1 #ifndef STLPLUS_SAFE_ITERATOR
   2 #define STLPLUS_SAFE_ITERATOR
   3 ////////////////////////////////////////////////////////////////////////////////
   4
   5 //   Author:    Andy Rushton
   6 //   Copyright: (c) Southampton University 1999-2004
   7 //              (c) Andy Rushton           2004-2009
   8 //   License:   BSD License, see ../docs/license.html
   9
  10 //   The STLplus safe_iterator superclasses. This implements the STLplus safe
  11 //   iterator principles. Data structures can then be built using subclasses
  12 //   of safe_iterator for their iterator objects and they will inherit the
  13 //   safe iterator behaviour.
  14
  15 //   The data structure must contain a master iterator for each node in the
  16 //   structure. When an iterator is returned to the user, it must be created
  17 //   by the master iterator. When a node is removed from the data structure,
  18 //   its master iterator is destroyed. This sets all iterators pointing to the
  19 //   master iterator to end iterators.
  20
  21 ////////////////////////////////////////////////////////////////////////////////
  22 #include "containers_fixes.hpp"
  23 #include "exceptions.hpp"
  24
  25 namespace stlplus
  26 {
  27
  28   ////////////////////////////////////////////////////////////////////////////////
  29   // internals
  30
  31   template<typename O, typename N>
  32   class safe_iterator_body;
  33
  34   template<typename O, typename N>
  35   class safe_iterator;
  36
  37   ////////////////////////////////////////////////////////////////////////////////
  38   // Master Iterator
  39   // Create one of these in each node in the data structure
  40   // Generate iterators by obtaining a safe-iterator object from the master iterator
  41   ////////////////////////////////////////////////////////////////////////////////
  42
  43   template<typename O, typename N>
  44   class master_iterator
  45   {
  46   public:
  47
  48     // construct a valid master iterator connected to the node
  49     master_iterator(const O* owner, N* node) throw();
  50
  51     // destructor - disconnects all iterators from the node
  52     ~master_iterator(void) throw();
  53
  54     // dereference
  55     N* node(void) const throw();
  56     const O* owner(void) const throw();
  57
  58     // when you move a node from one owner to another, call this on the node's master iterator
  59     // this effectively moves all other iterators to the node so that they are owned by the new owner too
  60     void change_owner(const O* owner) throw();
  61
  62     friend class safe_iterator<O,N>;
  63   private:
  64     master_iterator(const master_iterator&) throw();
  65     master_iterator& operator=(const master_iterator&) throw();
  66     safe_iterator_body<O,N>* m_body;
  67   };
  68
  69   ////////////////////////////////////////////////////////////////////////////////
  70   // Safe Iterator
  71   ////////////////////////////////////////////////////////////////////////////////
  72
  73   template<typename O, typename N>
  74   class safe_iterator
  75   {
  76   public:
  77
  78     // construct a null iterator
  79     safe_iterator(void) throw();
  80
  81     // construct a valid iterator by aliasing from the owner node's master iterator
  82     safe_iterator(const master_iterator<O,N>&) throw();
  83
  84     // copy constructor does aliasing
  85     safe_iterator(const safe_iterator<O,N>&) throw();
  86
  87     // alias an iterator by assignment
  88     safe_iterator<O,N>& operator=(const safe_iterator<O,N>&) throw();
  89
  90     // destructor
  91     ~safe_iterator(void) throw();
  92
  93     // reassignment to another node used in increment/decrement operation
  94     void set(const master_iterator<O,N>&) throw();
  95
  96     // dereference
  97     N* node(void) const throw();
  98     const O* owner(void) const throw();
  99
 100     // change to a null iterator - i.e. one that does not belong to any object
 101     // this does not affect any other iterators pointing to the same node
 102     void set_null(void) throw();
 103
 104     ////////////////////////////////////////////////////////////////////////////////
 105     // operations for clients that do not have a master end iterator
 106     // alternatively, have a master end iterator as part of the container
 107     // and call constructor(master_end) or set(master_end)
 108
 109     // construct an end iterator
 110     safe_iterator(const O* owner) throw();
 111
 112     // change to an end iterator - e.g. as a result of incrementing off the end
 113     void set_end(void) throw();
 114
 115     ////////////////////////////////////////////////////////////////////////////////
 116     // tests
 117
 118     // comparison
 119     bool equal(const safe_iterator<O,N>& right) const throw();
 120     int compare(const safe_iterator<O,N>& right) const throw();
 121
 122     // a null iterator is one that has not been initialised with a value yet
 123     // i.e. you just declared it but didn't assign to it
 124     bool null(void) const throw();
 125
 126     // an end iterator is one that points to the end element of the list of nodes
 127     // in STL conventions this is one past the last valid element and must not be dereferenced
 128     bool end(void) const throw();
 129
 130     // a valid iterator is one that can be dereferenced
 131     // i.e. non-null and non-end
 132     bool valid(void) const throw();
 133
 134     // check the rules for a valid iterator that can be dereferenced
 135     // optionally also check that the iterator is owned by the owner
 136     void assert_valid(void) const throw(null_dereference,end_dereference);
 137     void assert_valid(const O* owner) const throw(wrong_object,null_dereference,end_dereference);
 138     // assert the rules for a non-null iterator - i.e. valid or end, values that occur in increment operations
 139     void assert_non_null(void) const throw(null_dereference);
 140     // assert that this iterator is owned by this container
 141     void assert_owner(const O* owner) const throw(wrong_object);
 142
 143     ////////////////////////////////////////////////////////////////////////////////
 144
 145     friend class master_iterator<O,N>;
 146   private:
 147     safe_iterator_body<O,N>* m_body;
 148   };
 149
 150   ////////////////////////////////////////////////////////////////////////////////
 151
 152 } // end namespace stlplus
 153
 154 #include "safe_iterator.tpp"
 155 #endif