Changeset 3067

Timestamp:

Jan 19, 2005, 5:46:53 PM (22 years ago)

Author:

Paul Price

Message:

Updates to psList from RHL comments.

Location:

trunk/doc/pslib

Files:

• ChangeLogSDRS.tex (modified) (2 diffs)
• psLibSDRS.tex (modified) (9 diffs)

trunk/doc/pslib/ChangeLogSDRS.tex

@@ -1 @@
-%%% $Id: ChangeLogSDRS.tex,v 1.55 2005-01-07 22:31:45 price Exp $
+%%% $Id: ChangeLogSDRS.tex,v 1.56 2005-01-20 03:46:53 price Exp $
 
 \subsection{Changes from version 00 to version 01}
@@ -409 +409 @@
 minimization.
 \item Added \code{psPlaneAlloc, psSphereAlloc, psProjectionAlloc}.
-\end{itemize}
+\item \code{psList}:
+  \begin{itemize}
+  \item Adopted new names: \code{psListGetAndIncrement,
+    psListGetAndDecrement} instead of \code{psListGetNext,
+    psListGetPrev} --- clearer description of functionality.
+  \item Changed \code{PS_LIST_HEAD = 0} and \code{PS_LIST_TAIL = -1};
+    negative indices specify an item relative to the end of the list.
+  \item The action of retrieving data from a list (with one of the
+    three \code{psListGet} functions) is considered ``borrowing'' the
+    reference, so no action is performed on the reference counter.
+    Removed other mentions of reference counters, since these were not
+    necessary.
+  \item \code{mutable} boolean in \code{psListIterator} specifies
+    whether \code{psListAddAfter} or \code{psListAddBefore} may be
+    used to modify the list through the iterator.  This allows the use
+    of \code{const psList} in \code{psListIteratorAlloc}.
+  \end{itemize}
+
+\end{itemize}

trunk/doc/pslib/psLibSDRS.tex

@@ -1 @@
-%%% $Id: psLibSDRS.tex,v 1.166 2005-01-09 00:50:15 eugene Exp $
+%%% $Id: psLibSDRS.tex,v 1.167 2005-01-20 03:46:48 price Exp $
 \documentclass[panstarrs,spec]{panstarrs}
 
@@ -1534 +1534 @@
 and the first element in the list, pointed to by both
 \code{psList.head} and \code{psList.tail}.  If the data entry is
-\code{NULL}, then an empty list, with both pointers are set to
-\code{NULL} should be created.  The number of iterators in the list is
-initially set to zero.
+\code{NULL}, then an empty list, with both pointers set to \code{NULL}
+should be created.  The number of iterators in the list is initially
+set to zero.
 
 The destructor function for \code{psList} must call \code{psFree} for
@@ -1545 +1545 @@
 removed from a list, they must have their reference counters
 decremented.  The action of retrieving data from a list (with one of
-the three \code{psListGet} functions) also increments the reference
-counter.
+the three \code{psListGet} functions) is considered ``borrowing'' the
+reference, so no action is performed on the reference counter.
 
 Iteration on the list shall be achieved by means of a list iterator
@@ -1556 +1556 @@
     bool offEnd;                       ///< Is the iterator off the end?
     int index;                         ///< Index of iterator, to assist performance
+    bool mutable;                      ///< Is it permissible to modify the list?
 } psListIterator;
 \end{verbatim}
@@ -1563 +1564 @@
 using numerical locations.  The boolean member, \code{offEnd},
 indicates whether the iterator has progressed off the end of the list
-(i.e., beyond the last item).
+(i.e., beyond the last item).  The boolean \code{mutable} specifies
+whether it is permissible to modify the list pointed to by the
+iterator.  \code{psListAddBefore} and \code{psListAddAfter} are not
+permitted to modify a list that is not \code{mutable} (i.e., only the
+\code{psListGetAndIncrement} and \code{psListGetAndDecrement}
+operations are permissible for a non-\code{mutable} list).
 
 The corresponding constructor shall be:
 \begin{verbatim}
-psListIterator *psListIteratorAlloc(psList *list, int location);
+psListIterator *psListIteratorAlloc(const psList *list, int location, bool mutable);
 \end{verbatim}
 Here, \code{list} is the \code{psList} on which the iterator will
 iterate, and \code{location} is the initial starting point, and may be
 a numerical index or it may be one of the special values:
-\code{PS_LIST_HEAD} or \code{PS_LIST_TAIL}, which are defined as
-negative integers.  Of course, the \code{psListElem} pointed to by the
-iterator shall have its \code{refCounter} incremented.
+\code{PS_LIST_HEAD} or \code{PS_LIST_TAIL}, which are defined as 0 and
+-1, respectively; a negative index is interpreted as relative to the
+end of the list.  The boolean \code{mutable} specifies whether it is
+permissible to modify the list pointed to by the iterator.
 
 The destructor for \code{psListIterator} shall, after freeing the
-\code{psListIterator} and decrementing the \code{refCounter} of the
-\code{psListElem} that it pointed to, also reorganise the \code{iter}
-array (replacing the element being removed with the last element) and
+\code{psListIterator}, also reorganise the \code{iter} array
+(replacing the element being removed with the last element) and
 resizing the array appropriately.
 
@@ -1589 +1595 @@
 Again, the \code{location} may be a numerical index or it may be one
 of the special values: \code{PS_LIST_HEAD} or \code{PS_LIST_TAIL},
-which are defined as negative integers.  The function shall return
-\code{true} if the reset was successful, or \code{false} otherwise.
+which are defined as 0 and -1, respectively; a negative index is
+interpreted as relative to the end of the list.  The function shall
+return \code{true} if the reset was successful, or \code{false}
+otherwise.
 
 \begin{verbatim}
@@ -1604 +1612 @@
 warning and add the \code{data} to the tail) or it may be one of the
 special values: \code{PS_LIST_HEAD} or \code{PS_LIST_TAIL}, which are
-defined as negative integers.  The other two functions,
+defined as 0 and -1, respectively; a negative index is interpreted as
+relative to the end of the list.  The other two functions,
 \code{psListAddAfter} and \code{psListAddBefore} specify that the
 \code{data} shall be added after or before (respectively) the current
@@ -1611 +1620 @@
 \begin{verbatim}
 void *psListGet(psList *list, int location);
-void *psListGetNext(psListIterator *iterator);
-void *psListGetPrevious(psListIterator *iterator);
+void *psListGetAndIncrement(psListIterator *iterator);
+void *psListGetAndDecrement(psListIterator *iterator);
 \end{verbatim}
 A data item may be retrieved from the list with these functions.  The
-first function, \code{psListGet} simply returns the value specified
-by its \code{location}, which may be a numerical index or it may be
-one of the special values: \code{PS_LIST_HEAD} or \code{PS_LIST_TAIL},
-which are defined as negative integers, allowing \code{location} to
-also be the index of one of the data items.  The other two functions,
-\code{psListGetNext} and \code{psListGetPrevious} return the item
-under the iteration cursor before advancing to the next or previous
-item, respectively.
+first function, \code{psListGet} simply returns the value specified by
+its \code{location}, which may be a numerical index or it may be one
+of the special values: \code{PS_LIST_HEAD = 0} or \code{PS_LIST_TAIL =
+-1}; negative indices are interpreted as relative to the end of the
+list.  The other two functions, \code{psListGetAndIncrement} and
+\code{psListGetAndDecrement} return the item under the iteration
+cursor before advancing to the next or previous item, respectively.
 
 In the event that the iteration cursor is at the tail of the list,
-\code{psListGetNext} shall return the tail item and then set the
-\code{cursor} to \code{NULL} and \code{offEnd} to \code{true}.  In the
-event that the iteration cursor is at the head of the list,
-\code{psListGetPrevious} shall return the head item and then set the
-\code{cursor} to \code{NULL} (and \code{offEnd} should already be
+\code{psListGetAndIncrement} shall return the tail item and then set
+the \code{cursor} to \code{NULL} and \code{offEnd} to \code{true}.  In
+the event that the iteration cursor is at the head of the list,
+\code{psListGetAndDecrement} shall return the head item and then set
+the \code{cursor} to \code{NULL} (and \code{offEnd} should already be
 \code{false}).  In the event that the iteration \code{cursor} is
-\code{NULL}, \code{psListGetNext} and \code{psListGetPrevious} shall
-return \code{NULL}, and advance the iteration \code{cursor} only if
-the intended direction places the cursor back on the list; otherwise a
-warning shall be generated, and no change shall be made.  If
-\code{psListGetPrevious} was called with \code{offEnd} as \code{true},
-then \code{offEnd} shall also be toggled back to \code{false} to
-indicate that the \code{cursor} is no longer off the end of the list.
-When setting the \code{cursor}, the appropriate \code{refCounter}s
-shall be incremented and decremented.
+\code{NULL}, \code{psListGetAndIncrement} and
+\code{psListGetAndDecrement} shall return \code{NULL}, and advance the
+iteration \code{cursor} only if the intended direction places the
+cursor back on the list; otherwise a warning shall be generated, and
+no change shall be made.  If \code{psListGetAndDecrement} was called
+with \code{offEnd} as \code{true}, then \code{offEnd} shall also be
+toggled back to \code{false} to indicate that the \code{cursor} is no
+longer off the end of the list.
 
 \begin{verbatim}
@@ -1648 +1655 @@
 \code{psListRemove}, the value of \code{location} may be the numerical
 index or it may be one of the special values: \code{PS_LIST_HEAD} or
-\code{PS_LIST_TAIL}, which are defined as negative integers.  For
+\code{PS_LIST_TAIL}, which are defined as 0 and -1, respectively; a
+negative index is interpreted as relative to the end of the list.  For
 \code{psListRemoveData}, the data item to be removed is identified by
 matching the pointer value with \code{void *data}.  The functions