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 inline int af_is_open(const asciiFile_t t)

Determine if the file is open.

Parameters

t – [in] constant asciiFile_t file structure.

Returns

int 1 if open, 0 if closed.

static inline int af_open(asciiFile_t *t)

Open the file.

Parameters

t – [in] constant asciiFile_t file structure.

Returns

int 0 if opened successfully, -1 otherwise.

static inline int af_close(asciiFile_t *t)

Close the file.

Parameters

t – [in] constant asciiFile_t file structure.

Returns

int 0 if closed successfully, -1 otherwise.

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

Check if string starts with a comment.

Parameters

  • t – [in] constant asciiFile_t file structure.

  • line – [in] constant character pointer to string that should be checked.

Returns

int 1 if line starts with a comment, 0 otherwise.

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

Read a single line from the file without realloc.

Parameters

  • t – [in] constant asciiFile_t file structure.

  • line – [out] 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 – [in] Size of allocated buffer.

Returns

int On success, the number of characters read, -1 on failure.

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

Read a single line from the file with realloc.

Parameters

  • t – [in] constant asciiFile_t file structure.

  • line – [out] 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 – [in] 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.

Returns

int On success, the number of characters read, -1 on failure.

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

Write a single line to the file.

Parameters

  • t – [in] constant asciiFile_t file structure.

  • line – [out] constant character pointer to string that should be written.

Returns

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

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

Update an existing asciiFile_t structure.

Parameters

  • t – [in] asciiFile_t* Address of file structure to update.

  • filepath – [in] constant character pointer to file path.

  • io_mode – [in] constant character pointer to I/O mode. “r” for read, “w” for write.

Returns

int -1 if there is an error, 0 otherwise.

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

Constructor for asciiFile_t structure.

Parameters

  • filepath – [in] constant character pointer to file path.

  • io_mode – [in] const character pointer to I/O mode. “r” for read, “w” for write.

  • comment – [in] const character pointer to character(s) that should indicate a comment. If NULL, comment is set to “# “.

  • newline – [in] const character pointer to character(s) that should indicate a newline. If NULL, newline is set to “\n”.

Returns

asciiFile_t File structure.

struct asciiFile_t
#include <AsciiFile.h>

Structure containing information about an ASCII text file.

Public Members

const char *filepath

Full path to file.

char io_mode[64]

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

char comment[64]

Character(s) indicating a comment.

char newline[64]

Character(s) indicating a newline.

FILE *fd

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:

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

Functions

static inline int count_complex_formats(const char *fmt_str)

Count format specifiers for complex numbers.

Parameters

fmt_str – [in] constant character pointer to string that should be searched for format specifiers.

Returns

int Number of complex format specifiers found.

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

Parameters

fmt_str – [in] constant character pointer to string that should be searched for format specifiers.

Returns

int Number of format specifiers found.

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

Remove extra format characters that confusing sscanf.

Parameters

  • fmt_str – [in] character pointer to string that should be modified.

  • fmt_len – [in] constant size_t, length of the fmt_str buffer.

Returns

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.

static inline int at_open(asciiTable_t *t)

Open the file.

Parameters

t – [in] asciiTable_t table structure.

Returns

int 0 if opened successfully, -1 otherwise.

static inline void at_close(asciiTable_t *t)

Close the file.

Parameters

t – [in] asciiTable_t table structure.

Returns

int 0 if ocloseded successfully, -1 otherwise.

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

Parameters

  • t – [in] constant asciiTable_t table structure.

  • buf – [out] pointer to memory where read line should be stored.

  • len_buf – [in] Size of buffer where line should be stored.

  • allow_realloc – [in] const int If 1, the buffer will be realloced if it is not large enought. Otherwise an error will be returned.

Returns

int On success, the number of characters read. -1 on failure.

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

Parameters

  • t – [in] constant asciiTable_t table structure.

  • buf – [out] pointer to memory where read line should be stored.

  • len_buf – [in] Size of buffer where line should be stored. The the message is larger than len_buf, an error will be returned.

Returns

int On success, the number of characters read. -1 on failure.

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

Write a line to the file.

Parameters

  • t – [in] constant asciiTable_t table structure.

  • line – [in] Pointer to line that should be written.

Returns

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

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

Parse a line to get row columns.

Parameters

  • t – [in] constant asciiTable_t table structure.

  • line – [in] Pointer to memory containing the line to be parsed.

  • ap – [out] va_list Pointers to variables where parsed arguments should be stored.

Returns

int On success, the number of arguments filled. -1 on failure.

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

Parameters

  • t – [in] constant asciiTable_t table structure.

  • buf – [out] Pointer to memory where the formated row should be stored.

  • buf_siz – [in] size_t Size of buf. If the formatted message will exceed the size of the buffer, an error will be returned.

  • ap – [in] va_list Variables that should be formatted using the format string to create a line in the table.

Returns

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

static inline int at_vreadline(const asciiTable_t t, va_list ap)

Read a line from the file and parse it.

Parameters

  • t – [in] constant asciiTable_t table structure.

  • ap – [out] va_list Pointers to variables where parsed arguments should be stored.

Returns

int On success, the number of characters read. -1 on failure.

static inline int at_vwriteline(const asciiTable_t t, va_list ap)

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

Parameters

  • t – [in] constant asciiTable_t table structure.

  • ap – [out] va_list Variables that should be formatted using the format string to create a line in the table.

Returns

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

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

Read a line from the file and parse it.

Parameters

  • t – [in] constant asciiTable_t table structure.

  • ... – [out] Pointers to variables where parsed arguments should be stored.

Returns

int On success, the number of characters read. -1 on failure.

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

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

Parameters

  • t – [in] constant asciiTable_t table structure.

  • ... – [out] Variables that should be formatted using the format string to create a line in the table.

Returns

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

static inline int at_writeformat(const asciiTable_t t)

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

Parameters

t – [in] constant asciiTable_t table structure.

Returns

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

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

Parameters

t – [in] constant asciiTable_t table structure.

Returns

0 on success, -1 on failure.

static inline int at_set_ncols(asciiTable_t *t)

Set the number of columns by counting the format specifiers.

Parameters

t – [in] constant asciiTable_t table structure.

Returns

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

static inline int at_set_format_siz(asciiTable_t *t)

Determine the column sizes based on the types.

Parameters

t – [in] asciiTable_t table structure that sizes will be added to.

Returns

int 0 on success, -1 on failure.

static inline int at_set_format_typ(asciiTable_t *t)

Determine the column types by parsing the format string.

Parameters

t – [in] asciiTable_t table structure that types will be added to.

Returns

int 0 on success, -1 on failure. TODO: switch to regex

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

Parameters

  • t – [in] constant asciiTable_t table structure.

  • data – [in] constant character pointer to memory containing data that should be parsed.

  • data_siz – [in] constant size_t Size of data in bytes.

  • ap – [out] va_list Pointers to pointers to memory where columns should be stored.

Returns

int Number of rows read on success, -1 on failure.

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

Parameters

  • t – [in] constant asciiTable_t table structure.

  • data – [out] Pointer to memory where encoded arrays should be stored.

  • data_siz – [in] Integer size of data.

  • ap – [in] 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.

Returns

int Number of bytes written. If larger than data_siz, the message will not be written to data and data should be resized first.

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

Convert data into arrays for columns.

Parameters

  • t – [in] constant asciiTable_t table structure.

  • data – [in] constant character pointer to memory containing data that should be parsed.

  • data_siz – [in] constant size_t Size of data in bytes.

  • ... – [out] Pointers to pointers to memory where columns should be stored.

Returns

int Number of rows read on success, -1 on failure.

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

Encode a set of arrays as bytes.

Parameters

  • t – [in] constant asciiTable_t table structure.

  • data – [out] Pointer to memory where encoded arrays should be stored.

  • data_siz – [in] Integer size of data.

  • ... – [in] 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.

Returns

int Number of bytes written. If larger than data_siz, the message will not be written to data and data should be resized first.

static inline void at_cleanup(asciiTable_t *t)

Deallocate and clean up asciiTable_t structure.

Parameters

t – [in] asciiTable_t table structure.

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

Update an existing asciiTable_t structure.

Parameters

  • t – [in] asciiTable_t* Address of table structure to update.

  • filepath – [in] constant character pointer to file path.

  • io_mode – [in] constant character pointer to I/O mode. “r” for read, “w” for write.

Returns

int -1 if there is an error, 0 otherwise.

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

Parameters

  • filepath – [in] constant character pointer to file path.

  • io_mode – [in] constant character pointer to I/O mode. “r” for read, “w” for write.

  • format_str – [in] 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 – [in] const character pointer to character(s) that should indicate a comment. If NULL, comment is set to “# “.

  • column – [in] const character pointer to character(s) that should separate columns in the table. If NULL, column is set to “\t”.

  • newline – [in] const character pointer to character(s) that should indicate a newline. If NULL, newline is set to “\n”.

Returns

asciiTable_t table structure.

struct asciiTable_t
#include <AsciiTable.h>

Structure containing information about an ASCII table.

Public Members

asciiFile_t f

ASCII file structure.

char format_str[LINE_SIZE_MAX]

Format string for rows.

char column[64]

Character(s) used to seperate columns.

int ncols

Number of columns in the table.

int *format_typ

Array of ncols integers specifying column types.

int *format_siz

Array of ncols sizes for elements in each column.

int row_siz

Size of an entire row in bytes.

int status

Negative if format_str has not been set yet.