]>
Dogcows Code - chaz/yoink/blob - Moof/stlplus/safe_iterator.hpp
1 #ifndef STLPLUS_SAFE_ITERATOR
2 #define STLPLUS_SAFE_ITERATOR
3 ////////////////////////////////////////////////////////////////////////////////
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
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.
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.
21 ////////////////////////////////////////////////////////////////////////////////
22 #include "containers_fixes.hpp"
23 #include "exceptions.hpp"
28 ////////////////////////////////////////////////////////////////////////////////
31 template<typename O
, typename N
>
32 class safe_iterator_body
;
34 template<typename O
, typename N
>
37 ////////////////////////////////////////////////////////////////////////////////
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 ////////////////////////////////////////////////////////////////////////////////
43 template<typename O
, typename N
>
48 // construct a valid master iterator connected to the node
49 master_iterator(const O
* owner
, N
* node
) throw();
51 // destructor - disconnects all iterators from the node
52 ~master_iterator(void) throw();
55 N
* node(void) const throw();
56 const O
* owner(void) const throw();
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();
62 friend class safe_iterator
<O
,N
>;
64 master_iterator(const master_iterator
&) throw();
65 master_iterator
& operator=(const master_iterator
&) throw();
66 safe_iterator_body
<O
,N
>* m_body
;
69 ////////////////////////////////////////////////////////////////////////////////
71 ////////////////////////////////////////////////////////////////////////////////
73 template<typename O
, typename N
>
78 // construct a null iterator
79 safe_iterator(void) throw();
81 // construct a valid iterator by aliasing from the owner node's master iterator
82 safe_iterator(const master_iterator
<O
,N
>&) throw();
84 // copy constructor does aliasing
85 safe_iterator(const safe_iterator
<O
,N
>&) throw();
87 // alias an iterator by assignment
88 safe_iterator
<O
,N
>& operator=(const safe_iterator
<O
,N
>&) throw();
91 ~safe_iterator(void) throw();
93 // reassignment to another node used in increment/decrement operation
94 void set(const master_iterator
<O
,N
>&) throw();
97 N
* node(void) const throw();
98 const O
* owner(void) const throw();
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();
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)
109 // construct an end iterator
110 safe_iterator(const O
* owner
) throw();
112 // change to an end iterator - e.g. as a result of incrementing off the end
113 void set_end(void) throw();
115 ////////////////////////////////////////////////////////////////////////////////
119 bool equal(const safe_iterator
<O
,N
>& right
) const throw();
120 int compare(const safe_iterator
<O
,N
>& right
) const throw();
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();
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();
130 // a valid iterator is one that can be dereferenced
131 // i.e. non-null and non-end
132 bool valid(void) const throw();
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
);
143 ////////////////////////////////////////////////////////////////////////////////
145 friend class master_iterator
<O
,N
>;
147 safe_iterator_body
<O
,N
>* m_body
;
150 ////////////////////////////////////////////////////////////////////////////////
152 } // end namespace stlplus
154 #include "safe_iterator.tpp"
This page took 0.040363 seconds and 4 git commands to generate.