AT_PUT_STRING(3)
NAME
at_read, at_write, at_create, at_define_table, at_free,
at_check_n_grow, at_put_info, at_put_name, at_put_string,
at_put_time, at_put_value, at_rec_setkey_double,
at_rec_setkey_int, at_rec_setkey_str, at_rec_setkey_time,
at_rec_setkey_time_interval, at_rec_setkey_uint, at_col,
at_cols, at_rows, at_get_ascii, at_get_name, at_get_string,
at_get_time, at_get_value, at_rec_getkey_double,
at_rec_getkey_int, at_rec_getkey_str, AT_rec_getkey_str,
at_rec_getkey_time, at_rec_getkey_time_interval,
at_rec_getkey_uint, at_error_msg, at_in_bounds, at_copy_row,
at_remove_row, at_remove_rows
-a set of functions to create and manipulate tabular data
SYNOPSIS
#include <soi_at.h>
read and write tables
AT *at_read(char *pathname);
int at_write(AT *at, char *pathname);
create table
AT *at_create(char *header_info);
AT *at_define_table(int cols, int rows);
void at_free(AT *at);
int at_check_n_grow(AT *at, int col, int row);
insert info
int at_put_info(AT *at, char *header_info);
int at_put_name(AT *at, int col, char *name);
int at_put_string(AT *at, int col, int row, char *text);
int at_put_time (AT *at, int col, int row, double value);
int at_put_value(AT *at, int col, int row, double value);
int at_rec_setkey_double(AT *at, int rec, char *key, double dval);
int at_rec_setkey_int(AT *at, int rec, char *key, int ival);
int at_rec_setkey_str(AT *at, int rec, char *key, char *val);
int at_rec_setkey_time(AT *at, int rec, char *key, TIME tval);
int at_rec_setkey_time_interval(AT *at, int rec, char *key, TIME tival);
int at_rec_setkey_uint(AT *at, int rec, char *key, unsigned int ival);
retrieve info
int at_col(AT *at, char *data_name);
int at_cols(AT *at);
int at_rows(AT *at);
char *at_get_ascii(AT *at, int col, int row);
char *at_get_name(AT *at, int col);
char *at_get_string(AT *at, int col, int row);
double at_get_time (AT *at, int col, int row);
double at_get_value(AT *at, int col, int row);
double at_rec_getkey_double(AT *at, int rec, char *key);
int at_rec_getkey_int(AT *at, int rec, char *key);
char *at_rec_getkey_str(AT *at, int rec, char *key);
char *AT_rec_getkey_str(AT *at, int rec, char *key);
TIME at_rec_getkey_time(AT *at, int rec, char *key);
TIME at_rec_getkey_time_interval(AT *at, int rec, char *key);
unsigned int at_rec_getkey_uint(AT *at, int rec, char *key);
char *at_error_msg(AT *at);
int at_in_bounds(AT *at, int col, int row);
manipulate tables
int at_copy_row (AT *at, int new, int old);
int at_remove_row (AT *at, int row);
int at_remove_rows (AT *at, int row0, int row1);
DESCRIPTION
This library provides support for simple "spreadsheet-style"
tables of values. The terminology used is:
row A row in the table
col A column in the table
header an initial line with names
File format is RDB format with all data kept in strings in
the file and in the structure. functions are provided for
conversions to/from numbers and times
at_read reads an RDB formatted file and returns a pointer to
a table data structure containing the column headings, rows,
and columns of the file. It uncompresses files using zcat
if necessary. It returns NULL on error and sets soi_errno.
Note that the return from reading a 0 length file is not
treated as an error but rather returns a pointer to a struc-
ture with no rows and columns.
at_write writes an RDB formatted file containing the column
headings, rows, and columns of the table data structure.
at_create creates a table with column headings but no rows.
The info argument to at_create is a string containing the
tab-separated column headings.
at_free frees free all memory associated with a table data
structure. It does not (and cannot) set the pointer argu-
ment itself to NULL.
at_col returns the column index of the table column with the
given heading. On error, it returns AT_BAD_COL_COUNT.
at_cols returns the number of columns in the table.
at_rows returns the number of rows in the table.
at_put* functions insert info into a table. at_put_info
adds string of one or more lines. Other put functions
insert cells into the table based on column and row indices,
performing data conversions as necessary.
at_rec_setkey* functions insert cells into the table based
on column name and row index and perform data conversions..
at_get* and at_at_rec_getkey* retrieve information from a
table data structure.
at_copy_row() copies the contents of row old to new; both
original and target records must be within the existing
table range.
at_remove_row() removes the requested row from the table.
at_remove_rows() removes rows row0 through row1 inclusive
from the table. The entire range of deleted rows must be
within the table; otherwise nothing is removed.
EXAMPLES
The function to read an existing table is:
AT *at; at = at_read("filename");
The function to save a table to a file is:
AT *at; at_write(at, "filename");
To make a table from scratch, a line of names must be pro-
vided. they should be delimited by tabs. The name line can
be ingested with "at_put_info" A line of "---" per col
should follow with at_put_info. Then the data can be ing-
ested a line at a time with "at_put_info"
Alternatively, set the table rows and cols with
"at_define_table" then stick in the names and values at will
with at_put_name and at_put_value, at_put_time,
at_put_string calls.
FILES
~soi/CM/include/soi_key.h
SEE ALSO
~soi/CM/src/modules/*.c ~soi/CM/src/pipe/*.c
/soidata/info/mdi_rec/lev*/*/*.record.rdb*
DIAGNOSTICS
soi_errno is set on error.
BUGS
The structure of the AT is too tightly bound to the RDB file
format; more general representations of ASCII tabular data
should be supported.
HISTORY
2001.07.06 SOI Version 4.8