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