src/data/variable.h

   1 /* PSPP - computes sample statistics.
   2    Copyright (C) 1997-9, 2000 Free Software Foundation, Inc.
   3    Written by Ben Pfaff <blp@gnu.org>.
   4
   5    This program is free software; you can redistribute it and/or
   6    modify it under the terms of the GNU General Public License as
   7    published by the Free Software Foundation; either version 2 of the
   8    License, or (at your option) any later version.
   9
  10    This program is distributed in the hope that it will be useful, but
  11    WITHOUT ANY WARRANTY; without even the implied warranty of
  12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13    General Public License for more details.
  14
  15    You should have received a copy of the GNU General Public License
  16    along with this program; if not, write to the Free Software
  17    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  18    02110-1301, USA. */
  19
  20 #if !variable_h
  21 #define variable_h 1
  22
  23
  24 #include <stddef.h>
  25 #include "config.h"
  26 #include <stdbool.h>
  27 #include "category.h"
  28 #include "format.h"
  29 #include "missing-values.h"
  30
  31 /* Variable type. */
  32 enum var_type
  33   {
  34     NUMERIC,                    /* A numeric variable. */
  35     ALPHA                       /* A string variable. */
  36   };
  37
  38 bool var_type_is_valid (enum var_type);
  39 const char *var_type_adj (enum var_type);
  40 const char *var_type_noun (enum var_type);
  41
  42 /* Alignment of data for display. */
  43 enum alignment
  44   {
  45     ALIGN_LEFT = 0,
  46     ALIGN_RIGHT = 1,
  47     ALIGN_CENTRE = 2,
  48     n_ALIGN
  49   };
  50
  51 bool alignment_is_valid (enum alignment);
  52
  53 /* How data is measured. */
  54 enum measure
  55   {
  56     MEASURE_NOMINAL = 1,
  57     MEASURE_ORDINAL = 2,
  58     MEASURE_SCALE = 3,
  59     n_MEASURES
  60   };
  61
  62 bool measure_is_valid (enum measure);
  63
  64 /* Maximum lengths of short and long variable names.
  65    Most operations support long variable names,
  66    but some file formats are limited to short names. */
  67 #define SHORT_NAME_LEN 8        /* Short name length. */
  68 #define LONG_NAME_LEN 64        /* Long name length. */
  69
  70 /* A variable's dictionary entry.  */
  71 struct variable
  72   {
  73     /* Dictionary information. */
  74     char name[LONG_NAME_LEN + 1]; /* Variable name.  Mixed case. */
  75     int width;                  /* 0 for numeric, otherwise string width. */
  76     struct missing_values miss; /* Missing values. */
  77     struct fmt_spec print;      /* Default format for PRINT. */
  78     struct fmt_spec write;      /* Default format for WRITE. */
  79     struct val_labs *val_labs;  /* Value labels. */
  80     char *label;                /* Variable label. */
  81
  82     /* GUI information. */
  83     enum measure measure;       /* Nominal, ordinal, or continuous. */
  84     int display_width;          /* Width of data editor column. */
  85     enum alignment alignment;   /* Alignment of data in GUI. */
  86
  87     /* Case information. */
  88     int fv;                     /* Index into `value's. */
  89     bool leave;                 /* Leave value from case to case? */
  90
  91     /* Data for use by containing dictionary. */
  92     int index;                  /* Dictionary index. */
  93
  94     /* Short name, used only for system and portable file input
  95        and output.  Upper case only.  There is no index for short
  96        names.  Short names are not necessarily unique.  Any
  97        variable may have no short name, indicated by an empty
  98        string. */
  99     char short_name[SHORT_NAME_LEN + 1];
 100
 101     /* Each command may use these fields as needed. */
 102     void *aux;
 103     void (*aux_dtor) (struct variable *);
 104
 105     /* Values of a categorical variable.  Procedures need
 106        vectors with binary entries, so any variable of type ALPHA will
 107        have its values stored here. */
 108     struct cat_vals *obs_vals;
 109   };
 110
 111 /* Variable names. */
 112 const char *var_get_name (const struct variable *);
 113 void var_set_name (struct variable *, const char *);
 114 bool var_is_valid_name (const char *, bool issue_error);
 115 bool var_is_plausible_name (const char *name, bool issue_error);
 116 int  compare_var_names (const void *, const void *, const void *);
 117 unsigned hash_var_name (const void *, const void *);
 118
 119 /* Variable types and widths. */
 120 enum var_type var_get_type (const struct variable *);
 121 int var_get_width (const struct variable *);
 122 void var_set_width (struct variable *, int width);
 123 bool var_is_numeric (const struct variable *);
 124 bool var_is_alpha (const struct variable *);
 125 bool var_is_short_string (const struct variable *);
 126 bool var_is_long_string (const struct variable *);
 127 bool var_is_very_long_string (const struct variable *);
 128
 129 /* Variables' missing values. */
 130 const struct missing_values *var_get_missing_values (const struct variable *);
 131 void var_set_missing_values (struct variable *, const struct missing_values *);
 132 void var_clear_missing_values (struct variable *);
 133 bool var_has_missing_values (const struct variable *);
 134
 135 typedef bool var_is_missing_func (const struct variable *,
 136                                   const union value *);
 137 bool var_is_value_missing (const struct variable *, const union value *);
 138 bool var_is_num_missing (const struct variable *, double);
 139 bool var_is_str_missing (const struct variable *, const char[]);
 140 bool var_is_value_user_missing (const struct variable *,
 141                                 const union value *);
 142 bool var_is_num_user_missing (const struct variable *, double);
 143 bool var_is_str_user_missing (const struct variable *, const char[]);
 144 bool var_is_value_system_missing (const struct variable *,
 145                                   const union value *);
 146
 147 /* Print and write formats. */
 148 const struct fmt_spec *var_get_print_format (const struct variable *);
 149 void var_set_print_format (struct variable *, const struct fmt_spec *);
 150 const struct fmt_spec *var_get_write_format (const struct variable *);
 151 void var_set_write_format (struct variable *, const struct fmt_spec *);
 152 void var_set_both_formats (struct variable *, const struct fmt_spec *);
 153
 154 /* Variable labels. */
 155 const char *var_get_label (const struct variable *);
 156 void var_set_label (struct variable *, const char *);
 157 void var_clear_label (struct variable *);
 158 bool var_has_label (const struct variable *);
 159
 160 /* GUI information. */
 161 enum measure var_get_measure (const struct variable *);
 162 void var_set_measure (struct variable *, enum measure);
 163
 164 int var_get_display_width (const struct variable *);
 165 void var_set_display_width (struct variable *, int display_width);
 166
 167 enum alignment var_get_alignment (const struct variable *);
 168 void var_set_alignment (struct variable *, enum alignment);
 169
 170 /* Variable location in cases. */
 171 size_t var_get_value_cnt (const struct variable *);
 172
 173 /* Whether variables' values should be preserved from case to
 174    case. */
 175 bool var_get_leave (const struct variable *);
 176
 177 /* Short names. */
 178 const char *var_get_short_name (const struct variable *);
 179 void var_set_short_name (struct variable *, const char *);
 180 void var_set_short_name_suffix (struct variable *, const char *, int suffix);
 181 void var_clear_short_name (struct variable *);
 182
 183 /* Pointers to `struct variable', by name. */
 184 int compare_var_ptr_names (const void *, const void *, const void *);
 185 unsigned hash_var_ptr_name (const void *, const void *);
 186
 187 /* Variable auxiliary data. */
 188 void *var_attach_aux (struct variable *,
 189                       void *aux, void (*aux_dtor) (struct variable *));
 190 void var_clear_aux (struct variable *);
 191 void *var_detach_aux (struct variable *);
 192 void var_dtor_free (struct variable *);
 193
 194 /* Classes of variables. */
 195 enum dict_class
 196   {
 197     DC_ORDINARY,                /* Ordinary identifier. */
 198     DC_SYSTEM,                  /* System variable. */
 199     DC_SCRATCH                  /* Scratch variable. */
 200   };
 201
 202 enum dict_class dict_class_from_id (const char *name);
 203 const char *dict_class_to_name (enum dict_class dict_class);
 204 \f
 205 /* Vector of variables. */
 206 struct vector
 207   {
 208     int idx;                    /* Index for dict_get_vector(). */
 209     char name[LONG_NAME_LEN + 1]; /* Name. */
 210     struct variable **var;      /* Vector of variables. */
 211     int cnt;                    /* Number of variables. */
 212   };
 213
 214
 215 /* Return a string representing this variable, in the form most
 216    appropriate from a human factors perspective.
 217    (IE: the label if it has one, otherwise the name )
 218 */
 219 const char * var_to_string(const struct variable *var);
 220
 221
 222 int width_to_bytes(int width);
 223
 224
 225 #endif /* !variable.h */