Since the book explains its design and implementation in a very comprehensive way, not to mention the copyright issues, it is nothing but waste to repeat it here, so I finish this document by giving introduction to the library; how to use the facilities is deeply explained in files that define them.
The Table Library reserves identifiers starting with table_
and TABLE_
, and imports the Assertion Library (which requires the Exception Handling Library) and the Memory Management Library.
Similarly for other data structure libraries, use of the Table Library follows this sequence: create, use and destroy. Except for functions to inspect tables, all other functions do one of them in various ways.
table_new() that creates an empty table takes three unusual arguments. The first one is a hint for the expected length of the table it creates, and the other two are to specify user-defined functions that perform creation and comparison of hash values used to represent keys. Some important conditions that those functions have to satisfy are described in the function.
Once a table created, a key-value pair can be added to and removed from a table using table_put() and table_remove(). Adding a pair to a table also entails memory allocation, and thus an exception can be raised. table_get() takes a key and returns its relevant value if any, and table_length() gives the number of key-value pairs in a table, a.k.a. the length of a table.
There are two ways to apply some operations on every pair in a table; table_map() takes a user-defined function and calls it for each of key-value pairs, and table_toarray() converts a table into a dynamic arrays; the array converted from a table has keys in elements with even indices and values in those with odd ones. A storage for the generated array is allocated by the library (thus, an exception is possible again), but a user program is responsible for releasing the storage when the array is no longer necessary.
table_free() takes a table and releases the storage used to maintain it. Note that any storage allocated by a user program to contain or represent keys and values is not deallocated by the library.
As an example, the following code creates a table (whose expected length is set to 20 and keys are generated by the Hash Library), and uses it to compute the frequencies of different characters in the input. To explain details, it first inspects if the table already has an input character and its frequency in it. If found, the frequency is simply increased. Otherwise, a storage to contain the frequency is allocated and put into the table after set properly.
(This is intended to just show an example for using a table; as you (and probably everyone who have learned to program in C) already know, an ordinary array is enough to print the frequencies of different characters that appear in the user input.)
int c; char b; int *pfrq; table_t *mytab; const char *key; void **pa, **pb; mytab = table_new(20, NULL, NULL); while ((c = getchar()) != EOF) { b = c; key = hash_new(&b, 1); if ((pfrq = table_get(mytab, key))) == NULL) { MEM_NEW(pfrq); *pfrq = 0; } (*pfrq)++; table_put(mytab, key, pfrq); } pa = table_toarray(mytab, NULL); for (pb = pa; *pb; pb += 2) { printf("%c: %d\n", *(char *)pb[0], *(int *)pb[1]); MEM_FREE(pb[1]); } MEM_FREE(pa); hash_reset(); table_free(&mytab);
where hash_new() and hash_reset() come from the Hash Library, and MEM_NEW() and MEM_FREE() from the Memory Management Library.
Things to note include:
Any comments about the library are welcomed. If you have a proposal or question on the library just email me, and then I will reply as soon as possible.
Copyright (c) 1994,1995,1996,1997 by David R. Hanson.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
For the parts I added or modified, the following applies:
Copyright (C) 2009-2011 by Jun Woong.
This package is a table implementation by Jun Woong. The implementation was written so as to conform with the Standard C published by ISO 9899:1990 and ISO 9899:1999.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.