chiark / gitweb /
New function allowing an atom's length to be specified at intern time.
[mLib] / atom.h
CommitLineData
c1c43500 1/* -*-c-*-
2 *
3 * $Id: atom.h,v 1.1 2001/01/20 11:50:16 mdw Exp $
4 *
5 * Atom management
6 *
7 * (c) 2000 Straylight/Edgeware
8 */
9
10/*----- Licensing notice --------------------------------------------------*
11 *
12 * This file is part of the mLib utilities library.
13 *
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.
18 *
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.
23 *
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,
27 * MA 02111-1307, USA.
28 */
29
30/*----- Revision history --------------------------------------------------*
31 *
32 * $Log: atom.h,v $
33 * Revision 1.1 2001/01/20 11:50:16 mdw
34 * Implementation of atom tables (for example, as found in X11).
35 *
36 */
37
38#ifndef MLIB_ATOM_H
39#define MLIB_ATOM_H
40
41#ifdef __cplusplus
42 extern "C" {
43#endif
44
45/*----- Header files ------------------------------------------------------*/
46
47#ifndef MLIB_SYM_H
48# include "sym.h"
49#endif
50
51/*----- Data structures ---------------------------------------------------*/
52
53typedef struct atom_table {
54 sym_table t; /* Symbol table of interned atoms */
55 hash_base *g; /* List of uninterned atoms */
56 unsigned long gseq; /* Sequence number for @gensym@ */
57} atom_table;
58
59typedef struct atom {
60 sym_base b; /* Base structure for symbol table */
61 unsigned f; /* Various useful flags */
62} atom;
63
64#define ATOMF_GENSYM 1u /* Atom is uninterned */
65
66typedef struct { sym_iter i; } atom_iter;
67
68/*----- Global magic ------------------------------------------------------*/
69
70#define ATOM_GLOBAL 0
71
72/*----- Functions provided ------------------------------------------------*/
73
74/* --- @atom_createtable@ --- *
75 *
76 * Arguments: @atom_table *t@ = pointer to an atom table
77 *
78 * Returns: ---
79 *
80 * Use: Initializes an atom table.
81 */
82
83extern void atom_createtable(atom_table */*t*/);
84
85/* --- @atom_destroytable@ --- *
86 *
87 * Arguments: @atom_table *t@ = pointer to an atom table
88 *
89 * Returns: ---
90 *
91 * Use: Destroys all of the atoms in an atom table. All of the atoms
92 * (including uninterned atoms) are freed. Any references to
93 * atoms from the table become invalid, and any association
94 * tables dependent on the atom table are unusable, except that
95 * they may be destroyed safely.
96 */
97
98extern void atom_destroytable(atom_table */*t*/);
99
100/* --- @atom_intern@ --- *
101 *
102 * Arguments: @atom_table *t@ = pointer to an atom table
103 * @const char *p@ = pointer to the string to intern
104 *
105 * Returns: A pointer to the atom block for the given symbol string.
106 *
107 * Use: Interns an atom, returning the atom block. The string can be
108 * extracted from the atom by means of the @ATOM_NAME@ macro.
109 */
110
111#define INTERN(p) atom_intern(ATOM_GLOBAL, (p))
112
113extern atom *atom_intern(atom_table */*t*/, const char */*p*/);
114
115/* --- @atom_gensym@ --- *
116 *
117 * Arguments: @atom_table *t@ = pointer to a symbol table
118 *
119 * Returns: A pointer to a new atom block, not previously interned.
120 *
121 * Use: Creates a new, uninterned atom. This atom will never be
122 * returned by either @atom_intern@ or any other call to
123 * @atom_gensym@, while the symbol table exists.
124 */
125
126#define GENSYM atom_gensym(ATOM_GLOBAL)
127
128extern atom *atom_gensym(atom_table */*t*/);
129
130/* --- @atom_name@ --- *
131 *
132 * Arguments: @atom *a@ = pointer to an atom
133 *
134 * Returns: The atom's textual name.
135 *
136 * Use: Given an atom, returns the name with which it was interned
137 * (or a made-up name if it was created using @gensym@.
138 */
139
140#define ATOM_NAME(a) SYM_NAME(a)
141
142extern const char *atom_name(const atom */*a*/);
143
144/* --- @atom_len@ --- *
145 *
146 * Arguments: @atom *a@ = pointer to an atom
147 *
148 * Returns: The atom string's length.
149 *
150 * Use: Given an atom, return the length of its textual
151 * representation.
152 */
153
154#define ATOM_LEN(a) (SYM_LEN(a) - 1)
155
156extern size_t atom_len(const atom */*a*/);
157
158/* --- @atom_hash@ --- *
159 *
160 * Arguments: @atom *a@ = pointer to an atom
161 *
162 * Returns: The atom's hash.
163 *
164 * Use: Given an atom, returns its hash.
165 */
166
167#define ATOM_HASH(a) SYM_HASH(a)
168
169extern uint32 atom_hash(const atom */*a*/);
170
171/* --- @atom_mkiter@ , @atom_next@ --- *
172 *
173 * Arguments: @atom_table *t@ = pointer to an atom table
174 * @atom_iter *i@ = pointer to an iterator structure
175 *
176 * Returns: Next atom, for @atom_next@; nothing for @atom_mkiter@.
177 *
178 * Use: Iterates over atoms (both interned and uninterned).
179 */
180
181extern void atom_mkiter(atom_iter */*i*/, atom_table */*t*/);
182extern atom *atom_next(atom_iter */*i*/);
183
184/*----- That's all, folks -------------------------------------------------*/
185
186#ifdef __cplusplus
187 }
188#endif
189
190#endif