505ae79da395cac5f00de6e57bbcfa91b8fec80e
[pspp-builds.git] / src / data / variable.c
1 /* PSPP - a program for statistical analysis.
2    Copyright (C) 1997-9, 2000, 2006, 2009 Free Software Foundation, Inc.
3
4    This program is free software: you can redistribute it and/or modify
5    it under the terms of the GNU General Public License as published by
6    the Free Software Foundation, either version 3 of the License, or
7    (at your option) any later version.
8
9    This program is distributed in the hope that it will be useful,
10    but WITHOUT ANY WARRANTY; without even the implied warranty of
11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12    GNU General Public License for more details.
13
14    You should have received a copy of the GNU General Public License
15    along with this program.  If not, see <http://www.gnu.org/licenses/>. */
16
17 #include <config.h>
18 #include "variable.h"
19
20 #include <stdlib.h>
21
22 #include <data/attributes.h>
23 #include <data/category.h>
24 #include <data/data-out.h>
25 #include <data/format.h>
26 #include <data/dictionary.h>
27 #include <data/identifier.h>
28 #include <data/missing-values.h>
29 #include <data/value-labels.h>
30 #include <data/vardict.h>
31
32 #include <libpspp/misc.h>
33 #include <libpspp/assertion.h>
34 #include <libpspp/compiler.h>
35 #include <libpspp/hash.h>
36 #include <libpspp/message.h>
37 #include <libpspp/str.h>
38
39 #include "xalloc.h"
40
41 #include "gettext.h"
42 #define _(msgid) gettext (msgid)
43
44 /* A variable. */
45 struct variable
46   {
47     /* Dictionary information. */
48     char name[VAR_NAME_LEN + 1]; /* Variable name.  Mixed case. */
49     int width;                  /* 0 for numeric, otherwise string width. */
50     struct missing_values miss; /* Missing values. */
51     struct fmt_spec print;      /* Default format for PRINT. */
52     struct fmt_spec write;      /* Default format for WRITE. */
53     struct val_labs *val_labs;  /* Value labels. */
54     char *label;                /* Variable label. */
55
56     /* GUI information. */
57     enum measure measure;       /* Nominal, ordinal, or continuous. */
58     int display_width;          /* Width of data editor column. */
59     enum alignment alignment;   /* Alignment of data in GUI. */
60
61     /* Case information. */
62     bool leave;                 /* Leave value from case to case? */
63
64     /* Data for use by containing dictionary. */
65     struct vardict_info vardict;
66
67     /* Used only for system and portable file input and output.
68        See short-names.h. */
69     char **short_names;
70     size_t short_name_cnt;
71
72     /* Each command may use these fields as needed. */
73     void *aux;
74     void (*aux_dtor) (struct variable *);
75
76     /* Values of a categorical variable.  Procedures need
77        vectors with binary entries, so any variable of type ALPHA will
78        have its values stored here. */
79     struct cat_vals *obs_vals;
80
81     /* Custom attributes. */
82     struct attrset attributes;
83   };
84 \f
85 /* Creates and returns a new variable with the given NAME and
86    WIDTH and other fields initialized to default values.  The
87    variable is not added to a dictionary; for that, use
88    dict_create_var instead. */
89 struct variable *
90 var_create (const char *name, int width)
91 {
92   struct variable *v;
93   enum val_type type;
94
95   assert (width >= 0 && width <= MAX_STRING);
96
97   v = xmalloc (sizeof *v);
98   v->vardict.dict_index = v->vardict.case_index = -1;
99   var_set_name (v, name);
100   v->width = width;
101   mv_init (&v->miss, width);
102   v->leave = var_must_leave (v);
103   type = val_type_from_width (width);
104   v->alignment = var_default_alignment (type);
105   v->measure = var_default_measure (type);
106   v->display_width = var_default_display_width (width);
107   v->print = v->write = var_default_formats (width);
108   v->val_labs = NULL;
109   v->label = NULL;
110   v->short_names = NULL;
111   v->short_name_cnt = 0;
112   v->aux = NULL;
113   v->aux_dtor = NULL;
114   v->obs_vals = NULL;
115   attrset_init (&v->attributes);
116
117   return v;
118 }
119
120 /* Creates and returns a clone of OLD_VAR.  Most properties of
121    the new variable are copied from OLD_VAR, except:
122
123     - The variable's short name is not copied, because there is
124       no reason to give a new variable with potentially a new
125       name the same short name.
126
127     - The new variable is not added to OLD_VAR's dictionary by
128       default.  Use dict_clone_var, instead, to do that.
129
130     - Auxiliary data and obs_vals are not copied. */
131 struct variable *
132 var_clone (const struct variable *old_var)
133 {
134   struct variable *new_var = var_create (var_get_name (old_var),
135                                          var_get_width (old_var));
136
137   var_set_missing_values (new_var, var_get_missing_values (old_var));
138   var_set_print_format (new_var, var_get_print_format (old_var));
139   var_set_write_format (new_var, var_get_write_format (old_var));
140   var_set_value_labels (new_var, var_get_value_labels (old_var));
141   var_set_label (new_var, var_get_label (old_var));
142   var_set_measure (new_var, var_get_measure (old_var));
143   var_set_display_width (new_var, var_get_display_width (old_var));
144   var_set_alignment (new_var, var_get_alignment (old_var));
145   var_set_leave (new_var, var_get_leave (old_var));
146   var_set_attributes (new_var, var_get_attributes (old_var));
147
148   return new_var;
149 }
150
151 /* Create a variable to be used for internal calculations only.
152    The variable is assigned a unique dictionary index and a case
153    index of CASE_IDX. */
154 struct variable *
155 var_create_internal (int case_idx)
156 {
157   struct variable *v = var_create ("$internal", 0);
158   struct vardict_info vdi;
159   static int counter = INT_MAX / 2;
160
161   vdi.dict = NULL;
162   vdi.case_index = case_idx;
163   vdi.dict_index = counter++;
164   if (counter == INT_MAX)
165     counter = INT_MAX / 2;
166
167   var_set_vardict (v, &vdi);
168
169   return v;
170 }
171
172 /* Destroys variable V.
173    V must not belong to a dictionary.  If it does, use
174    dict_delete_var instead. */
175 void
176 var_destroy (struct variable *v)
177 {
178   if (v != NULL)
179     {
180       if (var_has_vardict (v))
181         {
182           const struct vardict_info *vdi = var_get_vardict (v);
183           assert (vdi->dict == NULL);
184         }
185       cat_stored_values_destroy (v->obs_vals);
186       var_clear_short_names (v);
187       var_clear_aux (v);
188       val_labs_destroy (v->val_labs);
189       var_clear_label (v);
190       free (v);
191     }
192 }
193 \f
194 /* Variable names. */
195
196 /* Return variable V's name. */
197 const char *
198 var_get_name (const struct variable *v)
199 {
200   return v->name;
201 }
202
203 /* Sets V's name to NAME.
204    Do not use this function for a variable in a dictionary.  Use
205    dict_rename_var instead. */
206 void
207 var_set_name (struct variable *v, const char *name)
208 {
209   assert (v->vardict.dict_index == -1);
210   assert (var_is_plausible_name (name, false));
211
212   str_copy_trunc (v->name, sizeof v->name, name);
213   dict_var_changed (v);
214 }
215
216 /* Returns true if NAME is an acceptable name for a variable,
217    false otherwise.  If ISSUE_ERROR is true, issues an
218    explanatory error message on failure. */
219 bool
220 var_is_valid_name (const char *name, bool issue_error)
221 {
222   bool plausible;
223   size_t length, i;
224
225   assert (name != NULL);
226
227   /* Note that strlen returns number of BYTES, not the number of
228      CHARACTERS */
229   length = strlen (name);
230
231   plausible = var_is_plausible_name(name, issue_error);
232
233   if ( ! plausible )
234     return false;
235
236
237   if (!lex_is_id1 (name[0]))
238     {
239       if (issue_error)
240         msg (SE, _("Character `%c' (in %s) may not appear "
241                    "as the first character in a variable name."),
242              name[0], name);
243       return false;
244     }
245
246
247   for (i = 0; i < length; i++)
248     {
249     if (!lex_is_idn (name[i]))
250       {
251         if (issue_error)
252           msg (SE, _("Character `%c' (in %s) may not appear in "
253                      "a variable name."),
254                name[i], name);
255         return false;
256       }
257     }
258
259   return true;
260 }
261
262 /* Returns true if NAME is an plausible name for a variable,
263    false otherwise.  If ISSUE_ERROR is true, issues an
264    explanatory error message on failure.
265    This function makes no use of LC_CTYPE.
266 */
267 bool
268 var_is_plausible_name (const char *name, bool issue_error)
269 {
270   size_t length;
271
272   assert (name != NULL);
273
274   /* Note that strlen returns number of BYTES, not the number of
275      CHARACTERS */
276   length = strlen (name);
277   if (length < 1)
278     {
279       if (issue_error)
280         msg (SE, _("Variable name cannot be empty string."));
281       return false;
282     }
283   else if (length > VAR_NAME_LEN)
284     {
285       if (issue_error)
286         msg (SE, _("Variable name %s exceeds %d-character limit."),
287              name, (int) VAR_NAME_LEN);
288       return false;
289     }
290
291   if (lex_id_to_token (ss_cstr (name)) != T_ID)
292     {
293       if (issue_error)
294         msg (SE, _("`%s' may not be used as a variable name because it "
295                    "is a reserved word."), name);
296       return false;
297     }
298
299   return true;
300 }
301
302 /* Returns VAR's dictionary class. */
303 enum dict_class
304 var_get_dict_class (const struct variable *var)
305 {
306   return dict_class_from_id (var->name);
307 }
308
309 /* A hsh_compare_func that orders variables A and B by their
310    names. */
311 int
312 compare_vars_by_name (const void *a_, const void *b_, const void *aux UNUSED)
313 {
314   const struct variable *a = a_;
315   const struct variable *b = b_;
316
317   return strcasecmp (a->name, b->name);
318 }
319
320 /* A hsh_hash_func that hashes variable V based on its name. */
321 unsigned
322 hash_var_by_name (const void *v_, const void *aux UNUSED)
323 {
324   const struct variable *v = v_;
325
326   return hash_case_string (v->name, 0);
327 }
328
329 /* A hsh_compare_func that orders pointers to variables A and B
330    by their names. */
331 int
332 compare_var_ptrs_by_name (const void *a_, const void *b_,
333                           const void *aux UNUSED)
334 {
335   struct variable *const *a = a_;
336   struct variable *const *b = b_;
337
338   return strcasecmp (var_get_name (*a), var_get_name (*b));
339 }
340
341 /* A hsh_compare_func that orders pointers to variables A and B
342    by their dictionary indexes. */
343 int
344 compare_var_ptrs_by_dict_index (const void *a_, const void *b_,
345                                 const void *aux UNUSED)
346 {
347   struct variable *const *a = a_;
348   struct variable *const *b = b_;
349   size_t a_index = var_get_dict_index (*a);
350   size_t b_index = var_get_dict_index (*b);
351
352   return a_index < b_index ? -1 : a_index > b_index;
353 }
354
355 /* A hsh_hash_func that hashes pointer to variable V based on its
356    name. */
357 unsigned
358 hash_var_ptr_by_name (const void *v_, const void *aux UNUSED)
359 {
360   struct variable *const *v = v_;
361
362   return hash_case_string (var_get_name (*v), 0);
363 }
364 \f
365 /* Returns the type of variable V. */
366 enum val_type
367 var_get_type (const struct variable *v)
368 {
369   return val_type_from_width (v->width);
370 }
371
372 /* Returns the width of variable V. */
373 int
374 var_get_width (const struct variable *v)
375 {
376   return v->width;
377 }
378
379 /* Changes the width of V to NEW_WIDTH.
380    This function should be used cautiously. */
381 void
382 var_set_width (struct variable *v, int new_width)
383 {
384   const int old_width = v->width;
385
386   if (mv_is_resizable (&v->miss, new_width))
387     mv_resize (&v->miss, new_width);
388   else
389     mv_init (&v->miss, new_width);
390
391   if (v->val_labs != NULL)
392     {
393       if (val_labs_can_set_width (v->val_labs, new_width))
394         val_labs_set_width (v->val_labs, new_width);
395       else
396         {
397           val_labs_destroy (v->val_labs);
398           v->val_labs = NULL;
399         }
400     }
401
402   fmt_resize (&v->print, new_width);
403   fmt_resize (&v->write, new_width);
404
405   v->width = new_width;
406
407   {
408     const int old_val_count = value_cnt_from_width (old_width);
409     const int new_val_count = value_cnt_from_width (new_width);
410
411     if ( old_val_count != new_val_count)
412          dict_var_resized (v, new_val_count - old_val_count);
413   }
414
415   dict_var_changed (v);
416 }
417
418 /* Returns true if variable V is numeric, false otherwise. */
419 bool
420 var_is_numeric (const struct variable *v)
421 {
422   return var_get_type (v) == VAL_NUMERIC;
423 }
424
425 /* Returns true if variable V is a string variable, false
426    otherwise. */
427 bool
428 var_is_alpha (const struct variable *v)
429 {
430   return var_get_type (v) == VAL_STRING;
431 }
432
433 /* Returns true if variable V is a short string variable, false
434    otherwise. */
435 bool
436 var_is_short_string (const struct variable *v)
437 {
438   return v->width > 0 && v->width <= MAX_SHORT_STRING;
439 }
440
441 /* Returns true if variable V is a long string variable, false
442    otherwise. */
443 bool
444 var_is_long_string (const struct variable *v)
445 {
446   return v->width > MAX_SHORT_STRING;
447 }
448
449 /* Returns the number of "union value"s need to store a value of
450    variable V. */
451 size_t
452 var_get_value_cnt (const struct variable *v)
453 {
454   return value_cnt_from_width (v->width);
455 }
456 \f
457 /* Returns variable V's missing values. */
458 const struct missing_values *
459 var_get_missing_values (const struct variable *v)
460 {
461   return &v->miss;
462 }
463
464 /* Sets variable V's missing values to MISS, which must be of V's
465    width or at least resizable to V's width.
466    If MISS is null, then V's missing values, if any, are
467    cleared. */
468 void
469 var_set_missing_values (struct variable *v, const struct missing_values *miss)
470 {
471   if (miss != NULL)
472     {
473       assert (mv_is_resizable (miss, v->width));
474       mv_copy (&v->miss, miss);
475       mv_resize (&v->miss, v->width);
476     }
477   else
478     mv_init (&v->miss, v->width);
479
480   dict_var_changed (v);
481 }
482
483 /* Sets variable V to have no user-missing values. */
484 void
485 var_clear_missing_values (struct variable *v)
486 {
487   var_set_missing_values (v, NULL);
488 }
489
490 /* Returns true if V has any user-missing values,
491    false otherwise. */
492 bool
493 var_has_missing_values (const struct variable *v)
494 {
495   return !mv_is_empty (&v->miss);
496 }
497
498 /* Returns true if VALUE is in the given CLASS of missing values
499    in V, false otherwise. */
500 bool
501 var_is_value_missing (const struct variable *v, const union value *value,
502                       enum mv_class class)
503 {
504   return mv_is_value_missing (&v->miss, value, class);
505 }
506
507 /* Returns true if D is in the given CLASS of missing values in
508    V, false otherwise.
509    V must be a numeric variable. */
510 bool
511 var_is_num_missing (const struct variable *v, double d, enum mv_class class)
512 {
513   return mv_is_num_missing (&v->miss, d, class);
514 }
515
516 /* Returns true if S[] is a missing value for V, false otherwise.
517    S[] must contain exactly as many characters as V's width.
518    V must be a string variable. */
519 bool
520 var_is_str_missing (const struct variable *v, const char s[],
521                     enum mv_class class)
522 {
523   return mv_is_str_missing (&v->miss, s, class);
524 }
525 \f
526 /* Returns variable V's value labels,
527    possibly a null pointer if it has none. */
528 const struct val_labs *
529 var_get_value_labels (const struct variable *v)
530 {
531   return v->val_labs;
532 }
533
534 /* Returns true if variable V has at least one value label. */
535 bool
536 var_has_value_labels (const struct variable *v)
537 {
538   return val_labs_count (v->val_labs) > 0;
539 }
540
541 /* Sets variable V's value labels to a copy of VLS,
542    which must have a width equal to V's width or one that can be
543    changed to V's width.
544    If VLS is null, then V's value labels, if any, are removed. */
545 void
546 var_set_value_labels (struct variable *v, const struct val_labs *vls)
547 {
548   val_labs_destroy (v->val_labs);
549   v->val_labs = NULL;
550
551   if (vls != NULL)
552     {
553       assert (val_labs_can_set_width (vls, v->width));
554       v->val_labs = val_labs_clone (vls);
555       val_labs_set_width (v->val_labs, v->width);
556       dict_var_changed (v);
557     }
558 }
559
560 /* Makes sure that V has a set of value labels,
561    by assigning one to it if necessary. */
562 static void
563 alloc_value_labels (struct variable *v)
564 {
565   assert (!var_is_long_string (v));
566   if (v->val_labs == NULL)
567     v->val_labs = val_labs_create (v->width);
568 }
569
570 /* Attempts to add a value label with the given VALUE and LABEL
571    to V.  Returns true if successful, false if VALUE has an
572    existing label or if V is a long string variable. */
573 bool
574 var_add_value_label (struct variable *v,
575                      const union value *value, const char *label)
576 {
577   alloc_value_labels (v);
578   return val_labs_add (v->val_labs, *value, label);
579 }
580
581 /* Adds or replaces a value label with the given VALUE and LABEL
582    to V.
583    Has no effect if V is a long string variable. */
584 void
585 var_replace_value_label (struct variable *v,
586                          const union value *value, const char *label)
587 {
588   alloc_value_labels (v);
589   val_labs_replace (v->val_labs, *value, label);
590 }
591
592 /* Removes V's value labels, if any. */
593 void
594 var_clear_value_labels (struct variable *v)
595 {
596   var_set_value_labels (v, NULL);
597 }
598
599 /* Returns the label associated with VALUE for variable V,
600    or a null pointer if none. */
601 const char *
602 var_lookup_value_label (const struct variable *v, const union value *value)
603 {
604   return val_labs_find (v->val_labs, *value);
605 }
606
607 /* Append STR with a string representing VALUE for variable V.
608    That is, if VALUE has a label, append that label,
609    otherwise format VALUE and append the formatted string.
610    STR must be a pointer to an initialised struct string.
611 */
612 void
613 var_append_value_name (const struct variable *v, const union value *value,
614                        struct string *str)
615 {
616   const char *name = var_lookup_value_label (v, value);
617   if (name == NULL)
618     {
619       char *s = ds_put_uninit (str, v->print.w);
620       data_out (value, &v->print, s);
621     }
622   else
623     ds_put_cstr (str, name);
624 }
625 \f
626 /* Print and write formats. */
627
628 /* Returns V's print format specification. */
629 const struct fmt_spec *
630 var_get_print_format (const struct variable *v)
631 {
632   return &v->print;
633 }
634
635 /* Sets V's print format specification to PRINT, which must be a
636    valid format specification for a variable of V's width
637    (ordinarily an output format, but input formats are not
638    rejected). */
639 void
640 var_set_print_format (struct variable *v, const struct fmt_spec *print)
641 {
642   assert (fmt_check_width_compat (print, v->width));
643   v->print = *print;
644   dict_var_changed (v);
645 }
646
647 /* Returns V's write format specification. */
648 const struct fmt_spec *
649 var_get_write_format (const struct variable *v)
650 {
651   return &v->write;
652 }
653
654 /* Sets V's write format specification to WRITE, which must be a
655    valid format specification for a variable of V's width
656    (ordinarily an output format, but input formats are not
657    rejected). */
658 void
659 var_set_write_format (struct variable *v, const struct fmt_spec *write)
660 {
661   assert (fmt_check_width_compat (write, v->width));
662   v->write = *write;
663   dict_var_changed (v);
664 }
665
666 /* Sets V's print and write format specifications to FORMAT,
667    which must be a valid format specification for a variable of
668    V's width (ordinarily an output format, but input formats are
669    not rejected). */
670 void
671 var_set_both_formats (struct variable *v, const struct fmt_spec *format)
672 {
673   var_set_print_format (v, format);
674   var_set_write_format (v, format);
675 }
676
677 /* Returns the default print and write format for a variable of
678    the given TYPE, as set by var_create.  The return value can be
679    used to reset a variable's print and write formats to the
680    default. */
681 struct fmt_spec
682 var_default_formats (int width)
683 {
684   return (width == 0
685           ? fmt_for_output (FMT_F, 8, 2)
686           : fmt_for_output (FMT_A, width, 0));
687 }
688 \f
689 /* Return a string representing this variable, in the form most
690    appropriate from a human factors perspective, that is, its
691    variable label if it has one, otherwise its name. */
692 const char *
693 var_to_string (const struct variable *v)
694 {
695   return v->label != NULL ? v->label : v->name;
696 }
697
698 /* Returns V's variable label, or a null pointer if it has none. */
699 const char *
700 var_get_label (const struct variable *v)
701 {
702   return v->label;
703 }
704
705 /* Sets V's variable label to LABEL, stripping off leading and
706    trailing white space and truncating to 255 characters.
707    If LABEL is a null pointer or if LABEL is an empty string
708    (after stripping white space), then V's variable label (if
709    any) is removed. */
710 void
711 var_set_label (struct variable *v, const char *label)
712 {
713   free (v->label);
714   v->label = NULL;
715
716   if (label != NULL)
717     {
718       struct substring s = ss_cstr (label);
719       ss_trim (&s, ss_cstr (CC_SPACES));
720       ss_truncate (&s, 255);
721       if (!ss_is_empty (s))
722         v->label = ss_xstrdup (s);
723     }
724   dict_var_changed (v);
725 }
726
727 /* Removes any variable label from V. */
728 void
729 var_clear_label (struct variable *v)
730 {
731   var_set_label (v, NULL);
732 }
733
734 /* Returns true if V has a variable V,
735    false otherwise. */
736 bool
737 var_has_label (const struct variable *v)
738 {
739   return v->label != NULL;
740 }
741 \f
742 /* Returns true if M is a valid variable measurement level,
743    false otherwise. */
744 bool
745 measure_is_valid (enum measure m)
746 {
747   return m == MEASURE_NOMINAL || m == MEASURE_ORDINAL || m == MEASURE_SCALE;
748 }
749
750 /* Returns V's measurement level. */
751 enum measure
752 var_get_measure (const struct variable *v)
753 {
754   return v->measure;
755 }
756
757 /* Sets V's measurement level to MEASURE. */
758 void
759 var_set_measure (struct variable *v, enum measure measure)
760 {
761   assert (measure_is_valid (measure));
762   v->measure = measure;
763   dict_var_changed (v);
764 }
765
766 /* Returns the default measurement level for a variable of the
767    given TYPE, as set by var_create.  The return value can be
768    used to reset a variable's measurement level to the
769    default. */
770 enum measure
771 var_default_measure (enum val_type type)
772 {
773   return type == VAL_NUMERIC ? MEASURE_SCALE : MEASURE_NOMINAL;
774 }
775 \f
776 /* Returns V's display width, which applies only to GUIs. */
777 int
778 var_get_display_width (const struct variable *v)
779 {
780   return v->display_width;
781 }
782
783 /* Sets V's display width to DISPLAY_WIDTH. */
784 void
785 var_set_display_width (struct variable *v, int new_width)
786 {
787   int old_width = v->display_width;
788
789   v->display_width = new_width;
790
791   if ( old_width != new_width)
792     dict_var_display_width_changed (v);
793
794   dict_var_changed (v);
795 }
796
797 /* Returns the default display width for a variable of the given
798    WIDTH, as set by var_create.  The return value can be used to
799    reset a variable's display width to the default. */
800 int
801 var_default_display_width (int width)
802 {
803   return width == 0 ? 8 : MIN (width, 32);
804 }
805 \f
806 /* Returns true if A is a valid alignment,
807    false otherwise. */
808 bool
809 alignment_is_valid (enum alignment a)
810 {
811   return a == ALIGN_LEFT || a == ALIGN_RIGHT || a == ALIGN_CENTRE;
812 }
813
814 /* Returns V's display alignment, which applies only to GUIs. */
815 enum alignment
816 var_get_alignment (const struct variable *v)
817 {
818   return v->alignment;
819 }
820
821 /* Sets V's display alignment to ALIGNMENT. */
822 void
823 var_set_alignment (struct variable *v, enum alignment alignment)
824 {
825   assert (alignment_is_valid (alignment));
826   v->alignment = alignment;
827   dict_var_changed (v);
828 }
829
830 /* Returns the default display alignment for a variable of the
831    given TYPE, as set by var_create.  The return value can be
832    used to reset a variable's display alignment to the default. */
833 enum alignment
834 var_default_alignment (enum val_type type)
835 {
836   return type == VAL_NUMERIC ? ALIGN_RIGHT : ALIGN_LEFT;
837 }
838 \f
839 /* Whether variables' values should be preserved from case to
840    case. */
841
842 /* Returns true if variable V's value should be left from case to
843    case, instead of being reset to system-missing or blanks. */
844 bool
845 var_get_leave (const struct variable *v)
846 {
847   return v->leave;
848 }
849
850 /* Sets V's leave setting to LEAVE. */
851 void
852 var_set_leave (struct variable *v, bool leave)
853 {
854   assert (leave || !var_must_leave (v));
855   v->leave = leave;
856   dict_var_changed (v);
857 }
858
859 /* Returns true if V must be left from case to case,
860    false if it can be set either way. */
861 bool
862 var_must_leave (const struct variable *v)
863 {
864   return var_get_dict_class (v) == DC_SCRATCH;
865 }
866 \f
867 /* Returns the number of short names stored in VAR.
868
869    Short names are used only for system and portable file input
870    and output.  They are upper-case only, not necessarily unique,
871    and limited to SHORT_NAME_LEN characters (plus a null
872    terminator).  Ordinarily a variable has at most one short
873    name, but very long string variables (longer than 255 bytes)
874    may have more.  A variable might not have any short name at
875    all if it hasn't been saved to or read from a system or
876    portable file. */
877 size_t
878 var_get_short_name_cnt (const struct variable *var) 
879 {
880   return var->short_name_cnt;
881 }
882
883 /* Returns VAR's short name with the given IDX, if it has one
884    with that index, or a null pointer otherwise.  Short names may
885    be sparse: even if IDX is less than the number of short names
886    in VAR, this function may return a null pointer. */
887 const char *
888 var_get_short_name (const struct variable *var, size_t idx)
889 {
890   return idx < var->short_name_cnt ? var->short_names[idx] : NULL;
891 }
892
893 /* Sets VAR's short name with the given IDX to SHORT_NAME,
894    truncating it to SHORT_NAME_LEN characters and converting it
895    to uppercase in the process.  Specifying a null pointer for
896    SHORT_NAME clears the specified short name. */
897 void
898 var_set_short_name (struct variable *var, size_t idx, const char *short_name)
899 {
900   assert (var != NULL);
901   assert (short_name == NULL || var_is_plausible_name (short_name, false));
902
903   /* Clear old short name numbered IDX, if any. */
904   if (idx < var->short_name_cnt) 
905     {
906       free (var->short_names[idx]);
907       var->short_names[idx] = NULL; 
908     }
909
910   /* Install new short name for IDX. */
911   if (short_name != NULL) 
912     {
913       if (idx >= var->short_name_cnt)
914         {
915           size_t old_cnt = var->short_name_cnt;
916           size_t i;
917           var->short_name_cnt = MAX (idx * 2, 1);
918           var->short_names = xnrealloc (var->short_names, var->short_name_cnt,
919                                         sizeof *var->short_names);
920           for (i = old_cnt; i < var->short_name_cnt; i++)
921             var->short_names[i] = NULL;
922         }
923       var->short_names[idx] = xstrndup (short_name, MAX_SHORT_STRING);
924       str_uppercase (var->short_names[idx]);
925     }
926
927   dict_var_changed (var);
928 }
929
930 /* Clears V's short names. */
931 void
932 var_clear_short_names (struct variable *v)
933 {
934   size_t i;
935
936   for (i = 0; i < v->short_name_cnt; i++)
937     free (v->short_names[i]);
938   free (v->short_names);
939   v->short_names = NULL;
940   v->short_name_cnt = 0;
941 }
942 \f
943 /* Relationship with dictionary. */
944
945 /* Returns V's index within its dictionary, the value
946    for which "dict_get_var (dict, index)" will return V.
947    V must be in a dictionary. */
948 size_t
949 var_get_dict_index (const struct variable *v)
950 {
951   assert (v->vardict.dict_index != -1);
952   return v->vardict.dict_index;
953 }
954
955 /* Returns V's index within the case represented by its
956    dictionary, that is, the value for which "case_data_idx (case,
957    index)" will return the data for V in that case.
958    V must be in a dictionary. */
959 size_t
960 var_get_case_index (const struct variable *v)
961 {
962   assert (v->vardict.case_index != -1);
963   return v->vardict.case_index;
964 }
965 \f
966 /* Returns V's auxiliary data, or a null pointer if none has been
967    attached. */
968 void *
969 var_get_aux (const struct variable *v)
970 {
971   return v->aux;
972 }
973
974 /* Assign auxiliary data AUX to variable V, which must not
975    already have auxiliary data.  Before V's auxiliary data is
976    cleared, AUX_DTOR(V) will be called.  (var_dtor_free, below,
977    may be appropriate for use as AUX_DTOR.) */
978 void *
979 var_attach_aux (const struct variable *v_,
980                 void *aux, void (*aux_dtor) (struct variable *))
981 {
982   struct variable *v = (struct variable *) v_ ; /* cast away const  */
983   assert (v->aux == NULL);
984   assert (aux != NULL);
985   v->aux = aux;
986   v->aux_dtor = aux_dtor;
987   return aux;
988 }
989
990 /* Remove auxiliary data, if any, from V, and return it, without
991    calling any associated destructor. */
992 void *
993 var_detach_aux (struct variable *v)
994 {
995   void *aux = v->aux;
996   assert (aux != NULL);
997   v->aux = NULL;
998   return aux;
999 }
1000
1001 /* Clears auxiliary data, if any, from V, and calls any
1002    associated destructor. */
1003 void
1004 var_clear_aux (struct variable *v)
1005 {
1006   assert (v != NULL);
1007   if (v->aux != NULL)
1008     {
1009       if (v->aux_dtor != NULL)
1010         v->aux_dtor (v);
1011       v->aux = NULL;
1012     }
1013 }
1014
1015 /* This function is appropriate for use an auxiliary data
1016    destructor (passed as AUX_DTOR to var_attach_aux()) for the
1017    case where the auxiliary data should be passed to free(). */
1018 void
1019 var_dtor_free (struct variable *v)
1020 {
1021   free (v->aux);
1022 }
1023 \f
1024 /* Observed categorical values. */
1025
1026 /* Returns V's observed categorical values,
1027    which V must have. */
1028 struct cat_vals *
1029 var_get_obs_vals (const struct variable *v)
1030 {
1031   assert (v->obs_vals != NULL);
1032   return v->obs_vals;
1033 }
1034
1035 /* Sets V's observed categorical values to CAT_VALS.
1036    V becomes the owner of CAT_VALS. */
1037 void
1038 var_set_obs_vals (const struct variable *v_, struct cat_vals *cat_vals)
1039 {
1040   struct variable *v = (struct variable *) v_ ; /* cast away const */
1041   cat_stored_values_destroy (v->obs_vals);
1042   v->obs_vals = cat_vals;
1043 }
1044
1045 /* Returns true if V has observed categorical values,
1046    false otherwise. */
1047 bool
1048 var_has_obs_vals (const struct variable *v)
1049 {
1050   return v->obs_vals != NULL;
1051 }
1052 \f
1053 /* Returns variable V's attribute set.  The caller may examine or
1054    modify the attribute set, but must not destroy it.  Destroying
1055    V, or calling var_set_attributes() on V, will also destroy its
1056    attribute set. */
1057 struct attrset *
1058 var_get_attributes (const struct variable *v) 
1059 {
1060   return (struct attrset *) &v->attributes;
1061 }
1062
1063 /* Replaces variable V's attributes set by a copy of ATTRS. */
1064 void
1065 var_set_attributes (struct variable *v, const struct attrset *attrs) 
1066 {
1067   attrset_destroy (&v->attributes);
1068   attrset_clone (&v->attributes, attrs);
1069 }
1070
1071 /* Returns true if V has any custom attributes, false if it has none. */
1072 bool
1073 var_has_attributes (const struct variable *v)
1074 {
1075   return attrset_count (&v->attributes) > 0;
1076 }
1077 \f
1078 /* Returns V's vardict structure. */
1079 const struct vardict_info *
1080 var_get_vardict (const struct variable *v)
1081 {
1082   assert (var_has_vardict (v));
1083   return &v->vardict;
1084 }
1085
1086 /* Sets V's vardict data to VARDICT. */
1087 void
1088 var_set_vardict (struct variable *v, const struct vardict_info *vardict)
1089 {
1090   assert (vardict->dict_index >= 0);
1091   assert (vardict->case_index >= 0);
1092   v->vardict = *vardict;
1093 }
1094
1095 /* Returns true if V has vardict data. */
1096 bool
1097 var_has_vardict (const struct variable *v)
1098 {
1099   return v->vardict.dict_index != -1;
1100 }
1101
1102 /* Clears V's vardict data. */
1103 void
1104 var_clear_vardict (struct variable *v)
1105 {
1106   v->vardict.dict_index = v->vardict.case_index = -1;
1107 }