src/data/value.h

   1 /* PSPP - a program for statistical analysis.
   2    Copyright (C) 1997-9, 2000, 2007, 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 #ifndef DATA_VALUE_H
  18 #define DATA_VALUE_H 1
  19
  20 #include <assert.h>
  21 #include <stdbool.h>
  22 #include <stdlib.h>
  23 #include <stdint.h>
  24 #include <string.h>
  25 #include "xalloc.h"
  26 \f
  27 /* Maximum length of a "short" string, that is represented in
  28    "union value" without a separate pointer.
  29
  30    This is an implementation detail of the "union value" code.
  31    There is little reason for client code to use it. */
  32 #define MAX_SHORT_STRING 8
  33
  34 /* A numeric or string value.
  35
  36    The client is responsible for keeping track of the value's
  37    width.
  38
  39    This structure is semi-opaque:
  40
  41        - If the value is a number, clients may access the 'f'
  42          member directly.
  43
  44        - Clients should not access other members directly.
  45 */
  46 union value
  47   {
  48     double f;
  49     uint8_t short_string[MAX_SHORT_STRING];
  50     uint8_t *long_string;
  51   };
  52
  53 static inline void value_init (union value *, int width);
  54 static inline bool value_needs_init (int width);
  55 static inline bool value_try_init (union value *, int width);
  56 static inline void value_destroy (union value *, int width);
  57
  58 static inline double value_num (const union value *);
  59 static inline const uint8_t *value_str (const union value *, int width);
  60 static inline uint8_t *value_str_rw (union value *, int width);
  61
  62 static inline void value_copy (union value *, const union value *, int width);
  63 void value_copy_rpad (union value *, int dst_width,
  64                       const union value *, int src_width,
  65                       char pad);
  66 void value_copy_str_rpad (union value *, int dst_width, const uint8_t *,
  67                           char pad);
  68 void value_copy_buf_rpad (union value *dst, int dst_width,
  69                           const uint8_t *src, size_t src_len, char pad);
  70 void value_set_missing (union value *, int width);
  71 int value_compare_3way (const union value *, const union value *, int width);
  72 bool value_equal (const union value *, const union value *, int width);
  73 unsigned int value_hash (const union value *, int width, unsigned int basis);
  74
  75 bool value_is_resizable (const union value *, int old_width, int new_width);
  76 bool value_needs_resize (int old_width, int new_width);
  77 void value_resize (union value *, int old_width, int new_width);
  78
  79 static inline void value_swap (union value *, union value *);
  80
  81 struct pool;
  82 void value_init_pool (struct pool *, union value *, int width);
  83 void value_resize_pool (struct pool *, union value *,
  84                         int old_width, int new_width);
  85 \f
  86 /* Initializes V as a value of the given WIDTH, where 0
  87    represents a numeric value and a positive integer represents a
  88    string value WIDTH bytes long.
  89
  90    A WIDTH of -1 is ignored.
  91
  92    The contents of value V are indeterminate after
  93    initialization. */
  94 static inline void
  95 value_init (union value *v, int width)
  96 {
  97   if (width > MAX_SHORT_STRING)
  98     v->long_string = xmalloc (width);
  99 }
 100
 101 /* Returns true if a value of the given WIDTH actually needs to
 102    have the value_init and value_destroy functions called, false
 103    if those functions are no-ops for values of the given WIDTH.
 104
 105    Using this function is only a valuable optimization if a large
 106    number of values of the given WIDTH are to be initialized*/
 107 static inline bool
 108 value_needs_init (int width)
 109 {
 110   return width > MAX_SHORT_STRING;
 111 }
 112
 113 /* Same as value_init, except that failure to allocate memory
 114    causes it to return false instead of terminating the
 115    program.  On success, returns true. */
 116 static inline bool
 117 value_try_init (union value *v, int width)
 118 {
 119   if (width > MAX_SHORT_STRING)
 120     {
 121       v->long_string = malloc (width);
 122       return v->long_string != NULL;
 123     }
 124   else
 125     return true;
 126 }
 127
 128 /* Frees any memory allocated by value_init for V, which must
 129    have the given WIDTH. */
 130 static inline void
 131 value_destroy (union value *v, int width)
 132 {
 133   if (width > MAX_SHORT_STRING)
 134     free (v->long_string);
 135 }
 136
 137 /* Returns the numeric value in V, which must have width 0. */
 138 static inline double
 139 value_num (const union value *v)
 140 {
 141   return v->f;
 142 }
 143
 144 /* Returns the string value in V, which must have width WIDTH.
 145
 146    The returned value is not null-terminated.
 147
 148    It is important that WIDTH be the actual value that was passed
 149    to value_init.  Passing, e.g., a smaller value because only
 150    that number of bytes will be accessed will not always work. */
 151 static inline const uint8_t *
 152 value_str (const union value *v, int width)
 153 {
 154   assert (width > 0);
 155   return (width > MAX_SHORT_STRING ? v->long_string : v->short_string);
 156 }
 157
 158 /* Returns the string value in V, which must have width WIDTH.
 159
 160    The returned value is not null-terminated.
 161
 162    It is important that WIDTH be the actual value that was passed
 163    to value_init.  Passing, e.g., a smaller value because only
 164    that number of bytes will be accessed will not always work. */
 165 static inline uint8_t *
 166 value_str_rw (union value *v, int width)
 167 {
 168   assert (width > 0);
 169   return (width > MAX_SHORT_STRING ? v->long_string : v->short_string);
 170 }
 171
 172 /* Copies SRC to DST, given that they both contain data of the
 173    given WIDTH. */
 174 static inline void
 175 value_copy (union value *dst, const union value *src, int width)
 176 {
 177   if (width <= MAX_SHORT_STRING)
 178     *dst = *src;
 179   else if (dst != src)
 180     memcpy (dst->long_string, src->long_string, width);
 181 }
 182
 183 /* Exchanges the contents of A and B. */
 184 static inline void
 185 value_swap (union value *a, union value *b)
 186 {
 187   union value tmp = *a;
 188   *a = *b;
 189   *b = tmp;
 190 }
 191
 192 #endif /* data/value.h */