diff options
Diffstat (limited to 'clib/table.h')
| -rw-r--r-- | clib/table.h | 272 |
1 files changed, 272 insertions, 0 deletions
diff --git a/clib/table.h b/clib/table.h new file mode 100644 index 0000000..b2190b5 --- /dev/null +++ b/clib/table.h @@ -0,0 +1,272 @@ +/* + * Copyright (c) International Business Machines Corp., 2014 + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program. If not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ + +/*! + * @file table.h + * @brief Table Container + * @details For example, + * @code + * #include <clib/array.h> + * #include <clib/array_iter.h> + * + * int main(const int argc, const char * argv[]) { + * table t; + * table_init(&t, COLS); + * + * const char * str = "column0 is a really long string"; + * + * table_name(&t, "table name"); + * table_name(&t, 0, str); + * table_name(&t, 1, "column1"); + * table_name(&t, 2, "column2"); + * table_name(&t, 3, "column3"); + * table_name(&t, 4, "column4"); + * + * printf("%s\n", table_name(&t, 0)); + * + * size_t r, c; + * value v; + * + * for (r=0; r<COLS; r++) { + * for (c=0; c<COLS; c++) { + * table_put(&t, r, c, + * value_set(&v, r * COLS + c)); + * + * printf("t[%d][%d] --> %d\n", r, c, r * COLS + c); + * } + * } + * + * table_iter it; + * table_iter_init(&it, &t); + * + * value * val; + * table_for_each(&it, val) + * value_dump(val, stdout); + * + * table_delete(&t); + * + * return 0; + * } + * @endcode + * @author Shaun Wetzstein <shaun@us.ibm.com> + * @date 2010-2011 + */ + +#ifndef __TABLE_H__ +#define __TABLE_H__ + +#include <stdint.h> +#include <stdbool.h> + +#include "compare.h" +#include "vector.h" +#include "value.h" +#include "mqueue.h" + +/* ======================================================================= */ + +#define TABLE_NAME_SIZE 52 //!< Maximum table name size (in bytes) + +#define TABLE_MAGIC "TBLE" //!< Table magic number + +#define TABLE_FLAG_LSB 0x01 //!< little-endian header data +#define TABLE_FLAG_MSB 0x02 //!< big-endian header data + +#define INIT_TABLE_HEADER {INIT_IDENT,{0,},0} +#define INIT_TABLE {INIT_TABLE_HEADER,INIT_VECTOR,INIT_VECTOR,INIT_VECTOR} + +/*! + * @brief table container header + */ +struct table_header { + ident_t id; //!< Identification + char name[TABLE_NAME_SIZE]; //!< Table name + + size_t col_nr; //!< Number of columns +}; +typedef struct table_header table_header_t; //!< Alias for the @em table_header class + +/*! + * @brief table container + */ +struct table { //!< The Table class + table_header_t hdr; //!< Table metadata + + vector_t table; //!< @private + vector_t string; //!< @private + vector_t blob; //!< @private +}; +typedef struct table table_t; //!< Alias for the @em table class + +/* ==================================================================== */ + +/*! + * @brief Constructs a @em table object + * @memberof table + * @param self [in] table object @em self pointer + * @param name [in] table object @em name string + * @param col_nr [in] Number of columns + * @return None + */ +extern int table_init(table_t *, const char *, size_t) +/*! @cond */ +__nonnull((1, 2)) /*! @endcond */ ; + +/*! + * @brief Destructs an @em table container object + * @details Deallocate all backing storage associated with this \em table object + * @memberof table + * @param self [in] table object @em self pointer + * @return None + */ +extern int table_delete(table_t *) +/*! @cond */ +__nonnull((1)) /*! @endcond */ ; + +/*! + * @brief Copy content from the @em table + * @memberof table + * @param self [in] table object @em self pointer + * @param row [in] Row number + * @param col [out] Column number + * @return Reference to @em value on success, NULL otherwise + * @throws UNEXPECTED if @em self pointer is NULL + */ +extern value_t *table_get(table_t *, size_t, size_t) +/*! @cond */ +__nonnull((1)) /*! @endcond */ ; + +/*! + * @fn const void * table_row(table_iter_t * self, size_t row_nr, + * [ value_t * row ]) + */ +/*! @cond */ +#define table_row(...) STRCAT(table_row, NARGS(__VA_ARGS__))(__VA_ARGS__) +extern value_t *table_row2(table_t *, size_t) +/*! @cond */ +__nonnull((1)) /*! @endcond */ ; +extern int table_row3(table_t *, size_t, value_t *) +/*! @cond */ +__nonnull((1, 3)) /*! @endcond */ ; +/* !endcond */ + +extern value_t *table_column(table_t *, value_t *, size_t) +/*! @cond */ +__nonnull((1, 2)) /*! @endcond */ ; + +/*! + * @brief Assign new content to the @em table + * @memberof table + * @param self [in] table object @em self pointer + * @param row [in] Row number + * @param col [in] Column number + * @param value [in] Reference to source @em value + * @return None + * @throws UNEXPECTED if @em self pointer is NULL + */ +extern int table_put(table_t *, size_t, size_t, value_t *) +/*! @cond */ +__nonnull((1, 4)) /*! @endcond */ ; + +/*! + * @fn const char * table_name(table_t * self, size_t col, const char * name, + * size_t len) + * @brief Set or return the name of a column within a @em table + * @note If the fourth parameter is omitted, the @em name is assumed to contain + * a trailing NULL-byte + * @note If the third parameter is omitted, the column's current name is + * returned + * @memberof table + * @param self [in] table object @em self pointer + * @param col [in] Column number + * @param name [in] New column name string (optional) + * @param len [in] New column name string length (optional) + * @return None + * @throws UNEXPECTED if @em self pointer is NULL + */ + +/*! @cond */ +#define table_name(...) STRCAT(table_name, NARGS(__VA_ARGS__))(__VA_ARGS__) +extern const char *table_name2(table_t *, size_t) __nonnull((1)); + +#define table_name3(t,c,s) \ + choose_expr(const_expr(s), \ + _table_name3((t),(c),(const char *)(s)), \ + _table_name3((t),(c),(const char *)(s))) + +extern int _table_name3(table_t *, size_t, const char *) __nonnull((1, 3)); + +#define table_name4(t,c,s,l) \ + choose_expr(const_expr(s), \ + _table_name4((t),(c),(const char *)(s),(l)), \ + _table_name4((t),(c),(const char *)(s),(l))) + +extern int _table_name4(table_t *, size_t, const char *, size_t) +__nonnull((1, 3)); +/*! @endcond */ + +/*! + * @brief Return the number of rows in the @em table + * @memberof table + * @param self [in] table object @em self pointer + * @return None + */ +extern size_t table_rows(table_t *) /*! @cond */ __nonnull((1)) /*! @endcond */ +; + +/*! + * @brief Return the number of column in the @em table + * @memberof table + * @param self [in] table object @em self pointer + * @return None + */ +extern size_t table_columns(table_t *) +/*! @cond */ +__nonnull((1)) /*! @endcond */ ; + +extern int table_serialize(table_t *) +/*! @cond */ +__nonnull((1)) /*! @endcond */ ; + +extern int table_deserialize(table_t *) +/*! @cond */ +__nonnull((1)) /*! @endcond */ ; + +extern ssize_t table_save(table_t *, FILE *) +/*! @cond */ +__nonnull((1, 2)) /*! @endcond */ ; + +extern ssize_t table_load(table_t *, FILE *) +/*! @cond */ +__nonnull((1, 2)) /*! @endcond */ ; + +extern void table_print(table_t *, FILE *) +/*! @cond */ +__nonnull((1)) /*! @endcond */ ; + +extern void table_dump(table_t *, FILE *) +/*! @cond */ +__nonnull((1)) /*! @endcond */ ; + +extern int table_sort(table_t *, compare_f) +/*! @cond */ +__nonnull((1, 2)) /*! @endcond */ ; + +/* ==================================================================== */ + +#endif /* __TABLE_H__ */ |
