Polaris: RefList.h Source File

RefList.h Go to the documentation of this file. /// /// #ifndef _REF_LIST_H #define _REF_LIST_H /// /// \class RefList /// \brief template for types derived from Listable /// \defgroup Polaris /// \ingroup Polaris /// C++ VDL /// \see RefList.h /// /// \endcode /// \section Overview Overview /// The RefList class creates a templatized linked-list object for /// references to objects which must be derived from Listable. Since the /// RefList is built from Collection it works with Iterators. An object /// must be in a live structure, like List, before it can be used in a /// reference structure, like RefList. /// /// \endcode /// \section DESCRIPTION DESCRIPTION /// All objects in a RefList must exist in some other /// live structure. If this is not the case, an error /// is raised upon insertion. If the live object is /// removed from its owner-structure, references to it /// within the RefList will become invalid. /// /// RefList is subject to the restrictions of the /// Iterators--that is, when a wrapper is taken out of /// the RefList, only the pointers of the neighboring /// wrappers are changed--the out-going pointers are /// maintained (ie, _unlink_wrapper is called). /// /// It is possible to have more than one reference to a /// single object within a RefList. This could cause /// confusion in terms of how the methods behave. If an /// object (it's address) is used as a reference point for /// a method and more than one exist, the first one /// encountered will be operated on. /// /// \endcode /// \section Hierarchy Hierarchy Structure /// RefList does not inherit from Collection, instead it contains /// a BaseRefList (which does) and inherits from TypedCollection /// (which provides an interface with the Iterators). /// The hierarchy can be represented by: /// /// \code /// --- : inherited from relationship /// -c- : contained in relationship /// /// /// Collection /// / \ // /// / \ // /// BaseList Listable BaseRefList /// | \ | / | /// | \ | / | /// | c TypedCollection c | /// | \ / \ / | /// | \ / \ / | /// | LIST RefList | /// | Set RefSet | /// c c /// | Listable | /// | | | /// | | | /// | BaseMapRoot | /// | / \ | /// | / \ | /// BaseMap BaseRefMap /// | | /// | | /// TypedBaseMap TypedBaseRefMap /// / \ / \ // /// / \ / \ // /// ProtoDatabase ProtoMap ProtoRefMap ProtoRefDatabase /// / \ | | | | | \ // /// / \ | | | | | \ // /// Database KeyDatabase Map KeyMap RefMap KeyMap RefDatabase RefKeyDatabase /// \endcode /// /// \endcode /// \section Bugs Bugs /// Currently, RefLists are not equipped to be static. /// /// \endcode /// \section See See Also /// Collection, Listable, RefWrapper, Iterator, TypedCollection, Zombie, /// BaseRefList, RefSet /// /// #include <stream.h> /// #include "BaseRefList.h" #include "TypedCollection.h" /// template <class T> class RefList : public TypedCollection<T> { friend class Iterator <T>; friend class Mutator <T>; ///< gcc-2.96 need the stupid "<>" pair ///< friend ostream & operator << (ostream & o, const RefList<T> &l); friend ostream & operator << <> (ostream & o, const RefList<T> &l); protected: BaseRefList _list; virtual INLINE const Collection & _base_collection() const; virtual INLINE Collection & _base_collection(); public: INLINE RefList(); INLINE RefList(const RefList<T >&l); virtual INLINE ~RefList(); INLINE int entries() const; INLINE const T &operator[] (int sub) const; INLINE T &operator[] (int sub); ///< Implements the subscript operator (indexed from 0). ///< If the subth element is not valid, an error is ///< raised. ///< Should be used for random access only. INLINE void print(ostream & out, char *sep) const; ///< print list to out with 'sep' sepperating each element INLINE void modify(int loc, T &el); ///< change the reference at loc to a reference to el. INLINE void ins(const T &new_element, int loc); ///< Insert new_element at location loc, where 0 <= loc < entries(). INLINE T & grab(); ///< Remove a node and returns it's reference. INLINE T & grab(T &el); ///< Remove a node and returns it's reference. INLINE T & grab(int loc); ///< Remove a node and returns it's reference. INLINE void del(T &el); ///< Delete node 'el'. el MUST be in the list (this is not ///< necessarily checked). INLINE void del(T &el, int loc); ///< Delete first occurence of node 'el' at or beyond locth position. ///< el MUST be in the list (this is not necessarily checked). INLINE void del(int loc); ///< Random Access Delete. ///< Delete the Node in position loc where 0 <= loc < entries()-1. INLINE Boolean member(const T &el) const; ///< Check to see if node 'el' is a member of the RefList. Return ///< 0 if the element was not found, else return 1. INLINE int index(const T &el) const; ///< Check to see if node 'el' is a member of the RefList. Return ///< -1 if the element was not found, else return the index of the element. INLINE Boolean valid(int loc) const; ///< Check to see if the locth element is valid. INLINE Boolean valid(const T &el) const; ///< Check to see if the first occurence of T in the RefList is valid. INLINE void ins_first(const T &new_element); ///< Prepend new_element to the beginning of the list. INLINE void ins_last(const T &new_element); ///< Append new_element to the end of the list INLINE void ins_before(const T &new_element, const T &ref); ///< Insert new_element before the reference element 'ref' ///< (if ref == 0, insert at END of list). ///< ref MUST be in the list (this is not necessarily ///< checked). INLINE void ins_after(const T &new_element, const T &ref); ///< Insert new_element after the reference element 'ref' ///< (if ref == 0, insert at BEGINNING of list). ///< ref MUST be in the list (this is not necessarily ///< checked). INLINE void clear(); ///< Delete the entire list. INLINE RefList<T >&operator = (const RefList<T >&l); ///< Copy operator copies all the valid elements of a RefList. INLINE int structures_OK() const; ///< Check the structure of the data for errors or inconsistency. ///< Return 0 and print error message if problems found, otherwise ///< return 1 without message. INLINE Listable *listable_clone() const; ///< Needed for Listable class. INLINE void print(ostream &o) const; ///< Needed for Listable class. }; ///< implementation template <class T> INLINE RefList<T>::RefList() { ///< nothing to do } template <class T> INLINE RefList<T>::RefList(const RefList<T >&l) { _list = l._list; } template <class T> INLINE RefList<T>::~RefList() { ///< nothing to do } template <class T> INLINE int RefList<T>::entries() const { return _list.entries(); } template <class T> INLINE const T & RefList<T>::operator[] (int sub) const { return (const T &) _list[sub]; } template <class T> INLINE T & RefList<T>::operator[] (int sub) { return (T &) _list[sub]; } template <class T> INLINE void RefList<T>::print(ostream & out, char *sep) const { _list.print(out, sep); } template <class T> INLINE void RefList<T>::modify(int loc, T &el) { _list.modify( loc, el ); } template <class T> INLINE void RefList<T>::ins(const T &new_element, int loc) { _list.ins( new_element, loc ); } template <class T> INLINE void RefList<T>::del(int loc) { _list.del(loc); } template <class T> INLINE void RefList<T>::del(T &el, int loc) { _list.del( el, loc ); } template <class T> INLINE void RefList<T>::del(T &el) { _list.del( el, 0 ); } template <class T> INLINE T & RefList<T>::grab() { return grab(0); } template <class T> INLINE T & RefList<T>::grab(int loc) { T &el = (*this)[loc]; this->del(loc); return el; } template <class T> INLINE T & RefList<T>::grab(T &el) { this->del(el,0); return el; } template <class T> INLINE int RefList<T>::index(const T &el) const { return _list.index( el ); } template <class T> INLINE Boolean RefList<T>::member(const T &el) const { return _list.member( el ); } template <class T> INLINE Boolean RefList<T>::valid(int loc) const { return _list.valid(loc); } template <class T> INLINE Boolean RefList<T>::valid(const T &el) const { return _list.valid( el ); } template <class T> INLINE void RefList<T>::ins_first(const T &new_element) { _list.ins( new_element, 0 ); } template <class T> INLINE void RefList<T>::ins_last(const T &new_element) { _list.ins( new_element, _list.entries() ); } template <class T> INLINE void RefList<T>::ins_before(const T &new_element, const T &ref) { _list.ins_before( new_element, ref ); } template <class T> INLINE void RefList<T>::ins_after(const T &new_element, const T &ref) { _list.ins_after( new_element, ref ); } template <class T> INLINE void RefList<T>::clear() { _list.clear(); } template <class T> INLINE RefList<T> & RefList<T>::operator = (const RefList<T >&l) { _list = l._list; return *this; } template <class T> INLINE int RefList<T>::structures_OK() const { return _list.structures_OK(); } template <class T> INLINE const Collection & RefList<T>::_base_collection() const { return _list; } template <class T> INLINE Collection & RefList<T>::_base_collection() { return _list; } template <class T> INLINE Listable * RefList<T>::listable_clone() const { return (Listable *) new RefList<T>(*this); } template <class T> INLINE void RefList<T>::print(ostream &o) const { print(o, ", "); } ///< This interface is for testing purposes only. It invokes a non-virtual ///< member function to print a representation of the data structure at this ///< level of the Collection hierarchy, and, since it is not a class member ///< function, it must be explicitly instantiated before use. template <class T> ostream & operator << (ostream & o, const RefList<T> &l) { l.print(o, ", "); return o; } #endif

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