chiark / gitweb /
Infrastructure: Split the files into subdirectories.
[mLib] / struct / atom.3
CommitLineData
1025598e 1.\" -*-nroff-*-
2.de VS
3.sp 1
4.RS
5.nf
6.ft B
7..
8.de VE
9.ft R
10.fi
11.RE
12.sp 1
13..
fbf20b5b 14.TH atom 3 "21 January 2001" "Straylight/Edgeware" "mLib utilities library"
1025598e 15.SH NAME
16atom \- atom table manager
17.\" @atom_createtable
18.\" @atom_destroytable
19.\" @atom_intern
20.\" @atom_nintern
21.\" @atom_gensym
22.\" @atom_name
23.\" @atom_len
24.\" @atom_hash
25.\" @atom_mkiter
26.\" @atom_next
27.\"
28.\" @ATOM_GLOBAL
29.\" @INTERN
30.\" @GENSYM
31.\" @ATOM_NAME
32.\" @ATOM_LEN
33.\" @ATOM_HASH
34.\"
35.SH SYNOPSIS
36.nf
37.B "#include <mLib/atom.h>"
38
39.BI "void atom_createtable(atom_table *" t );
40.BI "void atom_destroytable(atom_table *" t );
41
42.BI "atom *atom_intern(atom_table *" t ", const char *" p );
43.BI "atom *atom_nintern(atom_table *" t ", const char *" p ", size_t " n );
44.BI "atom *atom_gensym(atom_table *" t );
45.BI "atom *INTERN(const char *" p );
46.BI "atom *GENSYM;"
47
48.BI "const char *atom_name(const atom *" a );
49.BI "size_t atom_len(const atom *" a );
50.BI "uint32 atom_hash(const atom *" a );
51.BI "const char *ATOM_NAME(const atom *" a );
52.BI "size_t ATOM_LEN(const atom *" a );
53.BI "uint32 ATOM_HASH(const atom *" a );
54
55.BI "void atom_mkiter(atom_iter *" i ", atom_table *" t );
56.BI "atom *atom_next(atom_iter *" i );
57
58.BI "extern atom_table *ATOM_GLOBAL;"
59.fi
60.SH DESCRIPTION
61The
62.B atom
63functions and macros implement a data type similar to immutable strings,
64with an additional property: that the addresses of two atoms from the
65same table are equal if and only if they contain the same text. Atom
66strings don't have to be null-terminated, although the interface is
67simpler if you know that all of your atoms are null-terminated. It's
68also possible to make
69.IR "uninterned atoms" :
70see below.
71.PP
72If a necessary memory allocation fails during an atom operation, the
73exception
74.B EXC_NOMEM
75is raised.
76.PP
77Atoms are useful for speeding up string comparisons, and for saving
78memory when many possibly-identical strings need storing.
79.PP
80There is a global atom table, named
81.BR ATOM_GLOBAL ,
82available for general use. You can initialize your own atom table if
83either you want to ensure that the atoms are not shared with some other
84table, or if you want to be able to free the atoms later. Private atom
85tables have the type
86.BR atom_table ;
87initialize it using the function
88.B atom_createtable
89and free it when you're finished using
90.BR atom_destroytable .
91.SS "Creating atoms from strings"
92The process of making atoms from strings is called
93.IR interning .
94The function
95.B atom_nintern
96takes an atom table, a string, and a length, and returns an atom with
97the same text. If your string is null-terminated, you can instead use
98.B atom_intern
99which has no length argument; if, in addition, you want to use the
100global atom table, you can use the single-argument
101.B INTERN
102macro, which takes just a null-terminated string.
103.PP
104A terminating null byte is always appended to an atom name. This is not
105considered to be a part of the name itself, and does not contribute to
106the atom's length as reported by the
107.B ATOM_LEN
108macro.
109.SS "Uninterned atoms"
110You can make an atom which is guaranteed to be distinct from every other
111atom, and has no sensible text string, by calling
112.BR atom_gensym ,
113passing it the address of your atom table. The macro
114.B GENSYM
115(which doesn't look like a function, and has no parentheses following
116it!) will return a unique atom from the global table. Uninterned atoms
117have a generated name of the form
118.RB ` *gen- \fInnn * '
119where
120.I nnn
121is an atom-table-specific sequence number. This text is there as a
122debugging convenience, and doesn't mean that the uninterned atom has the
123same address as an interned atom with the same text.
124.SS "Other enquiries about atoms"
125Atoms can be interrogated to find their names and hashes. The macro
126.B ATOM_NAME
127returns a pointer to the atom's name (its text);
128.B ATOM_LEN
129returns the length of the atom's name, excluding the terminating null;
130and
131.B ATOM_HASH
132returns the atom's hash value, which is useful if you want to use the
133atom as a key in some other structure. There are lower-case function
134versions of these, which have the same effect. There is little point in
135using the functions.
136.SS "Enumerating atoms"
137You can iterate over the atoms in an atom table. The
138.B atom_mkiter
139function initializes an iterator object to iterate over a particular
140atom table;
141.B atom_next
142returns the next atom from the iterator. Atoms are not returned in any
143particular order.
144.SH SEE ALSO
145.BR assoc (3),
146.BR hash (3),
147.BR mLib (3).
148.SH AUTHOR
9b5ac6ff 149Mark Wooding, <mdw@distorted.org.uk>