src/data/value-labels.h

   1 /* PSPP - a program for statistical analysis.
   2    Copyright (C) 1997-9, 2000, 2009 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 /* One value label.
  34
  35    A value label is normally part of a struct val_labs (see
  36    below). */
  37 struct val_lab
  38   {
  39     struct hmap_node node;      /* Node in hash map. */
  40     union value value;          /* The value being labeled. */
  41     struct atom *label;         /* A ref-counted string. */
  42   };
  43
  44 /* Returns the value in VL.  The caller must not modify or free
  45    the returned value.
  46
  47    The width of the returned value cannot be determined directly
  48    from VL.  It may be obtained by calling val_labs_get_width on
  49    the val_labs struct that VL is in. */
  50 static inline const union value *val_lab_get_value (const struct val_lab *vl)
  51 {
  52   return &vl->value;
  53 }
  54
  55 const char *val_lab_get_label (const struct val_lab *);
  56 \f
  57 /* A set of value labels. */
  58 struct val_labs
  59   {
  60     int width;                  /* 0=numeric, otherwise string width. */
  61     struct hmap labels;         /* Hash table of `struct int_val_lab's. */
  62   };
  63
  64 /* Creating and destroying sets of value labels. */
  65 struct val_labs *val_labs_create (int width);
  66 struct val_labs *val_labs_clone (const struct val_labs *);
  67 void val_labs_clear (struct val_labs *);
  68 void val_labs_destroy (struct val_labs *);
  69 size_t val_labs_count (const struct val_labs *);
  70
  71 /* Looking up value labels. */
  72 const char *val_labs_find (const struct val_labs *, const union value *);
  73 const struct val_lab *val_labs_lookup (const struct val_labs *,
  74                                        const union value *);
  75
  76 /* Basic properties. */
  77 size_t val_labs_count (const struct val_labs *);
  78 int val_labs_get_width (const struct val_labs *);
  79 bool val_labs_can_set_width (const struct val_labs *, int new_width);
  80 void val_labs_set_width (struct val_labs *, int new_width);
  81
  82 /* Adding value labels. */
  83 bool val_labs_add (struct val_labs *, const union value *, const char *);
  84 void val_labs_replace (struct val_labs *, const union value *, const char *);
  85 void val_labs_remove (struct val_labs *, const struct val_lab *);
  86
  87 /* Iterating through value labels. */
  88 const struct val_lab *val_labs_first (const struct val_labs *);
  89 const struct val_lab *val_labs_next (const struct val_labs *,
  90                                      const struct val_lab *);
  91 const struct val_lab **val_labs_sorted (const struct val_labs *);
  92
  93 #endif /* data/value-labels.h */