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

t: constant asciiFile_t file structure.

static int af_open(asciiFile_t *t)¶

Open the file.

Return

int 0 if opened successfully, -1 otherwise.

Parameters

t: constant asciiFile_t file structure.

static int af_close(asciiFile_t *t)¶

Close the file.

Return

int 0 if closed successfully, -1 otherwise.

Parameters

t: constant asciiFile_t file structure.

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

t: asciiTable_t table structure.

static void at_close(asciiTable_t *t)¶

Close the file.

Return

int 0 if ocloseded successfully, -1 otherwise.

Parameters

t: asciiTable_t table structure.

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

t: constant asciiTable_t table structure.

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

t: constant asciiTable_t table structure.

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

t: constant asciiTable_t table structure.

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

t: asciiTable_t table structure.

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.