Polaris: KeyIterator.h Source File

KeyIterator.h Go to the documentation of this file. /// /// #ifndef _KEY_ITERATOR_H #define _KEY_ITERATOR_H /// /// \class KeyIterator /// \brief /// /// \endcode /// \section DESCRIPTION DESCRIPTION /// A template for a complex iterator over a map for keys /// of type S to objects of type T where: /// /// \code /// 1. 'S' is a class with: /// /// a) <, == and << operators taking S& arguments. /// b) a copy constructor S(S &) to clone the /// input object or simple enough structure /// for the default copy constructor to work. /// /// 2. 'T' is a class derived from Listable. /// \endcode /// /// These Iterators are designed to work much like the general /// Collection Iterator: /// /// Declare an iterator: /// \code /// BaseIter Li = some_map_structure; /// \endcode /// /// --or-- /// /// \code /// BaseIter Li(some_map_structure); /// \endcode /// /// This implementation works with the reference counting /// scheme of Collections. Thus, it is not possible for an /// element of a Collection to be deleted out from under /// an iterator. It is possible, however, for the current() /// node to suddenly become invalid--that is for the object /// suddenly being made inaccessable, turning the current /// node into a ghost-node. It is illegal to try to access /// the current node if it is a ghost-node. This can be /// checked by calling current_valid(). /// /// Ghost nodes can only be encountered in live structures by /// loosing ownership of the current node, but they are more /// frequent in reference structures. If an object is /// deleted from a live structure, references to it will /// remain. These, too, become "ghost-nodes". /// By default, ghost-nodes are skipped over by the iterator. /// For example, the Iterator forms described above skip /// over ghost-nodes. However, if an iterator is declared as /// the default, it is still possible to check for ghost nodes /// within the iteration space /// by calling next() and prev() using the STOP_AT_GHOSTS option: /// next(STOP_AT_GHOSTS) --or-- prev(STOP_AT_GHOSTS). /// /// Also, it is possible to declare an iterator which will /// always stop on the ghost nodes. This is done by passing /// a positive flag in the constructor after the name of the /// list. This can be done as follows: /// /// \code /// BaseIter Li(some_collection, STOP_AT_GHOSTS) /// (iterate over whole list including ghosts) /// \endcode /// /// In these above forms, the increment and decrement will stop /// on ghost nodes. next() and prev() will still stop on ghost- /// nodes only if they have the STOP_AT_GHOSTS flag. The general rule is /// that the ++ and -- operators behave according to how the /// Iterator was declared, while next and prev behave according to /// whether they have an argument. /// /// #include "../macros.h" #include "../String.h" /// #include "BaseIter.h" #include "TypedBaseMap.h" #include "TypedBaseRefMap.h" /// #include "ghost_enum.h" /// template <class S, class T> class KeyIterator { private: BaseIter _iter; public: INLINE T &current_data(); ///< Return data of current element. Cause an error ///< if valid() == 0 INLINE const S &current_key() const; INLINE S &current_key(); ///< Return key of current element. Cause an error ///< if valid() == 0 INLINE void reset(); ///< Go back to the beginning of the iteration space INLINE void set_to_last(); ///< Set the iterator to the last value ///< Useful if you need to iterator backwards INLINE void next(iter_option option = STOP_ON_GHOSTS); ///< go to the next valid element, or if STOP_AT_GHOSTS ///< to the next element INLINE void operator++ (); ///< go to next element according to how KeyIterator was ///< defined INLINE void prev(iter_option option = STOP_ON_GHOSTS); ///< go to the previous valid element, or if STOP_AT_GHOSTS ///< to the previous element INLINE void operator-- (); ///< go to next element according to how KeyIterator was ///< defined INLINE Boolean end(); ///< Return true if there no more Nodes to iterate on INLINE Boolean valid(); ///< Equivalent to NOT end() INLINE Boolean current_valid() const; ///< Return true iff valid() would return 1 AND the current node is ///< still valid. This function will return 0 even if valid() ///< returns 1 if the current node is invalid, which will happen if ///< the current node has become a ghost node by being deleted from ///< its Collection. ///< In the event that the current node is invalid, it is ///< a checked run-time error to make a call to current(). ///< However, the valid() method still returns 1 since ///< the end of the iteration space has not yet been reached. ///< Also, the operator++/--/prev()/next() methods ///< will all work correctly and properly find the next element in ///< the iteration space. ///< If there is any chance that the current element pointed to ///< by a BaseIter can be deleted, both valid() and ///< current_valid() must return 1 for a call to current() to be ///< acceptable. INLINE Boolean current_invalid() const; ///< Equivalent to ( ! current_valid() ) INLINE KeyIterator(const KeyIterator<S, T> &other); ///< This method copies the entire state (including current element) ///< of the iterator. If you don't like this, then immediately follow ///< this constructor with a call to reset() INLINE KeyIterator<S, T> & operator = (const KeyIterator<S, T> &other); ///< This method copies the entire state (including current element) ///< of the iterator. If you don't like this, then immediately follow ///< this constructor with a call to reset() INLINE KeyIterator(const TypedBaseMap<S, T> &map, iter_option option = STOP_ON_GHOSTS); ///< Constructor -- note: The iterator does not contain a copy of ///< the map -- it just contains some pointers into it, ///< therefore the map may not have items deleted or ///< inserted during the lifetime of this iterator. INLINE KeyIterator<S, T> & operator = (const TypedBaseMap<S, T> &map); INLINE KeyIterator(const TypedBaseRefMap<S, T> &map, iter_option option = STOP_ON_GHOSTS); ///< Constructor -- note: The iterator does not contain a copy of ///< the map -- it just contains some pointers into it, ///< therefore the map may not have items deleted or ///< inserted during the lifetime of this iterator. INLINE KeyIterator<S, T> & operator = (const TypedBaseRefMap<S, T> &map); INLINE ~KeyIterator(); }; ///< INLINE functions template <class S, class T> INLINE T & KeyIterator<S, T>::current_data() { return (T &) _iter.current(); } template <class S, class T> INLINE const S & KeyIterator<S, T>::current_key() const { const S &key = *((S *) _iter.current_key()); return key; } template <class S, class T> INLINE S & KeyIterator<S, T>::current_key() { S &key = *((S *) _iter.current_key()); return key; } template <class S, class T> INLINE void KeyIterator<S, T>::reset() { _iter.reset(); } template <class S, class T> INLINE void KeyIterator<S, T>::set_to_last() { _iter.set_to_last(); } template <class S, class T> INLINE void KeyIterator<S, T>::next(iter_option option GIV(STOP_ON_GHOSTS)) { _iter.next(option); } template <class S, class T> INLINE void KeyIterator<S, T>::operator++ () { _iter.next(_iter.skip_ghosts() ? SKIP_GHOSTS : STOP_ON_GHOSTS); } template <class S, class T> INLINE void KeyIterator<S, T>::prev(iter_option option GIV(STOP_ON_GHOSTS)) { _iter.prev(option); } template <class S, class T> INLINE void KeyIterator<S, T>::operator-- () { _iter.prev(_iter.skip_ghosts() ? SKIP_GHOSTS : STOP_ON_GHOSTS); } template <class S, class T> INLINE Boolean KeyIterator<S, T>::end() { return _iter.end(); } template <class S, class T> INLINE Boolean KeyIterator<S, T>::valid() { return _iter.valid(); } template <class S, class T> INLINE Boolean KeyIterator<S, T>::current_valid() const { return _iter.current_valid(); } template <class S, class T> INLINE Boolean KeyIterator<S, T>::current_invalid() const { return _iter.current_invalid(); } template <class S, class T> INLINE KeyIterator<S, T>::KeyIterator(const KeyIterator<S, T> &other) : _iter(other._iter) { ///< nothing else to do } template <class S, class T> INLINE KeyIterator<S, T> & KeyIterator<S,T>::operator = (const KeyIterator<S, T> &other) { _iter = other._iter; return *this; } template <class S, class T> INLINE KeyIterator<S, T>::KeyIterator(const TypedBaseMap<S, T> &map, iter_option option GIV(STOP_ON_GHOSTS)) : _iter(map._base_data_list(), option) { ///< nothing to do } template <class S, class T> INLINE KeyIterator<S, T> & KeyIterator<S, T>::operator = (const TypedBaseMap<S, T> &map) { _iter = map._base_data_list(); return *this; } template <class S, class T> INLINE KeyIterator<S, T>::KeyIterator(const TypedBaseRefMap<S, T> &map, iter_option option GIV(STOP_ON_GHOSTS)) : _iter(map._base_data_list(), option) { ///< nothing to do } template <class S, class T> INLINE KeyIterator<S, T> & KeyIterator<S, T>::operator = (const TypedBaseRefMap<S, T> &map) { _iter = map._base_data_list(); return *this; } template <class S, class T> INLINE KeyIterator<S, T>::~KeyIterator() { ///< nothing to do } #endif

© 1995-2005 University of Illinois, Urbana-Champaign. All rights reserved.  Fri Mar 25 23:05:57 2005