/** @file  psFitsTable.h
 *
 *  @brief Contains Fits I/O routines
 *
 *  @ingroup FileIO
 *
 *  @author Robert DeSonia, MHPCC
 *
 *  @version $Revision: 1.2 $ $Name: not supported by cvs2svn $
 *  @date $Date: 2006-04-04 19:52:42 $
 *
 *  Copyright 2004-2005 Maui High Performance Computing Center, University of Hawaii
 */

#ifndef PS_FITSTABLE_H
#define PS_FITSTABLE_H

#include "psFits.h"

#include "psType.h"
#include "psArray.h"
#include "psVector.h"
#include "psMetadata.h"
#include "psImage.h"

/// @addtogroup FileIO
/// @{

/** Reads a table row.  The current HDU type must be either
 *  PS_FITS_TYPE_BINARY_TABLE or PS_FITS_TYPE_ASCII_TABLE.
 *
 *  @return psMetadata*    The table row's data.  The keys are the column names.
 */
psMetadata* psFitsReadTableRow(
    const psFits* fits,                ///< the psFits object
    int row                            ///< row number to read
);

/** Reads a table column.  The current HDU type must be either
 *  PS_FITS_TYPE_BINARY_TABLE or PS_FITS_TYPE_ASCII_TABLE.
 *
 *  @return psArray*    Array of data items for the specified column or NULL
 *                      if an error occurred.
 */
psArray* psFitsReadTableColumn(
    const psFits* fits,                ///< the psFits object
    const char* colname                ///< the column name
);

/** Reads a table column of numbers.  The current HDU type must be either
 *  PS_FITS_TYPE_BINARY_TABLE or PS_FITS_TYPE_ASCII_TABLE.
 *
 *  @return psVector*    Vector of data for the specified column or NULL
 *                       if an error occurred.
 */
psVector* psFitsReadTableColumnNum(
    const psFits* fits,                ///< the psFits object
    const char* colname                ///< the column name
);


/** Reads a whole FITS table.  The current HDU type must be either
 *  PS_FITS_TYPE_BINARY_TABLE or PS_FITS_TYPE_ASCII_TABLE.
 *
 *  @return psArray*     Array of psMetadata items, which contains the output
 *                       data items of each row.
 *
 *  @see psFitsReadTableRow
 */
psArray* psFitsReadTable(
    psFits* fits                       ///< the psFits object
);

/** Writes a whole FITS table. A new HDU of the type BINTABLE is appended
 *  to the file.
 *
 *  @return bool        TRUE if the write was successful, otherwise FALSE
 *
 *  @see psFitsReadTable
 *  @see psFitsInsertTable
 */
bool psFitsWriteTable(
    psFits* fits,                      ///< the psFits object
    const psMetadata* header,          ///< header items for the new HDU.  Can be NULL.
    const psArray* table
    ///< Array of psMetadata items, which contains the output data items of each row.
);

/** Inserts a whole FITS table. A new HDU of the type BINTABLE is inserted either
 *  before or after, depending on the AFTER parameter, the current HDU.
 *
 *  @return bool        TRUE if the insert/write was successful, otherwise FALSE
 *
 *  @see psFitsWriteTable
 */
bool psFitsInsertTable(
    psFits* fits,                  ///< the psFits object
    const psMetadata* header,      ///< header items for the new HDU.  Can be NULL.
    const psArray* table,
    ///< Array of psMetadata items, which contains the output data items of each row.
    bool after
    ///< TRUE if insert is done after CHDU, otherwise table is inserted before CHDU
);

/** Updates a FITS table.  The current HDU type must be either
 *  PS_FITS_TYPE_BINARY_TABLE or PS_FITS_TYPE_ASCII_TABLE.
 *
 *  @return bool        TRUE if the write was successful, otherwise FALSE
 *
 *  @see psFitsWriteTable
 */
bool psFitsUpdateTable(
    psFits* fits,                      ///< the psFits object
    const psMetadata* data,
    ///< Array of psMetadata items, which contains the output data items of each row.
    int row                            ///< the row number to update.
);

/// @}

#endif // #ifndef PS_FITS_H
