Index: trunk/psLib/src/astronomy/psMetadata.h =================================================================== --- trunk/psLib/src/astronomy/psMetadata.h (revision 1441) +++ trunk/psLib/src/astronomy/psMetadata.h (revision 1496) @@ -11,6 +11,6 @@ * @author Ross Harman, MHPCC * -* @version $Revision: 1.19 $ $Name: not supported by cvs2svn $ -* @date $Date: 2004-08-09 23:40:54 $ +* @version $Revision: 1.20 $ $Name: not supported by cvs2svn $ +* @date $Date: 2004-08-12 01:23:20 $ * * Copyright 2004 Maui High Performance Computing Center, University of Hawaii @@ -34,16 +34,16 @@ */ typedef enum { - PS_META_ITEM_SET = 0, ///< Null. Metadata is in psMetadataItem.items - PS_META_BOOL, ///< Boolean data. - PS_META_S32, ///< Signed 32-bit integer data. - PS_META_F32, ///< Single-precision float data. - PS_META_F64, ///< Double-precision float data. - PS_META_STR, ///< String data (Stored in as void *). - PS_META_IMG, ///< Image data (Stored in as void *). - PS_META_JPEG, ///< JPEG data (Stored in as void . - PS_META_PNG, ///< PNG data (Stored in as void *). - PS_META_ASTROM, ///< Astrometric coefficients (Stored in as void *). - PS_META_UNKNOWN, ///< Other data (Stored in as void *). - PS_META_NTYPE ///< Number of types. Must be last. + PS_META_ITEM_SET = 0, ///< Null. Metadata is in psMetadataItem.items + PS_META_BOOL, ///< Boolean data. + PS_META_S32, ///< Signed 32-bit integer data. + PS_META_F32, ///< Single-precision float data. + PS_META_F64, ///< Double-precision float data. + PS_META_STR, ///< String data (Stored in as void *). + PS_META_IMG, ///< Image data (Stored in as void *). + PS_META_JPEG, ///< JPEG data (Stored in as void *). + PS_META_PNG, ///< PNG data (Stored in as void *). + PS_META_ASTROM, ///< Astrometric coefficients (Stored in as void *). + PS_META_UNKNOWN, ///< Other data (Stored in as void *). + PS_META_NTYPE ///< Number of types. Must be last. } psMetadataType; @@ -55,16 +55,16 @@ typedef struct psMetadataItem { - const int id; ///< Unique ID for metadata item. - char *restrict name; ///< Name of metadata item. - psMetadataType type; ///< Type of metadata item. + const int id; ///< Unique ID for metadata item. + char *restrict name; ///< Name of metadata item. + psMetadataType type; ///< Type of metadata item. union { - bool B; - psS32 S32; ///< Signed 32-bit integer data. - psF32 F32; ///< Single-precision float data. - psF64 F64; ///< Double-precision float data. - psPTR V; ///< Pointer to other type of data. - } data; ///< Union for data types. - char *comment; ///< Optional comment ("", not NULL). - psList* restrict items; ///< List of psMetadataItems with same name. + bool B; ///< boolean data + psS32 S32; ///< Signed 32-bit integer data. + psF32 F32; ///< Single-precision float data. + psF64 F64; ///< Double-precision float data. + psPTR V; ///< Pointer to other type of data. + } data; ///< Union for data types. + char *comment; ///< Optional comment ("", not NULL). + psList* restrict items; ///< List of psMetadataItems with same name. } psMetadataItem; @@ -72,12 +72,13 @@ /** Metadata data structure. * - * Struct for holding metadata items. Metadata items are held in two containers. The first employs a - * doubly-linked list to preserve the order of the metadata. The second container employs a hash table which - * allows fast lookup when given a metadata keyword. + * Struct for holding metadata items. Metadata items are held in two + * containers. The first employs a doubly-linked list to preserve the order + * of the metadata. The second container employs a hash table which + * allows fast lookup when given a metadata keyword. */ typedef struct psMetadata { - psList* restrict list; - psHash* restrict table; + psList* restrict list; ///< the metadata in linked-list + psHash* restrict table; ///< the metadata in a hash table } psMetadata; @@ -91,120 +92,135 @@ /** Create a metadata item. * - * Returns a fill psMetadataItem ready for insertion into the psMetadata struct. The name argument specifies - * the name to use for this item, and may include sprintf formatting codes. The format entry specifies both - * the metadata type and optional flags and is created by bit-wise or of the appropriate type and flag. The - * comment argument is a fixed string used to comment the metadata item. The arguments to the name formatting - * codes and the metadata itself are passed as arguments following the comment string. The data must be - * a pointer for any of the elements stored in data.void. The argument list must be interpreted appropriately - * by the va_list operators in the function. - * specified size and type. - * - * @return psMetadataItem* : Pointer metadata item. - */ -psMetadataItem* psMetadataItemAlloc(const char *name, ///< Name of metadata item. - psMetadataType type, ///< Type of metadata item. - const char *comment, ///< Comment for metadata item. - ... ///< Arguments for name formatting and metadata item data. - ); + * Returns a fill psMetadataItem ready for insertion into the psMetadata + * struct. The name argument specifies the name to use for this item, and + * may include sprintf formatting codes. The format entry specifies both + * the metadata type and optional flags and is created by bit-wise or of the + * appropriate type and flag. The comment argument is a fixed string used to + * comment the metadata item. The arguments to the name formatting codes and + * the metadata itself are passed as arguments following the comment string. + * The data must be a pointer for any of the elements stored in data.void. + * The argument list must be interpreted appropriately by the va_list + * operators in the function specified size and type. + * + * @return psMetadataItem* : Pointer metadata item. + */ +psMetadataItem* psMetadataItemAlloc( + const char *name, ///< Name of metadata item. + psMetadataType type, ///< Type of metadata item. + const char *comment, ///< Comment for metadata item. + ... ///< Arguments for name formatting and metadata item data. +); /** Create a metadata item with va_list. * - * Returns a fill psMetadataItem ready for insertion into the psMetadata struct. The name argument specifies - * the name to use for this item, and may include sprintf formatting codes. The format entry specifies both - * the metadata type and optional flags and is created by bit-wise or of the appropriate type and flag. The - * comment argument is a fixed string used to comment the metadata item. The arguments to the name formatting - * codes and the metadata itself are passed as arguments following the comment string. The data must be - * a pointer for any of the elements stored in data.void. The argument list must be interpreted appropriately - * by the va_list operators in the function. - * specified size and type. - * - * @return psMetadataItem* : Pointer metadata item. - */ -psMetadataItem* psMetadataItemAllocV(const char *name, ///< Name of metadata item. - psMetadataType type, ///< Type of metadata item. - const char *comment, ///< Comment for metadata item. - va_list list ///< Arguments for name formatting and metadata item - // data. - ); + * Returns a fill psMetadataItem ready for insertion into the psMetadata + * struct. The name argument specifies the name to use for this item, and + * may include sprintf formatting codes. The format entry specifies both + * the metadata type and optional flags and is created by bit-wise or of the + * appropriate type and flag. The comment argument is a fixed string used to + * comment the metadata item. The arguments to the name formatting codes and + * the metadata itself are passed as arguments following the comment string. + * The data must be a pointer for any of the elements stored in data.void. + * The argument list must be interpreted appropriately by the va_list + * operators in the function specified size and type. + * + * @return psMetadataItem* : Pointer metadata item. + */ +psMetadataItem* psMetadataItemAllocV( + const char *name, ///< Name of metadata item. + psMetadataType type, ///< Type of metadata item. + const char *comment, ///< Comment for metadata item. + va_list list ///< Arguments for name formatting and metadata item data. +); /** Create a metadata collection. * - * Returns an empty metadata container with fully allocated internal metadata containers. - * - * @return psMetadata* : Pointer metadata. - */ -psMetadata* psMetadataAlloc(void ///< Void. - ); + * Returns an empty metadata container with fully allocated internal metadata + * containers. + * + * @return psMetadata* : Pointer metadata. + */ +psMetadata* psMetadataAlloc(void); /** Add existing metadata item to metadata collection. * - * Add a metadata item that has already been created to the metadata collection. + * Add a metadata item that has already been created to the metadata + * collection. + * + * @return bool: True for success, false for failure. + */ +bool psMetadataAddItem( + psMetadata* restrict md, ///< Metadata collection to insert metadat item. + int where, ///< Location to be added. + psMetadataItem* restrict item ///< Metadata item to be added. +); + +/** Create and add a metadata item to metadata collection. + * + * Creates a new metadata item add to the metadata collection. * * @return bool: True for success, false for failure. */ -bool psMetadataAddItem(psMetadata* restrict md, ///< Metadata collection to insert metadat item. - int where, ///< Location to be added. - psMetadataItem* restrict item ///< Metadata item to be added. - ); - -/** Create and add a metadata item to metadata collection. - * - * Creates a new metadata item add to the metadata collection. +bool psMetadataAdd( + psMetadata* restrict md, ///< Metadata collection to insert metadat item. + int where, ///< Location to be added. + const char *name, ///< Name of metadata item. + psMetadataType type, ///< Type of metadata item. + const char *comment, ///< Comment for metadata item. + ... ///< Arguments for name formatting and metadata item data. +); + +/** Remove an item from metadata collection. + * + * Items may be removed from metadata by specifing a key or location. If the + * name is null, the where argument is used instead. If name is not null, + * where is set to PS_LIST_UNKNOWN. If the item is found, it is removed from + * the metadata and true is returned. If the key is not unique, then all + * items corresponding to it are removed. * * @return bool: True for success, false for failure. */ -bool psMetadataAdd(psMetadata* restrict md, ///< Metadata collection to insert metadat item. - int where, ///< Location to be added. - const char *name, ///< Name of metadata item. - psMetadataType type, ///< Type of metadata item. - const char *comment, ///< Comment for metadata item. - ... ///< Arguments for name formatting and metadata item data. - ); - -/** Remove an item from metadata collection. - * - * Items may be removed from metadata by specifing a key or location. If the name is null, the where argument - * is used instead. If name is not null, where is set to PS_LIST_UNKNOWN. If the item is found, it is removed - * from the metadata and true is returned. If the key is not unique, then all items corresponding to it are - * removed. - * - * @return bool: True for success, false for failure. - */ -bool psMetadataRemove(psMetadata* restrict md, ///< Metadata collection to insert metadat item. - int where, ///< Location to be removed. - const char *restrict key ///< Name of metadata key. - ); +bool psMetadataRemove( + psMetadata* restrict md, ///< Metadata collection to insert metadat item. + int where, ///< Location to be removed. + const char *restrict key ///< Name of metadata key. +); /** Find an item in the metadata collection based on key name. * - * Items may be found in the metadata by providing a key. If the key is non-unique, the first item is - * returned. If the item is not found, null is returned. - * - * @return psMetadataItem* : Pointer metadata item. - */ -psMetadataItem* psMetadataLookup(psMetadata* restrict md, ///< Metadata collection to insert metadat - // item. - const char *restrict key ///< Name of metadata key. - ); + * Items may be found in the metadata by providing a key. If the key is + * non-unique, the first item is returned. If the item is not found, null is + * returned. + * + * @return psMetadataItem* : Pointer metadata item. + */ +psMetadataItem* psMetadataLookup( + psMetadata* restrict md, ///< Metadata collection to insert metadata item. + const char *restrict key ///< Name of metadata key. +); /** Find an item in the metadata collection based on list index. * - * Items may be found in the metadata by their entry position in the list container. - * - * @return psMetadataItem* : Pointer metadata item. - */ -psMetadataItem* psMetadataGet(psMetadata* restrict md, ///< Metadata collection to insert metadat item. - int where ///< Location to be retrieved. - ); + * Items may be found in the metadata by their entry position in the list + * container. + * + * @return psMetadataItem* : Pointer metadata item. + */ +psMetadataItem* psMetadataGet( + psMetadata* restrict md, ///< Metadata collection to insert metadat item. + int where ///< Location to be retrieved. +); /** Set or reset metadata iterator. * - * Metadata may be iterated by setting or resetting an iterator to a location in the metadata list. + * Metadata may be iterated by setting or resetting an iterator to a location + * in the metadata list. * * @return void: void. */ -bool psMetadataSetIterator(psMetadata* restrict md, ///< Metadata collection to iterate. - int where ///< Location of iterator. - ); +bool psMetadataSetIterator( + psMetadata* restrict md, ///< Metadata collection to iterate. + int where ///< Location of iterator. +); /** Get next metadata item. @@ -214,8 +230,9 @@ * @return psMetadataItem* : Pointer metadata item. */ -psMetadataItem* psMetadataGetNext(psMetadata* restrict md, ///< Metadata collection to iterate. - const char *restrict match, ///< Beginning of key name. - int which ///< Iterator to be used. - ); +psMetadataItem* psMetadataGetNext( + psMetadata* restrict md, ///< Metadata collection to iterate. + const char *restrict match, ///< Beginning of key name. + int which ///< Iterator to be used. +); /** Get previous metadata item. @@ -225,48 +242,55 @@ * @return psMetadataItem* : Pointer metadata item. */ -psMetadataItem* psMetadataGetPrevious(psMetadata* restrict md, ///< Metadata collection to iterate. - const char *restrict match, ///< Beginning of key name. - int which ///< Iterator to be used. - ); +psMetadataItem* psMetadataGetPrevious( + psMetadata* restrict md, ///< Metadata collection to iterate. + const char *restrict match, ///< Beginning of key name. + int which ///< Iterator to be used. +); /** Print metadata item to file. * - * Metadata items may be printed to an open file descriptor based on a provided format. The format is a - * sprintf format statement with exactly one % formatting command. If the metadata item type is a numeric - * type, this formatting command must also be numeric, and the type conversion performed to the value to match - * the format type. If the metadata type is a string, the fromatting command must also be for a string. If the - * metadata type is any other data type, printing is not allowed. - * - * @return psMetadataItem* : Pointer metadata item. - */ -void psMetadataItemPrint(FILE * fd, ///< Pointer to file to write metadata item. - const char *format, ///< Format to print metadata item. - const psMetadataItem* restrict metadataItem ///< Metadata item to print. - ); + * Metadata items may be printed to an open file descriptor based on a + * provided format. The format is a sprintf format statement with exactly + * one % formatting command. If the metadata item type is a numeric type, + * this formatting command must also be numeric, and the type conversion + * performed to the value to match the format type. If the metadata type is + * a string, the fromatting command must also be for a string. If the + * metadata type is any other data type, printing is not allowed. + * + * @return psMetadataItem* : Pointer metadata item. + */ +void psMetadataItemPrint( + FILE * fd, ///< Pointer to file to write metadata item. + const char *format, ///< Format to print metadata item. + const psMetadataItem* restrict metadataItem ///< Metadata item to print. +); /** Read metadata header. * - * Read a metadata header from file. If the file is not found, an error is reported. This file is currently - * unimplemented. - * - * @return psMetadata* : Pointer metadata. - */ -psMetadata* psMetadataReadHeader(psMetadata* output, ///< Resulting metadata from read. - char *extname, ///< File name extension string. - int extnum, ///< File name extension number. Starts at 1. - char *filename ///< Name of file to read. - ); + * Read a metadata header from file. If the file is not found, an error is + * reported. This file is currently unimplemented. + * + * @return psMetadata* : Pointer metadata. + */ +psMetadata* psMetadataReadHeader( + psMetadata* output, ///< Resulting metadata from read. + char *extname, ///< File name extension string. + int extnum, ///< File name extension number. Starts at 1. + char *filename ///< Name of file to read. +); /** Read metadata header. * - * Read a metadata header from file. If the file is not found, an error is reported. - * - * @return psMetadata* : Pointer metadata. - */ -psMetadata* psMetadataFReadHeader(psMetadata* output, ///< Resulting metadata from read. - char *extName, ///< File name extension string. - int extNum, ///< File name extension number. - fitsfile * fd ///< Pointer to file to read. - ); + * Read a metadata header from file. If the file is not found, an error is + * reported. + * + * @return psMetadata* : Pointer metadata. + */ +psMetadata* psMetadataFReadHeader( + psMetadata* output, ///< Resulting metadata from read. + char *extName, ///< File name extension string. + int extNum, ///< File name extension number. + fitsfile * fd ///< Pointer to file to read. +); /// @}