summaryrefslogtreecommitdiff
path: root/utils
diff options
context:
space:
mode:
Diffstat (limited to 'utils')
-rw-r--r--utils/DList.cc163
-rw-r--r--utils/List.cc76
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)
{