GNU Astronomy Utilities


Next: , Previous: , Up: File input output   [Contents][Index]


10.3.12.1 Text files (txt.h)

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.

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

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.

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 array or 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 use gal_table_info which will allow getting information from a variety of table formats based on the filename (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, uint8_t colinfoinstdout)

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.

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

If 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 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).

When filename==NULL, the column information will be printed on the standard output (command-line). When colinfoinstdout!=0 and 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 a #) must be ignored. In such cases, you only print the column values by passing 0 to colinfoinstdout.


Next: , Previous: , Up: File input output   [Contents][Index]