The Table Library  0.2.1
Typedefs
table.h File Reference

Documentation for Table Library (CDSL) More...

#include <stddef.h>
Include dependency graph for table.h:
This graph shows which files directly or indirectly include this file:

Typedefs

typedef struct table_t table_t
 represents a table.

Functions

table creating/destroying functions:
table_ttable_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.

Detailed Description

Documentation for Table Library (CDSL)

Header for Table Library (CDSL)


Function Documentation

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

Parameters:
[in,out]ptablepointer to table to destroy
Returns:
nothing
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 key.

Possible exceptions: assert_exceptfail

Unchecked errors: foreign data structure given for table

Parameters:
[in]tabletable in which key-value pair to be found
[in]keykey for which value to be returned
Returns:
value for given key or null pointer
Return values:
non-nullvalue found
NULLvalue not found
Warning:
If the stored value was a null pointer, an ambiguous situation may occur.
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 key-value pairs in a table.

Possible exceptions: assert_exceptfail

Unchecked errors: foreign data structure given for table

Parameters:
[in]tabletable whose length returned
Returns:
length of table
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 key with a new one and returns the previous value. If there is no existing one, the 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

Parameters:
[in,out]tabletable to which value to be stored
[in]keykey for which value to be stored
[in]valuevalue to store to table
Returns:
previous value for key or null pointer
Return values:
non-nullprevious value
NULLno previous value found
Warning:
If the stored value was a null pointer, an ambiguous situation may occur.
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 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

Parameters:
[in,out]tabletable from which key-value pair removed
[in]keykey for which key-value pair removed
Returns:
previous value for given key or null pointer
Return values:
non-nullprevious value for key
NULLkey not found
Warning:
If the stored value is a null pointer, an ambiguous situation may occur.
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

Warning:
The size of an array generated from an empty table cannot be zero, since there is always an end-mark value.
As in table_map(), the order in which an array is created for each key-value pair is unspecified.
Parameters:
[in]tabletable for which array generated
[in]endend-mark to save in last element of array
Returns:
array generated from table
Todo:
Improvements are possible and planned:
  • it sometimes serves better to call a user callback for key-value pairs in order they are stored.
 All Files Functions Typedefs