GNU Astronomy Utilities


Next: , Previous: , Up: Gnuastro library   [Contents][Index]


10.3.10 Text files (txt.h)

FITS files are the primary data container in astronomy. FITS indeed as many useful features, but the most universal and portable format for data storage are plain text files. They can be viewed and edited on any text editor or even on the command-line. Therefore the functions in this section are defined to simplify reading from and writing to plain text files.

Lines are one of the most basic buiding blocks (delimiters) of a text file. Some operating systems like Microsoft Windows, terminate their ASCII text lines with a carriage return character and a new-line character (two characters, also known as CRLF line terminators). While Unix-like operating systems just use a single new-line character. The functions below that read an ASCII text file are able to identify lines with both kinds of line terminators.

Gnuastro defines a simple format for metadata of table columns in a plain text file that is discussed in Gnuastro text table format. The functions to get information from, read from and write to plain text files also follow those conventions.

Macro: GAL_TXT_LINESTAT_INVALID
Macro: GAL_TXT_LINESTAT_BLANK
Macro: GAL_TXT_LINESTAT_COMMENT
Macro: GAL_TXT_LINESTAT_DATAROW

Status codes for lines in a plain text file that may be returned by gal_txt_line_stat). Lines which have a # character as their first non-white character are considered to be comments. Lines with nothing but white space characters are considered blank.

Function:
int
gal_txt_line_stat (char *line)

Check the contents of line and see if it is a blank, comment, or data line. The returned values are the macros that start with GAL_TXT_LINESTAT.

Function:
gal_data_t *
gal_txt_table_info (char *filename, size_t *numcols, size_t *numrows)

Store the information of each column in filename into an array of data structures with numcols elements (one data structure for each column) see Arrays of datasets. The total number of rows in the table is also put into the memory that numrows points to.

Note that other than the character strings (column name, units and comments), nothing in the data structure(s) will be allocated by this function for the actual data (e.g., the array or dsize elements). This function is just for column information. This is a low-level function particular to reading tables in FITS format. It is recommended to use gal_table_info which will allow getting information from a variety of table formats (see Table input output (table.h)).

Function:
gal_data_t *
gal_txt_table_read (char *filename, size_t numrows, gal_data_t *colinfo, gal_list_sizet_t *indexll, size_t minmapsize)

Read the columns given in the list indexll from a plain text table into a linked list of data structures, see List of size_t and List of gal_data_t. If the necessary space for each column is larger than minmapsize, don’t keep it in the RAM, but in a file on the HDD/SSD, see the description under the same name in Generic data container (gal_data_t).

Note that this is a low-level function, so the output data list is the inverse of the input indexs linked list. It is recommended to use gal_table_read for generic reading of tables in any format, see Table input output (table.h).

Function:
gal_data_t *
gal_txt_image_read (char *filename, size_t minmapsize)

Read the 2D plain text dataset in filename into a dataset and return the dataset. If the necessary space for the image is larger than minmapsize, don’t keep it in the RAM, but in a file on the HDD/SSD, see the description under the same name in Generic data container (gal_data_t).

Function:
void
gal_txt_write (gal_data_t *cols, gal_list_str_t *comment, char *filename, int dontdelete)

Write cols in a plain text file filename. cols may have one or two dimensions which determines the output:

1D

cols is treated as a column and a list of datasets (see List of gal_data_t): every node in the list is written as one column in a table.

2D

cols is a two dimensional array, it cannot be treated as a list (only one 2D array can currently be written to a text file). So if cols->next!=NULL the next nodes in the list are ignored and will not be written.

If filename already exists and dontdelete is non-zero, then this function will abort with an error and will not write over the existing file. If comments!=NULL, a # will be put at the start of each node of the list of strings and will be written in the file before the column meta-data in filename (see List of strings).

Note that this is a low-level function for tables. It is recommended to use gal_table_write for generic writing of tables in a variety of formats, see Table input output (table.h).


Next: , Previous: , Up: Gnuastro library   [Contents][Index]