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. This section are describes some functions that help in reading from and writing to plain text files.
Lines are one of the most basic building 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 are 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. The remaining lines are
considered as containing data.
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.
This function is just for column information. Therefore it only stores
meta-data like column name, units and comments. No actual data (contents of
the columns for example the
dsize elements) will be
allocated by this function. This is a low-level function particular to
reading tables in plain text format. To be generic, it is recommended to
gal_table_info which will allow getting information from a
variety of table formats based on the filename (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
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).
filename already exists this function will abort with an error
and will not write over the existing file. Before calling this function
make sure if the file exists or not. If
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
List of strings).
filename==NULL, the column information will be printed on the
standard output (command-line). When
filename==NULL (columns are printed in the standard output), the
dataset metadata will also printed in the standard output. When printing to
the standard output, the column information can be piped into another
program for further processing and thus the meta-data (lines starting with
#) must be ignored. In such cases, you only print the column
values by passing