Ticket #160: psMetadata.h

#if !defined(PS_META_DATA_H)
#define PS_META_DATA_H 1

/** \file psMetadata.h
 *  \brief Metadata handling structures and functions
 *  \ingroup AstroGroup
 */

/** Possible types of metadata. */
typedef enum {                          ///< type of val is:
    PS_META_ITEM_SET = 0,               ///< NULL; metadata is in psMetadataType.items
    PS_META_S32,                        ///< int (.i)
    PS_META_F32,                        ///< float (.f)
    PS_META_F64,                        ///< float (.f)
    PS_META_STR,                        ///< string (.v)
    PS_META_IMG,                        ///< image (.v)
    PS_META_JPEG,                       ///< JPEG (.v)
    PS_META_PNG,                        ///< PNG (.v)
    PS_META_ASTROM,                     ///< astrometric coefficients (.v)
    PS_META_UNKNOWN,                    ///< other (.v)
    PS_META_NTYPE                       ///< Number of types; must be last
} psMetadataType;

/** A struct to define a single item of metadata */
typedef struct {
    const int id;                       ///< unique ID for this item
    const char *name;                   ///< Name of item
    psMetadataType type;                ///< type of this item
    const union {
        psS32 S32;                      ///< integer value
        psF32 F32;                      ///< floating value
        psF64 F64;                      ///< double value
        void *void;                     ///< other type
    } data;                             ///< value of metadata
    char *comment;                      ///< optional comment ("", not NULL)
    psDlist *items;                     ///< list of psMetadataItems with the same name
} psMetadataItem;

/** A set of metadata */
typedef struct {
    psDlist *list;                      ///< list of psMetadataItem
    psHash *table;                      ///< hash table of the same metadata
} psMetadata;

/** Functions **************************************************************/
/** \addtogroup AstroGroup Astronomy-Specific Utilities
 *  \{
 */

/** Constructor */
psMetadataItem *psMetadataItemAlloc(const char *name, ///< name of new item of metadata (sprintf format)
                                    psMetadataType type, ///< type of this piece of metadata
                                    const char *comment, ///< comment associated with item
                                    ...)        ///< arguments for name and data
;

psMetadataItem *psMetadataItemAllocV(const char *name, ///< name of new item of metadata (sprintf format)
                                    psMetadataType type, ///< type of this piece of metadata
                                    const char *comment, ///< comment associated with item
                                    va_list ap) ///< arguments for name and data
;

/** Constructor */
psMetadata *psMetadataAlloc(void)   ///< make a new set of metadata
;

/**** Utilities **********************************************************************/

/// Add item to the end of the metadata
bool *psMetadataAddItem(psMetadata *md, ///< metadata to add to
                        int location,   ///< Where to add item
                        psMetadataItem *item) ///< Metatdata item to add
;

/// Add item to the end of the metadata.  Combines psMetadataItemAlloc and psMetadataAppendItem
bool *psMetadataAdd(psMetadata *md,     ///< Metadata to add to
                    int location,       ///< Where to add item
                    const char *name,   ///< name of new item of metadata (sprintf format)
                    int format,         ///< type of this piece of metadata + flags
                    const char *comment, ///< comment associated with item
                    ...)                ///< possible arguments for name format
;

/// delete item from the metadata
bool *psMetadataRemove(psMetadata *md,  ///< metadata to delete from
                       int location,    ///< Where to remove
                       const char *key  ///< Key to delete
    );

/// find the metadata with the specified key
psMetadataItem *psMetadataLookup(const psMetadata *md, ///< metadata to look up
                                 const char *key ///< Key to find
    );

/// retrieve the metadata on the basis of entry position
psMetadataItem *psMetadataGet(const psMetadata *md, ///< metadata to look up
                              int location ///< entry position
    );

/// reset the iterator to the start of the list
void psMetadataSetIterator(psMetadata *md, ///< metadata to set iterator for
                           int iterator, ///< Which iterator to set
                           int location ///< Where to set iterator
                           );

/// get the next item in the sequence
psMetadataItem *psMetadataGetNext(psMetadata *md, ///< metadata to get from
                                  const char *match, ///< String to match
                                  int iterator ///< Which iterator to use
    );

/// get the next item in the sequence
psMetadataItem *psMetadataGetPrevious(psMetadata *md, ///< metadata to get from
                                      const char *match, ///< String to match
                                      int iterator ///< Which iterator to use
    );

/// print metadata item to the specified stream
void psMetadataItemPrint(FILE *fd,      ///< file descriptor to write to
                         const char *format, ///< Format of output
                         const psMetadataItem *md ///< item of metadata to print
    );

/// Read only header from image file.
psMetadata *
psMetadataReadHeader(psMetadata *out,   ///< read data to this structure
                     const char *ext,   ///< MEF extension name ("PHU" for primary header)
                     int extnum,        ///< MEF extension number (-1 for "PHU", 0 : Nextend - 1)
                     const char *file)  ///< file to read from
;

/// Read only header from image file descriptor.
psMetadata *
psMetadataFReadHeader(psMetadata *out,  ///< read data to this structure
                      const char *ext,  ///< MEF extension name ("PHU" for primary header)
                      int extnum,       ///< MEF extension number (-1 for "PHU", 0 : Nextend - 1)
                      FILE *f)          ///< file descriptor to read from
;

/* \} */ // End of AstroGroup Functions
#endif