Changeset 404

Timestamp:

Apr 8, 2004, 1:22:10 PM (22 years ago)

Author:

Paul Price

Message:

Fleshed out metadata functions.

File:

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

trunk/doc/pslib/psLibSDRS.tex

@@ -1 @@
-%%% $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 +489 @@
 
 \subsubsection{Relation of Memory Management to Structures}
+\label{sec:free}
 
 In this document, we specify several C \code{struct}s.  It is expected
@@ -2477 +2478 @@
     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 +2487 @@
     } 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 +2494 @@
 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 +2501 @@
 
 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 +2515 @@
     PS_META_UNKNOWN,                    ///< other (.v)
     PS_META_NTYPE                       ///< Number of types; must be last
-} psMetaDataType;
+} psMetadataType;
 \end{verbatim}
 
@@ -2542 +2543 @@
 /** 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 +2558 @@
 
 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 +2567 @@
     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 +2588 @@
     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 +2607 @@
 
 \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 +2624 @@
 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 +2630 @@
 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 +2664 @@
 
 /** 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 +3113 @@
     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 +3141 @@
                                         ///< 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 +3171 @@
     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 +3207 @@
     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