Index: trunk/psLib/src/astronomy/psMetadata.h =================================================================== --- trunk/psLib/src/astronomy/psMetadata.h (revision 1286) +++ trunk/psLib/src/astronomy/psMetadata.h (revision 1288) @@ -10,6 +10,6 @@ * @author Ross Harman, MHPCC * - * @version $Revision: 1.1 $ $Name: not supported by cvs2svn $ - * @date $Date: 2004-07-23 01:30:29 $ + * @version $Revision: 1.2 $ $Name: not supported by cvs2svn $ + * @date $Date: 2004-07-23 18:46:13 $ * * Copyright 2004 Maui High Performance Computing Center, University of Hawaii @@ -71,5 +71,5 @@ psPTR V; ///< Pointer to other type of data. } - data; ///< Union for data types. + data; ///< Union for data types. char *comment; ///< Optional comment ("", not NULL). psList *restrict items; ///< List of psMetadataItems with same name. @@ -142,7 +142,148 @@ */ psMetadata *psMetadataAlloc( - void ///< Void -); - + void ///< Void. +); + +/** Add existing metadata item to 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 *psMetadataAdd( + psMetadata *restrict md, ///< Metadata collection to insert metadat item. + int where, ///< Location to be added. + const char *name, ///< Name of metadata item. + int format, ///< Binary OR combination of metadata type and metadata flag. + 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. +); + +/** 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. +); + +/** 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. +); + +/** Set or reset metadata iterator. + * + * 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. +); + +/** Get next metadata item. + * + * Get next metadata item in iterator list. + * + * @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. +); + +/** Get previous metadata item. + * + * Get previous metadata item in iterator list. + * + * @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. +); + +/** 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 br 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 metadat item. + const psMetadataItem *restrict md ///< Metadata item to print. +); + +/** Read metadata header. + * + * Read a metadata header from file. If the file is not found, an error is reported. + * + * @return psMetadata*: Pointer metadata. + */ +psMetadata *psMetadataReadHeader( + psMetadata *output, ///< Resulting metadata frim read. + const char *extname, ///< File name extension string. + int extnum, ///< File name extension number. + const 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 frim read. + const char *extname, ///< File name extension string. + int extnum, ///< File name extension number. + FILE *fd ///< Pointer to file to read. +); /// @}