--- /dev/null
+#ifndef STLPLUS_SAFE_ITERATOR\r
+#define STLPLUS_SAFE_ITERATOR\r
+////////////////////////////////////////////////////////////////////////////////\r
+\r
+// Author: Andy Rushton\r
+// Copyright: (c) Southampton University 1999-2004\r
+// (c) Andy Rushton 2004-2009\r
+// License: BSD License, see ../docs/license.html\r
+\r
+// The STLplus safe_iterator superclasses. This implements the STLplus safe\r
+// iterator principles. Data structures can then be built using subclasses\r
+// of safe_iterator for their iterator objects and they will inherit the\r
+// safe iterator behaviour.\r
+\r
+// The data structure must contain a master iterator for each node in the\r
+// structure. When an iterator is returned to the user, it must be created\r
+// by the master iterator. When a node is removed from the data structure,\r
+// its master iterator is destroyed. This sets all iterators pointing to the\r
+// master iterator to end iterators.\r
+\r
+////////////////////////////////////////////////////////////////////////////////\r
+#include "containers_fixes.hpp"\r
+#include "exceptions.hpp"\r
+\r
+namespace stlplus\r
+{\r
+\r
+ ////////////////////////////////////////////////////////////////////////////////\r
+ // internals\r
+\r
+ template<typename O, typename N>\r
+ class safe_iterator_body;\r
+\r
+ template<typename O, typename N>\r
+ class safe_iterator;\r
+\r
+ ////////////////////////////////////////////////////////////////////////////////\r
+ // Master Iterator\r
+ // Create one of these in each node in the data structure\r
+ // Generate iterators by obtaining a safe-iterator object from the master iterator\r
+ ////////////////////////////////////////////////////////////////////////////////\r
+\r
+ template<typename O, typename N>\r
+ class master_iterator\r
+ {\r
+ public:\r
+\r
+ // construct a valid master iterator connected to the node\r
+ master_iterator(const O* owner, N* node) throw();\r
+\r
+ // destructor - disconnects all iterators from the node\r
+ ~master_iterator(void) throw();\r
+\r
+ // dereference\r
+ N* node(void) const throw();\r
+ const O* owner(void) const throw();\r
+\r
+ // when you move a node from one owner to another, call this on the node's master iterator\r
+ // this effectively moves all other iterators to the node so that they are owned by the new owner too\r
+ void change_owner(const O* owner) throw();\r
+\r
+ friend class safe_iterator<O,N>;\r
+ private:\r
+ master_iterator(const master_iterator&) throw();\r
+ master_iterator& operator=(const master_iterator&) throw();\r
+ safe_iterator_body<O,N>* m_body;\r
+ };\r
+\r
+ ////////////////////////////////////////////////////////////////////////////////\r
+ // Safe Iterator\r
+ ////////////////////////////////////////////////////////////////////////////////\r
+\r
+ template<typename O, typename N>\r
+ class safe_iterator\r
+ {\r
+ public:\r
+\r
+ // construct a null iterator\r
+ safe_iterator(void) throw();\r
+\r
+ // construct a valid iterator by aliasing from the owner node's master iterator\r
+ safe_iterator(const master_iterator<O,N>&) throw();\r
+\r
+ // copy constructor does aliasing\r
+ safe_iterator(const safe_iterator<O,N>&) throw();\r
+\r
+ // alias an iterator by assignment\r
+ safe_iterator<O,N>& operator=(const safe_iterator<O,N>&) throw();\r
+\r
+ // destructor\r
+ ~safe_iterator(void) throw();\r
+\r
+ // reassignment to another node used in increment/decrement operation\r
+ void set(const master_iterator<O,N>&) throw();\r
+\r
+ // dereference\r
+ N* node(void) const throw();\r
+ const O* owner(void) const throw();\r
+\r
+ // change to a null iterator - i.e. one that does not belong to any object\r
+ // this does not affect any other iterators pointing to the same node\r
+ void set_null(void) throw();\r
+\r
+ ////////////////////////////////////////////////////////////////////////////////\r
+ // operations for clients that do not have a master end iterator\r
+ // alternatively, have a master end iterator as part of the container\r
+ // and call constructor(master_end) or set(master_end)\r
+\r
+ // construct an end iterator\r
+ safe_iterator(const O* owner) throw();\r
+\r
+ // change to an end iterator - e.g. as a result of incrementing off the end\r
+ void set_end(void) throw();\r
+\r
+ ////////////////////////////////////////////////////////////////////////////////\r
+ // tests\r
+\r
+ // comparison\r
+ bool equal(const safe_iterator<O,N>& right) const throw();\r
+ int compare(const safe_iterator<O,N>& right) const throw();\r
+\r
+ // a null iterator is one that has not been initialised with a value yet\r
+ // i.e. you just declared it but didn't assign to it\r
+ bool null(void) const throw();\r
+\r
+ // an end iterator is one that points to the end element of the list of nodes\r
+ // in STL conventions this is one past the last valid element and must not be dereferenced\r
+ bool end(void) const throw();\r
+\r
+ // a valid iterator is one that can be dereferenced\r
+ // i.e. non-null and non-end\r
+ bool valid(void) const throw();\r
+\r
+ // check the rules for a valid iterator that can be dereferenced\r
+ // optionally also check that the iterator is owned by the owner\r
+ void assert_valid(void) const throw(null_dereference,end_dereference);\r
+ void assert_valid(const O* owner) const throw(wrong_object,null_dereference,end_dereference);\r
+ // assert the rules for a non-null iterator - i.e. valid or end, values that occur in increment operations\r
+ void assert_non_null(void) const throw(null_dereference);\r
+ // assert that this iterator is owned by this container\r
+ void assert_owner(const O* owner) const throw(wrong_object);\r
+\r
+ ////////////////////////////////////////////////////////////////////////////////\r
+\r
+ friend class master_iterator<O,N>;\r
+ private:\r
+ safe_iterator_body<O,N>* m_body;\r
+ };\r
+\r
+ ////////////////////////////////////////////////////////////////////////////////\r
+\r
+} // end namespace stlplus\r
+\r
+#include "safe_iterator.tpp"\r
+#endif\r