FITS header handling


Functions

qfits_header * qfits_header_new (void)
 FITS header constructor.
qfits_header * qfits_header_default (void)
 FITS header default constructor.
void qfits_header_add (qfits_header *hdr, const char *key, const char *val, const char *com, const char *lin)
 Add a new card to a FITS header.
void qfits_header_add_after (qfits_header *hdr, const char *after, const char *key, const char *val, const char *com, const char *lin)
 add a new card to a FITS header
void qfits_header_append (qfits_header *hdr, const char *key, const char *val, const char *com, const char *lin)
 Append a new card to a FITS header.
void qfits_header_del (qfits_header *hdr, const char *key)
 Delete a card in a FITS header.
void qfits_header_mod (qfits_header *hdr, const char *key, const char *val, const char *com)
 Modifies a FITS card.
int qfits_header_sort (qfits_header **hdr)
 Sort a FITS header.
qfits_header * qfits_header_copy (const qfits_header *src)
 Copy a FITS header.
void qfits_header_destroy (qfits_header *hdr)
 qfits_header destructor
char * qfits_header_getstr (const qfits_header *hdr, const char *key)
 Return the value associated to a key, as a string.
int qfits_header_getitem (const qfits_header *hdr, int idx, char *key, char *val, char *com, char *lin)
 Return the i-th key/val/com/line tuple in a header.
char * qfits_header_getcom (const qfits_header *hdr, const char *key)
 Return the comment associated to a key, as a string.
int qfits_header_getint (const qfits_header *hdr, const char *key, int errval)
 Return the value associated to a key, as an int.
double qfits_header_getdouble (const qfits_header *hdr, const char *key, double errval)
 Return the value associated to a key, as a double.
int qfits_header_getboolean (const qfits_header *hdr, const char *key, int errval)
 Return the value associated to a key, as a boolean (int).
int qfits_header_dump (const qfits_header *hdr, FILE *out)
 Dump a FITS header to an opened file.

Detailed Description

This file contains definition and related methods for the FITS header structure. This structure is meant to remain opaque to the user, who only accesses it through the dedicated functions.

The 'keytuple' type is strictly internal to this module. It describes FITS cards as tuples (key,value,comment,line), where key is always a non-NULL character string, value and comment are allowed to be NULL. 'line' is a string containing the line as it has been read from the input FITS file (raw). It is set to NULL if the card is modified later. This allows in output two options: either reconstruct the FITS lines by printing key = value / comment in a FITS-compliant way, or output the lines as they were found in input, except for the modified ones.

The following functions are associated methods to this data structure:

Function Documentation

void qfits_header_add (  qfits_header *  hdr,
const char *  key,
const char *  val,
const char *  com,
const char *  lin
) 
 

Add a new card to a FITS header.

Parameters:
hdr qfits_header object to modify
key FITS key
val FITS value
com FITS comment
lin FITS original line if exists
Returns:
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_after (  qfits_header *  hdr,
const char *  after,
const char *  key,
const char *  val,
const char *  com,
const char *  lin
) 
 

add a new card to a FITS header

Parameters:
hdr qfits_header object to modify
after Key to specify insertion place
key FITS key
val FITS value
com FITS comment
lin FITS original line if exists
Returns:
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_append (  qfits_header *  hdr,
const char *  key,
const char *  val,
const char *  com,
const char *  lin
) 
 

Append a new card to a FITS header.

Parameters:
hdr qfits_header object to modify
key FITS key
val FITS value
com FITS comment
lin FITS original line if exists
Returns:
void
Adds a new card in a FITS header as the last one. All fields can be NULL except key.

qfits_header* qfits_header_copy (  const qfits_header *  src  ) 
 

Copy a FITS header.

Parameters:
src Header to replicate
Returns:
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_default (  void   ) 
 

FITS header default constructor.

Returns:
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).

void qfits_header_del (  qfits_header *  hdr,
const char *  key
) 
 

Delete a card in a FITS header.

Parameters:
hdr qfits_header to modify
key specifies which card to remove
Returns:
void
Removes a card from a FITS header. The first found card that matches the key is removed.

void qfits_header_destroy (  qfits_header *  hdr  ) 
 

qfits_header destructor

Parameters:
hdr qfits_header to deallocate
Returns:
void
Frees all memory associated to a given qfits_header object.

int qfits_header_dump (  const qfits_header *  hdr,
FILE *  out
) 
 

Dump a FITS header to an opened file.

Parameters:
hdr FITS header to dump
out Opened file pointer
Returns:
int 0 if Ok, -1 otherwise Dumps a FITS header to an opened file pointer.

int qfits_header_getboolean (  const qfits_header *  hdr,
const char *  key,
int  errval
) 
 

Return the value associated to a key, as a boolean (int).

Parameters:
hdr qfits_header to parse
key key to find
errval default value to return if nothing is found
Returns:
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'.

char* qfits_header_getcom (  const qfits_header *  hdr,
const char *  key
) 
 

Return the comment associated to a key, as a string.

Parameters:
hdr qfits_header to parse
key key to find
Returns:
pointer to statically allocated string
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.

double qfits_header_getdouble (  const qfits_header *  hdr,
const char *  key,
double  errval
) 
 

Return the value associated to a key, as a double.

Parameters:
hdr qfits_header to parse
key key to find
errval default value to return if nothing is found
Returns:
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.

int qfits_header_getint (  const qfits_header *  hdr,
const char *  key,
int  errval
) 
 

Return the value associated to a key, as an int.

Parameters:
hdr qfits_header to parse
key key to find
errval default value to return if nothing is found
Returns:
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_getitem (  const qfits_header *  hdr,
int  idx,
char *  key,
char *  val,
char *  com,
char *  lin
) 
 

Return the i-th key/val/com/line tuple in a header.

Parameters:
hdr Header to consider
idx Index of the requested card
key Output key
val Output value
com Output comment
lin Output initial line
Returns:
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.

  int i ;
  char key[FITS_LINESZ+1] ;
  char val[FITS_LINESZ+1] ;
  char com[FITS_LINESZ+1] ;
  char lin[FITS_LINESZ+1] ;

  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);
  }

This function has primarily been written to interface a qfits_header object to other languages (C++/Python). If you are working within a C program, you should use the other header manipulation routines available in this module.

char* qfits_header_getstr (  const qfits_header *  hdr,
const char *  key
) 
 

Return the value associated to a key, as a string.

Parameters:
hdr qfits_header to parse
key key to find
Returns:
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.

void qfits_header_mod (  qfits_header *  hdr,
const char *  key,
const char *  val,
const char *  com
) 
 

Modifies a FITS card.

Parameters:
hdr qfits_header to modify
key FITS key
val FITS value
com FITS comment
Returns:
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.

qfits_header* qfits_header_new (  void   ) 
 

FITS header constructor.

Returns:
1 newly allocated (empty) qfits_header object.
This is the main constructor for a qfits_header object. It returns an allocated linked-list handler with an empty card list.

int qfits_header_sort (  qfits_header **  hdr  ) 
 

Sort a FITS header.

Parameters:
hdr Header to sort (modified)
Returns:
-1 in error case, 0 otherwise