IPP Software Navigation Tools IPP Links Communication Pan-STARRS Links

Ignore:
Timestamp:
Aug 11, 2004, 3:23:20 PM (22 years ago)
Author:
desonia
Message:

doxygen cleanup.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/psLib/src/astronomy/psMetadata.h

    r1441 r1496  
    1111*  @author Ross Harman, MHPCC
    1212*
    13 *  @version $Revision: 1.19 $ $Name: not supported by cvs2svn $
    14 *  @date $Date: 2004-08-09 23:40:54 $
     13*  @version $Revision: 1.20 $ $Name: not supported by cvs2svn $
     14*  @date $Date: 2004-08-12 01:23:20 $
    1515*
    1616*  Copyright 2004 Maui High Performance Computing Center, University of Hawaii
    … …  
    3434 */
    3535typedef enum {
    36     PS_META_ITEM_SET = 0,       ///< Null. Metadata is in psMetadataItem.items
    37     PS_META_BOOL,                          ///< Boolean data.
    38     PS_META_S32,                           ///< Signed 32-bit integer data.
    39     PS_META_F32,                           ///< Single-precision float data.
    40     PS_META_F64,                           ///< Double-precision float data.
    41     PS_META_STR,                           ///< String data (Stored in as void *).
    42     PS_META_IMG,                           ///< Image data (Stored in as void *).
    43     PS_META_JPEG,                          ///< JPEG data (Stored in as void .
    44     PS_META_PNG,                           ///< PNG data (Stored in as void *).
    45     PS_META_ASTROM,                        ///< Astrometric coefficients (Stored in as void *).
    46     PS_META_UNKNOWN,                       ///< Other data (Stored in as void *).
    47     PS_META_NTYPE                          ///< Number of types. Must be last.
     36    PS_META_ITEM_SET = 0,              ///< Null. Metadata is in psMetadataItem.items
     37    PS_META_BOOL,                      ///< Boolean data.
     38    PS_META_S32,                       ///< Signed 32-bit integer data.
     39    PS_META_F32,                       ///< Single-precision float data.
     40    PS_META_F64,                       ///< Double-precision float data.
     41    PS_META_STR,                       ///< String data (Stored in as void *).
     42    PS_META_IMG,                       ///< Image data (Stored in as void *).
     43    PS_META_JPEG,                      ///< JPEG data (Stored in as void *).
     44    PS_META_PNG,                       ///< PNG data (Stored in as void *).
     45    PS_META_ASTROM,                    ///< Astrometric coefficients (Stored in as void *).
     46    PS_META_UNKNOWN,                   ///< Other data (Stored in as void *).
     47    PS_META_NTYPE                      ///< Number of types. Must be last.
    4848} psMetadataType;
    4949
    … …  
    5555typedef struct psMetadataItem
    5656{
    57     const int id;               ///< Unique ID for metadata item.
    58     char *restrict name;        ///< Name of metadata item.
    59     psMetadataType type;        ///< Type of metadata item.
     57    const int id;                      ///< Unique ID for metadata item.
     58    char *restrict name;               ///< Name of metadata item.
     59    psMetadataType type;               ///< Type of metadata item.
    6060    union {
    61         bool B;
    62         psS32 S32;              ///< Signed 32-bit integer data.
    63         psF32 F32;              ///< Single-precision float data.
    64         psF64 F64;              ///< Double-precision float data.
    65         psPTR V;                ///< Pointer to other type of data.
    66     } data;                     ///< Union for data types.
    67     char *comment;              ///< Optional comment ("", not NULL).
    68     psList* restrict items;     ///< List of psMetadataItems with same name.
     61        bool B;                        ///< boolean data
     62        psS32 S32;                     ///< Signed 32-bit integer data.
     63        psF32 F32;                     ///< Single-precision float data.
     64        psF64 F64;                     ///< Double-precision float data.
     65        psPTR V;                       ///< Pointer to other type of data.
     66    } data;                            ///< Union for data types.
     67    char *comment;                     ///< Optional comment ("", not NULL).
     68    psList* restrict items;            ///< List of psMetadataItems with same name.
    6969}
    7070psMetadataItem;
    … …  
    7272/** Metadata data structure.
    7373 *
    74  * Struct for holding metadata items. Metadata items are held in two containers. The first employs a
    75  * doubly-linked list to preserve the order of the metadata. The second container employs a hash table which
    76  * allows fast lookup when given a metadata keyword.
     74 *  Struct for holding metadata items. Metadata items are held in two
     75 *  containers. The first employs a doubly-linked list to preserve the order
     76 *  of the metadata. The second container employs a hash table which
     77 *  allows fast lookup when given a metadata keyword.
    7778 */
    7879typedef struct psMetadata
    7980{
    80     psList* restrict list;
    81     psHash* restrict table;
     81    psList* restrict list;             ///< the metadata in linked-list
     82    psHash* restrict table;            ///< the metadata in a hash table
    8283}
    8384psMetadata;
    … …  
    9192/** Create a metadata item.
    9293 *
    93  * Returns a fill psMetadataItem ready for insertion into the psMetadata struct. The name argument specifies
    94  * the name to use for this item, and may include sprintf formatting codes. The format entry specifies both
    95  * the metadata type and optional flags and is created by bit-wise or of the appropriate type and flag. The
    96  * comment argument is a fixed string used to comment the metadata item. The arguments to the name formatting
    97  * codes and the metadata itself are passed as arguments following the comment string. The data must be
    98  * a pointer for any of the elements stored in data.void. The argument list must be interpreted appropriately
    99  * by the va_list operators in the function.
    100  * specified size and type.
    101  *
    102  * @return psMetadataItem* : Pointer metadata item.
    103  */
    104 psMetadataItem* psMetadataItemAlloc(const char *name,   ///< Name of metadata item.
    105                                     psMetadataType type,        ///< Type of metadata item.
    106                                     const char *comment,        ///< Comment for metadata item.
    107                                     ... ///< Arguments for name formatting and metadata item data.
    108                                    );
     94 *  Returns a fill psMetadataItem ready for insertion into the psMetadata
     95 *  struct. The name argument specifies the name to use for this item, and
     96 *  may include sprintf formatting codes. The format entry specifies both
     97 *  the metadata type and optional flags and is created by bit-wise or of the
     98 *  appropriate type and flag. The comment argument is a fixed string used to
     99 *  comment the metadata item. The arguments to the name formatting codes and
     100 *  the metadata itself are passed as arguments following the comment string.
     101 *  The data must be a pointer for any of the elements stored in data.void.
     102 *  The argument list must be interpreted appropriately by the va_list
     103 *  operators in the function specified size and type.
     104 *
     105 * @return psMetadataItem* : Pointer metadata item.
     106 */
     107psMetadataItem* psMetadataItemAlloc(
     108    const char *name,                  ///< Name of metadata item.
     109    psMetadataType type,               ///< Type of metadata item.
     110    const char *comment,               ///< Comment for metadata item.
     111    ...                                ///< Arguments for name formatting and metadata item data.
     112);
    109113
    110114/** Create a metadata item with va_list.
    111115 *
    112  * Returns a fill psMetadataItem ready for insertion into the psMetadata struct. The name argument specifies
    113  * the name to use for this item, and may include sprintf formatting codes. The format entry specifies both
    114  * the metadata type and optional flags and is created by bit-wise or of the appropriate type and flag. The
    115  * comment argument is a fixed string used to comment the metadata item. The arguments to the name formatting
    116  * codes and the metadata itself are passed as arguments following the comment string. The data must be
    117  * a pointer for any of the elements stored in data.void. The argument list must be interpreted appropriately
    118  * by the va_list operators in the function.
    119  * specified size and type.
    120  *
    121  * @return psMetadataItem* : Pointer metadata item.
    122  */
    123 psMetadataItem* psMetadataItemAllocV(const char *name,  ///< Name of metadata item.
    124                                      psMetadataType type,       ///< Type of metadata item.
    125                                      const char *comment,       ///< Comment for metadata item.
    126                                      va_list list       ///< Arguments for name formatting and metadata item
    127                                      // data.
    128                                     );
     116 *  Returns a fill psMetadataItem ready for insertion into the psMetadata
     117 *  struct. The name argument specifies the name to use for this item, and
     118 *  may include sprintf formatting codes. The format entry specifies both
     119 *  the metadata type and optional flags and is created by bit-wise or of the
     120 *  appropriate type and flag. The comment argument is a fixed string used to
     121 *  comment the metadata item. The arguments to the name formatting codes and
     122 *  the metadata itself are passed as arguments following the comment string.
     123 *  The data must be a pointer for any of the elements stored in data.void.
     124 *  The argument list must be interpreted appropriately by the va_list
     125 *  operators in the function specified size and type.
     126 *
     127 * @return psMetadataItem* : Pointer metadata item.
     128 */
     129psMetadataItem* psMetadataItemAllocV(
     130    const char *name,                  ///< Name of metadata item.
     131    psMetadataType type,               ///< Type of metadata item.
     132    const char *comment,               ///< Comment for metadata item.
     133    va_list list                       ///< Arguments for name formatting and metadata item data.
     134);
    129135
    130136/** Create a metadata collection.
    131137 *
    132  * Returns an empty metadata container with fully allocated internal metadata containers.
    133  *
    134  * @return psMetadata* : Pointer metadata.
    135  */
    136 psMetadata* psMetadataAlloc(void        ///< Void.
    137                            );
     138 *  Returns an empty metadata container with fully allocated internal metadata
     139 *  containers.
     140 *
     141 *  @return psMetadata* : Pointer metadata.
     142 */
     143psMetadata* psMetadataAlloc(void);
    138144
    139145/** Add existing metadata item to metadata collection.
    140146 *
    141  * Add a metadata item that has already been created to the metadata collection.
     147 *  Add a metadata item that has already been created to the metadata
     148 *  collection.
     149 *
     150 *  @return bool: True for success, false for failure.
     151 */
     152bool psMetadataAddItem(
     153    psMetadata* restrict md,           ///< Metadata collection to insert metadat item.
     154    int where,                         ///< Location to be added.
     155    psMetadataItem* restrict item      ///< Metadata item to be added.
     156);
     157
     158/** Create and add a metadata item to metadata collection.
     159 *
     160 * Creates a new metadata item add to the metadata collection.
    142161 *
    143162 * @return bool: True for success, false for failure.
    144163 */
    145 bool psMetadataAddItem(psMetadata* restrict md,        ///< Metadata collection to insert metadat item.
    146                        int where,       ///< Location to be added.
    147                        psMetadataItem* restrict item   ///< Metadata item to be added.
    148                       );
    149 
    150 /** Create and add a metadata item to metadata collection.
    151  *
    152  * Creates a new metadata item add to the metadata collection.
     164bool psMetadataAdd(
     165    psMetadata* restrict md,           ///< Metadata collection to insert metadat item.
     166    int where,                         ///< Location to be added.
     167    const char *name,                  ///< Name of metadata item.
     168    psMetadataType type,               ///< Type of metadata item.
     169    const char *comment,               ///< Comment for metadata item.
     170    ...                                ///< Arguments for name formatting and metadata item data.
     171);
     172
     173/** Remove an item from metadata collection.
     174 *
     175 *  Items may be removed from metadata by specifing a key or location. If the
     176 *  name is null, the where argument is used instead. If name is not null,
     177 *  where is set to PS_LIST_UNKNOWN. If the item is found, it is removed from
     178 *  the metadata and true is returned.  If the key is not unique, then all
     179 *  items corresponding to it are removed.
    153180 *
    154181 * @return bool: True for success, false for failure.
    155182 */
    156 bool psMetadataAdd(psMetadata* restrict md,    ///< Metadata collection to insert metadat item.
    157                    int where,   ///< Location to be added.
    158                    const char *name,    ///< Name of metadata item.
    159                    psMetadataType type, ///< Type of metadata item.
    160                    const char *comment, ///< Comment for metadata item.
    161                    ...          ///< Arguments for name formatting and metadata item data.
    162                   );
    163 
    164 /** Remove an item from metadata collection.
    165  *
    166  * Items may be removed from metadata by specifing a key or location. If the name is null, the where argument
    167  * is used instead. If name is not null, where is set to PS_LIST_UNKNOWN. If the item is found, it is removed
    168  * from the metadata and true is returned.  If the key is not unique, then all items corresponding to it are
    169  * removed.
    170  *
    171  * @return bool: True for success, false for failure.
    172  */
    173 bool psMetadataRemove(psMetadata* restrict md, ///< Metadata collection to insert metadat item.
    174                       int where,        ///< Location to be removed.
    175                       const char *restrict key  ///< Name of metadata key.
    176                      );
     183bool psMetadataRemove(
     184    psMetadata* restrict md,           ///< Metadata collection to insert metadat item.
     185    int where,                         ///< Location to be removed.
     186    const char *restrict key           ///< Name of metadata key.
     187);
    177188
    178189/** Find an item in the metadata collection based on key name.
    179190 *
    180  * Items may be found in the metadata by providing a key. If the key is non-unique, the first item is
    181  * returned. If the item is not found, null is returned.
    182  *
    183  * @return psMetadataItem* : Pointer metadata item.
    184  */
    185 psMetadataItem* psMetadataLookup(psMetadata* restrict md,      ///< Metadata collection to insert metadat
    186                                  // item.
    187                                  const char *restrict key       ///< Name of metadata key.
    188                                 );
     191 *  Items may be found in the metadata by providing a key. If the key is
     192 *  non-unique, the first item is returned. If the item is not found, null is
     193 *  returned.
     194 *
     195 * @return psMetadataItem* : Pointer metadata item.
     196 */
     197psMetadataItem* psMetadataLookup(
     198    psMetadata* restrict md,           ///< Metadata collection to insert metadata item.
     199    const char *restrict key           ///< Name of metadata key.
     200);
    189201
    190202/** Find an item in the metadata collection based on list index.
    191203 *
    192  * Items may be found in the metadata by their entry position in the list container.
    193  *
    194  * @return psMetadataItem* : Pointer metadata item.
    195  */
    196 psMetadataItem* psMetadataGet(psMetadata* restrict md, ///< Metadata collection to insert metadat item.
    197                               int where ///< Location to be retrieved.
    198                              );
     204 *  Items may be found in the metadata by their entry position in the list
     205 *  container.
     206 *
     207 *  @return psMetadataItem* : Pointer metadata item.
     208 */
     209psMetadataItem* psMetadataGet(
     210    psMetadata* restrict md,           ///< Metadata collection to insert metadat item.
     211    int where                          ///< Location to be retrieved.
     212);
    199213
    200214/** Set or reset metadata iterator.
    201215 *
    202  * Metadata may be iterated by setting or resetting an iterator to a location in the metadata list.
     216 *  Metadata may be iterated by setting or resetting an iterator to a location
     217 *  in the metadata list.
    203218 *
    204219 * @return void: void.
    205220 */
    206 bool psMetadataSetIterator(psMetadata* restrict md,    ///< Metadata collection to iterate.
    207                            int where    ///< Location of iterator.
    208                           );
     221bool psMetadataSetIterator(
     222    psMetadata* restrict md,           ///< Metadata collection to iterate.
     223    int where                          ///< Location of iterator.
     224);
    209225
    210226/** Get next metadata item.
    … …  
    214230 * @return psMetadataItem* : Pointer metadata item.
    215231 */
    216 psMetadataItem* psMetadataGetNext(psMetadata* restrict md,     ///< Metadata collection to iterate.
    217                                   const char *restrict match,   ///< Beginning of key name.
    218                                   int which     ///< Iterator to be used.
    219                                  );
     232psMetadataItem* psMetadataGetNext(
     233    psMetadata* restrict md,           ///< Metadata collection to iterate.
     234    const char *restrict match,        ///< Beginning of key name.
     235    int which                          ///< Iterator to be used.
     236);
    220237
    221238/** Get previous metadata item.
    … …  
    225242 * @return psMetadataItem* : Pointer metadata item.
    226243 */
    227 psMetadataItem* psMetadataGetPrevious(psMetadata* restrict md, ///< Metadata collection to iterate.
    228                                       const char *restrict match,       ///< Beginning of key name.
    229                                       int which ///< Iterator to be used.
    230                                      );
     244psMetadataItem* psMetadataGetPrevious(
     245    psMetadata* restrict md,           ///< Metadata collection to iterate.
     246    const char *restrict match,        ///< Beginning of key name.
     247    int which                          ///< Iterator to be used.
     248);
    231249
    232250/** Print metadata item to file.
    233251 *
    234  * Metadata items may be printed to an open file descriptor based on a provided format. The format is a
    235  * sprintf format statement with exactly one % formatting command. If the metadata item type is a numeric
    236  * type, this formatting command must also be numeric, and the type conversion performed to the value to match
    237  * the format type. If the metadata type is a string, the fromatting command must also be for a string. If the
    238  * metadata type is any other data type, printing is not allowed.
    239  *
    240  * @return psMetadataItem* : Pointer metadata item.
    241  */
    242 void psMetadataItemPrint(FILE * fd,     ///< Pointer to file to write metadata item.
    243                          const char *format,    ///< Format to print metadata item.
    244                          const psMetadataItem* restrict metadataItem   ///< Metadata item to print.
    245                         );
     252 *  Metadata items may be printed to an open file descriptor based on a
     253 *  provided format. The format is a sprintf format statement with exactly
     254 *  one % formatting command. If the metadata item type is a numeric type,
     255 *  this formatting command must also be numeric, and the type conversion
     256 *  performed to the value to match the format type. If the metadata type is
     257 *  a string, the fromatting command must also be for a string. If the
     258 *  metadata type is any other data type, printing is not allowed.
     259 *
     260 * @return psMetadataItem* : Pointer metadata item.
     261 */
     262void psMetadataItemPrint(
     263    FILE * fd,                         ///< Pointer to file to write metadata item.
     264    const char *format,                ///< Format to print metadata item.
     265    const psMetadataItem* restrict metadataItem ///< Metadata item to print.
     266);
    246267
    247268/** Read metadata header.
    248269 *
    249  * Read a metadata header from file. If the file is not found, an error is reported. This file is currently
    250  * unimplemented.
    251  *
    252  * @return psMetadata* : Pointer metadata.
    253  */
    254 psMetadata* psMetadataReadHeader(psMetadata* output,   ///< Resulting metadata from read.
    255                                  char *extname, ///< File name extension string.
    256                                  int extnum,    ///< File name extension number. Starts at 1.
    257                                  char *filename ///< Name of file to read.
    258                                 );
     270 *  Read a metadata header from file. If the file is not found, an error is
     271 *  reported. This file is currently unimplemented.
     272 *
     273 *  @return psMetadata* : Pointer metadata.
     274 */
     275psMetadata* psMetadataReadHeader(
     276    psMetadata* output,                ///< Resulting metadata from read.
     277    char *extname,                     ///< File name extension string.
     278    int extnum,                        ///< File name extension number. Starts at 1.
     279    char *filename                     ///< Name of file to read.
     280);
    259281
    260282/** Read metadata header.
    261283 *
    262  * Read a metadata header from file. If the file is not found, an error is reported.
    263  *
    264  * @return psMetadata* : Pointer metadata.
    265  */
    266 psMetadata* psMetadataFReadHeader(psMetadata* output,  ///< Resulting metadata from read.
    267                                   char *extName,        ///< File name extension string.
    268                                   int extNum,   ///< File name extension number.
    269                                   fitsfile * fd ///< Pointer to file to read.
    270                                  );
     284 *  Read a metadata header from file. If the file is not found, an error is
     285 *  reported.
     286 *
     287 *  @return psMetadata* : Pointer metadata.
     288 */
     289psMetadata* psMetadataFReadHeader(
     290    psMetadata* output,                ///< Resulting metadata from read.
     291    char *extName,                     ///< File name extension string.
     292    int extNum,                        ///< File name extension number.
     293    fitsfile * fd                      ///< Pointer to file to read.
     294);
    271295
    272296/// @}
Note: See TracChangeset for help on using the changeset viewer.