C DataIO API — cis_interface 0.3.0 documentation

# 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_t `filepath`

    Full path to file.

  char asciiFile_t `io_mode`[64]

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

  char asciiFile_t `comment`[64]

    Character(s) indicating a comment.

  char asciiFile_t `newline`[64]

    Character(s) indicating a newline.

  FILE *asciiFile_t `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:

  `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_t `f`

    ASCII file structure.

  char asciiTable_t `format_str`[`LINE_SIZE_MAX`]

    Format string for rows.

  char asciiTable_t `column`[64]

    Character(s) used to seperate columns.

  int asciiTable_t `ncols`

    Number of columns in the table.

  int *asciiTable_t `format_typ`

    Array of ncols integers specifying column types.

  int *asciiTable_t `format_siz`

    Array of ncols sizes for elements in each column.

  int asciiTable_t `row_siz`

    Size of an entire row in bytes.

  int asciiTable_t `status`

    Negative if format_str has not been set yet.