diff options
Diffstat (limited to 'utils')
| -rw-r--r-- | utils/DList.cc | 163 | ||||
| -rw-r--r-- | utils/List.cc | 76 |
2 files changed, 211 insertions, 28 deletions
diff --git a/utils/DList.cc b/utils/DList.cc index 96a2db8..711a32c 100644 --- a/utils/DList.cc +++ b/utils/DList.cc @@ -430,13 +430,14 @@ CcuDList :: RemoveAfter (const CcuDListIter& li) Remove the element pointed at by the iterator \var{li}. If \var{li} points before the beginning of the list, or has reached its end, the return value is null, and the status flag is set to \var{TooEarly} -{resp. \var{TooFar}). In all other cases, \var{li} is rewinded by one step, +(resp. \var{TooFar}). In all other cases, \var{li} is rewinded by one step, in order to allow such loops as: +\begin{ccode} CcuDListIter li (l); - while (++li) { + while (++li) if (do_remove (*li)) l.RemoveAt (l); - } +\end{ccode} ?*/ CcuDListItem* CcuDList :: RemoveAt (CcuDListIter& li) @@ -461,11 +462,17 @@ CcuDList :: RemoveAt (CcuDListIter& li) #ifdef DOC +/*?class CcuDListIter +The class \typ{CcuDListIter} allows iterations on lists. +Several iterators may be used at a time on the same list. It is dangerous to modify +a list that is being iterated. +?*/ + /*? Initialize an iterator associated to the list \var{l}. That iterator will point at the beginning of the list, {\em before} the first element. ?*/ -CcuDListIter :: CcuDListIter (CcuDList& l) +CcuDListIter :: CcuDListIter (const CcuDList& l) { } @@ -478,14 +485,20 @@ CcuDListIter :: GetStatus () const { } +/*?nextdoc?*/ +void +CcuDListIter :: Reset () +{ +} + /*? -Reset an iterator to the beginning of the list. +Reset an iterator to the beginning (resp. the end) of the list. ?*/ void -CcuDListIter :: Reset () +CcuDListIter :: GotoEnd () { } -#endif +#endif /* DOC */ /*? @@ -575,3 +588,139 @@ CcuDListIter :: FindBack (CcuDListItem* e) return 0; } +#ifdef DOC + +/*?class CcuDListOf +The generic classes \typ{CcuDListOf} and \typ{CcuDListIterOf} are derived classes +of \typ{CcuDList} and \typ{CcuDListIter} that provide lists of pointers to class objects. +When parameterized by the class \typ{ITEM}, the following functions are redefined: +?*/ + +/*?nextdoc?*/ +CcuDListOf :: CcuDListOf (ITEM* it) +{ +} + +/*?nextdoc?*/ +ITEM* +CcuDListOf :: First () +{ +} + +/*?nextdoc?*/ +ITEM* +CcuDListOf :: Last () +{ +} + +/*?nextdoc?*/ +ITEM* +CcuDListOf :: Nth (int n) +{ +} + +/*?nextdoc?*/ +int +CcuDListOf :: Find (ITEM* it) const +{ +} + +/*?nextdoc?*/ +void +CcuDListOf :: Append (ITEM* it) +{ +} + +/*?nextdoc?*/ +void +CcuDListOf :: Prepend (ITEM* it) +{ +} + +/*?nextdoc?*/ +CcuDListOf& +CcuDListOf :: operator << (ITEM* it) +{ +} + +/*?nextdoc?*/ +ITEM* +CcuDListOf :: RemoveFirst () +{ +} + +/*?nextdoc?*/ +ITEM* +CcuDListOf :: RemoveLast () +{ +} + +/*?nextdoc?*/ +int +CcuDListOf :: Remove (ITEM* it, int nb = 1) +{ +} + +/*?nextdoc?*/ +int +CcuDListOf :: Remove (int (*p) (ITEM*), int nb = 1) +{ +} + +/*?nextdoc?*/ +void +CcuDListOf :: InsertAfter (const CcuDListIterOf <ITEM>& li, ITEM*it) +{ +} + +/*?nextdoc?*/ +void +CcuDListOf :: InsertBefore (const CcuDListIterOf <ITEM>& li, ITEM* it) +{ +} + +/*?nextdoc?*/ +ITEM* +CcuDListOf :: RemoveAfter (const CcuDListIterOf <ITEM>& li) +{ +} + +/*? +These functions are equivalent to their homonyms in the class \typ{CcuDList}, +except that they are customized in order to manipulate pointers to \typ{ITEM} +instead of \typ{void*}. +?*/ +ITEM* +CcuDListOf :: RemoveAt (CcuDListIterOf <ITEM>& li) +{ +} + +/*?nextdoc?*/ +CcuDListIterOf :: CcuDListIterOf (const CcuDListOf <ITEM>& l) +{ +} + +/*?nextdoc?*/ +ITEM* +CcuDListIterOf :: operator * () const +{ +} + +/*?nextdoc?*/ +int +CcuDListIterOf :: Find (ITEM* it) +{ +} + +/*? +These functions are equivalent to their homonyms in the class \typ{CcuDListIter}, +except that they are customized in order to manipulate pointers to \typ{ITEM} +instead of \typ{void*}. +?*/ +int +CcuDListIterOf :: FindBack (ITEM* it) +{ +} + + +#endif /* DOC */ diff --git a/utils/List.cc b/utils/List.cc index cbac66f..dd07956 100644 --- a/utils/List.cc +++ b/utils/List.cc @@ -166,6 +166,17 @@ CcuList :: operator = (const CcuList& l) return *this; } +#ifdef DOC +/*? +Get the status flag of a list. This can be one of \var{NoError, WasEmpty, TooEarly, TooFar} or +\var{BadIterator}. The status flag is modified by most operations on lists. Those which +modify it when errors are encountered also set it to \var{NoError} when there is no error. +?*/ +list_status +CcuList :: GetStatus () const +{ +} +#endif /* DOC */ /*?nextdoc?*/ CcuListItem* @@ -182,7 +193,8 @@ CcuList :: First () /*? Return the first (resp. last) element in the list, or 0 if the list was empty. The case of a null element can be distinguished from the case -when the list is empty with the function \fun{GetStatus}. +when the list is empty with the function \fun{GetStatus}: the status flag is +set to \var{WasEmpty} in the latter case. ?*/ CcuListItem* CcuList :: Last () @@ -264,7 +276,8 @@ CcuList :: Append (CcuListItem* e) } /*? -Remove the first element of a list and return it. +Remove the first element of a list and return it. The status flag is set to +\var{WasEmpty} when the list was empty. ?*/ CcuListItem* CcuList :: RemoveFirst () @@ -292,7 +305,8 @@ CcuList :: RemoveFirst () /*? -Remove the last element of a list and return it. This function has to locate the last +Remove the last element of a list and return it. The status flag is set to +\var{WasEmpty} when the list was empty. This function has to locate the last element, and hence has a linear cost. ?*/ CcuListItem* @@ -442,7 +456,8 @@ Insert an element before (resp. after) the current position of the iterator \var These functions are both equivalent to \fun{CcuList::Prepend} if the iterator is at the beginning of the list (ie. before the first element). \fun{InsertAfter} is performed in a constant time, while \fun{InsertBefore} -has a linear cost. +has a linear cost. If \var{li} is not an iterator on this list, the status flag of the list +is set to \var{BadIterator}. ?*/ void CcuList :: InsertBefore (const CcuListIter& li, CcuListItem* e) @@ -468,20 +483,24 @@ CcuList :: InsertBefore (const CcuListIter& li, CcuListItem* e) /*? Remove the element after the current element of the iterator \var{li}. -If \var{li} points before the beginning of the list, the first element is returned. +If \var{li} points before the beginning of the list, the first element is removed. If \var{li} points at the last element, the status flag is set to \var{TooFar}. If the list is empty, the flag is set to \var{EmptyList}. In both cases, the -return value is null. +return value is null. If \var{li} is not an iterator +on this list, the flag is set to \var{BadIterator}. This function may be used when one wants to iterate through a list and remove some elements: - CcuListIter li (l); - CcuListIter lj (l); +\begin{ccode} + CcuListIter li = l; + CcuListIter lj = l; while (++li) if (do_remove (*li)) { - RemoveAfter (lj); - li = lj; - } else - ++lj; + l.RemoveAfter (lj); + li = lj; + } else { + ++lj; + } +\end{ccode} ?*/ CcuListItem* CcuList :: RemoveAfter (const CcuListIter& li) @@ -505,11 +524,27 @@ CcuList :: RemoveAfter (const CcuListIter& li) #ifdef DOC +/*?class CcuListIter +The class \typ{CcuListIter} allows iterations on lists. +Several iterators may be used at a time on the same list. It is dangerous to modify +a list that is being iterated. Refer to the implementation figure for more details. +Of course, the functions such as \var{InsertAfter} or \var{RemoveAfter} are designed +to be harmless. However, they may be dangerous if another iterator is used at the same +time on the same list. +The basic usage of an iterator is the following: +\begin{ccode} + extern CcuList& l; + CcuListIter li = l; + while (++li) + foo (*li); // *li is the value that was stored with Append +\end{ccode} +?*/ + /*? Initialize an iterator associated to the list \var{l}. That iterator will point at the beginning of the list, {\em before} the first element. ?*/ -CcuListIter :: CcuListIter (CcuList& l) +CcuListIter :: CcuListIter (const CcuList& l) { } @@ -576,8 +611,7 @@ CcuListIter :: operator ++ () #ifndef CPLUS_BUG16 /*? Post-increment equivalent of the previous operator. This operator is just here -as a demonstrator: it was not tested because no known compiler implements that feature, -and its semantics is quite muddy. +as a placeholder: it does the same thing as the previous one. ?*/ CcuListIter& CcuListIter :: operator ++ (int) @@ -687,17 +721,17 @@ CcuListOf :: InsertAfter (const CcuListIterOf <ITEM>& li, ITEM*it) { } -/*? -These functions are equivalent to their homonyms in the class \typ{CcuList}, -except that they are customized in order to manipulate pointers to \typ{ITEM} -instead of \typ{void*}. -?*/ +/*?nextdoc?*/ void CcuListOf :: InsertBefore (const CcuListIterOf <ITEM>& li, ITEM* it) { } -/*?nextdoc?*/ +/*? +These functions are equivalent to their homonyms in the class \typ{CcuList}, +except that they are customized in order to manipulate pointers to \typ{ITEM} +instead of \typ{void*}. +?*/ ITEM* CcuListOf :: RemoveAfter (const CcuListIterOf <ITEM>& li) { |