home *** CD-ROM | disk | FTP | other *** search
/ GEMini Atari / GEMini_Atari_CD-ROM_Walnut_Creek_December_1993.iso / files / program / funnel / table.h < prev    next >
Encoding:
C/C++ Source or Header  |  1993-10-23  |  10.7 KB  |  190 lines
  1. /*##############################################################################
  2.  
  3. FUNNNELWEB COPYRIGHT
  4. ====================
  5. FunnelWeb is a literate-programming macro preprocessor.
  6.  
  7. Copyright (C) 1992 Ross N. Williams.
  8.  
  9.    Ross N. Williams
  10.    ross@spam.adelaide.edu.au
  11.    16 Lerwick Avenue, Hazelwood Park 5066, Australia.
  12.  
  13. This program is free software; you can redistribute it and/or modify
  14. it under the terms of Version 2 of the GNU General Public License as
  15. published by the Free Software Foundation.
  16.  
  17. This program is distributed WITHOUT ANY WARRANTY; without even the implied
  18. warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  19. See Version 2 of the GNU General Public License for more details.
  20.  
  21. You should have received a copy of Version 2 of the GNU General Public
  22. License along with this program. If not, you can FTP the license from
  23. prep.ai.mit.edu/pub/gnu/COPYING-2 or write to the Free Software
  24. Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  25.  
  26. Section 2a of the license requires that all changes to this file be
  27. recorded prominently in this file. Please record all changes here.
  28.  
  29. Programmers:
  30.    RNW  Ross N. Williams  ross@spam.adelaide.edu.au
  31.  
  32. Changes:
  33.    07-May-1992  RNW  Program prepared for release under GNU GPL V2.
  34.  
  35. ##############################################################################*/
  36.  
  37.  
  38. /******************************************************************************/
  39. /*                                   TABLE.H                                  */
  40. /******************************************************************************/
  41. /*                                                                            */
  42. /* Introduction                                                               */
  43. /* ------------                                                               */
  44. /* This table package (table.h and table.c) implements a table abstraction.   */
  45. /*                                                                            */
  46. /* Facts about Tables                                                         */
  47. /* ------------------                                                         */
  48. /* - A TABLE stores zero or more (KEY,VALUE) PAIRS.                           */
  49. /* - The user decides the types of keys and values and provides a             */
  50. /*   COMPARISON FUNCTION providing a complete ordering of the set of keys.    */
  51. /* - The comparison function must be consistent between calls.                */
  52. /* - Tables store pairs in key order.                                         */
  53. /* - A table cannot store more than one pair with the same key.               */
  54. /* - Pairs can be added, but not deleted.                                     */
  55. /* - A table can return the value corresponding to a given key.               */
  56. /* - The pairs in a table can be read sequentially in key order. At all       */
  57. /*   times, the table has an imaginary MARKER positioned on one of its pairs  */
  58. /*   (or after the last pair). You can move the marker to the first pair and  */
  59. /*   you can move the marker to the next pair, reading the pair as you go.    */
  60. /*   Upon table creation, a table's marker is at the end-of-table position.   */
  61. /* - If you try to perform an illegal operation on a table, the table package */
  62. /*   will call "error" to write out an error message and bomb the program.    */
  63. /* - Tables store copies of (key,value) pairs. They do not hold pointers to   */
  64. /*   outside data (unless your keys or values are pointers themselves).       */
  65. /* - If the keys are pointers themselves and point to other data which is     */
  66. /*   used by the comparison function, then that data must not be modified     */
  67. /*   in a way that will change the order of pairs in the table.               */
  68. /* - A table can hold from zero to about 2^31 pairs.                          */
  69. /* - The identifier "tb" is used as an abbreviation for "table".              */
  70. /* - The identifier "ky" is used as an abbreviation for "key".                */
  71. /* - The identifier "vl" is used as an abbreviation for "value".              */
  72. /* - The author would like to use longer names, but has chosen to use the     */
  73. /*   abbreviations so as to enhance the portability of the code.              */
  74. /* - IMPORTANT: Tables get all their memory using mm_temp calls.              */
  75. /*                                                                            */
  76. /* How To Use This Table Package                                              */
  77. /* -----------------------------                                              */
  78. /* 1. Include this .H file in your program file.                              */
  79. /* 2. Identify the key and value types that you are going to use.             */
  80. /* 3. Define a function (having two parameters being pointers to keys)        */
  81. /*    that compares two keys and returns [-1,0,1] accordingly.                */
  82. /* 4. Define a variable of type p_tb as a view to a table.                    */
  83. /* 5. Use the tb_* functions to perform the desired operations.               */
  84. /*    Start with a call to tb_cre and (optionally) end with a call to tb_des. */
  85. /*                                                                            */
  86. /******************************************************************************/
  87.  
  88. /* Ensure that the body of this header file is included at most once.         */
  89. #ifndef DONE_TABLE
  90. #define DONE_TABLE
  91.  
  92. /******************************************************************************/
  93.  
  94. #include <stddef.h>
  95. #include "style.h"
  96.  
  97. /******************************************************************************/
  98.  
  99. /* Hide the exported abstract definition of a table from the table.c package. */
  100. /* Table.c defines INTABLEC so as to prevent itself from seeing the following */
  101. /* definitions. It defines its own more concrete definitions.                 */
  102. #ifndef INTABLEC
  103.  
  104. /* The functions of the table abstraction pass keys and values exclusively    */
  105. /* using pointers. These two definitions define types for these pointers.     */
  106. /* Although the two types are both 'p_void', the different types are useful   */
  107. /* to indicate what is expected in each position of the parameter lists.      */
  108. typedef p_void p_tbky_t;
  109. typedef p_void p_tbvl_t;
  110.  
  111. /* Define a type for a function to compare two keys. Such functions are       */
  112. /* needed to organize the storage of (key,value) pairs inside the table.      */
  113. /* Given the arguments are (a,b), the function should return:                 */
  114. /*    -1 if a<b                                                               */
  115. /*     0 if a==b                                                              */
  116. /*     1 if a>b                                                               */
  117. /* The user must create such a function and hand it to the 'tb_create'        */
  118. /* function when creating new a new table.                                    */
  119. typedef sign (*p_kycm_t) P_((p_tbky_t,p_tbky_t));
  120.  
  121. /* Users manipulate tables through pointers to tables. Here the actual table  */
  122. /* internals are hidden from the user.                                        */
  123. typedef struct {word NEVER_USE_THIS_FIELD_UQJTKC;} tb_t;
  124. typedef tb_t *p_tb_t;
  125.  
  126. #endif
  127.  
  128. /******************************************************************************/
  129.  
  130. /* General Notes About These Functions                                        */
  131. /* -----------------------------------                                        */
  132. /* - All tables, keys, and values are passed by pointer. Whether a parameter  */
  133. /*   is read or written is determined by it's functions description.          */
  134. /* - Each function (except tb_cre) accepts a single pointer to a table and    */
  135. /*   each function's description is assumed to be referring to the table.     */
  136. /* - "Raising an error" means calling the external function "error" to        */
  137. /*   write out a message and bomb the program.                                */
  138. /* - You must create a table using tb_cre before performing any operations    */
  139. /*   upon it. The table operations will usually raise an error if they are    */
  140. /*   handed a pointer that does not point to a properly CREated table.        */
  141.  
  142. /* The Functions                                                              */
  143. /* -------------                                                              */
  144. EXPORT p_tb_t tb_cre P_((size_t,size_t,p_kycm_t));
  145. /* CREate. This function creates a new table and returns a pointer to the     */
  146. /* table. The user must supply 1) the size in bytes of keys, 2) the size in   */
  147. /* bytes of values, 3) a pointer to a function that compares two keys.        */
  148.  
  149. EXPORT bool tb_itb P_((p_tb_t,p_tbky_t));
  150. /* InTaBle. Returns TRUE iff the given key is in the table.                   */
  151.  
  152. EXPORT void tb_loo P_((p_tb_t,p_tbky_t,p_tbvl_t));
  153. /* LOOkup. Feed this function a table and a key and it will return (in the    */
  154. /* p_tbvl_t parameter) the value corresponding to the key. The function       */
  155. /* raises an error if the table does not contain the key.                     */
  156.  
  157. EXPORT void tb_ins P_((p_tb_t,p_tbky_t,p_tbvl_t));
  158. /* INSert. Inserts the (key,value) pair into the table. Raises an error if    */
  159. /* the key is already in the table.                                           */
  160.  
  161. EXPORT ulong tb_len P_((p_tb_t));
  162. /* LENgth. Returns the number of pairs in the table. */
  163.  
  164. EXPORT void tb_fir P_((p_tb_t));
  165. /* FIRst. Set's the table's marker to the first pair in the table (or the end */
  166. /* of table position if the table is empty.                                   */
  167.  
  168. EXPORT bool tb_rea P_((p_tb_t,p_tbky_t,p_tbvl_t));
  169. /* REAd. Returns in (p_tbky_t,p_tbvl_t) the (key,value) pair corresponding to */
  170. /* the marker and them moves the marker onto the next pair.                   */
  171. /* Returns TRUE  => Returned a pair.                                          */
  172. /* Returns FALSE => Did not return a pair. No more pairs left.                */
  173. /* of key) to be read from the table. Returns TRUE if it returns a pair       */
  174. /* This function will not raise an error if it is called more than once with  */
  175. /* the marker at the end of the table (it just keeps returning FALSE).        */
  176.  
  177. #if FALSE
  178. void tb_des P_((p_tb_t));
  179. /* DEStroy. Destroys a table, deallocating all its memory.                    */
  180. #endif
  181.  
  182. /******************************************************************************/
  183.  
  184. /* For #ifndef preventing multiple inclusion of the body of this header file. */
  185. #endif
  186.  
  187. /******************************************************************************/
  188. /*                                 End of TABLE.H                             */
  189. /******************************************************************************/
  190.