src/data/value-labels.h

   1 /* PSPP - a program for statistical analysis.
   2    Copyright (C) 1997-9, 2000, 2009, 2011 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     const char *label;          /* An interned string. */
  42     const char *escaped_label;  /* An interned string. */
  43   };
  44
  45 /* Returns the value in VL.  The caller must not modify or free
  46    the returned value.
  47
  48    The width of the returned value cannot be determined directly
  49    from VL.  It may be obtained by calling val_labs_get_width on
  50    the val_labs struct that VL is in. */
  51 static inline const union value *val_lab_get_value (const struct val_lab *vl)
  52 {
  53   return &vl->value;
  54 }
  55
  56 /* Returns the label in VL as a UTF-8 encoded interned string, in a format
  57    appropriate for use in output.  The caller must not modify or free the
  58    returned value. */
  59 static inline const char *
  60 val_lab_get_label (const struct val_lab *vl)
  61 {
  62   return vl->label;
  63 }
  64
  65 /* Returns the label in VL as a UTF-8 encoded interned string.  Any new-line
  66    characters in the label's usual output form are represented in the returned
  67    string as the two-byte sequence "\\n".  This form is used on the VALUE
  68    LABELS command, in system and portable files, and passed to val_labs_add()
  69    and val_labs_replace().
  70
  71    The caller must not modify or free the returned value. */
  72 static inline const char *
  73 val_lab_get_escaped_label (const struct val_lab *vl)
  74 {
  75   return vl->escaped_label;
  76 }
  77 \f
  78 /* A set of value labels. */
  79 struct val_labs
  80   {
  81     int width;                  /* 0=numeric, otherwise string width. */
  82     struct hmap labels;         /* Hash table of `struct val_lab's. */
  83   };
  84
  85 /* Creating and destroying sets of value labels. */
  86 struct val_labs *val_labs_create (int width);
  87 struct val_labs *val_labs_clone (const struct val_labs *);
  88 void val_labs_clear (struct val_labs *);
  89 void val_labs_destroy (struct val_labs *);
  90 size_t val_labs_count (const struct val_labs *);
  91
  92 /* Looking up value labels. */
  93 const char *val_labs_find (const struct val_labs *, const union value *);
  94 struct val_lab *val_labs_lookup (const struct val_labs *,
  95                                  const union value *);
  96
  97 /* Basic properties. */
  98 size_t val_labs_count (const struct val_labs *);
  99 int val_labs_get_width (const struct val_labs *);
 100 bool val_labs_can_set_width (const struct val_labs *, int new_width);
 101 void val_labs_set_width (struct val_labs *, int new_width);
 102
 103 /* Adding value labels. */
 104 bool val_labs_add (struct val_labs *, const union value *, const char *);
 105 void val_labs_replace (struct val_labs *, const union value *, const char *);
 106 void val_labs_remove (struct val_labs *, struct val_lab *);
 107
 108 /* Iterating through value labels. */
 109 const struct val_lab *val_labs_first (const struct val_labs *);
 110 const struct val_lab *val_labs_next (const struct val_labs *,
 111                                      const struct val_lab *);
 112 const struct val_lab **val_labs_sorted (const struct val_labs *);
 113
 114 #endif /* data/value-labels.h */