pintos-os.org Git - pspp/blob - src/data/value-labels.h

   1 /* PSPP - a program for statistical analysis.
   2    Copyright (C) 1997-9, 2000, 2009-2012 Free Software Foundation, Inc.
   3
   4    This program is free software: you can redistribute it and/or modify
   5    it under the terms of the GNU General Public License as published by
   6    the Free Software Foundation, either version 3 of the License, or
   7    (at your option) any later version.
   8
   9    This program is distributed in the hope that it will be useful,
  10    but WITHOUT ANY WARRANTY; without even the implied warranty of
  11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12    GNU General Public License for more details.
  13
  14    You should have received a copy of the GNU General Public License
  15    along with this program.  If not, see <http://www.gnu.org/licenses/>. */
  16
  17 /* Sets of value labels.
  18
  19    struct val_labs represents a mapping from `union value's to
  20    strings.  The `union value's in the mapping all have the same
  21    width.  If this width is numeric or short string, the mapping
  22    may contain any number of entries; long string mappings are
  23    always empty. */
  24
  25 #ifndef DATA_VALUE_LABELS_H
  26 #define DATA_VALUE_LABELS_H 1
  27
  28 #include <stdbool.h>
  29 #include <stddef.h>
  30 #include "data/value.h"
  31 #include "libpspp/hmap.h"
  32
  33 struct pxd;
  34
  35 /* One value label.
  36
  37    A value label is normally part of a struct val_labs (see
  38    below). */
  39 struct val_lab
  40   {
  41     struct hmap_node node;      /* Node in hash map. */
  42     struct pxd_object *cache;   /* Object cache. */
  43     union value value;          /* The value being labeled. */
  44     const char *label;          /* An interned string. */
  45     const char *escaped_label;  /* An interned string. */
  46   };
  47
  48 /* Returns the value in VL.  The caller must not modify or free
  49    the returned value.
  50
  51    The width of the returned value cannot be determined directly
  52    from VL.  It may be obtained by calling val_labs_get_width on
  53    the val_labs struct that VL is in. */
  54 static inline const union value *val_lab_get_value (const struct val_lab *vl)
  55 {
  56   return &vl->value;
  57 }
  58
  59 /* Returns the label in VL as a UTF-8 encoded interned string, in a format
  60    appropriate for use in output.  The caller must not modify or free the
  61    returned value. */
  62 static inline const char *
  63 val_lab_get_label (const struct val_lab *vl)
  64 {
  65   return vl->label;
  66 }
  67
  68 /* Returns the label in VL as a UTF-8 encoded interned string.  Any new-line
  69    characters in the label's usual output form are represented in the returned
  70    string as the two-byte sequence "\\n".  This form is used on the VALUE
  71    LABELS command, in system and portable files, and passed to val_labs_add()
  72    and val_labs_replace().
  73
  74    The caller must not modify or free the returned value. */
  75 static inline const char *
  76 val_lab_get_escaped_label (const struct val_lab *vl)
  77 {
  78   return vl->escaped_label;
  79 }
  80 \f
  81 /* A set of value labels. */
  82 struct val_labs
  83   {
  84     struct pxd_object *cache;   /* Object cache. */
  85     int width;                  /* 0=numeric, otherwise string width. */
  86     struct hmap labels;         /* Hash table of `struct val_lab's. */
  87   };
  88
  89 /* Creating and destroying sets of value labels. */
  90 struct val_labs *val_labs_create (int width);
  91 struct val_labs *val_labs_clone (const struct val_labs *);
  92 void val_labs_clear (struct val_labs *);
  93 void val_labs_destroy (struct val_labs *);
  94 size_t val_labs_count (const struct val_labs *);
  95
  96 /* Looking up value labels. */
  97 const char *val_labs_find (const struct val_labs *, const union value *);
  98 struct val_lab *val_labs_lookup (const struct val_labs *,
  99                                  const union value *);
 100 const union value *val_labs_find_value (const struct val_labs *,
 101                                         const char *label);
 102
 103 /* Basic properties. */
 104 size_t val_labs_count (const struct val_labs *);
 105 int val_labs_get_width (const struct val_labs *);
 106 bool val_labs_can_set_width (const struct val_labs *, int new_width);
 107 void val_labs_set_width (struct val_labs *, int new_width);
 108
 109 /* Adding value labels. */
 110 bool val_labs_add (struct val_labs *, const union value *, const char *);
 111 void val_labs_replace (struct val_labs *, const union value *, const char *);
 112 void val_labs_remove (struct val_labs *, struct val_lab *);
 113
 114 /* Iterating through value labels. */
 115 const struct val_lab *val_labs_first (const struct val_labs *);
 116 const struct val_lab *val_labs_next (const struct val_labs *,
 117                                      const struct val_lab *);
 118 const struct val_lab **val_labs_sorted (const struct val_labs *);
 119
 120 /* Properties of entire sets. */
 121 unsigned int val_labs_hash (const struct val_labs *, unsigned int basis);
 122 bool val_labs_equal (const struct val_labs *, const struct val_labs *);
 123
 124 /* Saving and loading. */
 125 struct pxd_object *val_labs_save (const struct val_labs *, struct pxd *);
 126 struct val_labs *val_labs_load (struct pxd_object *, const struct pxd *);
 127
 128 #endif /* data/value-labels.h */