chiark - git - mdw - mLib/blob - atom.h

   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
  53 typedef 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
  59 typedef 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
  66 typedef 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
  83 extern 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
  98 extern 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
 113 extern 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
 128 extern 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
 142 extern 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
 156 extern 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
 169 extern 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
 181 extern void atom_mkiter(atom_iter */*i*/, atom_table */*t*/);
 182 extern atom *atom_next(atom_iter */*i*/);
 183
 184 /*----- That's all, folks -------------------------------------------------*/
 185
 186 #ifdef __cplusplus
 187   }
 188 #endif
 189
 190 #endif