/*-------------------------------------------------------------------------*/
/**
   @file	tfits.h
   @author	Yves Jung
   @date	July 1999
   @version	$Revision: 1.5 $
   @brief	FITS table handling
*/
/*--------------------------------------------------------------------------*/

/*
	$Id: tfits.h,v 1.5 2002/01/10 08:53:08 ndevilla Exp $
	$Author: ndevilla $
	$Date: 2002/01/10 08:53:08 $
	$Revision: 1.5 $
*/

#ifndef _TFITS_H_
#define _TFITS_H_

#ifdef __cplusplus
extern "C" {
#endif

/*---------------------------------------------------------------------------
   								Includes
 ---------------------------------------------------------------------------*/

#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include <unistd.h>
	
#include "fits_h.h"
#include "static_sz.h"

/* <dox> */
/*---------------------------------------------------------------------------
   								Defines
 ---------------------------------------------------------------------------*/

/* The following defines the maximum acceptable size for a FITS value */
#define FITSVALSZ					60

#define QFITS_INVALIDTABLE			0
#define QFITS_BINTABLE				1
#define QFITS_ASCIITABLE			2

/*---------------------------------------------------------------------------
   								New types
 ---------------------------------------------------------------------------*/

/*-------------------------------------------------------------------------*/
/**
  @brief    Column object

  This structure contains all information needed to read a column in a table.
  These informations come from the header. 
  The qfits_table object contains a list of qfits_col objects.

  This structure has to be created from scratch and filled if one want to 
  generate a FITS table.
 */
/*-------------------------------------------------------------------------*/
typedef struct _qfits_col_
{
	/** 
	  Number of rows in the column. In a same table, all columns have 
	  the same nelem value.
	 */
	int		nelem ;
	
	/** 
	  Number of elements in one field. There are some differences according
	  types 
	  	- If the field contains a string, natoms = 1. In this case, the number
		of characters is given by ascii_size.
		- If the field contains elements of types 'L', 'I', 'J', 'E', 'D' or
		'B', natoms is simply the number of elements.
		- For complex types ('C' or 'M') natoms is the number of double or 
		float (number of complex * 2).
		- If the field contains elements of type P (pair of int), natoms is
		the number of int (nb of 'P' element * 2)
	*/
	int		natoms ;	
	
	/** 
	  Size of one element in bytes. In ASCII tables, atom_size is the size
	  of the element once it has been converted in its 'destination' type.
	  For example, if "123" is contained in an ASCII table in a column 
	  defined as I type, natoms=1, ascii_size=3, atom_size=4.
	  In ASCII tables:
	   - type 'A' : atom_size = ascii_size = number of chars
	   - type 'I', 'F' or 'E' : atom_size = 4
	   - type 'D' : atom_size = 8
	  In BIN tables :
	   - type 'A' : atom_size = ascii_size = atom_nb = number of chars
	   - type 'L', 'X', B' : atom_size = 1
	   - type 'I' : atom_size = 2
	   - type 'E', 'J', 'C', 'P' : atom_size = 4
	   - type 'D', 'M' : atom_size = 8
	 */
	int		atom_size ;	
	
	/** 
	  Only for ASCII fields (0 otherwise). Nb of characters of the field.
	*/
	int		ascii_size ;
	
	/** 
	  Type of data in the column as specified in TFORM keyword 
	  In ASCII tables : A, I, F, E or D 
	  In BIN tables : L, X, B, I, J, A, E, D, C, M or P 
	*/
	char	atom_type ;

	/** 
	  Number of atoms per field as specified in TFORM keyword 
	  Differ from natoms for ASCII table fields of type different from A: 
	  you can have the string "1234" (natoms = 1) specified as I4 
	  (atom_nb = 4)
	*/
	int		atom_nb ;
	
	/** 
	  Label of the column 
	 */
	char    tlabel[FITSVALSZ] ;

	/** 
	  Unit of the data 
	 */
	char    tunit[FITSVALSZ] ;
	
	/** 
	  Null value
	 */
	char	nullval[FITSVALSZ] ;

	/** 
	  Display format 
	  */
	char	disp[FITSVALSZ] ;
	
	/** 
	  zero and scale are used when the quantity in the field does not	 
	  represent a true physical quantity. Basically, thez should be used
	  when they are present: physical_value = zero + scale * field_value 
	  They are read from TZERO and TSCAL in the header
	 */
	int		zero_present ;	
	float	zero ;        
	int		scale_present ;
	float	scale ;   

	/** 
	  Offset between the beg. of the table and the beg. of the column.
	 */
	int		off_beg ;
	
	/** 
	  Width of the table in bytes
	 */
	int		off_jmp ;
	
	/** 
	  Flag to know if the column is readable. An empty col is not readable
	 */
	int		readable ;
} qfits_col ;

/*-------------------------------------------------------------------------*/
/**
  @brief    Table object

  This structure contains all information needed to read a FITS table.
  These information come from the header. The object is created by 
  qfits_open().
 
  To read a FITS table, here is a code example:
  @code
  int main(int argc, char* argv[])
  {
  	qfits_table     *   table ;
 	int					n_ext ;
	int					i ;

	n_ext = qfits_query_n_ext(argv[1]);
	for (i=0 ; i<n_ext ; i++) {
		if ((table = qfits_table_open(argv[1], i+1)) == NULL) {
			printf("cannot open table [%s]:[%d]\n", argv[1], i+1);
		} else {
			dump_extension(table, stdout, '|', 1, 1) ;
			qfits_table_close(table) ;
		}
	}
	return ;
  }
  @endcode
 */
/*-------------------------------------------------------------------------*/
typedef struct _qfits_table_
{
	/**
		Name of the file the table comes from or it is intended to end to
	 */
	char			filename[FILENAMESZ] ;
	/** 
		Table type. Possible values are QFITS_INVALIDTABLE, QFITS_BINTABLE
		or QFITS_ASCIITABLE
	 */
	int				tab_t ;
	/**
	  Number of columns
	 */
	int				nc ;			
	/** 
	  Array of qfits_col objects
	 */
	qfits_col	*	col ;			
} qfits_table ;

/*---------------------------------------------------------------------------
   							Function prototypes
 ---------------------------------------------------------------------------*/

/*-------------------------------------------------------------------------*/
/**
  @brief    Identify a file as containing a FITS table in extension.
  @param    filename    Name of the FITS file to examine.
  @param    xtnum       Extension number to check (starting from 1).
  @return   int 1 if the extension contains a table, 0 else.

  Examines the requested extension and identifies the presence of a
  FITS table.
 */
/*--------------------------------------------------------------------------*/
int qfits_is_table(char * filename, int xtnum) ;


/*-------------------------------------------------------------------------*/
/**
  @brief    Read a FITS extension.
  @param    filename    Name of the FITS file to examine.
  @param    xtnum       Extension number to read (starting from 1).
  @return   Pointer to newly allocated qfits_table structure.

  Read a FITS table from a given file name and extension, and return a
  newly allocated qfits_table structure. This structure contains the
  following informations:
    - Name of the FITS file associated to table
    - Table type
    - Number of columns in table
    - Array of qfits_col objects

  The table type is an int taking the following values:
    - QFITS_BINTABLE for binary tables
    - QFITS_ASCIITABLE for ascii tables
 */
/*--------------------------------------------------------------------------*/
qfits_table * qfits_table_open(char * filename, int xtnum) ;


/*-------------------------------------------------------------------------*/
/**
  @brief    Free a FITS table and associated pointers
  @param    t qfits_table to free
  @return   void
  Frees all memory associated to a qfits_table structure.
 */
/*--------------------------------------------------------------------------*/
void qfits_table_close(qfits_table * t) ;


/*-------------------------------------------------------------------------*/
/**
  @brief    Extract data from a column in a FITS table
  @param    th      Allocated qfits_table
  @param    colnum  Number of the column to extract (from 0 to colnum-1)
  @return   unsigned char array

  Extract a column from a FITS table and return the data as a bytes 
  array. The returned array type and size are determined by the
  column object in the qfits_table.

  Returned array size in bytes is:
  col->nelem * col->natoms * col->atom_size

  Numeric types are correctly understood and byte-swapped if needed,
  to be converted to the local machine type.

  NULL values have to be handled by the caller
 */
/*--------------------------------------------------------------------------*/
unsigned char * qfits_query_column(
        qfits_table     *   th,
        int                 colnum) ;


/*-------------------------------------------------------------------------*/
/**
  @brief    Extract binary data from a column in a FITS table
  @param    th      Allocated qfits_table
  @param    colnum  Number of the column to extract (from 0 to colnum-1)
  @param    null_value  Value to return when a NULL value comes
  @return   Pointer to void *

  Extract a column from a FITS table and return the data as a generic
  void* array. The returned array type and size are determined by the
  column object in the qfits_table.
    
  Returned array size in bytes is:
  col->nelem * col->atom_nb * col->atom_size
  
  NULL values are recognized and replaced by the specified value.
 */
/*--------------------------------------------------------------------------*/
void * qfits_query_column_data(
        qfits_table     *   th,
        int                 colnum,
        void            *   null_value) ;


/*-------------------------------------------------------------------------*/
/**
  @brief    Save a table to a FITS file with a given FITS header.
  @param    array           Data array.
  @param    table           table
  @param    filename        Name of the image on disk.
  @param    fh              FITS header to insert in the output file.
  @return   -1 in error case, 0 otherwise
 */
/*--------------------------------------------------------------------------*/
int qfits_save_table_hdrdump(
        void            **  array,
        qfits_table     *   table,
        char            *   filename,
        qfits_header    *   fh) ;


/*-------------------------------------------------------------------------*/
/**
  @brief    given a col and a row, find out the string to write for display
  @param    table   table structure
  @param    col_id  col id (0 -> nbcol-1)
  @param    row_id  row id (0 -> nrow-1)
  @param    column  array that contains the column data
  @param    use_zero_scale  Flag to use or not zero and scale
  @return   the string to write
 */
/*--------------------------------------------------------------------------*/
char * qfits_table_field_to_string(
        qfits_table     *   table,
        int                 col_id,
        int                 row_id,
        void            *   column,
        int                 use_zero_scale) ;


/*-------------------------------------------------------------------------*/
/**
  @brief    given a col and a row, find out the string to write for display
  @param    table   table structure
  @param    col_id  col id (0 -> nbcol-1)
  @param    row_id  row id (0 -> nrow-1)
  @param    column  array that contains the column data
  @param    use_zero_scale  Flag to use or not zero and scale
  @return   the string to write
  
  ASCII tables specific
 */
/*--------------------------------------------------------------------------*/
char * qfits_asciitable_field_to_string(
        qfits_table     *   table,
        int                 col_id,
        int                 row_id,
        void            *   column,
        int                 use_zero_scale) ;


/*-------------------------------------------------------------------------*/
/**
  @brief    given a col and a row, find out the string to write for display
  @param    table   table structure
  @param    col_id  col id (0 -> nbcol-1)
  @param    row_id  row id (0 -> nrow-1)
  @param    column  array that contains the column data
  @param    use_zero_scale  Flag to use or not zero and scale
  @return   the string to write
  
  BIN tables specific
 */
/*--------------------------------------------------------------------------*/
char * qfits_bintable_field_to_string(
        qfits_table     *   table,
        int                 col_id,
        int                 row_id,
        void            *   column,
        int                 use_zero_scale) ;

/* </dox> */
#ifdef __cplusplus
}
#endif

#endif
/* vim: set ts=4 et sw=4 tw=75 */