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 const char *var_type_adj (enum var_type);
  39 const char *var_type_noun (enum var_type);
  40
  41 /* Maximum lengths of short and long variable names.
  42    Most operations support long variable names,
  43    but some file formats are limited to short names. */
  44 #define SHORT_NAME_LEN 8        /* Short name length. */
  45 #define LONG_NAME_LEN 64        /* Long name length. */
  46
  47 /* A variable's dictionary entry.  */
  48 struct variable
  49   {
  50     /* Dictionary information. */
  51     char name[LONG_NAME_LEN + 1]; /* Variable name.  Mixed case. */
  52     enum var_type type;         /* NUMERIC or ALPHA. */
  53     int width;                  /* Size of string variables in chars. */
  54     struct missing_values miss; /* Missing values. */
  55     struct fmt_spec print;      /* Default format for PRINT. */
  56     struct fmt_spec write;      /* Default format for WRITE. */
  57     struct val_labs *val_labs;  /* Value labels. */
  58     char *label;                /* Variable label. */
  59     enum measure measure;       /* Nominal, ordinal, or continuous. */
  60     int display_width;          /* Width of data editor column. */
  61     enum alignment alignment;   /* Alignment of data in GUI. */
  62
  63     /* Case information. */
  64     int fv, nv;                 /* Index into `value's, number of values. */
  65     bool leave;                 /* Leave value from case to case? */
  66
  67     /* Data for use by containing dictionary. */
  68     int index;                  /* Dictionary index. */
  69
  70     /* Short name, used only for system and portable file input
  71        and output.  Upper case only.  There is no index for short
  72        names.  Short names are not necessarily unique.  Any
  73        variable may have no short name, indicated by an empty
  74        string. */
  75     char short_name[SHORT_NAME_LEN + 1];
  76
  77     /* Each command may use these fields as needed. */
  78     void *aux;
  79     void (*aux_dtor) (struct variable *);
  80
  81     /* Values of a categorical variable.  Procedures need
  82        vectors with binary entries, so any variable of type ALPHA will
  83        have its values stored here. */
  84     struct cat_vals *obs_vals;
  85   };
  86
  87 /* Variable names. */
  88 bool var_is_valid_name (const char *, bool issue_error);
  89 bool var_is_plausible_name (const char *name, bool issue_error);
  90 int compare_var_names (const void *, const void *, void *);
  91 unsigned hash_var_name (const void *, void *);
  92
  93 /* Short names. */
  94 void var_set_short_name (struct variable *, const char *);
  95 void var_set_short_name_suffix (struct variable *, const char *, int suffix);
  96 void var_clear_short_name (struct variable *);
  97
  98 /* Pointers to `struct variable', by name. */
  99 int compare_var_ptr_names (const void *, const void *, void *);
 100 unsigned hash_var_ptr_name (const void *, void *);
 101
 102 /* Variable auxiliary data. */
 103 void *var_attach_aux (struct variable *,
 104                       void *aux, void (*aux_dtor) (struct variable *));
 105 void var_clear_aux (struct variable *);
 106 void *var_detach_aux (struct variable *);
 107 void var_dtor_free (struct variable *);
 108
 109 /* Classes of variables. */
 110 enum dict_class
 111   {
 112     DC_ORDINARY,                /* Ordinary identifier. */
 113     DC_SYSTEM,                  /* System variable. */
 114     DC_SCRATCH                  /* Scratch variable. */
 115   };
 116
 117 enum dict_class dict_class_from_id (const char *name);
 118 const char *dict_class_to_name (enum dict_class dict_class);
 119 \f
 120 /* Vector of variables. */
 121 struct vector
 122   {
 123     int idx;                    /* Index for dict_get_vector(). */
 124     char name[LONG_NAME_LEN + 1]; /* Name. */
 125     struct variable **var;      /* Vector of variables. */
 126     int cnt;                    /* Number of variables. */
 127   };
 128 \f
 129 /* PROCESS IF expression. */
 130 extern struct expression *process_if_expr;
 131 \f
 132 struct ccase;
 133 void dump_split_vars (const struct ccase *);
 134 \f
 135 struct var_set;
 136
 137 struct dictionary;
 138 struct var_set *var_set_create_from_dict (const struct dictionary *d);
 139 struct var_set *var_set_create_from_array (struct variable *const *var,
 140                                            size_t);
 141
 142 size_t var_set_get_cnt (const struct var_set *vs);
 143 struct variable *var_set_get_var (const struct var_set *vs, size_t idx);
 144 struct variable *var_set_lookup_var (const struct var_set *vs,
 145                                      const char *name);
 146 bool var_set_lookup_var_idx (const struct var_set *vs, const char *name,
 147                              size_t *idx);
 148 void var_set_destroy (struct var_set *vs);
 149 \f
 150 /* Variable parsers. */
 151
 152 enum
 153   {
 154     PV_NONE = 0,                /* No options. */
 155     PV_SINGLE = 0001,           /* Restrict to a single name or TO use. */
 156     PV_DUPLICATE = 0002,        /* Don't merge duplicates. */
 157     PV_APPEND = 0004,           /* Append to existing list. */
 158     PV_NO_DUPLICATE = 0010,     /* Error on duplicates. */
 159     PV_NUMERIC = 0020,          /* Vars must be numeric. */
 160     PV_STRING = 0040,           /* Vars must be string. */
 161     PV_SAME_TYPE = 00100,       /* All vars must be the same type. */
 162     PV_NO_SCRATCH = 00200       /* Disallow scratch variables. */
 163   };
 164
 165 struct pool;
 166 struct variable *parse_variable (void);
 167 struct variable *parse_dict_variable (const struct dictionary *);
 168 int parse_variables (const struct dictionary *, struct variable ***, size_t *,
 169                      int opts);
 170 int parse_var_set_vars (const struct var_set *, struct variable ***, size_t *,
 171                         int opts);
 172 int parse_DATA_LIST_vars (char ***names, size_t *cnt, int opts);
 173 int parse_mixed_vars (char ***names, size_t *cnt, int opts);
 174 int parse_mixed_vars_pool (struct pool *,
 175                            char ***names, size_t *cnt, int opts);
 176
 177
 178 /* Return a string representing this variable, in the form most
 179    appropriate from a human factors perspective.
 180    (IE: the label if it has one, otherwise the name )
 181 */
 182 const char * var_to_string(const struct variable *var);
 183
 184
 185 /* Two complementary functions for dealing with
 186    Very Long String variables */
 187
 188 void copy_demangle (char *dst, size_t dst_size,
 189                     const char *src, size_t src_size);
 190
 191 void copy_mangle (char *dst, size_t dst_size,
 192                   const char *src, size_t src_size);
 193
 194 int width_to_bytes(int width);
 195
 196
 197 #endif /* !variable.h */