#include <stddef.h>
Typedefs | |
typedef struct table_t | table_t |
represents a table. | |
Functions | |
table creating/destroying functions: | |
table_t * | table_new (int, int(const void *, const void *), unsigned(const void *)) |
void | table_free (table_t **) |
destroys a table. | |
data/information retrieving functions: | |
size_t | table_length (const table_t *t) |
returns the length of a table. | |
void * | table_put (table_t *, const void *, void *) |
puts a value for a key to a table. | |
void * | table_get (const table_t *, const void *) |
gets data for a key from a table. | |
void * | table_remove (table_t *, const void *) |
removes a key-value pair from a table. | |
table handling functions: | |
void | table_map (table_t *, void(const void *, void **, void *), void *) |
void ** | table_toarray (const table_t *, void *) |
converts a table to an array. |
Header for Table Library (CDSL).
void table_free | ( | table_t ** | ptable | ) |
destroys a table.
table_free() destroys a table by deallocating the stroage for it and set a given pointer to the null pointer. As always, table_free() does not deallocate storages for values in the table, which must be done by a user.
Possible exceptions: assert_exceptfail
Unchecked errors: pointer to foreign data structure given for ptable
[in,out] | ptable | pointer to table to destroy |
void* table_get | ( | const table_t * | table, | |
const void * | key | |||
) |
gets data for a key from a table.
table_get() returns a value associated with a given key.
Possible exceptions: assert_exceptfail
Unchecked errors: foreign data structure given for table
[in] | table | table in which key-value pair to be found |
[in] | key | key for which value to be returned |
non-null | value found | |
NULL | value not found |
size_t table_length | ( | const table_t * | table | ) |
returns the length of a table.
table_length() returns the length of a table which is the number of all key-value pairs in a table.
Possible exceptions: assert_exceptfail
Unchecked errors: foreign data structure given for table
[in] | table | table whose length returned |
void* table_put | ( | table_t * | table, | |
const void * | key, | |||
void * | value | |||
) |
puts a value for a key to a table.
table_put() replaces an existing value for a given key with given one and returns the previous value. If there is no existing one, the given value is saved for the key and returns a null pointer.
Note that both a key and a value are pointers. If values are, say, integers in an application, objects to contain them are necessary to put them into a table.
Possible exceptions: assert_exceptfail, mem_exceptfail
Unchecked errors: foreign data structure given for table
[in,out] | table | table to which value to be stored |
[in] | key | key for which value to be stored |
[in] | value | value to store to table |
non-null | previous value | |
NULL | no previous value found |
void* table_remove | ( | table_t * | table, | |
const void * | key | |||
) |
removes a key-value pair from a table.
table_remove() gets rid of a key-value pair for a given key from a table. Note that table_remove() does not deallocate any storage for the pair to remove, which must be done by an user.
Possible exceptions: assert_exceptfail
Unchecked errors: foreign data structure given for table
[in,out] | table | table from which key-value pair removed |
[in] | key | key for which key-value pair removed |
non-null | previous value for key | |
NULL | key not found |
void** table_toarray | ( | const table_t * | table, | |
void * | end | |||
) |
converts a table to an array.
table_toarray() converts key-value pairs stored in a table to an array. The last element of the constructed array is assigned by end
, which is a null pointer in most cases. Do not forget deallocate the array when it is unnecessary.
The resulting array is consisted of key-value pairs: its elements with even indices have keys and those with odd indices have corresponding values. For example, the second element of a resulting array has a value corresponding to a key stored in the first element. Note that the end-marker given as end
has no corresponding value element.
Possible exceptions: assert_exceptfail, mem_exceptfail
Unchecked errors: foreign data structure given for table
As in table_map(), the order in which an array is created for each key-value pair is unspecified.
[in] | table | table for which array generated |
[in] | end | end-mark to save in last element of array |