doc: Distribute doc/pspp.xml, so that users don't need makeinfo or xmllint.
[pspp] / src / data / missing-values.c
1 /* PSPP - a program for statistical analysis.
2    Copyright (C) 2005, 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 #include <config.h>
18 #include <data/missing-values.h>
19 #include <assert.h>
20 #include <stdlib.h>
21 #include <data/variable.h>
22 #include <libpspp/assertion.h>
23 #include <libpspp/str.h>
24
25 /* Types of user-missing values.
26    Invisible--use access functions defined below instead. */
27 enum mv_type
28   {
29     MVT_NONE = 0,                /* No user-missing values. */
30     MVT_1 = 1,                   /* One user-missing value. */
31     MVT_2 = 2,                   /* Two user-missing values. */
32     MVT_3 = 3,                   /* Three user-missing values. */
33     MVT_RANGE = 4,               /* A range of user-missing values. */
34     MVT_RANGE_1 = 5              /* A range plus an individual value. */
35   };
36
37 /* Initializes MV as a set of missing values for a variable of
38    the given WIDTH.  MV should be destroyed with mv_destroy when
39    it is no longer needed. */
40 void
41 mv_init (struct missing_values *mv, int width)
42 {
43   int i;
44
45   assert (width >= 0 && width <= MAX_STRING);
46   mv->type = MVT_NONE;
47   mv->width = width;
48   for (i = 0; i < 3; i++)
49     value_init (&mv->values[i], width);
50 }
51
52 /* Initializes MV as a set of missing values for a variable of
53    the given WIDTH.  MV will be automatically destroyed along
54    with POOL; it must not be passed to mv_destroy for explicit
55    destruction. */
56 void
57 mv_init_pool (struct pool *pool, struct missing_values *mv, int width)
58 {
59   int i;
60
61   assert (width >= 0 && width <= MAX_STRING);
62   mv->type = MVT_NONE;
63   mv->width = width;
64   for (i = 0; i < 3; i++)
65     value_init_pool (pool, &mv->values[i], width);
66 }
67
68 /* Frees any storage allocated by mv_init for MV. */
69 void
70 mv_destroy (struct missing_values *mv)
71 {
72   if (mv != NULL)
73     {
74       int i;
75
76       for (i = 0; i < 3; i++)
77         value_destroy (&mv->values[i], mv->width);
78     }
79 }
80
81 /* Removes any missing values from MV. */
82 void
83 mv_clear (struct missing_values *mv)
84 {
85   mv->type = MVT_NONE;
86 }
87
88 /* Initializes MV as a copy of SRC. */
89 void
90 mv_copy (struct missing_values *mv, const struct missing_values *src)
91 {
92   int i;
93
94   mv_init (mv, src->width);
95   mv->type = src->type;
96   for (i = 0; i < 3; i++)
97     value_copy (&mv->values[i], &src->values[i], mv->width);
98 }
99
100 /* Returns true if VALUE, of the given WIDTH, may be added to a
101    missing value set also of the given WIDTH.  This is normally
102    the case, but string missing values over MV_MAX_STRING bytes
103    long must consist solely of spaces after the first
104    MV_MAX_STRING bytes.  */
105 bool
106 mv_is_acceptable (const union value *value, int width)
107 {
108   int i;
109
110   for (i = MV_MAX_STRING; i < width; i++)
111     if (value_str (value, width)[i] != ' ')
112       return false;
113   return true;
114 }
115
116 /* Returns true if MV is an empty set of missing values. */
117 bool
118 mv_is_empty (const struct missing_values *mv)
119 {
120   return mv->type == MVT_NONE;
121 }
122
123 /* Returns the width of the missing values that MV may
124    contain. */
125 int
126 mv_get_width (const struct missing_values *mv)
127 {
128   return mv->width;
129 }
130
131 /* Attempts to add individual value V to the set of missing
132    values MV.  Returns true if successful, false if MV has no
133    more room for missing values or if V is not an acceptable
134    missing value. */
135 bool
136 mv_add_value (struct missing_values *mv, const union value *v)
137 {
138   if (!mv_is_acceptable (v, mv->width))
139     return false;
140
141   switch (mv->type)
142     {
143     case MVT_NONE:
144     case MVT_1:
145     case MVT_2:
146     case MVT_RANGE:
147       value_copy (&mv->values[mv->type & 3], v, mv->width);
148       mv->type++;
149       return true;
150
151     case MVT_3:
152     case MVT_RANGE_1:
153       return false;
154     }
155   NOT_REACHED ();
156 }
157
158 /* Attempts to add S to the set of string missing values MV.  S
159    must contain exactly as many characters as MV's width.
160    Returns true if successful, false if MV has no more room for
161    missing values or if S is not an acceptable missing value. */
162 bool
163 mv_add_str (struct missing_values *mv, const uint8_t s[])
164 {
165   union value v;
166   bool ok;
167
168   assert (mv->width > 0);
169   value_init (&v, mv->width);
170   memcpy (value_str_rw (&v, mv->width), s, mv->width);
171   ok = mv_add_value (mv, &v);
172   value_destroy (&v, mv->width);
173
174   return ok;
175 }
176
177 /* Attempts to add D to the set of numeric missing values MV.
178    Returns true if successful, false if MV has no more room for
179    missing values.  */
180 bool
181 mv_add_num (struct missing_values *mv, double d)
182 {
183   union value v;
184   bool ok;
185
186   assert (mv->width == 0);
187   value_init (&v, 0);
188   v.f = d;
189   ok = mv_add_value (mv, &v);
190   value_destroy (&v, 0);
191
192   return ok;
193 }
194
195 /* Attempts to add range [LOW, HIGH] to the set of numeric
196    missing values MV.  Returns true if successful, false if MV
197    has no room for a range, or if LOW > HIGH. */
198 bool
199 mv_add_range (struct missing_values *mv, double low, double high)
200 {
201   assert (mv->width == 0);
202   if (low <= high && (mv->type == MVT_NONE || mv->type == MVT_1))
203     {
204       mv->values[1].f = low;
205       mv->values[2].f = high;
206       mv->type |= 4;
207       return true;
208     }
209   else
210     return false;
211 }
212
213 /* Returns true if MV contains an individual value,
214    false if MV is empty (or contains only a range). */
215 bool
216 mv_has_value (const struct missing_values *mv)
217 {
218   return mv_n_values (mv) > 0;
219 }
220
221 /* Removes one individual value from MV and stores it in V, which
222    must have been initialized as a value with the same width as MV.
223    MV must contain an individual value (as determined by
224    mv_has_value()).
225
226    We remove the first value from MV, not the last, because the
227    common use for this function is in iterating through a set of
228    missing values.  If we remove the last value then we'll output
229    the missing values in order opposite of that in which they
230    were added, so that a GET followed by a SAVE would reverse the
231    order of missing values in the system file, a weird effect. */
232 void
233 mv_pop_value (struct missing_values *mv, union value *v)
234 {
235   union value tmp;
236
237   assert (mv_has_value (mv));
238
239   value_copy (v, &mv->values[0], mv->width);
240   tmp = mv->values[0];
241   mv->values[0] = mv->values[1];
242   mv->values[1] = mv->values[2];
243   mv->values[2] = tmp;
244   mv->type--;
245 }
246
247 /* Returns MV's discrete value with index IDX.  The caller must
248    not modify or free this value, or access it after MV is
249    modified or freed.
250    IDX must be less than the number of discrete values in MV, as
251    reported by mv_n_values. */
252 const union value *
253 mv_get_value (const struct missing_values *mv, int idx)
254 {
255   assert (idx >= 0 && idx < mv_n_values (mv));
256   return &mv->values[idx];
257 }
258
259 /* Replaces MV's discrete value with index IDX by a copy of V,
260    which must have the same width as MV.
261    IDX must be less than the number of discrete values in MV, as
262    reported by mv_n_values. */
263 bool
264 mv_replace_value (struct missing_values *mv, const union value *v, int idx)
265 {
266   assert (idx >= 0) ;
267   assert (idx < mv_n_values(mv));
268
269   if (!mv_is_acceptable (v, mv->width))
270     return false;
271
272   value_copy (&mv->values[idx], v, mv->width);
273   return true;
274 }
275
276 /* Returns the number of individual (not part of a range) missing
277    values in MV. */
278 int
279 mv_n_values (const struct missing_values *mv)
280 {
281   return mv->type & 3;
282 }
283
284
285 /* Returns true if MV contains a numeric range,
286    false if MV is empty (or contains only individual values). */
287 bool
288 mv_has_range (const struct missing_values *mv)
289 {
290   return mv->type == MVT_RANGE || mv->type == MVT_RANGE_1;
291 }
292
293 /* Removes the numeric range from MV and stores it in *LOW and
294    *HIGH.  MV must contain a individual range (as determined by
295    mv_has_range()). */
296 void
297 mv_pop_range (struct missing_values *mv, double *low, double *high)
298 {
299   assert (mv_has_range (mv));
300   *low = mv->values[1].f;
301   *high = mv->values[2].f;
302   mv->type &= 3;
303 }
304
305 /* Returns the numeric range from MV  into *LOW and
306    *HIGH.  MV must contain a individual range (as determined by
307    mv_has_range()). */
308 void
309 mv_get_range (const struct missing_values *mv, double *low, double *high)
310 {
311   assert (mv_has_range (mv));
312   *low = mv->values[1].f;
313   *high = mv->values[2].f;
314 }
315
316 /* Returns true if values[IDX] is in use when the `type' member
317    is set to TYPE (in struct missing_values),
318    false otherwise. */
319 static bool
320 using_element (unsigned type, int idx)
321 {
322   assert (idx >= 0 && idx < 3);
323
324   switch (type)
325     {
326     case MVT_NONE:
327       return false;
328     case MVT_1:
329       return idx < 1;
330     case MVT_2:
331       return idx < 2;
332     case MVT_3:
333       return true;
334     case MVT_RANGE:
335       return idx > 0;
336     case MVT_RANGE_1:
337       return true;
338     }
339   NOT_REACHED ();
340 }
341
342 /* Returns true if MV can be resized to the given WIDTH with
343    mv_resize(), false otherwise.  Resizing is possible only when
344    each value in MV (if any) is resizable from MV's current width
345    to WIDTH, as determined by value_is_resizable. */
346 bool
347 mv_is_resizable (const struct missing_values *mv, int width)
348 {
349   int i;
350
351   for (i = 0; i < 3; i++)
352     if (using_element (mv->type, i)
353         && !value_is_resizable (&mv->values[i], mv->width, width))
354       return false;
355
356   return true;
357 }
358
359 /* Resizes MV to the given WIDTH.  WIDTH must fit the constraints
360    explained for mv_is_resizable. */
361 void
362 mv_resize (struct missing_values *mv, int width)
363 {
364   int i;
365
366   assert (mv_is_resizable (mv, width));
367   for (i = 0; i < 3; i++)
368     if (using_element (mv->type, i))
369       value_resize (&mv->values[i], mv->width, width);
370     else
371       {
372         value_destroy (&mv->values[i], mv->width);
373         value_init (&mv->values[i], width);
374       }
375   mv->width = width;
376 }
377
378 /* Returns true if D is a missing value in MV, false otherwise.
379    MV must be a set of numeric missing values. */
380 static bool
381 is_num_user_missing (const struct missing_values *mv, double d)
382 {
383   const union value *v = mv->values;
384   assert (mv->width == 0);
385   switch (mv->type)
386     {
387     case MVT_NONE:
388       return false;
389     case MVT_1:
390       return v[0].f == d;
391     case MVT_2:
392       return v[0].f == d || v[1].f == d;
393     case MVT_3:
394       return v[0].f == d || v[1].f == d || v[2].f == d;
395     case MVT_RANGE:
396       return v[1].f <= d && d <= v[2].f;
397     case MVT_RANGE_1:
398       return v[0].f == d || (v[1].f <= d && d <= v[2].f);
399     }
400   NOT_REACHED ();
401 }
402
403 /* Returns true if S[] is a missing value in MV, false otherwise.
404    MV must be a set of string missing values.
405    S[] must contain exactly as many characters as MV's width. */
406 static bool
407 is_str_user_missing (const struct missing_values *mv, const uint8_t s[])
408 {
409   const union value *v = mv->values;
410   assert (mv->width > 0);
411   switch (mv->type)
412     {
413     case MVT_NONE:
414       return false;
415     case MVT_1:
416       return !memcmp (value_str (&v[0], mv->width), s, mv->width);
417     case MVT_2:
418       return (!memcmp (value_str (&v[0], mv->width), s, mv->width)
419               || !memcmp (value_str (&v[1], mv->width), s, mv->width));
420     case MVT_3:
421       return (!memcmp (value_str (&v[0], mv->width), s, mv->width)
422               || !memcmp (value_str (&v[1], mv->width), s, mv->width)
423               || !memcmp (value_str (&v[2], mv->width), s, mv->width));
424     case MVT_RANGE:
425     case MVT_RANGE_1:
426       NOT_REACHED ();
427     }
428   NOT_REACHED ();
429 }
430
431 /* Returns true if V is a missing value in the given CLASS in MV,
432    false otherwise. */
433 bool
434 mv_is_value_missing (const struct missing_values *mv, const union value *v,
435                      enum mv_class class)
436 {
437   return (mv->width == 0
438           ? mv_is_num_missing (mv, v->f, class)
439           : mv_is_str_missing (mv, value_str (v, mv->width), class));
440 }
441
442 /* Returns true if D is a missing value in the given CLASS in MV,
443    false otherwise.
444    MV must be a set of numeric missing values. */
445 bool
446 mv_is_num_missing (const struct missing_values *mv, double d,
447                    enum mv_class class)
448 {
449   assert (mv->width == 0);
450   return ((class & MV_SYSTEM && d == SYSMIS)
451           || (class & MV_USER && is_num_user_missing (mv, d)));
452 }
453
454 /* Returns true if S[] is a missing value in the given CLASS in
455    MV, false otherwise.
456    MV must be a set of string missing values.
457    S[] must contain exactly as many characters as MV's width. */
458 bool
459 mv_is_str_missing (const struct missing_values *mv, const uint8_t s[],
460                    enum mv_class class)
461 {
462   assert (mv->width > 0);
463   return class & MV_USER && is_str_user_missing (mv, s);
464 }