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

   1 /* -*-c-*-
   2  *
   3  * $Id: atom.h,v 1.2 2001/01/25 21:13:40 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.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@
  36  * structure.
  37  *
  38  * Revision 1.1  2001/01/20 11:50:16  mdw
  39  * Implementation of atom tables (for example, as found in X11).
  40  *
  41  */
  42
  43 #ifndef MLIB_ATOM_H
  44 #define MLIB_ATOM_H
  45
  46 #ifdef __cplusplus
  47   extern "C" {
  48 #endif
  49
  50 /*----- Header files ------------------------------------------------------*/
  51
  52 #ifndef MLIB_SYM_H
  53 #  include "sym.h"
  54 #endif
  55
  56 /*----- Data structures ---------------------------------------------------*/
  57
  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@ */
  62 } atom_table;
  63
  64 typedef struct atom {
  65   sym_base b;                           /* Base structure for symbol table */
  66   unsigned f;                           /* Various useful flags */
  67 } atom;
  68
  69 #define ATOMF_GENSYM 1u                 /* Atom is uninterned */
  70
  71 typedef struct { sym_iter i; } atom_iter;
  72
  73 /*----- Global magic ------------------------------------------------------*/
  74
  75 #define ATOM_GLOBAL 0
  76
  77 /*----- Functions provided ------------------------------------------------*/
  78
  79 /* --- @atom_createtable@ --- *
  80  *
  81  * Arguments:   @atom_table *t@ = pointer to an atom table
  82  *
  83  * Returns:     ---
  84  *
  85  * Use:         Initializes an atom table.
  86  */
  87
  88 extern void atom_createtable(atom_table */*t*/);
  89
  90 /* --- @atom_destroytable@ --- *
  91  *
  92  * Arguments:   @atom_table *t@ = pointer to an atom table
  93  *
  94  * Returns:     ---
  95  *
  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.
 101  */
 102
 103 extern void atom_destroytable(atom_table */*t*/);
 104
 105 /* --- @atom_intern@ --- *
 106  *
 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)
 110  *
 111  * Returns:     A pointer to the atom block for the given symbol string.
 112  *
 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.
 115  */
 116
 117 #define INTERN(p) atom_intern(ATOM_GLOBAL, (p))
 118
 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*/);
 122
 123 /* --- @atom_gensym@ --- *
 124  *
 125  * Arguments:   @atom_table *t@ = pointer to a symbol table
 126  *
 127  * Returns:     A pointer to a new atom block, not previously interned.
 128  *
 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.
 132  */
 133
 134 #define GENSYM atom_gensym(ATOM_GLOBAL)
 135
 136 extern atom *atom_gensym(atom_table */*t*/);
 137
 138 /* --- @atom_name@ --- *
 139  *
 140  * Arguments:   @atom *a@ = pointer to an atom
 141  *
 142  * Returns:     The atom's textual name.
 143  *
 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@.
 146  */
 147
 148 #define ATOM_NAME(a) SYM_NAME(a)
 149
 150 extern const char *atom_name(const atom */*a*/);
 151
 152 /* --- @atom_len@ --- *
 153  *
 154  * Arguments:   @atom *a@ = pointer to an atom
 155  *
 156  * Returns:     The atom string's length.
 157  *
 158  * Use:         Given an atom, return the length of its textual
 159  *              representation.
 160  */
 161
 162 #define ATOM_LEN(a) SYM_LEN(a)
 163
 164 extern size_t atom_len(const atom */*a*/);
 165
 166 /* --- @atom_hash@ --- *
 167  *
 168  * Arguments:   @atom *a@ = pointer to an atom
 169  *
 170  * Returns:     The atom's hash.
 171  *
 172  * Use:         Given an atom, returns its hash.
 173  */
 174
 175 #define ATOM_HASH(a) SYM_HASH(a)
 176
 177 extern uint32 atom_hash(const atom */*a*/);
 178
 179 /* --- @atom_mkiter@ , @atom_next@ --- *
 180  *
 181  * Arguments:   @atom_table *t@ = pointer to an atom table
 182  *              @atom_iter *i@ = pointer to an iterator structure
 183  *
 184  * Returns:     Next atom, for @atom_next@; nothing for @atom_mkiter@.
 185  *
 186  * Use:         Iterates over atoms (both interned and uninterned).
 187  */
 188
 189 extern void atom_mkiter(atom_iter */*i*/, atom_table */*t*/);
 190 extern atom *atom_next(atom_iter */*i*/);
 191
 192 /*----- That's all, folks -------------------------------------------------*/
 193
 194 #ifdef __cplusplus
 195   }
 196 #endif
 197
 198 #endif