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