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