#ifndef _QFITS_H_
#define _QFITS_H_


/**

	@mainpage	qfits reference Manual

	<hr size="4">

	@section welcome	Introduction

	@b qfits is a stand-alone written in C to handle interactions
	with files complying with the FITS format. It is extremely
	fast and portable over any kind of POSIX-compliant platform.

	This library has not been developped from scratch as a
	library trying to cover the FITS format, but rather built day
	after day upon request. There are several levels of
	complexity, depending on whether you only want to retrieve
	ancillary data from headers, or only read pixels in, or do
	some true data manipulation or header re-formatting.

	This library also comes with a limited set of interfaces to
	Python to make some of its functionalities usable from this
	language. See the compilation instructions to build it as a
	Python module.


	<hr size="4">

	@section history History

	@b qfits was born from the need to have a simple but powerful
	C library to handle everything about FITS file accesses.
	There are already many libraries on the Net to handle FITS
	files, but they tend to be bloated with far too many features
	and would cause lots of problems in including in our own
	software (mainly for portability).

	@b qfits was written to take care of all low-level aspects of
	the FITS format, and only these. You will find there a wealth
	of optimized functions to access everything inside FITS
	files, but nothing about what you could do with the data,
	this is left to other (e.g. image processing) libraries.

	The idea is that people wanting to work with FITS might have
	different requirements: somebody writing an image viewer
	might just want to know the pixel type and buffer size,
	somebody handling headers only might want to have easy access
	to header information without touching pixel data. As soon as
	we introduce a type for pixels, we would oblige users of this
	library to subscribe to our conventions for pixel
	representation, which is considered too constraining to be a
	helpful feature.

	qfits offers three pixel loaders that are able to load image
	data into a memory buffer. These loaders return a pointer to
	int, a pointer to float, or a pointer to double, whatever
	kind of representation is used on your machine.

	<hr size="4">

	@section authors Authors

	Nicolas Devillard and Yves Jung, ESO.

	<hr size="4">

	@section overview Overview

	There are two parts to consider in FITS files: the headers,
	and the data arrays. Headers are simply formatted as 80-char
	lines (cards) containing ancillary data represented in ASCII
	format like:

	keyword = value / comment

	If you want to retrieve data from a FITS file header,
	simple.c offers various useful query routines to get a
	keyword value from main or extension headers.

	If you want to parse a FITS line into its components, see
	fits_p.c which offers various routines to do so.

	The data parts are also quite simply stored: they always
	contain data contiguously in uncompressed format, so reading
	them is mostly a matter of applying an @c fread() statement
	at the right place in the file, with the right size. The
	whole issue is to know where the samples are located in the
	file. simple.c also offers various query methods that will
	help you identify what sections are available and where.

	You may also want to load a whole FITS header into memory to
	work on it, e.g. to modify it and dump it into a new file. In
	this case, you want to use the qfits_header object.
	Once loaded into memory, a qfits_header object remains opaque
	and only accessible through the offered interface. You can
	retrieve/add/delete/modify keywords and keyword values. There
	are several things to notice about this object:

	- FITS headers are internally loaded as sets of strings, i.e.
	  no conversion is done to coerce numeric values to C numeric
	  types. Type recognition can be done using one of the
	  routines in simple and type coercion can be done by
	  calling the right method in fits_h.h.
	  
	- The default behaviour is to leave a FITS line untouched if
	  it has been read from a file. This ensures that lines which
	  have not been modified are kept as they were in the initial
	  file. A method of the qfits_header object allows to
	  @e touch a header, requesting all cards to be reformatted.

	@b qfits supports querying data from FITS extensions, and
	includes a caching mechanism to accelerate accesses to
	large files to an optimal access time (only one parsing of
	the file is needed, even with multiple queries on the same
	file). This mechanism is internal to this module and used
	invisibly for the programmer using @b qfits.

	@b qfits is reasonably small and simple to be included in any
	C/C++/Python project in need of all basic FITS
	functionalities. It is by no means the most complete FITS
	library available, but tries to cover enough functionalities
	to avoid the hardest part of FITS handling: efficient header
	parsing and storage in memory.

	Pixel loading is supported for images (for a cube and greater
	dimensions, apply the image pixel loader iteratively). The
	loader can return pixels as an allocated buffer of int,
	float, or double, whatever the representation used for these
	types on your platform.

	<hr size="4">

	@section features	Features

	Some of the unique features of this library are:

	@subsection features1	Portability

	This library has been ported and tested on the following
	platforms:

	- Linux x86 and alpha
	- Solaris 2.5, 2.6 and 2.8
	- HPUX 8, 9, 10, 11
	- AIX
	- BSD
	- Darwin (Mac OS X)
	- Tru64

	There is little chance that it could ever compile on Windows,
	except with the help from GNU tools (cygnus).

	@subsection features2	Speed

	The offered routines are extremely fast, making use of
	caching mechanisms and memory-mapping system calls to enhance
	FITS file parsing.

	@subsection features3	Interfaces to C++/Python

	You should be able to compile this library with a C++
	compiler, the header files include the usual blurb to allow
	that without warning from the compiler. You might have
	problems due to pointer casts and other various
	incompatibilities due to the variety of C++ dialects and
	compilers, though. If you really need to hook this library
	into C++ code, your best bet is probably to compile the
	library as a standard C library and link your C++ code
	against it.

	A limited set of interfaces to Python is offered. See below
	to install the Python module on your machine.

	The Python interfaces were initially generated by SWIG,
	they are now hand-written for portability between different
	versions of Python.

	@subsection features10	Numerical precision

	Since FITS headers are stored as strings, numerical precision
	is limited by the number of digits used to write a number in
	a FITS card, which is in theory larger than what a 32-bit
	floating-point can store. Using @b qfits, these values are
	available to a C programmer as a string, making sure that
	precision has at least not be lost in the reading process.

	@subsection features11	Conservative headers

	If you only need to load a header, modify a card and save it
	back, you will find out that @e only the card you touched has
	been modified, the rest was verbatim transferred. This is
	useful to ensure that the library formatting does not disturb
	your format. If you really want the library to reformat all
	cards, use the method dedicated to that purpose.

	@subsection features12	Native HIERARCH support

	Native support for @e HIERARCH keywords, as well as keywords
	of any length (up to 80 chars per line).

	@subsection features13	ESO/DICB keyword ordering

	Native support for DICB (ESO only) ordering of keywords in
	the headers. If you use this library to produce FITS files,
	you can reasonably be sure that all the files you create will
	be DICB compliant with respect to keyword ordering.

	@subsection features13	Memory model

	qfits does not only offer pixel loading mechanisms, it also
	comes bundled with a memory module based on a model optimized
	for the handling of very large data segments. In practice,
	it means that as soon as you have included qfits.h, your
	calls to malloc/calloc/free are re-directed to specific versions
	which put your program on steroids. Calls to memory allocators
	will yield valid data pointers past the hardware limits of your
	machine, up to 2 or 4 Gb on a 32-bit workstation and insanely
	high values on 64-bit processors.

	This memory module is also distributed as a stand-alone module
	which can be downloaded and used without qfits. It is mandatory
	to use this module when using qfits, to get the advantages of
	large memory handling.


	<hr size="4">

	@section install Installation instructions

	In the main @b qfits directory, type:

	@verbatim	
./configure ; make
	@endverbatim	

	To use the library in your programs, add the following line on top
	of your module:

	@code
#include "qfits.h"
	@endcode

	And link your program with the qfits library by adding
	@c -lqfits to the compile line.

	Notice that the only header file you need is qfits.h. This
	file contains all prototypes and symbols for the qfits
	library, so you can safely move it around.

	To compile @b qfits as a Python module, you need to have
	Python installed on your machine and available in your PATH.
	Type:

	@verbatim
% python setup.py install
	@endverbatim

	This should build the module and install it in your default library
	path. This makes use of the distutils package, standardized since
	Python 2.0. This means that you need Python 2.0 at least to
	compile and run this module.


	<hr size="4">

	@section low Reference manual for low-level functions

	These routines are low-level mechanisms that make life
	simpler for various situations. Although they are present in the
	library, they are lower level and not intended for any other module
	than @b qfits. Feel free to use them if you need!

	- byteswap.h offers routines to detect the endian-ness of the local
	  host at run-time and generic (fast) byte-swapping functions to swap
	  variables of any (even) size.
	- qerror.h offers routines handling communication between the library
	  and the console. This makes it easy to re-direct error/info messages
	  from @b qfits to other channels.
	- idformat.h offers various routines to identify file formats.
	- strlib.h offers various string processing services to complete the
	  standard C library.
	- t_iso8601.h offers routines to get the current date, possibly in ISO
	  8601 format.

	<hr size="4">

	@section high Reference manual for high-level functions

	High-level functions allow to load, write and manipulate FITS
	headers. They also provide enough informations about the file to
	be able to load the data. For table, a generic data loader is
	provided.

	- cache.h contains the implementation of the @b qfits caching
	  mechanism. This mechanism is purely internal and no function in this
	  module is meant to be directly called by @b qfits users.
	- expkey.h is a simple utility function to convert keywords between the
	  shortFITS and HIERARCH notation (ESO only).
	- fits_h.h offers all interfaces to the @b qfits_header object.
	- fits_md5.h contains a routine to compute the MD5 sum of all data
	  parts of a FITS file, e.g. to associate a signature to it.
	- fits_p.h is a FITS line parser, offering routines to separate a FITS
	  line into its components.
	- fits_rw.h offers read/write methods to the @c qfits_header object.
	- simple.h contains various useful query utilities.
	- tfits.h contains FITS table handling routines.


	<hr size="4">

	@section faq	Frequently Asked Questions

	@subsection faq1 Where should I start to use qfits?
	
	Try to build the library on your system first. You should
	then have a new library file called libqfits.a. To use the
	library functionalities in your programs, you must add the
	following include in your list of includes:

	  @verbatim
#include "qfits.h"
	  @endverbatim

	And then compile your program adding the correct flags to
	indicate where the @b qfits.h header file is, where the
	libqfits.a file is, and that you want to link against
	libqfits. Example: if the header file is in /usr/local/include and
	the library in /usr/local/lib, you would use:

	@verbatim
% cc -o myprog myprog.c -I/usr/local/include -L/usr/local/lib -lqfits
 	@endverbatim


	@subsection faq3 What should I know about the cache mechanism?

	Parsing FITS files to find extensions is a lengthy process,
	because the FITS format does not declare in the main header
	where the following extensions are located in the file.
	Any access to a FITS file with this library will cache a
	number of offset pointers in the file to allow fast access to
	extensions. This means that the file is parsed completely
	only once, the first time it is accessed through any of the
	qfits functions.

	This has two side-effects, due to the cache implementation.
	The cache is a memory buffer located inside the @b qfits
	library, which will grow for any new FITS file presented to
	its query functions. The amount of memory taken for each new
	file is small (less than 100 bytes), but will nonetheless
	accumulate if you start reading lots of new FITS files in an
	application that is meant to live a relatively long amount of
	time. To prevent the cache from growing indefinitely, a cache
	purging mechanism is installed, which will clear the cache
	every time you reach 4096 FITS files in the cache, which
	corresponds roughly to 300 kbytes. If you are working with
	huge number of files simultaneously and need to access them
	often, you might want to increase this limit in cache.c.

	The second side-effet is that the cache structure makes the
	cache module thread-unsafe. If you are concerned about
	writing multi-threaded applications, you should put a mutex
	on accessing this library. A thread-safe compliant version
	might become available some day, so if you want to help...

	<hr size="4">

	@section news	Latest news

	30 Nov 2001

	A new version of the library is about to be released.
	Lots of things have changed in the C API, mainly to make
	the namespace safe (all names start with qfits_).
	The Python interface in C has been rewritten by hand and
	simplified a lot, the Qfits.py interface file has also
	been completely changed, and that is backwards incompatible
	(sorry!).



 */

#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include <unistd.h>

extern char * qfits_version(void);


/* FITS header constants */

/** FITS block size */
#define FITS_BLOCK_SIZE     (2880)
/** FITS number of cards per block */
#define FITS_NCARDS 		(36)
/** FITS size of each line in bytes */
#define FITS_LINESZ 		(80)

/** FITS magic number */
#define FITS_MAGIC			"SIMPLE"
/** Size of the FITS magic number */
#define FITS_MAGIC_SZ		6




/* FITS pixel depths */

/** FITS BITPIX=8 */
#define BPP_8_UNSIGNED        (8)
/** FITS BITPIX=16 */
#define BPP_16_SIGNED        (16)
/** FITS BITPIX=32 */
#define BPP_32_SIGNED        (32)
/** FITS BITPIX=-32 */
#define BPP_IEEE_FLOAT      (-32)
/** FITS BITPIX=-64 */
#define BPP_IEEE_DOUBLE     (-64)

/** Default BITPIX for output */
#define BPP_DEFAULT         BPP_IEEE_FLOAT

/** Compute the number of bytes per pixel for a given BITPIX value */
#define BYTESPERPIXEL(x)    (   ((x) == BPP_8_UNSIGNED) ?     1 : \
                                ((x) == BPP_16_SIGNED)  ?     2 : \
                                ((x) == BPP_32_SIGNED)  ?     4 : \
                                ((x) == BPP_IEEE_FLOAT) ?     4 : \
                                ((x) == BPP_IEEE_DOUBLE) ?    8 : 0 ) 


/*-------------------------------------------------------------------------*/
/**
  @brief    Purge the qfits cache.
  @return   void

  This function is useful for programs running for a long period,
  to clean up the cache. Ideally in a daemon, it should be called
  by a timer at regular intervals. Notice that since the cache is
  fairly small, you should not need to care too much about this.
 */
/*--------------------------------------------------------------------------*/
void qfits_cache_purge(void);
/*-------------------------------------------------------------------------*/
/**
  @brief    Expand a keyword from shortFITS to HIERARCH notation.
  @param    keyword     Keyword to expand.
  @return   1 pointer to statically allocated string.

  This function expands a given keyword from shortFITS to HIERARCH
  notation, bringing it to uppercase at the same time.

  Examples:

  @verbatim
  det.dit          expands to     HIERARCH ESO DET DIT
  ins.filt1.id     expands to     HIERARCH ESO INS FILT1 ID
  @endverbatim

  If the input keyword is a regular FITS keyword (i.e. it contains
  not dots '.') the result is identical to the input.
 */
/*--------------------------------------------------------------------------*/
char * qfits_expand_keyword(char * keyword);
/*-------------------------------------------------------------------------*/
/**
  @brief	FITS header object

  This structure represents a FITS header in memory. It is actually no
  more than a thin layer on top of the keytuple object. No field in this
  structure should be directly modifiable by the user, only through
  accessor functions.

 */
/*-------------------------------------------------------------------------*/

typedef struct _qfits_header_ {
	void *	first ;		/* Pointer to list start */
	void *	last ;		/* Pointer to list end */
	int			n ;			/* Number of cards in list */
} qfits_header ;



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

/*-------------------------------------------------------------------------*/
/**
  @brief    FITS header constructor
  @return   1 newly allocated (empty) FITS header object.

  This is the main constructor for a qfits_header object. It returns
  an allocated linked-list handler with an empty card list.

 */
/*--------------------------------------------------------------------------*/
qfits_header * qfits_header_new(void);

/*-------------------------------------------------------------------------*/
/**
  @brief    FITS header default constructor.
  @return   1 newly allocated qfits_header object.

  This is a secondary constructor for a qfits_header object. It returns
  an allocated linked-list handler containing two cards: the first one
  (SIMPLE=T) and the last one (END).

 */
/*--------------------------------------------------------------------------*/
qfits_header * qfits_header_default(void);

/*-------------------------------------------------------------------------*/
/**
  @brief    Add a new card to a FITS header
  @param    hdr qfits_header object to modify
  @param    key FITS key
  @param    val FITS value
  @param    com FITS comment
  @param    lin FITS original line if exists
  @return   void

  This function adds a new card into a header, at the one-before-last
  position, i.e. the entry just before the END entry if it is there.
  The key must always be a non-NULL string, all other input parameters
  are allowed to get NULL values.
 */
/*--------------------------------------------------------------------------*/
void qfits_header_add(
    qfits_header * hdr,
    char    * key,
    char    * val,
    char    * com,
    char    * lin);


/*-------------------------------------------------------------------------*/
/**
  @brief    add a new card to a FITS header
  @param    hdr     qfits_header object to modify
  @param    after   Key to specify insertion place
  @param    key     FITS key
  @param    val     FITS value
  @param    com     FITS comment
  @param    lin     FITS original line if exists
  @return   void

  Adds a new card to a FITS header, after the specified key. Nothing
  happens if the specified key is not found in the header. All fields
  can be NULL, except after and key.
 */
/*--------------------------------------------------------------------------*/
void qfits_header_add_after(
    qfits_header * hdr,
    char    * after,
    char    * key,
    char    * val,
    char    * com,
    char    * lin);

/*-------------------------------------------------------------------------*/
/**
  @brief    Append a new card to a FITS header.
  @param    hdr qfits_header object to modify
  @param    key FITS key
  @param    val FITS value
  @param    com FITS comment
  @param    lin FITS original line if exists
  @return   void

  Adds a new card in a FITS header as the last one. All fields can be
  NULL except key.
 */
/*--------------------------------------------------------------------------*/
void qfits_header_append(
    qfits_header *   hdr,
    char    * key,
    char    * val,
    char    * com,
    char    * lin);


/*-------------------------------------------------------------------------*/
/**
  @brief    Delete a card in a FITS header.
  @param    hdr qfits_header to modify
  @param    key specifies which card to remove
  @return   void

  Removes a card from a FITS header. The first found card that matches
  the key is removed.
 */
/*--------------------------------------------------------------------------*/
void qfits_header_del(qfits_header * hdr, char * key);


/*-------------------------------------------------------------------------*/
/**
  @brief    Modifies a FITS card.
  @param    hdr qfits_header to modify
  @param    key FITS key
  @param    val FITS value
  @param    com FITS comment
  @return   void

  Finds the first card in the header matching 'key', and replaces its
  value and comment fields by the provided values. The initial FITS
  line is set to NULL in the card.
 */
/*--------------------------------------------------------------------------*/
void qfits_header_mod(qfits_header * hdr, char * key, char * val, char * com);


/*-------------------------------------------------------------------------*/
/**
  @brief    Updates a given header with another one.
  @param    base    Base header to update.
  @param    update  Updating header.
  @return   Newly allocated qfits_header object.
  @doc

  A new header is created from both input headers. It contains:

  - All keywords present in 'base' and not in 'update'.
  - All keywords present in 'update' and not in 'base'.
  - All keywords present in both headers with the same value.
  - In case of conflict (a keyword present in both headers but with
    different values), the key from the 'update' keyword is used.

  The returned header must be freed using qfits_header_destroy.
 */
/*--------------------------------------------------------------------------*/
qfits_header * qfits_header_merge(qfits_header * base, qfits_header * update);


/*-------------------------------------------------------------------------*/
/**
  @brief    Copy a FITS header
  @param    src Header to replicate
  @return   Pointer to newly allocated qfits_header object.

  Makes a strict copy of all information contained in the source
  header. The returned header must be freed using qfits_header_destroy.
 */
/*--------------------------------------------------------------------------*/
qfits_header * qfits_header_copy(qfits_header * src);


/*-------------------------------------------------------------------------*/
/**
  @brief    Touch all cards in a FITS header
  @param    hdr qfits_header to modify
  @return   void

  Touches all cards in a FITS header, i.e. all original FITS lines are
  freed and set to NULL. Useful when a header needs to be reformatted.
 */
/*--------------------------------------------------------------------------*/
void qfits_header_touchall(qfits_header * hdr);


/*-------------------------------------------------------------------------*/
/**
  @brief    Dump a FITS header to stdout
  @param    hdr qfits_header to dump
  @return   void

  Dump a FITS header to stdout. Mostly for debugging purposes.
 */
/*--------------------------------------------------------------------------*/
void qfits_header_consoledump(qfits_header * hdr);


/*-------------------------------------------------------------------------*/
/**
  @brief    qfits_header destructor
  @param    hdr qfits_header to deallocate
  @return   void

  Frees all memory associated to a given qfits_header object.
 */
/*--------------------------------------------------------------------------*/
void qfits_header_destroy(qfits_header * hdr);


/*-------------------------------------------------------------------------*/
/**
  @brief    Return the value associated to a key, as a string
  @param    hdr qfits_header to parse
  @param    key key to find
  @return   pointer to statically allocated string

  Finds the value associated to the given key and return it as a
  string. The returned pointer is statically allocated, so do not
  modify its contents or try to free it.

  Returns NULL if no matching key is found or no value is attached.
 */
/*--------------------------------------------------------------------------*/
char * qfits_header_getstr(qfits_header * hdr, char * key);


/*-------------------------------------------------------------------------*/
/**
  @brief    Find a matching key in a header.
  @param    hdr qfits_header to parse
  @param    key Key prefix to match
  @return   pointer to statically allocated string.

  This function finds the first keyword in the given header for 
  which the given 'key' is a prefix, and returns the full name
  of the matching key (NOT ITS VALUE). This is useful to locate
  any keyword starting with a given prefix. Careful with HIERARCH
  keywords, the shortFITS notation is not likely to be accepted here.

  Examples:

  @verbatim
  s = qfits_header_findmatch(hdr, "SIMP") returns "SIMPLE"
  s = qfits_header_findmatch(hdr, "HIERARCH ESO DET") returns
  the first detector keyword among the HIERACH keys.
  @endverbatim
 */
/*--------------------------------------------------------------------------*/
char * qfits_header_findmatch(qfits_header * hdr, char * key);


/*-------------------------------------------------------------------------*/
/**
  @brief    Return the i-th key/val/com/line tuple in a header.
  @param    hdr     Header to consider
  @param    idx     Index of the requested card
  @param    key     Output key
  @param    val     Output value
  @param    com     Output comment
  @param    lin     Output initial line
  @return   int 0 if Ok, -1 if error occurred.

  This function is useful to browse a FITS header object card by card.
  By iterating on the number of cards (available in the 'n' field of
  the qfits_header struct), you can retrieve the FITS lines and their
  components one by one. Indexes run from 0 to n-1. You can pass NULL
  values for key, val, com or lin if you are not interested in a
  given field.

  @code
  int i ;
  char key[80], val[80], com[80], lin[80] ;

  for (i=0 ; i<hdr->n ; i++) {
    qfits_header_getitem(hdr, i, key, val, com, lin);
    printf("card[%d] key[%s] val[%s] com[%s]\n", i, key, val, com);
  }
  @endcode

 */
/*--------------------------------------------------------------------------*/
int qfits_header_getitem(
    qfits_header    *   hdr,
    int                 idx,
    char            *   key,
    char            *   val,
    char            *   com,
    char            *   lin
);


/*-------------------------------------------------------------------------*/
/**
  @brief    Return the FITS line associated to a key, as a string
  @param    hdr qfits_header to parse
  @param    key key to find
  @return   pointer to statically allocated string

  Finds the FITS line associated to the given key and return it as a
  string. The returned pointer is statically allocated, so do not
  modify its contents or try to free it.

  Returns NULL if no matching key is found or no line is attached.
 */
/*--------------------------------------------------------------------------*/
char * qfits_header_getline(qfits_header * hdr, char * key);


/*-------------------------------------------------------------------------*/
/**
  @brief    Return the comment associated to a key, as a string
  @param    hdr qfits_header to parse
  @param    key key to find
  @return   pointer to statically allocated string
  @doc

  Finds the comment associated to the given key and return it as a
  string. The returned pointer is statically allocated, so do not
  modify its contents or try to free it.

  Returns NULL if no matching key is found or no comment is attached.
 */
/*--------------------------------------------------------------------------*/
char * qfits_header_getcom(qfits_header * hdr, char * key);


/*-------------------------------------------------------------------------*/
/**
  @brief    Return the value associated to a key, as an int
  @param    hdr qfits_header to parse
  @param    key key to find
  @param    errval default value to return if nothing is found
  @return   int

  Finds the value associated to the given key and return it as an
  int. Returns errval if no matching key is found or no value is
  attached.
 */
/*--------------------------------------------------------------------------*/
int qfits_header_getint(qfits_header * hdr, char * key, int errval);

/*-------------------------------------------------------------------------*/
/**
  @brief    Return the value associated to a key, as a double
  @param    hdr qfits_header to parse
  @param    key key to find
  @param    errval default value to return if nothing is found
  @return   double

  Finds the value associated to the given key and return it as a
  double. Returns errval if no matching key is found or no value is
  attached.
 */
/*--------------------------------------------------------------------------*/
double qfits_header_getdouble(qfits_header * hdr, char * key, double errval);

/*-------------------------------------------------------------------------*/
/**
  @brief    Return the value associated to a key, as a boolean (int).
  @param    hdr qfits_header to parse
  @param    key key to find
  @param    errval default value to return if nothing is found
  @return   int

  Finds the value associated to the given key and return it as a
  boolean. Returns errval if no matching key is found or no value is
  attached. A boolean is here understood as an int taking the value 0
  or 1. errval can be set to any other integer value to reflect that
  nothing was found.

  errval is returned if no matching key is found or no value is
  attached.

  A true value is any character string beginning with a 'y' (yes), a
  't' (true) or the digit '1'. A false value is any character string
  beginning with a 'n' (no), a 'f' (false) or the digit '0'.
 */
/*--------------------------------------------------------------------------*/
int qfits_header_getboolean(qfits_header * hdr, char * key, int errval);

/*-------------------------------------------------------------------------*/
/**
  @brief    Write out a key tuple to a string on 80 chars.
  @param    line    Allocated output character buffer.
  @param    key     Key to write.
  @param    val     Value to write.
  @param    com     Comment to write.
  @return   void

  Write out a key, value and comment into an allocated character buffer.
  The buffer must be at least 80 chars to receive the information.
  Formatting is done according to FITS standard.
 */
/*--------------------------------------------------------------------------*/
void keytuple2str(char * line, char * key, char * val, char * com);

/*-------------------------------------------------------------------------*/
/**
  @brief    Dump a FITS header to an opened file.
  @param    hdr     FITS header to dump
  @param    out     Opened file pointer
  @return   int 0 if Ok, -1 otherwise

  Dumps a FITS header to an opened file pointer.
 */
/*--------------------------------------------------------------------------*/
int qfits_header_dump(qfits_header * hdr, FILE * out);

/*-------------------------------------------------------------------------*/
/**
  @brief    Dump a fits header into a memory block.
  @param    fh      FITS header to dump
  @param    hsize   Size of the returned header, in bytes (output).
  @return   1 newly allocated memory block containing the FITS header.

  This function dumps a FITS header structure into a newly allocated
  memory block. The block is composed of characters, just as they would
  appear in a FITS file. This function is useful to make a FITS header
  in memory.

  The returned block size is indicated in the passed output variable
  'hsize'. The returned block must be deallocated using free().
 */
/*--------------------------------------------------------------------------*/
char * qfits_header_to_memblock(qfits_header * fh, int * hsize);
/*-------------------------------------------------------------------------*/
/**
  @brief    Compute the MD5 hash of data zones in a FITS file.
  @param    filename    Name of the FITS file to examine.
  @return   1 statically allocated character string, or NULL.

  This function expects the name of a FITS file.
  It will compute the MD5 hash on all data blocks in the main data section
  and possibly extensions (including zero-padding blocks if necessary) and
  return it as a string suitable for inclusion into a FITS keyword.

  The returned string is statically allocated inside this function,
  so do not free it or modify it. This function returns NULL in case
  of error.
 */
/*--------------------------------------------------------------------------*/
char * qfits_datamd5(char * filename);
/*---------------------------------------------------------------------------
						Function ANSI C prototypes
 ---------------------------------------------------------------------------*/

/*-------------------------------------------------------------------------*/
/**
  @brief    Find the keyword in a key card (80 chars)   
  @param    line allocated 80-char line from a FITS header
  @return   statically allocated char *

  Find out the part of a FITS line corresponding to the keyword.
  Returns NULL in case of error. The returned pointer is statically
  allocated in this function, so do not modify or try to free it.
 */
/*--------------------------------------------------------------------------*/
char * qfits_getkey(char * line);


/*-------------------------------------------------------------------------*/
/**
  @brief    Find the value in a key card (80 chars) 
  @param    line allocated 80-char line from a FITS header
  @return   statically allocated char *

  Find out the part of a FITS line corresponding to the value.
  Returns NULL in case of error, or if no value can be found. The
  returned pointer is statically allocated in this function, so do not
  modify or try to free it.
 */
/*--------------------------------------------------------------------------*/
char * qfits_getvalue(char * line);

/*-------------------------------------------------------------------------*/
/**
  @brief    Find the comment in a key card (80 chars)   
  @param    line allocated 80-char line from a FITS header
  @return   statically allocated char *

  Find out the part of a FITS line corresponding to the comment.
  Returns NULL in case of error, or if no comment can be found. The
  returned pointer is statically allocated in this function, so do not
  modify or try to free it.
 */
/*--------------------------------------------------------------------------*/
char * qfits_getcomment(char * line);
/*-------------------------------------------------------------------------*/
/**
  @brief    Read a FITS header from a file to an internal structure.
  @param    filename    Name of the file to be read
  @return   Pointer to newly allocated qfits_header

  This function parses a FITS (main) header, and returns an allocated
  qfits_header object. The qfits_header object contains a linked-list of
  key "tuples". A key tuple contains:

  - A keyword
  - A value
  - A comment
  - An original FITS line (as read from the input file)

  Direct access to the structure is not foreseen, use accessor
  functions in fits_h.h

  Value, comment, and original line might be NULL pointers.
  The qfits_header type is an alias for the llist_t type from the list
  module, which should remain opaque.

  Returns NULL in case of error.
 */
/*--------------------------------------------------------------------------*/
qfits_header * qfits_header_read(char * filename);


/*-------------------------------------------------------------------------*/
/**
  @brief    Read an extension header from a FITS file.
  @param    filename    Name of the FITS file to read
  @param    xtnum       Extension number to read, starting from 1.
  @return   Newly allocated qfits_header structure.

  Strictly similar to fits_read_header() but reads headers from
  extensions instead.

  Returns NULL in case of error.
 */
/*--------------------------------------------------------------------------*/
qfits_header * qfits_header_readext(char * filename, int xtnum);


/*-------------------------------------------------------------------------*/
/**
  @brief    Pad an existing file with zeros to a multiple of 2880.
  @param    filename    Name of the file to pad.
  @return   void

  This function simply pads an existing file on disk with enough zeros
  for the file size to reach a multiple of 2880, as required by FITS.
 */
/*--------------------------------------------------------------------------*/
void qfits_zeropad(char * filename);


/*-------------------------------------------------------------------------*/
/**
  @brief    Identify if a file is a FITS file.
  @param    filename name of the file to check
  @return   int 0, 1, or -1

  Returns 1 if the file name looks like a valid FITS file. Returns
  0 else. If the file does not exist, returns -1.
 */
/*--------------------------------------------------------------------------*/
int is_fits_file(char *filename);

/*---------------------------------------------------------------------------
   								Defines
 ---------------------------------------------------------------------------*/

/** Symbol to set returned pixel type to float */
#define PTYPE_FLOAT		0
/** Symbol to set returned pixel type to int */
#define PTYPE_INT		1
/** Symbol to set returned pixel type to double */
#define PTYPE_DOUBLE	2

/** FITS BITPIX=8 */
#define BPP_8_UNSIGNED        (8)
/** FITS BITPIX=16 */
#define BPP_16_SIGNED        (16)
/** FITS BITPIX=32 */
#define BPP_32_SIGNED        (32)
/** FITS BITPIX=-32 */
#define BPP_IEEE_FLOAT      (-32)
/** FITS BITPIX=-64 */
#define BPP_IEEE_DOUBLE     (-64)

/** Default BITPIX for output */
#define BPP_DEFAULT         BPP_IEEE_FLOAT

/** Compute the number of bytes per pixel for a given BITPIX value */
#define BYTESPERPIXEL(x)    (   ((x) == BPP_8_UNSIGNED) ?     1 : \
                                ((x) == BPP_16_SIGNED)  ?     2 : \
                                ((x) == BPP_32_SIGNED)  ?     4 : \
                                ((x) == BPP_IEEE_FLOAT) ?     4 : \
                                ((x) == BPP_IEEE_DOUBLE) ?    8 : 0 ) 


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

/*-------------------------------------------------------------------------*/
/**
  @brief	qfits loader control object

  This structure serves two purposes: input and output for the qfits
  pixel loading facility. To request pixels from a FITS file, you
  need to allocate (statically or dynamically) such a structure and
  fill up the input fields (filename, xtension number, etc.) to specify
  the pixels you want from the file.

  Before performing the actual load, you must pass the initialized
  structure to qfitsloader_init() which will check whether the operation
  is feasible or not (check its returned value).

  If the operation was deemed feasible, you can proceed to load the pixels,
  passing the same structure to qfits_loadpix() which will fill up the
  output fields of the struct. Notice that a pixel buffer will have been
  allocated (through malloc or mmap) and placed into the structure. You
  need to call free() on this pointer when you are done with it,
  typically in the image or cube destructor.

  The qfitsloader_init() function is also useful to probe a FITS file
  for useful informations, like getting the size of images in the file,
  the pixel depth, or data offset.

  Example of a code that prints out various informations about
  a plane to load, without actually loading it:

  @code
int main(int argc, char * argv[])
{
	qfitsloader	ql ;

	ql.filename = argv[1] ;
	ql.xtnum    = 0 ;
	ql.pnum     = 0 ;

	if (qfitsloader_init(&ql)!=0) {
		printf("cannot read info about %s\n", argv[1]);
		return -1 ;
	}

	printf(	"file         : %s"
			"xtnum        : %d"
			"pnum         : %d"
			"# xtensions  : %d"
			"size X       : %d"
			"size Y       : %d"
			"planes       : %d"
			"bitpix       : %d"
			"datastart    : %d"
			"bscale       : %g"
			"bzero        : %g",
			ql.filename,
			ql.xtnum,
			ql.pnum,
			ql.exts,
			ql.lx,
			ql.ly,
			ql.np,
			ql.bitpix,
			ql.seg_start,
			ql.bscale,
			ql.bzero);
	return 0 ;
}
  @endcode

 */
/*-------------------------------------------------------------------------*/
typedef struct _qfitsloader_ {

	/** Private field to see if structure has been initialized */
	int			_init ;
	
	/** input: Name of the file you want to read pixels from */
	char	*	filename ;
	/** input: xtension number you want to read */
	int			xtnum ;
	/** input: Index of the plane you want, from 0 to np-1 */
	int			pnum ;
	/** input: Pixel type you want (PTYPE_FLOAT, PTYPE_INT or PTYPE_DOUBLE) */
	int			ptype ;

	/** output: Total number of extensions found in file */
	int			exts ;
	/** output: Size in X of the requested plane */
	int			lx ;
	/** output: Size in Y of the requested plane */
	int			ly ;
	/** output: Number of planes present in this extension */
	int			np ;
	/** output: BITPIX for this extension */
	int			bitpix ;
	/** output: Start of the data segment (in bytes) for your request */
	int			seg_start ;
	/** output: BSCALE found for this extension */
	double		bscale ;
	/** output: BZERO found for this extension */
	double		bzero ;

	/** output: Pointer to pixel buffer loaded as integer values */
	int		*	ibuf ;
	/** output: Pointer to pixel buffer loaded as float values */
	float	*	fbuf ;
	/** output: Pointer to pixel buffer loaded as double values */
	double	*	dbuf ;

} qfitsloader ;


/*-------------------------------------------------------------------------*/
/**
  @brief	qfits dumper control object

  This structure offers various control parameters to dump a pixel
  buffer to a FITS file. The buffer will be dumped as requested
  to the requested file in append mode. Of course, the requested file
  must be writeable for the operation to succeed.

  The following example demonstrates how to save a linear ramp sized
  100x100 to a FITS file with BITPIX=16. Notice that this code only
  dumps the pixel buffer, no header information is provided in this
  case.

  @code
    int   i, j ;
	int * ibuf ;
	qfitsdumper	qd ;

	ibuf = malloc(100 * 100 * sizeof(int));
	for (j=0 ; j<100 ; j++) {
		for (i=0 ; i<100 ; i++) {
			ibuf[i+j*100] = i+j ;
		}
	}

	qd.filename  = "out.fits" ;
	qd.npix      = 100 * 100 ;
	qd.ptype     = PTYPE_INT ;
	qd.ibuf      = ibuf ;
	qd.out_ptype = BPP_16_SIGNED ;

	free(ibuf);
  @endcode
  
  If the provided output file name is "STDOUT" (all capitals), the
  function will dump the pixels to the stdout steam (usually the console,
  could have been re-directed).
 */
/*-------------------------------------------------------------------------*/
typedef struct _qfitsdumper_ {

	/** Name of the file to dump to, "STDOUT" to dump to stdout */
	char 	*	filename ;
	/** Number of pixels in the buffer to dump */
	int			npix ;
	/** Buffer type: PTYPE_FLOAT, PTYPE_INT or PTYPE_DOUBLE */
	int			ptype ;

	/** Pointer to input integer pixel buffer */
	int		*	ibuf ;
	/** Pointer to input float pixel buffer */
	float	*	fbuf ;
	/** Pointer to input double pixel buffer */
	double	*	dbuf ;

	/** Requested BITPIX in output FITS file */
	int			out_ptype ;
} qfitsdumper ;


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

/*-------------------------------------------------------------------------*/
/**
  @brief	Initialize a qfitsloader control object.
  @param	ql	qfitsloader object to initialize.
  @return	int 0 if Ok, -1 if error occurred.

  This function expects a qfitsloader object with a number of input
  fields correctly filled in. The minimum fields to set are:

  - filename: Name of the file to examine.
  - xtnum: Extension number to examine (0 for main section).
  - pnum: Plane number in the requested extension.

  You can go ahead with these fields only if you only want to get
  file information for this plane in this extension. If you want
  to later load the plane, you must additionally fill the 'ptype'
  field to a correct value (PTYPE_INT, PTYPE_FLOAT, PTYPE_DOUBLE)
  before calling qfits_loadpix() so that it knows which conversion
  to perform.

  This function is basically a probe sent on a FITS file to ask
  qfits if loading these data would be Ok or not. The actual loading
  is performed by qfits_loadpix() afterwards.
 */
/*--------------------------------------------------------------------------*/
int qfitsloader_init(qfitsloader * ql);



/*-------------------------------------------------------------------------*/
/**
  @brief	Load a pixel buffer for one image.
  @param	ql	Allocated and initialized qfitsloader control object.
  @return	int 0 if Ok, -1 if error occurred.

  This function performs a load of a pixel buffer into memory. It
  expects an allocated and initialized qfitsloader object in input.
  See qfitsloader_init() about initializing the object.

  This function will fill up the ibuf/fbuf/dbuf field, depending
  on the requested pixel type (resp. int, float or double).

  The returned buffer has been allocated using one of the special
  memory operators present in xmemory.c. To deallocate the buffer,
  you must call the version of free() offered by xmemory, not the
  usual system free(). It is enough to include "xmemory.h" in your
  code before you make calls to the pixel loader here.
 */
/*--------------------------------------------------------------------------*/
int qfits_loadpix(qfitsloader * ql);


/*-------------------------------------------------------------------------*/
/**
  @brief    Load a pixel buffer as floats.
  @param    p_source    Pointer to source buffer (as bytes).
  @param    npix        Number of pixels to load.
  @param    bitpix      FITS BITPIX in original file.
  @param    bscale      FITS BSCALE in original file.
  @param    bzero       FITS BZERO in original file.
  @return   1 pointer to a newly allocated buffer of npix floats.

  This function takes in input a pointer to a byte buffer as given
  in the original FITS file (big-endian format). It converts the
  buffer to an array of float (whatever representation is used for
  floats by this platform is used) and returns the newly allocated
  buffer, or NULL if an error occurred.

  The returned buffer must be deallocated using the free() offered
  by xmemory. It is enough to #include "xmemory.h" before calling
  free on the returned pointer.
 */
/*--------------------------------------------------------------------------*/
float  * qfits_pixin_float (char *, int, int, double, double);

/*-------------------------------------------------------------------------*/
/**
  @brief    Load a pixel buffer as ints.
  @param    p_source    Pointer to source buffer (as bytes).
  @param    npix        Number of pixels to load.
  @param    bitpix      FITS BITPIX in original file.
  @param    bscale      FITS BSCALE in original file.
  @param    bzero       FITS BZERO in original file.
  @return   1 pointer to a newly allocated buffer of npix ints.

  This function takes in input a pointer to a byte buffer as given
  in the original FITS file (big-endian format). It converts the
  buffer to an array of int (whatever representation is used for
  int by this platform is used) and returns the newly allocated
  buffer, or NULL if an error occurred.

  The returned buffer must be deallocated using the free() offered
  by xmemory. It is enough to #include "xmemory.h" before calling
  free on the returned pointer.
 */
/*--------------------------------------------------------------------------*/
int    * qfits_pixin_int   (char *, int, int, double, double);

/*-------------------------------------------------------------------------*/
/**     
  @brief    Load a pixel buffer as doubles.
  @param    p_source    Pointer to source buffer (as bytes).
  @param    npix        Number of pixels to load.
  @param    bitpix      FITS BITPIX in original file.
  @param    bscale      FITS BSCALE in original file.
  @param    bzero       FITS BZERO in original file.
  @return   1 pointer to a newly allocated buffer of npix doubles.

  This function takes in input a pointer to a byte buffer as given
  in the original FITS file (big-endian format). It converts the
  buffer to an array of double (whatever representation is used for
  int by this platform is used) and returns the newly allocated
  buffer, or NULL if an error occurred.

  The returned buffer must be deallocated using the free() offered
  by xmemory. It is enough to #include "xmemory.h" before calling
  free on the returned pointer.
 */     
/*--------------------------------------------------------------------------*/


double * qfits_pixin_double(char *, int, int, double, double);



/*-------------------------------------------------------------------------*/
/**
  @brief    Dump a pixel buffer to an output FITS file in append mode.
  @param    qd  qfitsdumper control object.
  @return   int 0 if Ok, -1 otherwise.

  This function takes in input a qfitsdumper control object. This object
  must be allocated beforehand and contain valid references to the data
  to save, and how to save it.

  The minimum fields to fill are:

  - filename: Name of the FITS file to dump to.
  - npix: Number of pixels in the buffer to be dumped.
  - ptype: Type of the passed buffer (PTYPE_FLOAT, PTYPE_INT, PTYPE_DOUBLE)
  - out_ptype: Requested FITS BITPIX for the output.

  One of the following fields must point to the corresponding pixel
  buffer:

  - ibuf for an int pixel buffer (ptype=PTYPE_INT)
  - fbuf for a float pixel buffer (ptype=PTYPE_FLOAT)
  - dbuf for a double pixel buffer (ptype=PTYPE_DOUBLE)

  This is a fairly low-level function, in the sense that it does not
  check that the output file already contains a proper header or even
  that the file it is appending to is indeed a FITS file. It will
  convert the pixel buffer to the requested BITPIX type and append
  the data to the file, without padding with zeros. See qfits_zeropad()
  about padding.

  If the given output file name is "STDOUT" (all caps), the dump
  will be performed to stdout.
 */
/*--------------------------------------------------------------------------*/
int qfits_pixdump(qfitsdumper * qd) ;


/*-------------------------------------------------------------------------*/
/**
  @brief    Convert a float pixel buffer to a byte buffer.
  @param    buf     Input float buffer.
  @param    npix    Number of pixels in the input buffer.
  @param    ptype   Requested output BITPIX type.
  @return   1 pointer to a newly allocated byte (char) buffer.
    
  This function converts the given float buffer to a buffer of bytes
  suitable for dumping to a FITS file (i.e. big-endian, in the
  requested pixel type). The returned pointer must be deallocated
  using the free() function offered by xmemory.
 */ 
/*--------------------------------------------------------------------------*/
char * qfits_pixdump_float(float * buf, int npix, int ptype);

/*-------------------------------------------------------------------------*/
/**
  @brief    Convert an int pixel buffer to a byte buffer.
  @param    buf     Input int buffer.
  @param    npix    Number of pixels in the input buffer.
  @param    ptype   Requested output BITPIX type.
  @return   1 pointer to a newly allocated byte (char) buffer.

  This function converts the given int buffer to a buffer of bytes
  suitable for dumping to a FITS file (i.e. big-endian, in the
  requested pixel type). The returned pointer must be deallocated
  using the free() function offered by xmemory.
 */
/*--------------------------------------------------------------------------*/
char * qfits_pixdump_int(int * buf, int npix, int ptype);

/*-------------------------------------------------------------------------*/
/**
  @brief    Convert a double pixel buffer to a byte buffer.
  @param    buf     Input double buffer.
  @param    npix    Number of pixels in the input buffer.
  @param    ptype   Requested output BITPIX type.
  @return   1 pointer to a newly allocated byte (char) buffer.

  This function converts the given double buffer to a buffer of bytes
  suitable for dumping to a FITS file (i.e. big-endian, in the
  requested pixel type). The returned pointer must be deallocated
  using the free() function offered by xmemory.
 */
/*--------------------------------------------------------------------------*/
char * qfits_pixdump_double(double * buf, int npix, int ptype);

/*---------------------------------------------------------------------------
   								Defines
 ---------------------------------------------------------------------------*/

/** Unknown type for FITS value */
#define QFITS_UNKNOWN		0
/** Boolean type for FITS value */
#define QFITS_BOOLEAN		1
/** Int type for FITS value */
#define	QFITS_INT			2
/** Float type for FITS value */
#define QFITS_FLOAT			3
/** Complex type for FITS value */
#define QFITS_COMPLEX		4
/** String type for FITS value */
#define QFITS_STRING			5

/** Default name of a place holder, as a character string */
#define QFITS_PLACEHOLDER	"PLACEHOLDER"

/*---------------------------------------------------------------------------
  							Function codes
 ---------------------------------------------------------------------------*/


/*-------------------------------------------------------------------------*/
/**
  @brief    Retrieve the value of a key in a FITS header
  @param    filename    Name of the FITS file to browse
  @param    keyword     Name of the keyword to find
  @return   pointer to statically allocated character string

  Provide the name of a FITS file and a keyword to look for. The input
  file is mmap'ed and the first keyword matching the requested one is
  located. The value corresponding to this keyword is copied to a
  statically allocated area, so do not modify it or free it.

  The input keyword is first converted to upper case and expanded to
  the HIERARCH scheme if given in the shortFITS notation.

  This function is pretty fast due to the mmapping. Due to buffering
  on most Unixes, it is possible to call many times this function in a
  row on the same file and do not suffer too much from performance
  problems. If the file contents are already in the cache, the file
  will not be re-opened every time.

  It is possible, though, to modify this function to perform several
  searches in a row. See the source code.

  Returns NULL in case the requested keyword cannot be found.
 */
/*--------------------------------------------------------------------------*/
char * qfits_query_hdr(char * filename, char * keyword) ;


/*-------------------------------------------------------------------------*/
/**
  @brief    Retrieve the value of a keyin a FITS extension header.
  @param    filename    name of the FITS file to browse.
  @param    keyword     name of the FITS key to look for.
  @param    xtnum       xtension number
  @return   pointer to statically allocated character string

  Same as qfits_query_hdr but for extensions. xtnum starts from 1 to
  the number of extensions.
 */
/*--------------------------------------------------------------------------*/
char * qfits_query_ext(char * filename, char * keyword, int xtnum);


/*-------------------------------------------------------------------------*/
/**
  @brief    Counts the number of extensions in a FITS file
  @param    filename    Name of the FITS file to browse.
  @return   int

  Counts how many extensions are in the file. Returns 0 if no
  extension is found, and -1 if an error occurred.
 */
/*--------------------------------------------------------------------------*/
int qfits_query_n_ext(char * filename);


/*-------------------------------------------------------------------------*/
/**
  @brief    Clean out a FITS string value.
  @param    s pointer to allocated FITS value string.
  @return   pointer to statically allocated character string

  From a string FITS value like 'marvin o''hara', remove head and tail
  quotes, replace double '' with simple ', trim blanks on each side,
  and return the result in a statically allocated area.

  Examples:

  - ['o''hara'] becomes [o'hara]
  - ['  H    '] becomes [H]
  - ['1.0    '] becomes [1.0]

 */
/*--------------------------------------------------------------------------*/
char * qfits_pretty_string(char * s);

/*-------------------------------------------------------------------------*/
/**
  @brief    Identify if a FITS value is boolean
  @param    s FITS value as a string
  @return   int 0 or 1

  Identifies if a FITS value is boolean.
 */
/*--------------------------------------------------------------------------*/
int qfits_is_boolean(char * s);

/*-------------------------------------------------------------------------*/
/**
  @brief    Identify if a FITS value is an int.
  @param    s FITS value as a string
  @return   int 0 or 1

  Identifies if a FITS value is an integer.
 */
/*--------------------------------------------------------------------------*/
int qfits_is_int(char * s);

/*-------------------------------------------------------------------------*/
/**
  @brief    Identify if a FITS value is float.
  @param    s FITS value as a string
  @return   int 0 or 1

  Identifies if a FITS value is float.
 */
/*--------------------------------------------------------------------------*/
int qfits_is_float(char * s);

/*-------------------------------------------------------------------------*/
/**
  @brief    Identify if a FITS value is complex.
  @param    s FITS value as a string
  @return   int 0 or 1

  Identifies if a FITS value is complex.
 */
/*--------------------------------------------------------------------------*/
int qfits_is_complex(char * s);

/*-------------------------------------------------------------------------*/
/**
  @brief    Identify if a FITS value is string.
  @param    s FITS value as a string
  @return   int 0 or 1

  Identifies if a FITS value is a string.
 */
/*--------------------------------------------------------------------------*/
int qfits_is_string(char * s);

/*-------------------------------------------------------------------------*/
/**
  @brief    Identify the type of a FITS value given as a string.
  @param    s FITS value as a string
  @return   integer naming the FITS type

  Returns the following value:

  - QFITS_UNKNOWN (0) for an unknown type.
  - QFITS_BOOLEAN (1) for a boolean type.
  - QFITS_INT (2) for an integer type.
  - QFITS_FLOAT (3) for a floating-point type.
  - QFITS_COMPLEX (4) for a complex number.
  - QFITS_STRING (5) for a FITS string.
 */
/*--------------------------------------------------------------------------*/
int qfits_get_type(char * s);

/*-------------------------------------------------------------------------*/
/**
  @brief    Retrieve offset to start and size of a header in a FITS file.
  @param    filename    Name of the file to examine
  @param    xtnum       Extension number (0 for main)
  @param    seg_start   Segment start in bytes (output)
  @param    seg_size    Segment size in bytes (output)
  @return   int 0 if Ok, -1 otherwise.

  This function retrieves the two most important informations about
  a header in a FITS file: the offset to its beginning, and the size
  of the header in bytes. Both values are returned in the passed
  pointers to ints. It is Ok to pass NULL for any pointer if you do
  not want to retrieve the associated value.

  You must provide an extension number for the header, 0 meaning the
  main header in the file.
 */
/*--------------------------------------------------------------------------*/
int qfits_get_hdrinfo(
    char * filename,
    int    xtnum,
    int  * seg_start,
    int  * seg_size
);

/*-------------------------------------------------------------------------*/
/**
  @brief    Retrieve offset to start and size of a data section in a file.
  @param    filename    Name of the file to examine.
  @param    xtnum       Extension number (0 for main).
  @param    seg_start   Segment start in bytes (output).
  @param    seg_size    Segment size in bytes (output).
  @return   int 0 if Ok, -1 otherwise.

  This function retrieves the two most important informations about
  a data section in a FITS file: the offset to its beginning, and the size
  of the section in bytes. Both values are returned in the passed
  pointers to ints. It is Ok to pass NULL for any pointer if you do
  not want to retrieve the associated value.

  You must provide an extension number for the header, 0 meaning the
  main header in the file.
 */
/*--------------------------------------------------------------------------*/
int qfits_get_datinfo(
    char * filename,
    int    xtnum,
    int  * seg_start,
    int  * seg_size
);

/*-------------------------------------------------------------------------*/
/**
  @brief    Retrieve the card containing a keyword in the main header.
  @param    filename    Name of the FITS file to examine.
  @param    keyword     Keyword to look for in header.
  @return   Pointer to statically allocated character string

  Retrieve the whole FITS line associated to a given keyword in the
  main header. The returned string is statically allocated, so do not
  modify it or try to free it. Returns NULL if an error occurred or
  the keyword cannot be found.

  The input keyword is first converted to upper case and expanded to
  the HIERARCH scheme if given in the shortFITS notation. 
 */
/*--------------------------------------------------------------------------*/
char * qfits_query_card_in_header(char * filename, char * keyword);


/*-------------------------------------------------------------------------*/
/**
  @brief    Replace a card in a FITS (main) header by a given card
  @param    filename    Name of the FITS file to modify.
  @param    keyword     Where to substitute a card in the header.
  @param    substitute  What to replace the line with.
  @return   int 0 if Ok, -1 otherwise

  Replaces a whole card (80 chars) in a FITS header by a given FITS
  line (80 chars). The replacing line is assumed correctly formatted
  and containing at least 80 characters. The file is modified: it must
  be accessible in read/write mode.

  The input keyword is first converted to upper case and expanded to
  the HIERARCH scheme if given in the shortFITS notation. 

  Returns 0 if everything worked Ok, -1 otherwise.
 */
/*--------------------------------------------------------------------------*/
int qfits_replace_card(char * filename, char * keyword, char * substitute) ;   


/*-------------------------------------------------------------------------*/
/**
  @brief    Replace a placeholder in a FITS header by a given card.
  @param    filename    Name of the FITS file to modify.
  @param    placeholder Name of the placeholder to replace.
  @param    substitute  What to replace the line with.
  @return   int 0 if Ok, -1 otherwise

  Similar to fits_replace_card, but to replace placeholder in FITS
  (main) headers. A placeholder is defined as being something like:

  COMMENT %s

  In the search process to look for placeholders, %s is replaced with
  the given character string. The default placeholder to look for is
  simply 'PLACEHOLDER'.
 */
/*--------------------------------------------------------------------------*/
int qfits_replace_placeholder(
    char    *   filename,
    char    *   placeholder,
    char    *   substitute
);


/*---------------------------------------------------------------------------
   								Defines
 ---------------------------------------------------------------------------*/

/** Maximum supported file name size */
#define FILENAMESZ				512

/** Maximum number of characters per line in an ASCII file */
#define ASCIILINESZ				1024

/*---------------------------------------------------------------------------
   								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) ;

/*---------------------------------------------------------------------------
						Function ANSI C prototypes
 ---------------------------------------------------------------------------*/

/*-------------------------------------------------------------------------*/
/**
  @brief    Returns the current date as a long (CCYYMMDD).
  @return   The current date as a long number.

  Returns the current date as a long value (CCYYMMDD). Since most
  system clocks do not return a century, this function assumes that
  all years 80 and above are in the 20th century, and all years 00 to
  79 are in the 21st century.  For best results, consume before 1 Jan
  2080.

  Example:  19 Oct 2000 is returned as 20001019
 */
/*--------------------------------------------------------------------------*/
long date_now (void);

/*-------------------------------------------------------------------------*/
/**
  @brief    Returns the current time as a long (HHMMSSCC).
  @return   The current time as a long number.

  Returns the current time as a long value (HHMMSSCC). If the system
  clock does not return centiseconds, these are set to zero.

  Example: 15:36:12.84 is returned as 15361284
 */
/*--------------------------------------------------------------------------*/
long time_now(void);

/*--------------------------------------------------------------------------*/
/**
  @brief    Returns the current date as a static string.
  @return   Pointer to statically allocated string.
 
  Build and return a string containing the date of today in ISO8601
  format. The returned pointer points to a statically allocated string
  in the function, so no need to free it.
  */
/*--------------------------------------------------------------------------*/
char * get_date_iso8601(void);

/*-------------------------------------------------------------------------*/
/**
  @brief    Returns the current date and time as a static string.
  @return   Pointer to statically allocated string
 
  Build and return a string containing the date of today and the
  current time in ISO8601 format. The returned pointer points to a
  statically allocated string in the function, so no need to free it.
 */
/*-------------------------------------------------------------------------*/
char * get_datetime_iso8601(void);



#endif