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 /* Script variables. */
  32
  33 /* Variable type. */
  34 enum var_type
  35   {
  36     NUMERIC,                    /* A numeric variable. */
  37     ALPHA                       /* A string variable. */
  38   };
  39
  40 const char *var_type_adj (enum var_type);
  41 const char *var_type_noun (enum var_type);
  42
  43 /* Maximum lengths of short and long variable names.
  44    Most operations support long variable names,
  45    but some file formats are limited to short names. */
  46 #define SHORT_NAME_LEN 8        /* Short name length. */
  47 #define LONG_NAME_LEN 64        /* Long name length. */
  48
  49 /* A variable's dictionary entry.  */
  50 struct variable
  51   {
  52     /* Dictionary information. */
  53     char name[LONG_NAME_LEN + 1]; /* Variable name.  Mixed case. */
  54     enum var_type type;         /* NUMERIC or ALPHA. */
  55     int width;                  /* Size of string variables in chars. */
  56     struct missing_values miss; /* Missing values. */
  57     struct fmt_spec print;      /* Default format for PRINT. */
  58     struct fmt_spec write;      /* Default format for WRITE. */
  59     struct val_labs *val_labs;  /* Value labels. */
  60     char *label;                /* Variable label. */
  61     enum measure measure;       /* Nominal, ordinal, or continuous. */
  62     int display_width;          /* Width of data editor column. */
  63     enum alignment alignment;   /* Alignment of data in GUI. */
  64
  65     /* Case information. */
  66     int fv, nv;                 /* Index into `value's, number of values. */
  67     bool init;                  /* True if needs init and possibly reinit. */
  68     bool reinit;                /* True: reinitialize; false: leave. */
  69
  70     /* Data for use by containing dictionary. */
  71     int index;                  /* Dictionary index. */
  72
  73     /* Short name, used only for system and portable file input
  74        and output.  Upper case only.  There is no index for short
  75        names.  Short names are not necessarily unique.  Any
  76        variable may have no short name, indicated by an empty
  77        string. */
  78     char short_name[SHORT_NAME_LEN + 1];
  79
  80     /* Each command may use these fields as needed. */
  81     void *aux;
  82     void (*aux_dtor) (struct variable *);
  83
  84     /* Values of a categorical variable.  Procedures need
  85        vectors with binary entries, so any variable of type ALPHA will
  86        have its values stored here. */
  87     struct cat_vals *obs_vals;
  88   };
  89
  90 /* Variable names. */
  91 bool var_is_valid_name (const char *, bool issue_error);
  92 bool var_is_plausible_name (const char *name, bool issue_error);
  93 int compare_var_names (const void *, const void *, void *);
  94 unsigned hash_var_name (const void *, void *);
  95
  96 /* Short names. */
  97 void var_set_short_name (struct variable *, const char *);
  98 void var_set_short_name_suffix (struct variable *, const char *, int suffix);
  99 void var_clear_short_name (struct variable *);
 100
 101 /* Pointers to `struct variable', by name. */
 102 int compare_var_ptr_names (const void *, const void *, void *);
 103 unsigned hash_var_ptr_name (const void *, void *);
 104
 105 /* Variable auxiliary data. */
 106 void *var_attach_aux (struct variable *,
 107                       void *aux, void (*aux_dtor) (struct variable *));
 108 void var_clear_aux (struct variable *);
 109 void *var_detach_aux (struct variable *);
 110 void var_dtor_free (struct variable *);
 111
 112 /* Classes of variables. */
 113 enum dict_class
 114   {
 115     DC_ORDINARY,                /* Ordinary identifier. */
 116     DC_SYSTEM,                  /* System variable. */
 117     DC_SCRATCH                  /* Scratch variable. */
 118   };
 119
 120 enum dict_class dict_class_from_id (const char *name);
 121 const char *dict_class_to_name (enum dict_class dict_class);
 122 \f
 123 /* Vector of variables. */
 124 struct vector
 125   {
 126     int idx;                    /* Index for dict_get_vector(). */
 127     char name[LONG_NAME_LEN + 1]; /* Name. */
 128     struct variable **var;      /* Vector of variables. */
 129     int cnt;                    /* Number of variables. */
 130   };
 131 \f
 132 void discard_variables (void);
 133
 134 /* This is the active file dictionary. */
 135 extern struct dictionary *default_dict;
 136 \f
 137 /* Transformation state. */
 138
 139 /* PROCESS IF expression. */
 140 extern struct expression *process_if_expr;
 141 \f
 142 /* TEMPORARY support. */
 143
 144 /* 1=TEMPORARY has been executed at some point. */
 145 extern int temporary;
 146
 147 /* If temporary!=0, the saved dictionary. */
 148 extern struct dictionary *temp_dict;
 149
 150 /* If temporary!=0, index into t_trns[] (declared far below) that
 151    gives the point at which data should be written out.  -1 means that
 152    the data shouldn't be changed since all transformations are
 153    temporary. */
 154 extern size_t temp_trns;
 155
 156 void cancel_temporary (void);
 157 \f
 158 struct ccase;
 159 void dump_split_vars (const struct ccase *);
 160 \f
 161 /* Transformations. */
 162
 163 /* trns_proc_func return values. */
 164 #define TRNS_CONTINUE   -1 /* Continue to next transformation. */
 165 #define TRNS_DROP_CASE  -2 /* Drop this case. */
 166 #define TRNS_ERROR      -3 /* A serious error, so stop the procedure. */
 167 #define TRNS_NEXT_CASE  -4 /* Skip to next case.  INPUT PROGRAM only. */
 168 #define TRNS_END_FILE   -5 /* End of input.  INPUT PROGRAM only. */
 169
 170 typedef int trns_proc_func (void *, struct ccase *, int);
 171 typedef bool trns_free_func (void *);
 172
 173 /* A transformation. */
 174 struct transformation
 175   {
 176     trns_proc_func *proc;       /* Transformation proc. */
 177     trns_free_func *free;       /* Garbage collector proc. */
 178     void *private;              /* Private data. */
 179   };
 180
 181 /* Array of transformations */
 182 extern struct transformation *t_trns;
 183
 184 /* Number of transformations, maximum number in array currently. */
 185 extern size_t n_trns, m_trns;
 186
 187 /* Index of first transformation that is really a transformation.  Any
 188    transformations before this belong to INPUT PROGRAM. */
 189 extern size_t f_trns;
 190
 191 void add_transformation (trns_proc_func *, trns_free_func *, void *);
 192 size_t next_transformation (void);
 193 bool cancel_transformations (void);
 194 \f
 195 struct var_set;
 196
 197 struct var_set *var_set_create_from_dict (const struct dictionary *d);
 198 struct var_set *var_set_create_from_array (struct variable *const *var,
 199                                            size_t);
 200
 201 size_t var_set_get_cnt (const struct var_set *vs);
 202 struct variable *var_set_get_var (const struct var_set *vs, size_t idx);
 203 struct variable *var_set_lookup_var (const struct var_set *vs,
 204                                      const char *name);
 205 bool var_set_lookup_var_idx (const struct var_set *vs, const char *name,
 206                              size_t *idx);
 207 void var_set_destroy (struct var_set *vs);
 208 \f
 209 /* Variable parsers. */
 210
 211 enum
 212   {
 213     PV_NONE = 0,                /* No options. */
 214     PV_SINGLE = 0001,           /* Restrict to a single name or TO use. */
 215     PV_DUPLICATE = 0002,        /* Don't merge duplicates. */
 216     PV_APPEND = 0004,           /* Append to existing list. */
 217     PV_NO_DUPLICATE = 0010,     /* Error on duplicates. */
 218     PV_NUMERIC = 0020,          /* Vars must be numeric. */
 219     PV_STRING = 0040,           /* Vars must be string. */
 220     PV_SAME_TYPE = 00100,       /* All vars must be the same type. */
 221     PV_NO_SCRATCH = 00200       /* Disallow scratch variables. */
 222   };
 223
 224 struct pool;
 225 struct variable *parse_variable (void);
 226 struct variable *parse_dict_variable (const struct dictionary *);
 227 int parse_variables (const struct dictionary *, struct variable ***, size_t *,
 228                      int opts);
 229 int parse_var_set_vars (const struct var_set *, struct variable ***, size_t *,
 230                         int opts);
 231 int parse_DATA_LIST_vars (char ***names, size_t *cnt, int opts);
 232 int parse_mixed_vars (char ***names, size_t *cnt, int opts);
 233 int parse_mixed_vars_pool (struct pool *,
 234                            char ***names, size_t *cnt, int opts);
 235
 236
 237 /* Return a string representing this variable, in the form most
 238    appropriate from a human factors perspective.
 239    (IE: the label if it has one, otherwise the name )
 240 */
 241 const char * var_to_string(const struct variable *var);
 242
 243
 244 #endif /* !variable.h */