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] ptable pointer 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 given key.

Possible exceptions: assert_exceptfail

Unchecked errors: foreign data structure given for table

Parameters:
[in] table table in which key-value pair to be found
[in] key key for which value to be returned
Returns:
value for given key or null pointer
Return values:
non-null value found
NULL value 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 all key-value pairs in a table.

Possible exceptions: assert_exceptfail

Unchecked errors: foreign data structure given for table

Parameters:
[in] table table 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 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

Parameters:
[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
Returns:
previous value for key or null pointer
Return values:
non-null previous value
NULL no 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 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

Parameters:
[in,out] table table from which key-value pair removed
[in] key key for which key-value pair removed
Returns:
previous value for given key or null pointer
Return values:
non-null previous value for key
NULL key 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 is not zero, since there is always an end-mark.

As in table_map(), the order in which an array is created for each key-value pair is unspecified.

Parameters:
[in] table table for which array generated
[in] end end-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.


Generated on Mon Jan 24 01:13:08 2011 for The Table Library by  doxygen 1.5.8