faf2cd2bd55d5945b09a1f0ede395f5e47c7fe10
[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 #include "t-test.h"
26 #include "val.h"
27
28 /* Frequency tables. */
29
30 /* Frequency table entry. */
31 struct freq
32   {
33     union value v;              /* The value. */
34     double c;                   /* The number of occurrences of the value. */
35   };
36
37 /* Types of frequency tables. */
38 enum
39   {
40     FRQM_GENERAL,
41     FRQM_INTEGER
42   };
43
44 /* Entire frequency table. */
45 struct freq_tab
46   {
47     int mode;                   /* FRQM_GENERAL or FRQM_INTEGER. */
48
49     /* General mode. */
50     struct hsh_table *data;     /* Undifferentiated data. */
51
52     /* Integer mode. */
53     double *vector;             /* Frequencies proper. */
54     int min, max;               /* The boundaries of the table. */
55     double out_of_range;        /* Sum of weights of out-of-range values. */
56     double sysmis;              /* Sum of weights of SYSMIS values. */
57
58     /* All modes. */
59     struct freq *valid;         /* Valid freqs. */
60     int n_valid;                /* Number of total freqs. */
61
62     struct freq *missing;       /* Missing freqs. */
63     int n_missing;              /* Number of missing freqs. */
64
65     /* Statistics. */
66     double total_cases;         /* Sum of weights of all cases. */
67     double valid_cases;         /* Sum of weights of valid cases. */
68   };
69 \f
70 /* Procedures' private per-variable data. */
71
72 /* Structure name suffixes for private data:
73    _proc: for a procedure (i.e., LIST -> list_proc).
74    _trns: for a transformation (i.e., COMPUTE -> compute_trns.
75    _pgm: for an input program (i.e., DATA LIST -> data_list_pgm). */
76
77 /* CROSSTABS private data. */
78 struct crosstab_proc
79   {
80     /* Integer mode only. */
81     int min;                    /* Minimum value. */
82     int max;                    /* Maximum value + 1. */
83     int count;                  /* max - min. */
84   };
85
86
87 /* FREQUENCIES private data. */
88 enum
89   {
90     frq_mean = 0, frq_semean, frq_median, frq_mode, frq_stddev, frq_variance,
91     frq_kurt, frq_sekurt, frq_skew, frq_seskew, frq_range, frq_min, frq_max,
92     frq_sum, frq_n_stats
93   };
94
95 struct frequencies_proc
96   {
97     int used;                   /* 1=This variable already used. */
98
99     /* Freqency table. */
100     struct freq_tab tab;        /* Frequencies table to use. */
101
102     /* Percentiles. */
103     int n_groups;               /* Number of groups. */
104     double *groups;             /* Groups. */
105
106     /* Statistics. */
107     double stat[frq_n_stats];
108   };
109
110 /* LIST private data. */
111 struct list_proc
112   {
113     int newline;                /* Whether a new line begins here. */
114     int width;                  /* Field width. */
115     int vert;                   /* Whether to print the varname vertically. */
116   };
117
118 /* GET private data. */
119 struct get_proc
120   {
121     int fv, nv;                 /* First, # of values. */
122   };
123
124 /* MEANS private data. */
125 struct means_proc
126   {
127     double min, max;            /* Range for integer mode. */
128   };
129
130 /* Different types of variables for MATRIX DATA procedure.  Order is
131    important: these are used for sort keys. */
132 enum
133   {
134     MXD_SPLIT,                  /* SPLIT FILE variables. */
135     MXD_ROWTYPE,                /* ROWTYPE_. */
136     MXD_FACTOR,                 /* Factor variables. */
137     MXD_VARNAME,                /* VARNAME_. */
138     MXD_CONTINUOUS,             /* Continuous variables. */
139
140     MXD_COUNT
141   };
142
143 /* MATRIX DATA private data. */
144 struct matrix_data_proc
145   {
146     int vartype;                /* Variable type. */
147     int subtype;                /* Subtype. */
148   };
149
150 /* MATCH FILES private data. */
151 struct match_files_proc
152   {
153     struct variable *master;    /* Corresponding master file variable. */
154   };
155
156 \f
157 /* Script variables. */
158
159 /* Variable type. */
160 enum
161   {
162     NUMERIC,                    /* A numeric variable. */
163     ALPHA                       /* A string variable.  (STRING is pre-empted by lexer.h) */
164   };
165
166 /* Types of missing values.  Order is significant, see
167    mis-val.c:parse_numeric(), sfm-read.c:sfm_read_dictionary()
168    sfm-write.c:sfm_write_dictionary(),
169    sysfile-info.c:cmd_sysfile_info(), mis-val.c:copy_missing_values(),
170    pfm-read.c:read_variables(), pfm-write.c:write_variables(),
171    apply-dict.c:cmd_apply_dictionary(), and more (?). */
172 enum
173   {
174     MISSING_NONE,               /* No user-missing values. */
175     MISSING_1,                  /* One user-missing value. */
176     MISSING_2,                  /* Two user-missing values. */
177     MISSING_3,                  /* Three user-missing values. */
178     MISSING_RANGE,              /* [a,b]. */
179     MISSING_LOW,                /* (-inf,a]. */
180     MISSING_HIGH,               /* (a,+inf]. */
181     MISSING_RANGE_1,            /* [a,b], c. */
182     MISSING_LOW_1,              /* (-inf,a], b. */
183     MISSING_HIGH_1,             /* (a,+inf), b. */
184     MISSING_COUNT
185   };
186
187 /* A variable's dictionary entry.  */
188 struct variable
189   {
190     char name[9];               /* As a string. */
191     int index;                  /* Index into its dictionary's var[]. */
192     int type;                   /* NUMERIC or ALPHA. */
193
194     int width;                  /* Size of string variables in chars. */
195     int fv, nv;                 /* Index into `value's, number of values. */
196     unsigned init : 1;          /* 1=VFM must init and possibly reinit. */
197     unsigned reinit : 1;        /* Cases are: 1=reinitialized; 0=left. */
198
199     /* Missing values. */
200     int miss_type;              /* One of the MISSING_* constants. */
201     union value missing[3];     /* User-missing value. */
202
203     /* Display formats. */
204     struct fmt_spec print;      /* Default format for PRINT. */
205     struct fmt_spec write;      /* Default format for WRITE. */
206
207     /* Labels. */
208     struct val_labs *val_labs;
209     char *label;                /* Variable label. */
210
211     /* Per-procedure info. */
212     void *aux;
213     struct get_proc get;
214     union
215       {
216         struct crosstab_proc crs;
217         struct frequencies_proc frq;
218         struct list_proc lst;
219         struct means_proc mns;
220         struct matrix_data_proc mxd;
221         struct match_files_proc mtf;
222         struct t_test_proc t_t;
223       }
224     p;
225   };
226
227 int compare_variables (const void *, const void *, void *);
228 unsigned hash_variable (const void *, void *);
229
230 /* Classes of variables. */
231 enum dict_class 
232   {
233     DC_ORDINARY,                /* Ordinary identifier. */
234     DC_SYSTEM,                  /* System variable. */
235     DC_SCRATCH                  /* Scratch variable. */
236   };
237
238 enum dict_class dict_class_from_id (const char *name);
239 const char *dict_class_to_name (enum dict_class dict_class);
240 \f
241 /* Vector of variables. */
242 struct vector
243   {
244     int idx;                    /* Index for dict_get_vector(). */
245     char name[9];               /* Name. */
246     struct variable **var;      /* Vector of variables. */
247     int cnt;                    /* Number of variables. */
248   };
249 \f
250 /* Cases. */
251
252 /* A single case.  (This doesn't need to be a struct anymore, but it
253    remains so for hysterical raisins.) */
254 struct ccase
255   {
256     union value data[1];
257   };
258
259 /* Linked list of cases. */
260 struct case_list 
261   {
262     struct case_list *next;
263     struct ccase c;
264   };
265 \f
266 /* Dictionary. */ 
267
268 /* Complete dictionary state. */
269 struct dictionary;
270
271 struct dictionary *dict_create (void);
272 struct dictionary *dict_clone (const struct dictionary *);
273 void dict_clear (struct dictionary *);
274 void dict_destroy (struct dictionary *);
275
276 size_t dict_get_var_cnt (const struct dictionary *);
277 struct variable *dict_get_var (const struct dictionary *, size_t idx);
278 void dict_get_vars (const struct dictionary *,
279                     struct variable ***vars, size_t *cnt,
280                     unsigned exclude_classes);
281
282 struct variable *dict_create_var (struct dictionary *, const char *,
283                                   int width);
284 struct variable *dict_create_var_assert (struct dictionary *, const char *,
285                                   int width);
286 struct variable *dict_clone_var (struct dictionary *, const struct variable *,
287                                  const char *);
288 void dict_rename_var (struct dictionary *, struct variable *, const char *);
289
290 struct variable *dict_lookup_var (const struct dictionary *, const char *);
291 struct variable *dict_lookup_var_assert (const struct dictionary *,
292                                          const char *);
293 int dict_contains_var (const struct dictionary *, const struct variable *);
294 void dict_delete_var (struct dictionary *, struct variable *);
295 void dict_delete_vars (struct dictionary *,
296                        struct variable *const *, size_t count);
297 void dict_reorder_vars (struct dictionary *,
298                         struct variable *const *, size_t count);
299 int dict_rename_vars (struct dictionary *,
300                       struct variable **, char **new_names,
301                       size_t count, char **err_name);
302
303 struct variable *dict_get_weight (const struct dictionary *);
304 double dict_get_case_weight (const struct dictionary *, const struct ccase *);
305 void dict_set_weight (struct dictionary *, struct variable *);
306
307 struct variable *dict_get_filter (const struct dictionary *);
308 void dict_set_filter (struct dictionary *, struct variable *);
309
310 int dict_get_case_limit (const struct dictionary *);
311 void dict_set_case_limit (struct dictionary *, int);
312
313 int dict_get_next_value_idx (const struct dictionary *);
314 size_t dict_get_case_size (const struct dictionary *);
315
316 void dict_compact_values (struct dictionary *);
317 size_t dict_get_compacted_value_cnt (const struct dictionary *);
318 int *dict_get_compacted_idx_to_fv (const struct dictionary *);
319
320 struct variable *const *dict_get_split_vars (const struct dictionary *);
321 size_t dict_get_split_cnt (const struct dictionary *);
322 void dict_set_split_vars (struct dictionary *,
323                           struct variable *const *, size_t cnt);
324
325 const char *dict_get_label (const struct dictionary *);
326 void dict_set_label (struct dictionary *, const char *);
327
328 const char *dict_get_documents (const struct dictionary *);
329 void dict_set_documents (struct dictionary *, const char *);
330
331 int dict_create_vector (struct dictionary *,
332                         const char *name,
333                         struct variable **, size_t cnt);
334 const struct vector *dict_get_vector (const struct dictionary *,
335                                       size_t idx);
336 size_t dict_get_vector_cnt (const struct dictionary *);
337 const struct vector *dict_lookup_vector (const struct dictionary *,
338                                          const char *name);
339 void dict_clear_vectors (struct dictionary *);
340 \f
341 void discard_variables (void);
342
343 /* This is the active file dictionary. */
344 extern struct dictionary *default_dict;
345 \f
346 /* Transformation state. */
347
348 /* Default file handle for DATA LIST, REREAD, REPEATING DATA
349    commands. */
350 extern struct file_handle *default_handle;
351
352 /* PROCESS IF expression. */
353 extern struct expression *process_if_expr;
354 \f
355 /* TEMPORARY support. */
356
357 /* 1=TEMPORARY has been executed at some point. */
358 extern int temporary;
359
360 /* If temporary!=0, the saved dictionary. */
361 extern struct dictionary *temp_dict;
362
363 /* If temporary!=0, index into t_trns[] (declared far below) that
364    gives the point at which data should be written out.  -1 means that
365    the data shouldn't be changed since all transformations are
366    temporary. */
367 extern int temp_trns;
368
369 /* If FILTER is active, whether it was executed before or after
370    TEMPORARY. */
371 extern int FILTER_before_TEMPORARY;
372
373 void cancel_temporary (void);
374 \f
375 /* Functions. */
376
377 void dump_split_vars (const struct ccase *);
378 typedef int (* is_missing_func )(const union value *, const struct variable *);
379
380 int is_num_user_missing (double, const struct variable *);
381 int is_str_user_missing (const unsigned char[], const struct variable *);
382 int is_missing (const union value *, const struct variable *);
383 int is_system_missing (const union value *, const struct variable *);
384 int is_user_missing (const union value *, const struct variable *);
385 void copy_missing_values (struct variable *dest, const struct variable *src);
386 \f
387 /* Transformations. */
388
389 struct trns_header;
390 typedef int trns_proc_func (struct trns_header *, struct ccase *, int);
391 typedef void trns_free_func (struct trns_header *);
392
393 /* Header for all transformations. */
394 struct trns_header
395   {
396     int index;                  /* Index into t_trns[]. */
397     trns_proc_func *proc;       /* Transformation proc. */
398     trns_free_func *free;       /* Garbage collector proc. */
399   };
400
401 /* Array of transformations */
402 extern struct trns_header **t_trns;
403
404 /* Number of transformations, maximum number in array currently. */
405 extern int n_trns, m_trns;
406
407 /* Index of first transformation that is really a transformation.  Any
408    transformations before this belong to INPUT PROGRAM. */
409 extern int f_trns;
410
411 void add_transformation (struct trns_header *trns);
412 void cancel_transformations (void);
413 \f
414 struct var_set;
415
416 struct var_set *var_set_create_from_dict (struct dictionary *d);
417 struct var_set *var_set_create_from_array (struct variable **var, size_t);
418
419 size_t var_set_get_cnt (struct var_set *vs);
420 struct variable *var_set_get_var (struct var_set *vs, size_t idx);
421 struct variable *var_set_lookup_var (struct var_set *vs, const char *name);
422 void var_set_destroy (struct var_set *vs);
423 \f
424 /* Variable parsers. */
425
426 enum
427   {
428     PV_NONE = 0,                /* No options. */
429     PV_SINGLE = 0001,           /* Restrict to a single name or TO use. */
430     PV_DUPLICATE = 0002,        /* Don't merge duplicates. */
431     PV_APPEND = 0004,           /* Append to existing list. */
432     PV_NO_DUPLICATE = 0010,     /* Error on duplicates. */
433     PV_NUMERIC = 0020,          /* Vars must be numeric. */
434     PV_STRING = 0040,           /* Vars must be string. */
435     PV_SAME_TYPE = 00100,       /* All vars must be the same type. */
436     PV_NO_SCRATCH = 00200       /* Disallow scratch variables. */
437   };
438
439 struct variable *parse_variable (void);
440 struct variable *parse_dict_variable (struct dictionary *);
441 int parse_variables (struct dictionary *, struct variable ***, int *,
442                      int opts);
443 int parse_var_set_vars (struct var_set *, struct variable ***, int *,
444                         int opts);
445 int parse_DATA_LIST_vars (char ***names, int *cnt, int opts);
446 int parse_mixed_vars (char ***names, int *cnt, int opts);
447
448 #endif /* !var_h */