Changeset 4453

Timestamp:

Jul 5, 2005, 1:52:23 PM (21 years ago)

Author:

Paul Price

Message:

Added accessors for the array-like collections. See bug 459.

File:

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

trunk/doc/pslib/psLibSDRS.tex

@@ -1 @@
-%%% $Id: psLibSDRS.tex,v 1.307 2005-07-01 04:30:18 price Exp $
+%%% $Id: psLibSDRS.tex,v 1.308 2005-07-05 23:52:23 price Exp $
 \documentclass[panstarrs,spec]{panstarrs}
 
@@ -560 +560 @@
 
 For array-like collections (specifically, \code{psArray},
-\code{psVector}, and \code{psImage}) we allow the user to refer to a
-negative index to mean address from the end.  Consequently, the number
-of elements in structures should be signed.  It is the responsibility
-of these structure allocators (e.g., \code{psArrayAlloc}) to check
-that the requested number of elements is not negative (calling
-\code{psAbort} otherwise).  All other allocators shall simply use
-\code{size_t} where the number of elements is needed (saving the
-trouble of checking before passing to psAlloc).
+\code{psPixels}, \code{psVector}, and \code{psImage}) we allow the
+user to refer to a negative index in the accessor (e.g.,
+\code{psArrayGet}) to mean address from the end.  Consequently, the
+number of elements in structures should be signed (in order to be able
+to access the full range of allocated values).  It is the
+responsibility of these structure allocators (e.g.,
+\code{psArrayAlloc}) to check that the requested number of elements is
+not negative (calling \code{psAbort} otherwise).  All other allocators
+shall simply use \code{size_t} where the number of elements is needed
+(saving the trouble of checking before passing to psAlloc).
 
 \subsubsection{Callback Routines}
@@ -1696 +1698 @@
 
 These accessor functions are provided as a convenience to the user.
-\code{psArraySet} sets the value of the \code{in} array at the specified
-\code{position} to \code{value}, returning \code{true} if successful.
-\code{psArrayGet} returns the value of the \code{in} array at the
-specified \code{position}.
+\code{psArraySet} sets the value of the \code{in} array at the
+specified \code{position} to \code{value}, returning \code{true} if
+successful.  \code{psArrayGet} returns the value of the \code{in}
+array at the specified \code{position}.  A negative \code{position}
+means index from the end.
 
 \begin{datatype}
@@ -2029 +2032 @@
 
 typedef struct {
-    psU32 n;                    // Number in use
-    const psU32 nalloc;         // Number allocated
+    long n;                     // Number in use
+    const long nalloc;          // Number allocated
     psPixelCoord *data;         // The pixel coordinates
     void *lock;                 // Lock for thread safety
@@ -2037 +2040 @@
 
 \begin{prototype}
-psPixels *psPixelsAlloc(psU32 nalloc);
-psPixels *psPixelsRealloc(psPixels *pixels, psU32 nalloc);
+psPixels *psPixelsAlloc(long nalloc);
+psPixels *psPixelsRealloc(psPixels *pixels, long nalloc);
 \end{prototype}
 
@@ -2064 +2067 @@
 are stored is not important, the values may be sorted, allowing the
 use of a faster algorithm than a linear scan).
+
+\begin{prototype}
+bool psPixelsSet(psPixels *pixels, long position, psPixelCoord value);
+psPixelCoord psPixelsGet(const psPixels *pixels, long position);
+\end{prototype}
+
+These accessor functions are provided as a convenience to the user.
+\code{psPixelsSet} sets the value of the \code{pixels} array at the
+specified \code{position} to \code{value} (a \code{psPixelCoord}
+passed by value), returning \code{true} if successful.
+\code{psPixelsGet} returns the value of the \code{pixels} array at the
+specified \code{position}.  A negative \code{position} means index
+from the end.
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -2539 +2555 @@
 The iterator may be set to a location in the \code{psMetadata} list,
 and the user may get the previous or next item in the list relative to
-that location.  \code{psMetadataGetNext} has the ability to match the
-key using a POSIX \code{regex}, 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 in the metadata list, even those that are contained in a
+that location.  The iterators may be used to return the next key
+matching a POSIX \code{regex}, 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 in the metadata list, even those that are contained in a
 \code{PS_DATA_LIST}.  The value \code{iterator} specifies the iterator
 to be used.  In setting the iterator, the position of the iterator is
@@ -3140 +3156 @@
 The input data is cast to match the vector datatype, allowing for
 integers to be preserved.
+
+\begin{prototype}
+bool psVectorSet(const psVector *input, long position, complex double value);
+complex double psVectorGet(const psVector *input, long position);
+\end{prototype}
+
+These accessor functions are provided as a convenience to the user.
+\code{psVectorSet} sets the value of the \code{input} vector at the
+specified \code{position} to \code{value} (appropriately cast),
+returning \code{true} if successful.  \code{psVectorGet} returns the
+value of the \code{input} vector at the specified \code{position}.  A
+negative \code{position} means index from the end.
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -3238 +3266 @@
 The input data is cast to match the image datatype, allowing for
 integers to be preserved.
+
+\begin{prototype}
+bool psImageSet(const psImage *image, int x, int y, complex double value);
+complex double psImageGet(const psImage *image, int x, int y);
+\end{prototype}
+
+These accessor functions are provided as a convenience to the user.
+\code{psImageSet} sets the value of the \code{image} at the specified
+\code{x,y} position to \code{value} (appropriately cast), returning
+\code{true} if successful.  \code{psImageGet} returns the value of the
+\code{image} at the specified \code{x,y} position.  A negative value
+for the \code{x,y} position means index from the end.
 
 \subsubsection{Image Regions}