src/data/missing-values.h

   1 /* PSPP - a program for statistical analysis.
   2    Copyright (C) 2005, 2009, 2013 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 /* User-missing values.
  18
  19    struct missing_values is an opaque type that represents a set
  20    of user-missing values associated with a variable.  Valid sets
  21    of missing values depend on variable width:
  22
  23         - Numeric variables may have up to 3 discrete numeric
  24           user-missing values, or a range of numeric values, or a
  25           range plus one discrete value.
  26
  27         - String variables may have up to 3 discrete string
  28           user-missing values.  (However, for long string
  29           variables all bytes after the first MV_MAX_STRING must
  30           be spaces.)
  31 */
  32
  33 #ifndef DATA_MISSING_VALUES_H
  34 #define DATA_MISSING_VALUES_H 1
  35
  36 #include <stdbool.h>
  37 #include "data/value.h"
  38
  39 struct pool;
  40
  41 /* Missing values for long string variables after the first
  42    MV_MAX_STRING bytes must be all spaces. */
  43 #define MV_MAX_STRING 8
  44
  45 /* Missing values.
  46    Opaque--use access functions defined below. */
  47 struct missing_values
  48   {
  49     int type;                   /* Types of missing values, one of MVT_*. */
  50     int width;                  /* 0=numeric, otherwise string width. */
  51     union value values[3];      /* Missing values.  [1], [2] are the range. */
  52   };
  53
  54 #define MV_INIT_EMPTY_NUMERIC { .type = 0 }
  55
  56 /* Classes of missing values.
  57
  58    These are useful as individual values and as masks, and they are used both
  59    ways. */
  60 enum mv_class
  61   {
  62     MV_USER = 1,                /* User-missing. */
  63     MV_SYSTEM = 2               /* System-missing. */
  64 #define MV_ANY (MV_USER | MV_SYSTEM)
  65   };
  66
  67 /* Is a value missing? */
  68 enum mv_class mv_is_value_missing (const struct missing_values *,
  69                                    const union value *);
  70 enum mv_class mv_is_num_missing (const struct missing_values *, double);
  71 enum mv_class mv_is_str_missing (const struct missing_values *,
  72                                  const uint8_t[]);
  73 enum mv_class mv_is_value_missing_varwidth (const struct missing_values *,
  74                                             const union value *,
  75                                             int value_width);
  76
  77 /* Initializing missing value sets. */
  78 void mv_init (struct missing_values *, int width);
  79 void mv_init_pool (struct pool *pool, struct missing_values *, int width);
  80 void mv_destroy (struct missing_values *);
  81 void mv_copy (struct missing_values *, const struct missing_values *);
  82 void mv_clear (struct missing_values *);
  83
  84 /* Changing width of a missing value set. */
  85 bool mv_is_resizable (const struct missing_values *, int width);
  86 void mv_resize (struct missing_values *, int width);
  87
  88 /* Basic property inspection. */
  89 bool mv_is_acceptable (const union value *, int width);
  90 bool mv_is_empty (const struct missing_values *);
  91 int mv_get_width (const struct missing_values *);
  92
  93 /* Inspecting discrete values. */
  94 int mv_n_values (const struct missing_values *);
  95 bool mv_has_value (const struct missing_values *);
  96 const union value *mv_get_value (const struct missing_values *, int idx);
  97
  98 /* Inspecting ranges. */
  99 bool mv_has_range (const struct missing_values *);
 100 void mv_get_range (const struct missing_values *, double *low, double *high);
 101
 102 /* Adding and modifying discrete values. */
 103 bool mv_add_value (struct missing_values *, const union value *);
 104 bool mv_add_str (struct missing_values *, const uint8_t[], size_t len);
 105 bool mv_add_num (struct missing_values *, double);
 106 void mv_pop_value (struct missing_values *, union value *);
 107 bool mv_replace_value (struct missing_values *, const union value *, int idx);
 108
 109 /* Adding and modifying ranges. */
 110 bool mv_add_range (struct missing_values *, double low, double high);
 111 void mv_pop_range (struct missing_values *, double *low, double *high);
 112
 113 /* Formatting. */
 114 char *mv_to_string (const struct missing_values *, const char *encoding);
 115
 116 #endif /* data/missing-values.h */