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

Timestamp:

Feb 7, 2005, 6:56:24 PM (21 years ago)

Author:

eugene

Message:

bugzilla changes (psMetadata iterators, pmObject stuff)

File:

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

trunk/doc/pslib/psLibSDRS.tex

@@ -1 @@
-%%% $Id: psLibSDRS.tex,v 1.173 2005-01-28 21:37:57 price Exp $
+%%% $Id: psLibSDRS.tex,v 1.174 2005-02-08 04:56:24 eugene Exp $
 \documentclass[panstarrs,spec]{panstarrs}
 
@@ -3901 +3901 @@
 \code{psMetadataItem} ready for insertion into the \code{psMetadata}.
 The \code{name} entry specifies the name to use for this metadata
-item, and may include \code{sprintf}-stype formating codes.  The
-\code{format} entry, which specifies both the metadata type and the
-optional flags, is constructed by bit-wise or'ing the appropriate type
-and flag.  The \code{comment} entry is a fixed string which is used
-for the comment associated with this metadata item.  The metadata data
-and the arguments to the \code{name} formatting codes are passed, in
-that order (metadata pointer first), to \code{psMetadataItemAlloc} as
+item, and may include \code{sprintf}-type formating codes.  The
+\code{comment} entry is a fixed string which is used for the comment
+associated with this metadata item.  The metadata data and the
+arguments to the \code{name} formatting codes are passed, in that
+order (metadata pointer first), to \code{psMetadataItemAlloc} as
 arguments following the comment string.  The data must be a pointer
 for any data types which are stored in the element \code{data.void},
@@ -3915 +3913 @@
 \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}
 
@@ -3933 +3930 @@
 (\code{true}) or failure of the operation.  The second function,
 \code{psMetadataAdd} takes a pointer or value which is interpreted by
-the function using variadic argument interpretation.  Both functions
-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
-which the key already exists in the metadata (and is not
-\code{PS_META_LIST}).
-%
-\begin{verbatim}
-bool psMetadataAddItem(psMetadata *md, psMetadataItem *item, int location);
+the function using variadic argument interpretation.  The third
+version is the \code{va_list} version of the second function.  All
+three functions take a parameter, \code{location}, which specifies
+where in the list to place the element, following the conventions for
+the \code{psList}.  The entry \code{mode} for \code{psMetadataAddItem}
+is a bit mask constructed by OR-ing the allowed option flags (eg,
+PS_META_REPLACE) which specifies minor variations on the behavior.
+The \code{format} entry, which specifies both the metadata type and
+the optional flags, is constructed by bit-wise OR-ing the appropriate
+\code{psMetadataType} and allowed option option flags.  Care should be
+taken not to leak memory when appending an item for which the key
+already exists in the metadata (and is not \code{PS_META_LIST}).
+%
+\begin{verbatim}
+bool psMetadataAddItem(psMetadata *md, psMetadataItem *item, int location, int mode);
 bool psMetadataAdd(psMetadata *md, int location, const char *name, int format, const char *comment, ...);
+bool psMetadataAddV(psMetadata *md, int location, const char *name, int format, const char *comment, ...);
+\end{verbatim}
+
+The functions above take option flags which modify the behavior when
+metadata items are added to the metadata list.  These flags must be
+bit-exclusive of those used above for the \code{psMetadataTypes}.  The
+flags have the following meanings: 
+
+\code{PS_META_DEFAULT}: This is the zero bit mask, to allow the
+default behavior for \code{psMetadataAddItem} above.  If this is OR-ed
+with a \code{psMetadataType}, the result is as if no OR-ing took
+place.
+
+\code{PS_META_REPLACE}: If the given metadata item exists in the
+metadata list, and is not of type \code{PS_META_LIST} or
+\code{PS_META_META} (ie, not a container type), then this entry is
+allowed to replace the existing entry.  If this mode bit is not set, a
+duplicate (non-container-type) entry is an error.
+
+\begin{verbatim}
+typedef enum {                          ///< option flags for psMetadata functions
+    PS_META_DEFAULT,                    ///< default behavior (0x0000) for use in mode above
+    PS_META_REPLACE,                    ///< allow entry to be replaced
+} psMetadataFlags;
+\end{verbatim}
+
+An example of code to use these metadata APIs to generate the
+structure seen in Figure~\ref{fig:metadata} is given below.
+
+\begin{verbatim}
+md = psMetadataAlloc();
+
+psMetadataAdd(md, PS_LIST_TAIL, "SIMPLE",   PS_META_BOOL, "basic fits",            TRUE);
+psMetadataAdd(md, PS_LIST_TAIL, "BLANK",    PS_META_S32,  "invalid pixel data",    -32768);
+psMetadataAdd(md, PS_LIST_TAIL, "DATE-OBS", PS_META_STR,  "observing date UT", "   2004-6-16");
+psMetadataAdd(md, PS_LIST_TAIL, "COMMENT",  PS_META_LIST, "head of comment block", NULL);
+psMetadataAdd(md, PS_LIST_TAIL, "COMMENT",  PS_META_STR,  "",                      "DATA");
+psMetadataAdd(md, PS_LIST_TAIL, "COMMENT",  PS_META_STR,  "",                      "PARAMS"); 
+psMetadataAdd(md, PS_LIST_TAIL, "EXPTIME",  PS_META_F32,  "exposure time (sec)",   1.05);
+psMetadataAdd(md, PS_LIST_TAIL, "COMMENT",  PS_META_STR,  "",                      "FOO");
+
+cell = psMetadataAlloc();
+psMetadataAdd(cell, PS_LIST_TAIL, "EXTNAME",  PS_META_STR,  "",                    "CCD00");
+psMetadataAdd(cell, PS_LIST_TAIL, "BIASNAME", PS_META_STR,  "",                    "BSEC-00");
+psMetadataAdd(cell, PS_LIST_TAIL, "CHIP",     PS_META_STR,  "",                    "CHIP.00");
+psMetadataAdd(md,   PS_LIST_TAIL, "CELL.00",  PS_META_META, "",                    cell);
+
+cell = psMetadataAlloc();
+psMetadataAdd(cell, PS_LIST_TAIL, "EXTNAME",  PS_META_STR,  "",                    "CCD01");
+psMetadataAdd(cell, PS_LIST_TAIL, "BIASNAME", PS_META_STR,  "",                    "BSEC-01");
+psMetadataAdd(cell, PS_LIST_TAIL, "CHIP",     PS_META_STR,  "",                    "CHIP.01");
+psMetadataAdd(md,   PS_LIST_TAIL, "CELL.01",  PS_META_META, "",                    cell);
+\end{verbatim}
+
+The following code shows how to use the APIs to replace one of these values:
+\begin{verbatim}
+psMetadataAdd(md, PS_LIST_TAIL, "EXPTIME",  PS_META_F32 | PS_REPLACE,  "new exposure time (sec)",   2.05);
 \end{verbatim}
 
@@ -3983 +4043 @@
 \end{verbatim}
 
-The metadata may be iterated over by (re-)setting a particular
-\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}
-bool 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);
+The metadata list component may be iterated over by using a
+\code{psListIterator} in a fashion equivalent to the usage for
+\code{psList}.  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 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_META_LIST}.  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}
+psListIterator *psMetadataIteratorAlloc(psMetadata *md, int location, bool mutable);
+bool psMetadataIteratorSet(psListIterator *iterator, int location);
+psMetadataItem *psMetadataGetAndIncrement(psListIterator *iterator, const char *regex);
+psMetadataItem *psMetadataGetAndDecrement(psListIterator *iterator, const char *regex);
 \end{verbatim}