Index: trunk/doc/pslib/psLibSDRS.tex =================================================================== --- trunk/doc/pslib/psLibSDRS.tex (revision 3106) +++ trunk/doc/pslib/psLibSDRS.tex (revision 3155) @@ -1,3 +1,3 @@ -%%% $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,11 +3901,9 @@ \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,6 +3913,5 @@ \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,14 +3930,77 @@ (\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,18 +4043,22 @@ \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}