Index: /trunk/doc/pslib/psLibSDRS.tex =================================================================== --- /trunk/doc/pslib/psLibSDRS.tex (revision 403) +++ /trunk/doc/pslib/psLibSDRS.tex (revision 404) @@ -1,3 +1,3 @@ -%%% $Id: psLibSDRS.tex,v 1.33 2004-04-08 02:13:17 price Exp $ +%%% $Id: psLibSDRS.tex,v 1.34 2004-04-08 23:22:10 price Exp $ \documentclass[panstarrs]{panstarrs} @@ -489,4 +489,5 @@ \subsubsection{Relation of Memory Management to Structures} +\label{sec:free} In this document, we specify several C \code{struct}s. It is expected @@ -2477,6 +2478,6 @@ const int id; ///< unique ID for this item char *restrict name; ///< Name of item - psMetaDataType type; ///< type of this item - psMetaDataFlags flags; ///< flags associated with this item + psMetadataType type; ///< type of this item + psMetadataFlags flags; ///< flags associated with this item const union { double d; ///< double value @@ -2486,6 +2487,6 @@ } val; ///< value of metadata char *comment; ///< optional comment ("", not NULL) - psDlist *restrict items; ///< list of psMetaDataItems with the same name -} psMetaDataItem; + psDlist *restrict items; ///< list of psMetadataItems with the same name +} psMetadataItem; \end{verbatim} @@ -2493,5 +2494,5 @@ shows that such tags are useful. -The \code{psMetaDataType type} entry specifies the type of the data +The \code{psMetadataType type} entry specifies the type of the data being represented; the possibilities are listed in section \ref{metadataTypes}. @@ -2500,9 +2501,9 @@ The possible types of metadata are identified by the enumerated type -\code{psMetaDataType} (see also table \ref{tabMetaDataTypes}); the initial defined values are: +\code{psMetadataType} (see also table \ref{tabMetaDataTypes}); the initial defined values are: \begin{verbatim} /** Possible types of metadata. */ typedef enum { ///< type of val is: - PS_META_ITEM_SET = 0, ///< NULL; metadata is in psMetaDataType.items + PS_META_ITEM_SET = 0, ///< NULL; metadata is in psMetadataType.items PS_META_FLOAT, ///< float (.f) PS_META_INT, ///< int (.i) @@ -2514,5 +2515,5 @@ PS_META_UNKNOWN, ///< other (.v) PS_META_NTYPE ///< Number of types; must be last -} psMetaDataType; +} psMetadataType; \end{verbatim} @@ -2542,12 +2543,12 @@ /** A set of metadata */ typedef struct { - psDlist *restrict list; ///< list of psMetaDataItem + psDlist *restrict list; ///< list of psMetadataItem psHash *restrict table; ///< hash table of the same metadata -} psMetaDataSet; -\end{verbatim} - -The type \code{psMetaDataSet} is a container class for metadata. Note +} psMetadata; +\end{verbatim} + +The type \code{psMetadata} is a container class for metadata. Note that there are in fact \emph{two} representations of the metadata -(each \code{psMetaDataItem} appears on both). The first +(each \code{psMetadataItem} appears on both). The first representation employs a doubly-linked list that allows the order of the metadata to be preserved (e.g., if FITS headers are read in a @@ -2557,7 +2558,7 @@ When we refer to ``metadata'' (especially in the case of images), we -generally mean a \code{psMetaDataSet}: -\begin{verbatim} -typedef psMetaDataSet psMetadata; +generally mean a \code{psMetadata}: +\begin{verbatim} +typedef psMetadata psMetadata; \end{verbatim} @@ -2566,19 +2567,19 @@ for (int i = 0; i < 10; i += 5) { float sqrti = sqrt(i); - psMetaDataAppend(ms, psMetaDataItemAlloc(PS_META_INT, &i, NULL, "const.%d", i)); - psMetaDataAppend(ms, psMetaDataItemAlloc(PS_META_FLOAT, &sqrti, "square root", "const.sqrt%d", i)); + psMetadataAppend(ms, psMetadataItemAlloc(PS_META_INT, &i, NULL, "const.%d", i)); + psMetadataAppend(ms, psMetadataItemAlloc(PS_META_FLOAT, &sqrti, "square root", "const.sqrt%d", i)); } - psMetaDataAppend(ms, psMetaDataItemAlloc(PS_META_STR, "Bonjour", "French", "lang.hello")); + psMetadataAppend(ms, psMetadataItemAlloc(PS_META_STR, "Bonjour", "French", "lang.hello")); /* * Remove a key */ - psMetaDataItemFree(psMetaDataRemove(ms, "lang.hello")); + psMetadataItemFree(psMetadataRemove(ms, "lang.hello")); /* * Print all metadata */ fprintf(stdout, "------\n"); - psMetaDataSetIterator(ms); - while ((meta = psMetaDataGetNext(ms, NULL)) != NULL) { - psMetaDataItemPrint(stdout, meta, ""); + psMetadataSetIterator(ms); + while ((meta = psMetadataGetNext(ms, NULL)) != NULL) { + psMetadataItemPrint(stdout, meta, ""); } /* @@ -2587,13 +2588,13 @@ fprintf(stdout, "------\n"); fprintf(stdout, "Looking up by name:\n"); - meta = psMetaDataLookup(ms, "const.5"); + meta = psMetadataLookup(ms, "const.5"); if (meta != NULL) { - psMetaDataItemPrint(stdout, meta, ""); + psMetadataItemPrint(stdout, meta, ""); } \end{verbatim} -\subsubsection{Naming convention for MetaData} - -The \code{psMetaDataItem} struct includes a name. This name should be of +\subsubsection{Naming convention for Metadata} + +The \code{psMetadataItem} struct includes a name. This name should be of the form \code{name1.name2.name3}$\cdots$, e.g.\hfil\break \null\qquad\qquad\code{IPP.phase1.ota12.biassec}. @@ -2606,16 +2607,16 @@ \begin{verbatim} - psMetaDataAppend(ms, psMetaDataItemAlloc(PS_META_STR | PS_META_NON_UNIQUE, + psMetadataAppend(ms, psMetadataItemAlloc(PS_META_STR | PS_META_NON_UNIQUE, "Bonjour", "French", "lang.hello")); - psMetaDataAppend(ms, psMetaDataItemAlloc(PS_META_STR | PS_META_NON_UNIQUE, + psMetadataAppend(ms, psMetadataItemAlloc(PS_META_STR | PS_META_NON_UNIQUE, "Aloha", "Hawaiian", "lang.hello")); - psMetaDataAppend(ms, psMetaDataItemAlloc(PS_META_STR | PS_META_NON_UNIQUE, + psMetadataAppend(ms, psMetadataItemAlloc(PS_META_STR | PS_META_NON_UNIQUE, "Good Morning", "English", "lang.hello")); /* * Print all metadata starting "lang" */ - psMetaDataSetIterator(ms); - while ((meta = psMetaDataGetNext(ms, "lang")) != NULL) { - psMetaDataItemPrint(stdout, meta, ""); + psMetadataSetIterator(ms); + while ((meta = psMetadataGetNext(ms, "lang")) != NULL) { + psMetadataItemPrint(stdout, meta, ""); } \end{verbatim} @@ -2623,5 +2624,5 @@ It is an unfortunate fact that certain metadata keywords (such as \code{COMMENT} and \code{HISTORY} in a FITS header) may be repeated -with different values. The \code{psMetaDataAppend} routine is +with different values. The \code{psMetadataAppend} routine is required to check that all metadata names are unique unless the type is qualified as \code{PS_META_NON_UNIQUE}; in this case a unique @@ -2629,25 +2630,29 @@ may either delete individual element separately or as a complete set: \begin{verbatim} -psMetaDataItemFree(psMetaDataRemove(ms, "lang.hello.0")); -psMetaDataItemFree(psMetaDataRemove(ms, "lang.hello")); -\end{verbatim} - -\subsubsection{MetaData APIs} +psMetadataItemFree(psMetadataRemove(ms, "lang.hello.0")); +psMetadataItemFree(psMetadataRemove(ms, "lang.hello")); +\end{verbatim} + +\subsubsection{Metadata APIs} In this section, we explain the metadata APIs more fully. -The allocator for \code{psMetaDataItem} returns a full -\code{psMetaDataItem} ready for insertion into the -\code{psMetaDataSet}. It is important to note that, in order to +The allocator for \code{psMetadataItem} returns a full +\code{psMetadataItem} ready for insertion into the +\code{psMetadata}. It is important to note that, in order to support multiple types, the data being input must be a pointer, even if it is a \code{float} or \code{int}, for example. The name of the -\code{psMetaDataItem} takes a \code{sprintf} format string, with the +\code{psMetadataItem} takes a \code{sprintf} format string, with the corresponding arguments following. -Note that the destructor does not +Note that the destructor for \code{psMetadataItem} must call the +appropriate destructor for the \code{val} (recall that it is the duty +of the \code{psMyTypeFree}s to decrement the \code{refCounter} and +free the memory if and only if the new value of the \code{refCounter} +is zero --- see \S\ref{sec:free}). \begin{verbatim} /** Constructor */ -psMetaDataItem *psMetaDataItemAlloc(int typeFlags, ///< type of this piece of metadata + flags +psMetadataItem *psMetadataItemAlloc(int typeFlags, ///< type of this piece of metadata + flags const void *val, ///< value of new item N.b. a pointer even if the item ///< is of type e.g. int @@ -2659,42 +2664,97 @@ /** Destructor */ -void psMetaDataItemFree(psMetaDataItem *ms ///< piece of metadata to destroy - ); +void psMetadataItemFree(psMetadataItem *ms ///< piece of metadata to destroy + ); +\end{verbatim} + + +The constructor for the collection of metadata, \code{psMetadata}, +simply returns an empty metadata container (employing the constructors +for the doubly-linked list and hash table). The destructor needs to +free each of the \code{psMetadataItem}s using +\code{psMetadataItemFree}. + +\begin{verbatim} /** Constructor */ -psMetaDataSet *psMetaDataSetAlloc(void); ///< make a new set of metadata +psMetadata *psMetadataAlloc(void); ///< make a new set of metadata /** Destructor */ -void psMetaDataSetFree(psMetaDataSet *ms ///< destroy a set of metadata - ); - -/**** Utilities **********************************************************************/ - -/// Add entry to the end of the metadata set -psMetaDataItem *psMetaDataAppend(psMetaDataSet *restrict ms, ///< Metadata set to add to - psMetaDataItem *restrict item ///< Metatdata to add - ); - -/// delete entry from the metadata set -psMetaDataItem *psMetaDataRemove(psMetaDataSet *restrict ms, ///< Metadata set to delete from +void psMetadataFree(psMetadata *md ///< destroy a set of metadata + ); +\end{verbatim} + + +Items may be added to the metadata in one of two ways --- firstly, an +item may be added by appending a \code{psMetadataItem} which has +already been created; and secondly by directly providing the data to +be appended. In both cases, the \code{psMetadataItem} that is +appended to the metadata is returned. + +\begin{verbatim} +/// Add item to the end of the metadata +psMetadataItem *psMetadataAppendItem(psMetadata *restrict md, ///< metadata to add to + psMetadataItem *restrict item ///< Metatdata to add + ); + +/// Add item to the end of the metadata. Combines psMetadataItemAlloc and psMetadataAppendItem +psMetadataItem *psMetadataAppend(psMetadata *restrict md, ///< Metadata to add to + int typeFlags ///< type of this piece of metadata + flags + const void *val, ///< value of new item N.b. a pointer even if the item + ///< is of type e.g. int + const char *comment, ///< comment associated with item + const char *name, ///< name of new item of metadata (may be in sprintf + ///< format) + ... ///< possible arguments for name format + ); +\end{verbatim} + +Items may be removed from the metadata by specifying a key. If the +key matches a metadata item, the item is removed from the metadata and +returned; otherwise, \code{NULL} is returned. If the key is not +unique, then \emph{all} items corresponding to the key are removed, +and the \tbd{first} item is returned. + +\begin{verbatim} +/// delete entry from the metadata +psMetadataItem *psMetadataRemove(psMetadata *restrict md, ///< metadata to delete from const char *restrict key ///< Key to delete ); - +\end{verbatim} + +The metadata may be iterated over by (re-)setting the iterator for the +appropriate \code{psMetadata}, and getting the 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}. + +\begin{verbatim} /// reset the iterator to the start of the list -void psMetaDataSetIterator(psMetaDataSet *ms ///< Metadata set to set iterator for +void psMetadataSetIterator(psMetadata *md ///< metadata to set iterator for ); /// get the next entry in the sequence -psMetaDataItem *psMetaDataGetNext(psMetaDataSet *restrict ms, ///< Metadata set to get from +psMetadataItem *psMetadataGetNext(psMetadata *restrict md, ///< metadata to get from const char *restrict match ///< Match this ); - +\end{verbatim} + +Items may be found within the metadata by providing a key. In the +event that the key is non-unique, the first item is returned. + +\begin{verbatim} /// find the metadata with the specified key -psMetaDataItem *psMetaDataLookup(const psMetaDataSet *restrict ms, ///< Metadata set to look up +psMetadataItem *psMetadataLookup(const psMetadata *restrict md, ///< metadata to look up const char *restrict key ///< Key to find ); - +\end{verbatim} + +Metadata items may be printed to an open file descriptor, optionally +pre-pending a specified string. + +\begin{verbatim} /// print metadata item to the specified stream -void psMetaDataItemPrint(FILE *fd, ///< file descriptor to write to - const psMetaDataItem *restrict ms, ///< item of metadata to print +void psMetadataItemPrint(FILE *fd, ///< file descriptor to write to + const psMetadataItem *restrict md, ///< item of metadata to print const char *prefix ///< print this at the beginning of each line ); @@ -3053,5 +3113,5 @@ psDlist *objects; ///< objects derived from cell psImage *overscan; ///< bias region (subimage) of cell - psMetaDataSet *md; ///< Readout-level metadata + psMetadata *md; ///< Readout-level metadata } psReadout; \end{verbatim} @@ -3081,5 +3141,5 @@ ///< image, objects and overscan. struct psReadout *readouts; ///< Readouts from the cell - psMetaDataSet *md; ///< Cell-level metadata + psMetadata *md; ///< Cell-level metadata psCoordXform *cellToChip; ///< Transformations from cell coordinates to chip coordinates @@ -3111,5 +3171,5 @@ psCell *cells; ///< Cells in the Chip - psMetaDataSet *md; ///< Chip-level metadata + psMetadata *md; ///< Chip-level metadata psCoordXform *chipToFPA; ///< Transformations from chip coordinates to FPA coordinates psCoordXform *FPAtoChip; ///< Transformations from FPA coordinates to chip @@ -3147,5 +3207,5 @@ psChip *chips; ///< Chips in the Focal Plane Array - psMetaDataSet *md; ///< FPA-level metadata + psMetadata *md; ///< FPA-level metadata psDistortion *TPtoFP; ///< Transformation term from psDistortion *FPtoTP; ///< Transformation term from