src/var.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., 59 Temple Place - Suite 330, Boston, MA
  18    02111-1307, USA. */
  19
  20 #if !var_h
  21 #define var_h 1
  22
  23 #include <stddef.h>
  24 #include "format.h"
  25 #include "t-test.h"
  26
  27 /* Values. */
  28
  29 /* Definition of the max length of a short string value, generally
  30    eight characters.  */
  31 #define MAX_SHORT_STRING ((SIZEOF_DOUBLE)>=8 ? ((SIZEOF_DOUBLE)+1)/2*2 : 8)
  32 #define MIN_LONG_STRING (MAX_SHORT_STRING+1)
  33
  34 /* FYI: It is a bad situation if sizeof(flt64) < MAX_SHORT_STRING:
  35    then short string missing values can be truncated in system files
  36    because there's only room for as many characters as can fit in a
  37    flt64. */
  38 #if MAX_SHORT_STRING > 8
  39 #error MAX_SHORT_STRING must be less than 8.
  40 #endif
  41
  42 /* Special values. */
  43 #define SYSMIS (-DBL_MAX)
  44 #define LOWEST second_lowest_value
  45 #define HIGHEST DBL_MAX
  46
  47 /* Describes one value, which is either a floating-point number or a
  48    short string. */
  49 union value
  50   {
  51     /* A numeric value. */
  52     double f;
  53
  54     /* A short-string value. */
  55     unsigned char s[MAX_SHORT_STRING];
  56
  57     /* This member is used by data-in.c to return a string result,
  58        since it may need to return a long string.  As currently
  59        implemented, it's a pointer to a static internal buffer in
  60        data-in.c.
  61
  62        Also used by evaluate_expression() to return a string result.
  63        As currently implemented, it's a pointer to a dynamic buffer in
  64        the appropriate expression.
  65
  66        Also used by the AGGREGATE procedure in handling string
  67        values. */
  68     unsigned char *c;
  69
  70     /* Sometimes we insert value's in a hash table. */
  71     unsigned long hash[SIZEOF_DOUBLE / SIZEOF_LONG];
  72   };
  73 \f
  74 /* Frequency tables. */
  75
  76 /* Frequency table entry. */
  77 struct freq
  78   {
  79     union value v;              /* The value. */
  80     double c;                   /* The number of occurrences of the value. */
  81   };
  82
  83 /* Types of frequency tables. */
  84 enum
  85   {
  86     FRQM_GENERAL,
  87     FRQM_INTEGER
  88   };
  89
  90 /* Entire frequency table. */
  91 struct freq_tab
  92   {
  93     int mode;                   /* FRQM_GENERAL or FRQM_INTEGER. */
  94
  95     /* General mode. */
  96     struct hsh_table *data;     /* Undifferentiated data. */
  97
  98     /* Integer mode. */
  99     double *vector;             /* Frequencies proper. */
 100     int min, max;               /* The boundaries of the table. */
 101     double out_of_range;        /* Sum of weights of out-of-range values. */
 102     double sysmis;              /* Sum of weights of SYSMIS values. */
 103
 104     /* All modes. */
 105     struct freq *valid;         /* Valid freqs. */
 106     int n_valid;                /* Number of total freqs. */
 107
 108     struct freq *missing;       /* Missing freqs. */
 109     int n_missing;              /* Number of missing freqs. */
 110
 111     /* Statistics. */
 112     double total_cases;         /* Sum of weights of all cases. */
 113     double valid_cases;         /* Sum of weights of valid cases. */
 114   };
 115 \f
 116 /* Procedures' private per-variable data. */
 117
 118 /* Structure name suffixes for private data:
 119    _proc: for a procedure (i.e., LIST -> list_proc).
 120    _trns: for a transformation (i.e., COMPUTE -> compute_trns.
 121    _pgm: for an input program (i.e., DATA LIST -> data_list_pgm). */
 122
 123 /* CROSSTABS private data. */
 124 struct crosstab_proc
 125   {
 126     /* Integer mode only. */
 127     int min;                    /* Minimum value. */
 128     int max;                    /* Maximum value + 1. */
 129     int count;                  /* max - min. */
 130   };
 131
 132
 133 /* FREQUENCIES private data. */
 134 enum
 135   {
 136     frq_mean = 0, frq_semean, frq_median, frq_mode, frq_stddev, frq_variance,
 137     frq_kurt, frq_sekurt, frq_skew, frq_seskew, frq_range, frq_min, frq_max,
 138     frq_sum, frq_n_stats
 139   };
 140
 141 struct frequencies_proc
 142   {
 143     int used;                   /* 1=This variable already used. */
 144
 145     /* Freqency table. */
 146     struct freq_tab tab;        /* Frequencies table to use. */
 147
 148     /* Percentiles. */
 149     int n_groups;               /* Number of groups. */
 150     double *groups;             /* Groups. */
 151
 152     /* Statistics. */
 153     double stat[frq_n_stats];
 154   };
 155
 156 /* LIST private data. */
 157 struct list_proc
 158   {
 159     int newline;                /* Whether a new line begins here. */
 160     int width;                  /* Field width. */
 161     int vert;                   /* Whether to print the varname vertically. */
 162   };
 163
 164 /* DESCRIPTIVES private data.  Note that the DESCRIPTIVES procedure also
 165    has a transformation, descriptives_trns. */
 166 enum
 167   {
 168     /* As these are used as bit indexes, there must be 32 or fewer.
 169        Be very careful in adjusting these, see the structure below
 170        and the table in descriptives.q. */
 171     dsc_mean = 0, dsc_semean, dsc_stddev, dsc_variance, dsc_kurt,
 172     dsc_sekurt, dsc_skew, dsc_seskew, dsc_range, dsc_min,
 173     dsc_max, dsc_sum, dsc_n_stats
 174   };
 175
 176 struct descriptives_proc
 177   {
 178     /* Miscellaneous. */
 179     int dup;                    /* Finds duplicates in list of
 180                                    variables. */
 181     char zname[10];             /* Name for z-score variable. */
 182
 183     /* Counts. */
 184     double valid, miss;         /* Valid, missing--general. */
 185
 186     /* Mean, moments about the mean. */
 187     double X_bar, M2, M3, M4;
 188     double min, max;
 189
 190     /* Statistics. */
 191     double stats[dsc_n_stats];  /* Everything glommed together. */
 192   };
 193
 194 /* GET private data. */
 195 struct get_proc
 196   {
 197     int fv, nv;                 /* First, # of values. */
 198   };
 199
 200 /* Sort order. */
 201 enum
 202   {
 203     SRT_ASCEND,                 /* A, B, C, ..., X, Y, Z. */
 204     SRT_DESCEND                 /* Z, Y, X, ..., C, B, A. */
 205   };
 206
 207 /* SORT CASES private data. */
 208 struct sort_cases_proc
 209   {
 210     int order;                  /* SRT_ASCEND or SRT_DESCEND. */
 211   };
 212
 213 /* MEANS private data. */
 214 struct means_proc
 215   {
 216     double min, max;            /* Range for integer mode. */
 217   };
 218
 219 /* Different types of variables for MATRIX DATA procedure.  Order is
 220    important: these are used for sort keys. */
 221 enum
 222   {
 223     MXD_SPLIT,                  /* SPLIT FILE variables. */
 224     MXD_ROWTYPE,                /* ROWTYPE_. */
 225     MXD_FACTOR,                 /* Factor variables. */
 226     MXD_VARNAME,                /* VARNAME_. */
 227     MXD_CONTINUOUS,             /* Continuous variables. */
 228
 229     MXD_COUNT
 230   };
 231
 232 /* MATRIX DATA private data. */
 233 struct matrix_data_proc
 234   {
 235     int vartype;                /* Variable type. */
 236     int subtype;                /* Subtype. */
 237   };
 238
 239 /* MATCH FILES private data. */
 240 struct match_files_proc
 241   {
 242     struct variable *master;    /* Corresponding master file variable. */
 243   };
 244
 245 \f
 246 /* Script variables. */
 247
 248 /* Variable type. */
 249 enum
 250   {
 251     NUMERIC,                    /* A numeric variable. */
 252     ALPHA                       /* A string variable.  (STRING is pre-empted by lexer.h) */
 253   };
 254
 255 /* Types of missing values.  Order is significant, see
 256    mis-val.c:parse_numeric(), sfm-read.c:sfm_read_dictionary()
 257    sfm-write.c:sfm_write_dictionary(),
 258    sysfile-info.c:cmd_sysfile_info(), mis-val.c:copy_missing_values(),
 259    pfm-read.c:read_variables(), pfm-write.c:write_variables(),
 260    apply-dict.c:cmd_apply_dictionary(), and more (?). */
 261 enum
 262   {
 263     MISSING_NONE,               /* No user-missing values. */
 264     MISSING_1,                  /* One user-missing value. */
 265     MISSING_2,                  /* Two user-missing values. */
 266     MISSING_3,                  /* Three user-missing values. */
 267     MISSING_RANGE,              /* [a,b]. */
 268     MISSING_LOW,                /* (-inf,a]. */
 269     MISSING_HIGH,               /* (a,+inf]. */
 270     MISSING_RANGE_1,            /* [a,b], c. */
 271     MISSING_LOW_1,              /* (-inf,a], b. */
 272     MISSING_HIGH_1,             /* (a,+inf), b. */
 273     MISSING_COUNT
 274   };
 275
 276 /* A variable's dictionary entry.  */
 277 struct variable
 278   {
 279     char name[9];               /* As a string. */
 280     int index;                  /* Index into its dictionary's var[]. */
 281     int type;                   /* NUMERIC or ALPHA. */
 282
 283     /* Also important but parse_variables() doesn't need it.  Still,
 284        check before reordering. */
 285     int width;                  /* Size of string variables in chars. */
 286     int fv, nv;                 /* Index into `value's, number of values. */
 287     unsigned init : 1;          /* 1=VFM must init and possibly reinit. */
 288     unsigned reinit : 1;        /* Cases are: 1=reinitialized; 0=left. */
 289
 290     /* Missing values. */
 291     int miss_type;              /* One of the MISSING_* constants. */
 292     union value missing[3];     /* User-missing value. */
 293
 294     /* Display formats. */
 295     struct fmt_spec print;      /* Default format for PRINT. */
 296     struct fmt_spec write;      /* Default format for WRITE. */
 297
 298     /* Labels. */
 299     struct val_labs *val_labs;
 300     char *label;                /* Variable label. */
 301
 302     /* Per-procedure info. */
 303     void *aux;
 304     struct get_proc get;
 305     union
 306       {
 307         struct crosstab_proc crs;
 308         struct descriptives_proc dsc;
 309         struct frequencies_proc frq;
 310         struct list_proc lst;
 311         struct means_proc mns;
 312         struct sort_cases_proc srt;
 313         struct matrix_data_proc mxd;
 314         struct match_files_proc mtf;
 315         struct t_test_proc t_t;
 316       }
 317     p;
 318   };
 319
 320 int compare_variables (const void *, const void *, void *);
 321 unsigned hash_variable (const void *, void *);
 322
 323 /* Classes of variables. */
 324 enum dict_class
 325   {
 326     DC_ORDINARY,                /* Ordinary identifier. */
 327     DC_SYSTEM,                  /* System variable. */
 328     DC_SCRATCH                  /* Scratch variable. */
 329   };
 330
 331 enum dict_class dict_class_from_id (const char *name);
 332 const char *dict_class_to_name (enum dict_class dict_class);
 333 \f
 334 /* Vector of variables. */
 335 struct vector
 336   {
 337     int idx;                    /* Index for dict_get_vector(). */
 338     char name[9];               /* Name. */
 339     struct variable **var;      /* Vector of variables. */
 340     int cnt;                    /* Number of variables. */
 341   };
 342 \f
 343 /* Cases. */
 344
 345 /* A single case.  (This doesn't need to be a struct anymore, but it
 346    remains so for hysterical raisins.) */
 347 struct ccase
 348   {
 349     union value data[1];
 350   };
 351 \f
 352 /* Dictionary. */
 353
 354 /* Complete dictionary state. */
 355 struct dictionary;
 356
 357 struct dictionary *dict_create (void);
 358 struct dictionary *dict_clone (const struct dictionary *);
 359 void dict_clear (struct dictionary *);
 360 void dict_destroy (struct dictionary *);
 361
 362 size_t dict_get_var_cnt (const struct dictionary *);
 363 struct variable *dict_get_var (const struct dictionary *, size_t idx);
 364 void dict_get_vars (const struct dictionary *,
 365                     struct variable ***vars, size_t *cnt,
 366                     unsigned exclude_classes);
 367
 368 struct variable *dict_create_var (struct dictionary *, const char *,
 369                                   int width);
 370 struct variable *dict_create_var_assert (struct dictionary *, const char *,
 371                                   int width);
 372 struct variable *dict_clone_var (struct dictionary *, const struct variable *,
 373                                  const char *);
 374 void dict_rename_var (struct dictionary *, struct variable *, const char *);
 375
 376 struct variable *dict_lookup_var (const struct dictionary *, const char *);
 377 struct variable *dict_lookup_var_assert (const struct dictionary *,
 378                                          const char *);
 379 int dict_contains_var (const struct dictionary *, const struct variable *);
 380 void dict_delete_var (struct dictionary *, struct variable *);
 381 void dict_delete_vars (struct dictionary *,
 382                        struct variable *const *, size_t count);
 383 void dict_reorder_vars (struct dictionary *,
 384                         struct variable *const *, size_t count);
 385 int dict_rename_vars (struct dictionary *,
 386                       struct variable **, char **new_names,
 387                       size_t count, char **err_name);
 388
 389 struct variable *dict_get_weight (const struct dictionary *);
 390 double dict_get_case_weight (const struct dictionary *, const struct ccase *);
 391 void dict_set_weight (struct dictionary *, struct variable *);
 392
 393 struct variable *dict_get_filter (const struct dictionary *);
 394 void dict_set_filter (struct dictionary *, struct variable *);
 395
 396 int dict_get_case_limit (const struct dictionary *);
 397 void dict_set_case_limit (struct dictionary *, int);
 398
 399 int dict_get_next_value_idx (const struct dictionary *);
 400 size_t dict_get_case_size (const struct dictionary *);
 401 void dict_compact_values (struct dictionary *);
 402
 403 struct variable *const *dict_get_split_vars (const struct dictionary *);
 404 size_t dict_get_split_cnt (const struct dictionary *);
 405 void dict_set_split_vars (struct dictionary *,
 406                           struct variable *const *, size_t cnt);
 407
 408 const char *dict_get_label (const struct dictionary *);
 409 void dict_set_label (struct dictionary *, const char *);
 410
 411 const char *dict_get_documents (const struct dictionary *);
 412 void dict_set_documents (struct dictionary *, const char *);
 413
 414 int dict_create_vector (struct dictionary *,
 415                         const char *name,
 416                         struct variable **, size_t cnt);
 417 const struct vector *dict_get_vector (const struct dictionary *,
 418                                       size_t idx);
 419 size_t dict_get_vector_cnt (const struct dictionary *);
 420 const struct vector *dict_lookup_vector (const struct dictionary *,
 421                                          const char *name);
 422 void dict_clear_vectors (struct dictionary *);
 423 \f
 424 void discard_variables (void);
 425
 426 /* This is the active file dictionary. */
 427 extern struct dictionary *default_dict;
 428 \f
 429 /* Transformation state. */
 430
 431 /* Default file handle for DATA LIST, REREAD, REPEATING DATA
 432    commands. */
 433 extern struct file_handle *default_handle;
 434
 435 /* PROCESS IF expression. */
 436 extern struct expression *process_if_expr;
 437 \f
 438 /* TEMPORARY support. */
 439
 440 /* 1=TEMPORARY has been executed at some point. */
 441 extern int temporary;
 442
 443 /* If temporary!=0, the saved dictionary. */
 444 extern struct dictionary *temp_dict;
 445
 446 /* If temporary!=0, index into t_trns[] (declared far below) that
 447    gives the point at which data should be written out.  -1 means that
 448    the data shouldn't be changed since all transformations are
 449    temporary. */
 450 extern int temp_trns;
 451
 452 /* If FILTER is active, whether it was executed before or after
 453    TEMPORARY. */
 454 extern int FILTER_before_TEMPORARY;
 455
 456 void cancel_temporary (void);
 457 \f
 458 /* Functions. */
 459
 460 void dump_split_vars (const struct ccase *);
 461
 462 int is_num_user_missing (double, const struct variable *);
 463 int is_str_user_missing (const unsigned char[], const struct variable *);
 464 int is_missing (const union value *, const struct variable *);
 465 int is_system_missing (const union value *, const struct variable *);
 466 int is_user_missing (const union value *, const struct variable *);
 467 void copy_missing_values (struct variable *dest, const struct variable *src);
 468 \f
 469 /* Transformations. */
 470
 471 /* Header for all transformations. */
 472 struct trns_header
 473   {
 474     /* Index into t_trns[]. */
 475     int index;
 476
 477     /* Transformation proc. */
 478     int (*proc) (struct trns_header *, struct ccase *);
 479
 480     /* Garbage collector proc. */
 481     void (*free) (struct trns_header *);
 482   };
 483
 484 /* Array of transformations */
 485 extern struct trns_header **t_trns;
 486
 487 /* Number of transformations, maximum number in array currently. */
 488 extern int n_trns, m_trns;
 489
 490 /* Index of first transformation that is really a transformation.  Any
 491    transformations before this belong to INPUT PROGRAM. */
 492 extern int f_trns;
 493
 494 void add_transformation (struct trns_header *trns);
 495 void cancel_transformations (void);
 496 \f
 497 struct var_set;
 498
 499 struct var_set *var_set_create_from_dict (struct dictionary *d);
 500 struct var_set *var_set_create_from_array (struct variable **var, size_t);
 501
 502 size_t var_set_get_cnt (struct var_set *vs);
 503 struct variable *var_set_get_var (struct var_set *vs, size_t idx);
 504 struct variable *var_set_lookup_var (struct var_set *vs, const char *name);
 505 void var_set_destroy (struct var_set *vs);
 506
 507 \f
 508 /* Variable parsers. */
 509
 510 enum
 511   {
 512     PV_NONE = 0,                /* No options. */
 513     PV_SINGLE = 0001,           /* Restrict to a single name or TO use. */
 514     PV_DUPLICATE = 0002,        /* Don't merge duplicates. */
 515     PV_APPEND = 0004,           /* Append to existing list. */
 516     PV_NO_DUPLICATE = 0010,     /* Error on duplicates. */
 517     PV_NUMERIC = 0020,          /* Vars must be numeric. */
 518     PV_STRING = 0040,           /* Vars must be string. */
 519     PV_SAME_TYPE = 00100,       /* All vars must be the same type. */
 520     PV_NO_SCRATCH = 00200,      /* Disallow scratch variables. */
 521   };
 522
 523 struct variable *parse_variable (void);
 524 struct variable *parse_dict_variable (struct dictionary *);
 525 int parse_variables (struct dictionary *, struct variable ***, int *,
 526                      int opts);
 527 int parse_var_set_vars (struct var_set *, struct variable ***, int *,
 528                         int opts);
 529 int parse_DATA_LIST_vars (char ***names, int *cnt, int opts);
 530 int parse_mixed_vars (char ***names, int *cnt, int opts);
 531
 532 #endif /* !var_h */