3 * $Id: atom.h,v 1.2 2001/01/25 21:13:40 mdw Exp $
7 * (c) 2000 Straylight/Edgeware
10 /*----- Licensing notice --------------------------------------------------*
12 * This file is part of the mLib utilities library.
14 * mLib is free software; you can redistribute it and/or modify
15 * it under the terms of the GNU Library General Public License as
16 * published by the Free Software Foundation; either version 2 of the
17 * License, or (at your option) any later version.
19 * mLib is distributed in the hope that it will be useful,
20 * but WITHOUT ANY WARRANTY; without even the implied warranty of
21 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
22 * GNU Library General Public License for more details.
24 * You should have received a copy of the GNU Library General Public
25 * License along with mLib; if not, write to the Free
26 * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
30 /*----- Revision history --------------------------------------------------*
33 * Revision 1.2 2001/01/25 21:13:40 mdw
34 * New function allowing an atom's length to be specified at intern time.
35 * Add @ATOM_HASH@ macro so that assoc doesn't have to dig in the @atom@
38 * Revision 1.1 2001/01/20 11:50:16 mdw
39 * Implementation of atom tables (for example, as found in X11).
50 /*----- Header files ------------------------------------------------------*/
56 /*----- Data structures ---------------------------------------------------*/
58 typedef struct atom_table {
59 sym_table t; /* Symbol table of interned atoms */
60 hash_base *g; /* List of uninterned atoms */
61 unsigned long gseq; /* Sequence number for @gensym@ */
65 sym_base b; /* Base structure for symbol table */
66 unsigned f; /* Various useful flags */
69 #define ATOMF_GENSYM 1u /* Atom is uninterned */
71 typedef struct { sym_iter i; } atom_iter;
73 /*----- Global magic ------------------------------------------------------*/
77 /*----- Functions provided ------------------------------------------------*/
79 /* --- @atom_createtable@ --- *
81 * Arguments: @atom_table *t@ = pointer to an atom table
85 * Use: Initializes an atom table.
88 extern void atom_createtable(atom_table */*t*/);
90 /* --- @atom_destroytable@ --- *
92 * Arguments: @atom_table *t@ = pointer to an atom table
96 * Use: Destroys all of the atoms in an atom table. All of the atoms
97 * (including uninterned atoms) are freed. Any references to
98 * atoms from the table become invalid, and any association
99 * tables dependent on the atom table are unusable, except that
100 * they may be destroyed safely.
103 extern void atom_destroytable(atom_table */*t*/);
105 /* --- @atom_intern@ --- *
107 * Arguments: @atom_table *t@ = pointer to an atom table
108 * @const char *p@ = pointer to the string to intern
109 * @size_t n@ = size of the string (for @atom_nintern)
111 * Returns: A pointer to the atom block for the given symbol string.
113 * Use: Interns an atom, returning the atom block. The string can be
114 * extracted from the atom by means of the @ATOM_NAME@ macro.
117 #define INTERN(p) atom_intern(ATOM_GLOBAL, (p))
119 extern atom *atom_intern(atom_table */*t*/, const char */*p*/);
120 extern atom *atom_nintern(atom_table */*t*/,
121 const char */*p*/, size_t /*n*/);
123 /* --- @atom_gensym@ --- *
125 * Arguments: @atom_table *t@ = pointer to a symbol table
127 * Returns: A pointer to a new atom block, not previously interned.
129 * Use: Creates a new, uninterned atom. This atom will never be
130 * returned by either @atom_intern@ or any other call to
131 * @atom_gensym@, while the symbol table exists.
134 #define GENSYM atom_gensym(ATOM_GLOBAL)
136 extern atom *atom_gensym(atom_table */*t*/);
138 /* --- @atom_name@ --- *
140 * Arguments: @atom *a@ = pointer to an atom
142 * Returns: The atom's textual name.
144 * Use: Given an atom, returns the name with which it was interned
145 * (or a made-up name if it was created using @gensym@.
148 #define ATOM_NAME(a) SYM_NAME(a)
150 extern const char *atom_name(const atom */*a*/);
152 /* --- @atom_len@ --- *
154 * Arguments: @atom *a@ = pointer to an atom
156 * Returns: The atom string's length.
158 * Use: Given an atom, return the length of its textual
162 #define ATOM_LEN(a) SYM_LEN(a)
164 extern size_t atom_len(const atom */*a*/);
166 /* --- @atom_hash@ --- *
168 * Arguments: @atom *a@ = pointer to an atom
170 * Returns: The atom's hash.
172 * Use: Given an atom, returns its hash.
175 #define ATOM_HASH(a) SYM_HASH(a)
177 extern uint32 atom_hash(const atom */*a*/);
179 /* --- @atom_mkiter@ , @atom_next@ --- *
181 * Arguments: @atom_table *t@ = pointer to an atom table
182 * @atom_iter *i@ = pointer to an iterator structure
184 * Returns: Next atom, for @atom_next@; nothing for @atom_mkiter@.
186 * Use: Iterates over atoms (both interned and uninterned).
189 extern void atom_mkiter(atom_iter */*i*/, atom_table */*t*/);
190 extern atom *atom_next(atom_iter */*i*/);
192 /*----- That's all, folks -------------------------------------------------*/