C Standard Library Extensions: FITS table handling

C Standard Library Extensions 6.2.0

- Main Page
- Modules
- Classes
- Files

Functions
FITS table handling

## Functions
int | qfits_is_table (const char *filename, int xtnum)
| Identify a file as containing a FITS table in extension.
qfits_header * | qfits_table_prim_header_default (void)
| Generate a default primary header to store tables.
qfits_header * | qfits_table_ext_header_default (const qfits_table *t)
| Generate a default extension header to store tables.
qfits_table * | qfits_table_new (const char *filename, int table_type, int table_width, int nb_cols, int nb_raws)
| Table object constructor.
int | qfits_col_fill (qfits_col *qc, int atom_nb, int atom_dec_nb, int atom_size, tfits_type atom_type, const char *label, const char *unit, const char *nullval, const char *disp, int zero_present, float zero, int scale_present, float scale, int offset_beg)
| Fill a column object with some provided informations.
qfits_table * | qfits_table_open (const char *filename, int xtnum)
| Read a FITS extension.
void | qfits_table_close (qfits_table *t)
| Free a FITS table and associated pointers.
unsigned char * | qfits_query_column (const qfits_table *th, int colnum, const int *selection)
| Extract data from a column in a FITS table.
unsigned char * | qfits_query_column_seq (const qfits_table *th, int colnum, int start_ind, int nb_rows)
| Extract consequtive values from a column in a FITS table.
void * | qfits_query_column_data (const qfits_table *th, int colnum, const int *selection, const void *null_value)
| Extract binary data from a column in a FITS table.
void * | qfits_query_column_seq_data (const qfits_table *th, int colnum, int start_ind, int nb_rows, const void *null_value)
| Extract binary data from a column in a FITS table.
int * | qfits_query_column_nulls (const qfits_table *th, int colnum, const int *selection, int *nb_vals, int *nb_nulls)
| Detect NULL values in a column.
int | qfits_save_table_hdrdump (const void **array, const qfits_table *table, const qfits_header *fh)
| Save a table to a FITS file with a given FITS header.
int | qfits_table_append_xtension (FILE *outfile, const qfits_table *t, const void **data)
| Appends a std extension header + data to a FITS table file.
int | qfits_table_append_xtension_hdr (FILE *outfile, const qfits_table *t, const void **data, const qfits_header *hdr)
| Appends a specified extension header + data to a FITS table file.
char * | qfits_table_field_to_string (const qfits_table *table, int col_id, int row_id, int use_zero_scale)
| given a col and a row, find out the string to write for display

## Detailed Description

## Function Documentation

int qfits_col_fill | ( | qfits_col * | qc,
|  | int | atom_nb,
|  | int | atom_dec_nb,
|  | int | atom_size,
|  | tfits_type | atom_type,
|  | const char * | label,
|  | const char * | unit,
|  | const char * | nullval,
|  | const char * | disp,
|  | int | zero_present,
|  | float | zero,
|  | int | scale_present,
|  | float | scale,
|  | int | offset_beg
| ) |  |

Fill a column object with some provided informations.

Parameters:

  qc | Pointer to the column that has to be filled
  unit | Unit of the data
  label | Label of the column
  disp | Way to display the data
  nullval | Null value
  atom_nb | Number of atoms per field. According to the type, an atom is a double, an int, a char, ...
  atom_dec_nb | Number of decimals as specified in TFORM
  atom_size | Size in bytes of the field for ASCII tables, and of an atom for BIN tables. ASCII tables only contain 1 atom per field (except for A type where you can of course have more than one char per field)
  atom_type | Type of data (11 types for BIN, 5 for ASCII)
  zero_present | Flag to use or not zero
  zero | Zero value
  scale_present | Flag to use or not scale
  scale | Scale value
  offset_beg | Gives the position of the column

Returns:
  -1 in error case, 0 otherwise

References qfits_col::atom_dec_nb, qfits_col::atom_nb, qfits_col::atom_size, qfits_col::atom_type, qfits_col::nullval, qfits_col::off_beg, qfits_col::readable, qfits_col::tdisp, qfits_col::tlabel, qfits_col::tunit, and qfits_col::zero_present.

Referenced by qfits_table_open().

int qfits_is_table | ( | const char * | filename,
|  | int | xtnum
| ) |  |

Identify a file as containing a FITS table in extension.

Parameters:

  filename | Name of the FITS file to examine.
  xtnum | Extension number to check (starting from 1).

Returns:
  int 1 if the extension contains a table, 0 else. Examines the requested extension and identifies the presence of a FITS table.

References qfits_pretty_string(), and qfits_query_ext().

Referenced by qfits_table_open().

unsigned char* qfits_query_column | ( | const qfits_table * | th,
|  | int | colnum,
|  | const int * | selection
| ) |  |

Extract data from a column in a FITS table.

Parameters:

  th | Allocated qfits_table
  colnum | Number of the column to extract (from 0 to colnum-1)
  selection | boolean array to define the selected rows

Returns:
  unsigned char array

If selection is NULL, select the complete column.

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 and by the selection parameter.

Returned array size in bytes is: nbselected * 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.

The returned object must be deallocated with qfits_free().

References qfits_col::atom_nb, qfits_col::atom_size, col, filename, nr, qfits_col::off_beg, qfits_swap_bytes(), qfits_col::readable, tab_t, and tab_w.

Referenced by qfits_query_column_data(), and qfits_query_column_nulls().

void* qfits_query_column_data | ( | const qfits_table * | th,
|  | int | colnum,
|  | const int * | selection,
|  | const void * | null_value
| ) |  |

Extract binary data from a column in a FITS table.

Parameters:

  th | Allocated qfits_table
  colnum | Number of the column to extract (from 0 to colnum-1)
  selection | bollean array to identify selected rows
  null_value | Value to return when a NULL value comes

Returns:
  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: nb_selected * col->atom_nb * col->atom_size

NULL values are recognized and replaced by the specified value. The returned object must be deallocated with qfits_free().

References qfits_col::atom_dec_nb, qfits_col::atom_nb, qfits_col::atom_size, qfits_col::atom_type, col, nr, qfits_col::nullval, qfits_query_column(), and qfits_col::readable.

int* qfits_query_column_nulls | ( | const qfits_table * | th,
|  | int | colnum,
|  | const int * | selection,
|  | int * | nb_vals,
|  | int * | nb_nulls
| ) |  |

Detect NULL values in a column.

Parameters:

  th | Allocated qfits_table
  colnum | Number of the column to check (from 0 to colnum-1)
  selection | Array to identify selected rows
  nb_vals | Gives the size of the output array
  nb_nulls | Gives the number of detected null values

Returns:
  array with 1 for NULLs and 0 for non-NULLs The returned object must be deallocated with qfits_free().

References qfits_col::atom_nb, qfits_col::atom_type, col, nr, qfits_col::nullval, qfits_query_column(), and qfits_col::readable.

unsigned char* qfits_query_column_seq | ( | const qfits_table * | th,
|  | int | colnum,
|  | int | start_ind,
|  | int | nb_rows
| ) |  |

Extract consequtive values from a column in a FITS table.

Parameters:

  th | Allocated qfits_table
  colnum | Number of the column to extract (from 0 to colnum-1)
  start_ind | Index of the first row (0 for the first)
  nb_rows | Number of rows to extract

Returns:
  unsigned char array Does the same as qfits_query_column() but on a consequtive sequence of rows Spares the overhead of the selection object allocation The returned object must be deallocated with qfits_free().

References qfits_col::atom_nb, qfits_col::atom_size, col, filename, nr, qfits_col::off_beg, qfits_swap_bytes(), qfits_col::readable, tab_t, and tab_w.

Referenced by qfits_query_column_seq_data().

void* qfits_query_column_seq_data | ( | const qfits_table * | th,
|  | int | colnum,
|  | int | start_ind,
|  | int | nb_rows,
|  | const void * | null_value
| ) |  |

Extract binary data from a column in a FITS table.

Parameters:

  th | Allocated qfits_table
  colnum | Number of the column to extract (from 0 to colnum-1)
  start_ind | Index of the first row (0 for the first)
  nb_rows | Number of rows to extract
  null_value | Value to return when a NULL value comes

Returns:
  Pointer to void * Does the same as qfits_query_column_data() but on a consequtive sequence of rows. Spares the overhead of the selection object allocation The returned object must be deallocated with qfits_free().

References qfits_col::atom_dec_nb, qfits_col::atom_nb, qfits_col::atom_size, qfits_col::atom_type, col, qfits_col::nullval, qfits_query_column_seq(), and qfits_col::readable.

int qfits_save_table_hdrdump | ( | const void ** | array,
|  | const qfits_table * | table,
|  | const qfits_header * | fh
| ) |  |

Save a table to a FITS file with a given FITS header.

Parameters:

  array | Data array.
  table | table
  fh | FITS header to insert in the output file.

Returns:
  -1 in error case, 0 otherwise

References filename, qfits_datamd5(), qfits_header_dump(), qfits_replace_card(), and tab_t.

int qfits_table_append_xtension | ( | FILE * | outfile,
|  | const qfits_table * | t,
|  | const void ** | data
| ) |  |

Appends a std extension header + data to a FITS table file.

Parameters:

  outfile | Pointer to (opened) file ready for writing.
  t | Pointer to qfits_table
  data | Table data to write

Returns:
  int 0 if Ok, -1 otherwise

Dumps a FITS table to a file. The whole table described by qfits_table, and the data arrays contained in 'data' are dumped to the file. An extension header is produced with all keywords needed to describe the table, then the data is dumped to the file. The output is then padded to reach a multiple of 2880 bytes in size. Notice that no main header is produced, only the extension part.

References tab_t.

int qfits_table_append_xtension_hdr | ( | FILE * | outfile,
|  | const qfits_table * | t,
|  | const void ** | data,
|  | const qfits_header * | hdr
| ) |  |

Appends a specified extension header + data to a FITS table file.

Parameters:

  outfile | Pointer to (opened) file ready for writing.
  t | Pointer to qfits_table
  data | Table data to write
  hdr | Specified extension header

Returns:
  int 0 if Ok, -1 otherwise

Dumps a FITS table to a file. The whole table described by qfits_table, and the data arrays contained in 'data' are dumped to the file following the specified fits header. The output is then padded to reach a multiple of 2880 bytes in size. Notice that no main header is produced, only the extension part.

References qfits_header_dump().

void qfits_table_close | ( | qfits_table * | t | ) |

Free a FITS table and associated pointers.

Parameters:

  t | qfits_table to free

Returns:
  void Frees all memory associated to a qfits_table structure.

References col, and nc.

Referenced by qfits_table_open().

qfits_header* qfits_table_ext_header_default | ( | const qfits_table * | t | ) |

Generate a default extension header to store tables.

Returns:
  the header object

References qfits_col::atom_nb, col, nc, nr, qfits_get_datetime_iso8601(), qfits_header_append(), qfits_header_destroy(), qfits_header_new(), tab_t, qfits_col::tlabel, qfits_col::tunit, and qfits_col::zero_present.

char* qfits_table_field_to_string | ( | const qfits_table * | table,
|  | int | col_id,
|  | int | row_id,
|  | int | use_zero_scale
| ) |  |

given a col and a row, find out the string to write for display

Parameters:

  table | table structure
  col_id | col id (0 -> nbcol-1)
  row_id | row id (0 -> nrow-1)
  use_zero_scale | Flag to use or not zero and scale

Returns:
  the string

This function is highly inefficient, it should not be used in loops to display a complete table. It is more to get one field from time to time, or for debugging puposes. The returned object must be deallocated with qfits_free().

References tab_t.

qfits_table* qfits_table_new | ( | const char * | filename,
|  | int | table_type,
|  | int | table_width,
|  | int | nb_cols,
|  | int | nb_raws
| ) |  |

Table object constructor.

Parameters:

  filename | Name of the FITS file associated to the table
  table_type | Type of the table (QFITS_ASCIITABLE or QFITS_BINTABLE)
  table_width | Width in bytes of the table
  nb_cols | Number of columns
  nb_raws | Number of raws

Returns:
  The table object The columns are also allocated. The object has to be deallocated with qfits_table_close()

References col, filename, nc, nr, tab_t, and tab_w.

Referenced by qfits_table_open().

qfits_table* qfits_table_open | ( | const char * | filename,
|  | int | xtnum
| ) |  |

Read a FITS extension.

Parameters:

  filename | Name of the FITS file to examine.
  xtnum | Extension number to read (starting from 1).

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

References col, nc, nr, qfits_col_fill(), qfits_get_datinfo(), qfits_is_fits(), qfits_is_table(), qfits_pretty_string(), qfits_query_ext(), qfits_table_close(), and qfits_table_new().

qfits_header* qfits_table_prim_header_default | ( | void |  | ) |

Generate a default primary header to store tables.

Returns:
  the header object

References qfits_header_append(), and qfits_header_new().