Changeset 1645 for trunk/doc/pslib/psLibSDRS.tex

Timestamp:

Aug 27, 2004, 1:18:42 PM (22 years ago)

Author:

Paul Price

Message:

Fixed order of psList arguments to match those for psMetadata.
Replaced horrible "which" and "where" arguments with "iterator" and
"location", which are more descriptive.

File:

• trunk/doc/pslib/psLibSDRS.tex (modified) (7 diffs)

trunk/doc/pslib/psLibSDRS.tex

@@ -1 @@
-%%% $Id: psLibSDRS.tex,v 1.89 2004-08-27 21:38:46 price Exp $
+%%% $Id: psLibSDRS.tex,v 1.90 2004-08-27 23:18:42 price Exp $
 \documentclass[panstarrs,spec]{panstarrs}
 
@@ -1434 +1434 @@
 
 \begin{verbatim}
-bool psListAdd(psList *list, void *data, int where);
+bool psListAdd(psList *list, int location, void *data);
 \end{verbatim}
 Add an entry to the list with this function, which takes a pointer to
 the list and returns a boolean giving the success or failure of the
-operation. The value of \code{where} specifies if the specified data
-item should be placed on the front of the list (\code{PS_LIST_HEAD}),
-at the end of the list (\code{PS_LIST_TAIL}), to add after
-(\code{PS_LIST_NEXT}) or before (\code{PS_LIST_PREV}) the current
-element (specified by the iteration cursor), or an index that the new
-\code{data} should inhabit.
-
-\begin{verbatim}
-void *psListGet(psList *list, int which);
+operation. The value of \code{location} specifies if the specified
+data item should be placed on the front of the list
+(\code{PS_LIST_HEAD}), at the end of the list (\code{PS_LIST_TAIL}),
+to add after (\code{PS_LIST_NEXT}) or before (\code{PS_LIST_PREV}) the
+current element (specified by the iteration cursor), or an index that
+the new \code{data} should inhabit.
+
+\begin{verbatim}
+void *psListGet(psList *list, int location);
 \end{verbatim}
 A data item may be retrieved from the list with this function.  The
-value of \code{which} may be the numerical index or it may be one of
-the special values: \code{PS_LIST_HEAD}, \code{PS_LIST_TAIL},
-\code{PS_LIST_PREV}, and \code{PS_LIST_NEXT}, all of which are
-defined as negative integers, allowing \code{where} to also be the
-index of one of the data items.
-
-\begin{verbatim}
-bool psListRemove(psList *list, void *data, int which);
+value of \code{location} may be the numerical index or it may be one
+of the special values: \code{PS_LIST_HEAD}, \code{PS_LIST_TAIL},
+\code{PS_LIST_PREV}, and \code{PS_LIST_NEXT}, all of which are defined
+as negative integers, allowing \code{location} to also be the index of
+one of the data items.
+
+\begin{verbatim}
+bool psListRemove(psList *list, int location, void *data);
 \end{verbatim}
 A data item may be removed from the list with this function.  The
-value of \code{which} may be the numerical index or it may be one of
-the special values: \code{PS_LIST_HEAD}, \code{PS_LIST_TAIL},
-\code{PS_LIST_PREV}, \code{PS_LIST_UNKNOWN}, and
-\code{PS_LIST_NEXT}, all of which are defined as negative integers.
-If the value of \code{which} is \code{PS_LIST_UNKNOWN}, then the data
-item is identified by matching the pointer value with \code{void
-*data}.  The function returns a value of \code{true} if the operation
-was successfull, and \code{false} otherwise.
+value of \code{location} may be the numerical index or it may be one
+of the special values: \code{PS_LIST_HEAD}, \code{PS_LIST_TAIL},
+\code{PS_LIST_PREV}, \code{PS_LIST_UNKNOWN}, and \code{PS_LIST_NEXT},
+all of which are defined as negative integers.  If the value of
+\code{location} is \code{PS_LIST_UNKNOWN}, then the data item is
+identified by matching the pointer value with \code{void *data}.  The
+function returns a value of \code{true} if the operation was
+successful, and \code{false} otherwise.
 
 All data items placed onto lists (\code{psListAdd}) must have their
@@ -1485 +1485 @@
 
 \begin{verbatim}
-void psListSetIterator(psList *list, int where, int which);
-void *psListGetNext(psList *list, int which);
-void *psListGetPrevious(psList *list, int which);
+void psListSetIterator(psList *list, int iterator, int location);
+void *psListGetNext(psList *list, int iterator);
+void *psListGetPrevious(psList *list, int iterator);
 \end{verbatim}
 Iteration over all elements of the list using the iteration cursor
 \code{iter} is provided by these functions.  The first of these
-functions uses the value of \code{where} to set the iteration cursor
-for the given list to the beginning \code{PS_LIST_HEAD} or the end
-\code{PS_LIST_TAIL} for the iterator specified by \code{which}.  The
-next two functions move the iteration cursor forward or backwards,
+functions uses the value of \code{location} to set the iteration
+cursor for the given list to the beginning \code{PS_LIST_HEAD} or the
+end \code{PS_LIST_TAIL} for the iterator specified by \code{iterator}.
+The next two functions move the iteration cursor forward or backwards,
 returning the data item from the resulting list entry, or returning
 \code{NULL} at the end of the list.  Explicit traversal of the list
@@ -3360 +3360 @@
 \begin{verbatim}
 psMetadataItem *psMetadataItemAlloc(const char *name, psMetadataType type, const char *comment, ...);
-psMetadataItem *psMetadataItemAllocV(const char *name, psMetadataType type, const char *comment, va_list list);
+psMetadataItem *psMetadataItemAllocV(const char *name, psMetadataType type,
+                                     const char *comment, va_list list);
 \end{verbatim}
 
@@ -3378 +3379 @@
 \code{psMetadataAdd} takes a pointer or value which is interpreted by
 the function using variadic argument interpretation.  Both functions
-take an parameter \code{where} which specifies where in the list to
+take an parameter \code{location} which specifies where in the list to
 place the element, following the conventions for the \code{psList}.
 Care should be taken not to leak memory when appending an item for
@@ -3385 +3386 @@
 %
 \begin{verbatim}
-bool psMetadataAddItem(psMetadata *md, int where, psMetadataItem *item);
-bool psMetadataAdd(psMetadata *md, int where, const char *name, int format, const char *comment, ...);
+bool psMetadataAddItem(psMetadata *md, psMetadataItem *item, int location);
+bool psMetadataAdd(psMetadata *md, int location, const char *name, int format, const char *comment, ...);
 \end{verbatim}
 
 Items may be removed from the metadata by specifying a key or a
 location in the list.  If the value of \code{name} is \code{NULL}, the
-value of \code{where} is used.  If the value of \code{name} is not
-\code{NULL}, then \code{where} must be set to \code{PS_LIST_UNKNOWN}.
-If the key matches a metadata item, the item is removed from the
-metadata and \code{true} is returned; otherwise, \code{false} is
-returned.  If the key is not unique, then \emph{all} items
-corresponding to the key are removed, and \code{true} is returned.
-%
-\begin{verbatim}
-bool psMetadataRemove(psMetadata *md, int where, const char *key);
+value of \code{location} is used.  If the value of \code{name} is not
+\code{NULL}, then \code{location} must be set to
+\code{PS_LIST_UNKNOWN}.  If the key matches a metadata item, the item
+is removed from the metadata and \code{true} is returned; otherwise,
+\code{false} is returned.  If the key is not unique, then \emph{all}
+items corresponding to the key are removed, and \code{true} is
+returned.
+%
+\begin{verbatim}
+bool psMetadataRemove(psMetadata *md, int location, const char *key);
 \end{verbatim}
 
@@ -3412 +3414 @@
 \code{psList}.
 \begin{verbatim}
-psMetadataItem *psMetadataGet(const psMetadata *md, int which);
+psMetadataItem *psMetadataGet(const psMetadata *md, int location);
 \end{verbatim}
 
 The metadata may be iterated over by (re-)setting a particular
-iterator, \code{which}, to a location in the \code{psMetadata} list,
-and getting the previous or next item.  \code{psMetadataGetNext} has
-the ability to match the beginning of a key, e.g., if the user only
-wants to iterate through \code{IPP.machines.sky} and doesn't want to
-bother with \code{IPP.machines.detector}.  The iterator should iterate
-over every item of metadata --- even those that are non-unique.  The
-value \code{which} specifies the iterator to be used.  In setting the
-iterator, the position of the iterator is defined by \code{where},
+\code{iterator}, to a location in the \code{psMetadata} list, and
+getting the previous or next item.  \code{psMetadataGetNext} has the
+ability to match the beginning of a key, e.g., if the user only wants
+to iterate through \code{IPP.machines.sky} and doesn't want to bother
+with \code{IPP.machines.detector}.  The iterator should iterate over
+every item of metadata --- even those that are non-unique.  The value
+\code{iterator} specifies the iterator to be used.  In setting the
+iterator, the position of the iterator is defined by \code{location},
 which follows the conventions of the \code{psList} iterators.
 \begin{verbatim}
-void psMetadataSetIterator(psMetadata *md, int which, int where);
-psMetadataItem *psMetadataGetNext(psMetadata *md, const char *match, int which);
-psMetadataItem *psMetadataGetPrevious(psMetadata *md, const char *match, int which);
+void psMetadataSetIterator(psMetadata *md, int iterator, int location);
+psMetadataItem *psMetadataGetNext(psMetadata *md, const char *match, int iterator);
+psMetadataItem *psMetadataGetPrevious(psMetadata *md, const char *match, int iterator);
 \end{verbatim}