C DataIO API

Defines

LINE_SIZE_MAX

Flag for checking if AsciiFile.h has already been included.

Maximum line size.

Typedefs

typedef struct asciiFile_t asciiFile_t

Structure containing information about an ASCII text file.

Functions

static int af_is_open(const asciiFile_t t)

Determine if the file is open.

Return
int 1 if open, 0 if closed.
Parameters

static int af_open(asciiFile_t *t)

Open the file.

Return
int 0 if opened successfully, -1 otherwise.
Parameters

static int af_close(asciiFile_t *t)

Close the file.

Return
int 0 if closed successfully, -1 otherwise.
Parameters

static int af_is_comment(const asciiFile_t t, const char *line)

Check if string starts with a comment.

Return
int 1 if line starts with a comment, 0 otherwise.
Parameters
  • t: constant asciiFile_t file structure.
  • line: constant character pointer to string that should be checked.

static int af_readline_full_norealloc(const asciiFile_t t, char *line, size_t n)

Read a single line from the file without realloc.

Return
int On success, the number of characters read, -1 on failure.
Parameters
  • t: constant asciiFile_t file structure.
  • line: constant character pointer to buffer where the read line should be stored. If line is not large enough to hold the read line, an error will be returned.
  • n: Size of allocated buffer.

static int af_readline_full(const asciiFile_t t, char **line, size_t *n)

Read a single line from the file with realloc.

Return
int On success, the number of characters read, -1 on failure.
Parameters
  • t: constant asciiFile_t file structure.
  • line: constant character pointer to pointer to buffer where the read line should be stored. If line is not large enough to hold the read line, it will be reallocated.
  • n: Pointer to size of allocated buffer. If line is not large enough to hold the read line and is reallocated, n will be changed to the new size.

static int af_writeline_full(const asciiFile_t t, const char *line)

Write a single line to the file.

Return
int On success, the number of characters written, -1 on failure.
Parameters
  • t: constant asciiFile_t file structure.
  • line: constant character pointer to string that should be written.

static int af_update(asciiFile_t *t, const char *filepath, const char *io_mode)

Update an existing asciiFile_t structure.

Return
int -1 if there is an error, 0 otherwise.
Parameters
  • t: asciiFile_t* Address of file structure to update.
  • filepath: constant character pointer to file path.
  • io_mode: constant character pointer to I/O mode. “r” for read, “w” for write.

static asciiFile_t asciiFile(const char *filepath, const char *io_mode, const char *comment, const char *newline)

Constructor for asciiFile_t structure.

Return
asciiFile_t File structure.
Parameters
  • filepath: constant character pointer to file path.
  • io_mode: const character pointer to I/O mode. “r” for read, “w” for write.
  • comment: const character pointer to character(s) that should indicate a comment. If NULL, comment is set to “# “.
  • newline: const character pointer to character(s) that should indicate a newline. If NULL, newline is set to “\n”.

struct asciiFile_t
#include <AsciiFile.h>

Structure containing information about an ASCII text file.

Public Members

const char *asciiFile_tfilepath

Full path to file.

char asciiFile_tio_mode[64]

I/O mode. ‘r’ for read, ‘w’ for write.

char asciiFile_tcomment[64]

Character(s) indicating a comment.

char asciiFile_tnewline[64]

Character(s) indicating a newline.

FILE *asciiFile_tfd

File identifier for ASCII file when open.

Defines

FMT_LEN

Flag for checking if AsciiTable.h has already been included.

Typedefs

typedef struct asciiTable_t asciiTable_t

Structure containing information about an ASCII table.

Enums

enum fmt_types

Enumerated types to be used for interpreting formats.

Values:

AT_STRING
AT_FLOAT
AT_DOUBLE
AT_COMPLEX
AT_SHORTSHORT
AT_SHORT
AT_INT
AT_LONG
AT_LONGLONG
AT_USHORTSHORT
AT_USHORT
AT_UINT
AT_ULONG
AT_ULONGLONG

Functions

static int count_complex_formats(const char *fmt_str)

Count format specifiers for complex numbers.

Return
int Number of complex format specifiers found.
Parameters
  • fmt_str: constant character pointer to string that should be searched for format specifiers.

static int count_formats(const char *fmt_str)

Count how many % format specifiers there are in format string. Formats are found by counting the number of matches to the regular expression adapted from https://stackoverflow.com/questions/446285/validate-sprintf-format-from-input-field-with-regex.

Return
int Number of format specifiers found.
Parameters
  • fmt_str: constant character pointer to string that should be searched for format specifiers.

static int simplify_formats(char *fmt_str, const size_t fmt_len)

Remove extra format characters that confusing sscanf.

Return
int -1 on failure if the regex could not be compiled or the buffer is not big enough to contain the result. If succesful, the new length of buf is returned.
Parameters
  • fmt_str: character pointer to string that should be modified.
  • fmt_len: constant size_t, length of the fmt_str buffer.

static int at_open(asciiTable_t *t)

Open the file.

Return
int 0 if opened successfully, -1 otherwise.
Parameters

static void at_close(asciiTable_t *t)

Close the file.

Return
int 0 if ocloseded successfully, -1 otherwise.
Parameters

static int at_readline_full_realloc(const asciiTable_t t, char **buf, const size_t len_buf, const int allow_realloc)

Read a line from the file until one is returned that is not a comment.

Return
int On success, the number of characters read. -1 on failure.
Parameters
  • t: constant asciiTable_t table structure.
  • buf: pointer to memory where read line should be stored.
  • len_buf: Size of buffer where line should be stored.
  • allow_realloc: const int If 1, the buffer will be realloced if it is not large enought. Otherwise an error will be returned.

static int at_readline_full(const asciiTable_t t, char *buf, const size_t len_buf)

Read a line from the file until one is returned that is not a comment.

Return
int On success, the number of characters read. -1 on failure.
Parameters
  • t: constant asciiTable_t table structure.
  • buf: pointer to memory where read line should be stored.
  • len_buf: Size of buffer where line should be stored. The the message is larger than len_buf, an error will be returned.

static int at_writeline_full(const asciiTable_t t, const char *line)

Write a line to the file.

Return
int On success, the number of characters written. -1 on failure.
Parameters
  • t: constant asciiTable_t table structure.
  • line: Pointer to line that should be written.

static int at_vbytes_to_row(const asciiTable_t t, const char *line, va_list ap)

Parse a line to get row columns.

Return
int On success, the number of arguments filled. -1 on failure.
Parameters
  • t: constant asciiTable_t table structure.
  • line: Pointer to memory containing the line to be parsed.
  • ap: va_list Pointers to variables where parsed arguments should be stored.

static int at_vrow_to_bytes(const asciiTable_t t, char *buf, const size_t buf_siz, va_list ap)

Format arguments to form a line.

Return
int On success, the number of characters written. -1 on failure.
Parameters
  • t: constant asciiTable_t table structure.
  • buf: Pointer to memory where the formated row should be stored.
  • buf_siz: size_t Size of buf. If the formatted message will exceed the size of the buffer, an error will be returned.
  • ap: va_list Variables that should be formatted using the format string to create a line in the table.

static int at_vreadline(const asciiTable_t t, va_list ap)

Read a line from the file and parse it.

Return
int On success, the number of characters read. -1 on failure.
Parameters
  • t: constant asciiTable_t table structure.
  • ap: va_list Pointers to variables where parsed arguments should be stored.

static int at_vwriteline(const asciiTable_t t, va_list ap)

Format arguments to form a line and write it to the file.

Return
int On success, the number of characters written. -1 on failure.
Parameters
  • t: constant asciiTable_t table structure.
  • ap: va_list Variables that should be formatted using the format string to create a line in the table.

static int at_readline(const asciiTable_t t, ...)

Read a line from the file and parse it.

Return
int On success, the number of characters read. -1 on failure.
Parameters
  • t: constant asciiTable_t table structure.
  • ...: Pointers to variables where parsed arguments should be stored.

static int at_writeline(const asciiTable_t t, ...)

Format arguments to form a line and write it to the file.

Return
int On success, the number of characters written. -1 on failure.
Parameters
  • t: constant asciiTable_t table structure.
  • ...: Variables that should be formatted using the format string to create a line in the table.

static int at_writeformat(const asciiTable_t t)

Write the format string the the file, prepending it with a comment.

Return
int On success, the number of characters written. -1 on failure.
Parameters

static int at_discover_format_str(asciiTable_t *t)

Try to find the format string in the file. The format string is assumed to start with a comment.

Return
0 on success, -1 on failure.
Parameters

static int at_set_ncols(asciiTable_t *t)

Set the number of columns by counting the format specifiers.

Return
int The number of columns counted. Negative values indicate errors.
Parameters

static int at_set_format_siz(asciiTable_t *t)

Determine the column sizes based on the types.

Return
int 0 on success, -1 on failure.
Parameters
  • t: asciiTable_t table structure that sizes will be added to.

static int at_set_format_typ(asciiTable_t *t)

Determine the column types by parsing the format string.

Return
int 0 on success, -1 on failure. TODO: switch to regex
Parameters
  • t: asciiTable_t table structure that types will be added to.

static int at_vbytes_to_array(const asciiTable_t t, const char *data, const size_t data_siz, va_list ap)

Convert data into arrays for columns.

Return
int Number of rows read on success, -1 on failure.
Parameters
  • t: constant asciiTable_t table structure.
  • data: constant character pointer to memory containing data that should be parsed.
  • data_siz: constant size_t Size of data in bytes.
  • ap: va_list Pointers to pointers to memory where columns should be stored.

static int at_varray_to_bytes(const asciiTable_t t, char *data, const size_t data_siz, va_list ap)

Encode a set of arrays as bytes.

Return
int Number of bytes written. If larger than data_siz, the message will not be written to data and data should be resized first.
Parameters
  • t: constant asciiTable_t table structure.
  • data: Pointer to memory where encoded arrays should be stored.
  • data_siz: Integer size of data.
  • ap: va_list Pointers to memory where column data is stored. The first argument in this set should be an integer, the number of rows in each column array.

static int at_bytes_to_array(const asciiTable_t t, char *data, size_t data_siz, ...)

Convert data into arrays for columns.

Return
int Number of rows read on success, -1 on failure.
Parameters
  • t: constant asciiTable_t table structure.
  • data: constant character pointer to memory containing data that should be parsed.
  • data_siz: constant size_t Size of data in bytes.
  • ...: Pointers to pointers to memory where columns should be stored.

static int at_array_to_bytes(const asciiTable_t t, char *data, const size_t data_siz, ...)

Encode a set of arrays as bytes.

Return
int Number of bytes written. If larger than data_siz, the message will not be written to data and data should be resized first.
Parameters
  • t: constant asciiTable_t table structure.
  • data: Pointer to memory where encoded arrays should be stored.
  • data_siz: Integer size of data.
  • ...: Pointers to memory where column data is stored. The first argument in this set should be an integer, the number of rows in each column array.

static void at_cleanup(asciiTable_t *t)

Deallocate and clean up asciiTable_t structure.

Parameters

static int at_update(asciiTable_t *t, const char *filepath, const char *io_mode)

Update an existing asciiTable_t structure.

Return
int -1 if there is an error, 0 otherwise.
Parameters
  • t: asciiTable_t* Address of table structure to update.
  • filepath: constant character pointer to file path.
  • io_mode: constant character pointer to I/O mode. “r” for read, “w” for write.

static asciiTable_t asciiTable(const char *filepath, const char *io_mode, const char *format_str, const char *comment, const char *column, const char *newline)

Constructor for asciiTable_t structure.

Return
asciiTable_t table structure.
Parameters
  • filepath: constant character pointer to file path.
  • io_mode: constant character pointer to I/O mode. “r” for read, “w” for write.
  • format_str: constant character pointer to string describing the format of the table roads. Required for io_mode == “w”, but if set to NULL for io_mode == “r”, it will attempt to be read from the table.
  • comment: const character pointer to character(s) that should indicate a comment. If NULL, comment is set to “# “.
  • column: const character pointer to character(s) that should separate columns in the table. If NULL, column is set to “\t”.
  • newline: const character pointer to character(s) that should indicate a newline. If NULL, newline is set to “\n”.

struct asciiTable_t
#include <AsciiTable.h>

Structure containing information about an ASCII table.

Public Members

asciiFile_t asciiTable_tf

ASCII file structure.

char asciiTable_tformat_str[LINE_SIZE_MAX]

Format string for rows.

char asciiTable_tcolumn[64]

Character(s) used to seperate columns.

int asciiTable_tncols

Number of columns in the table.

int *asciiTable_tformat_typ

Array of ncols integers specifying column types.

int *asciiTable_tformat_siz

Array of ncols sizes for elements in each column.

int asciiTable_trow_siz

Size of an entire row in bytes.

int asciiTable_tstatus

Negative if format_str has not been set yet.