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.
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.
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
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
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)).
Read the columns given in the list
indexll from a plain text table
into a linked list of data structures, see List of
gal_data_t. If the necessary space for each column is larger
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 (
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).
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 (
cols in a plain text file
have one or two dimensions which determines the output:
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
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
filename already exists and
dontdelete is non-zero, then
this function will abort with an error and will not write over the existing
# 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).