CORRELATIONS: Fixed bug displaying non-sqaure correlation matrices
[pspp] / src / data / variable.c
1 /* PSPP - a program for statistical analysis.
2    Copyright (C) 1997-9, 2000, 2006, 2009, 2010, 2011 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
19 #include "data/variable.h"
20
21 #include <stdlib.h>
22
23 #include "data/attributes.h"
24 #include "data/data-out.h"
25 #include "data/dictionary.h"
26 #include "data/format.h"
27 #include "data/identifier.h"
28 #include "data/missing-values.h"
29 #include "data/settings.h"
30 #include "data/value-labels.h"
31 #include "data/vardict.h"
32 #include "libpspp/assertion.h"
33 #include "libpspp/compiler.h"
34 #include "libpspp/hash-functions.h"
35 #include "libpspp/i18n.h"
36 #include "libpspp/message.h"
37 #include "libpspp/misc.h"
38 #include "libpspp/str.h"
39
40 #include "gl/minmax.h"
41 #include "gl/xalloc.h"
42
43 #include "gettext.h"
44 #define _(msgid) gettext (msgid)
45
46 /* A variable. */
47 struct variable
48   {
49     /* Dictionary information. */
50     char *name;                 /* Variable name.  Mixed case. */
51     int width;                  /* 0 for numeric, otherwise string width. */
52     struct missing_values miss; /* Missing values. */
53     struct fmt_spec print;      /* Default format for PRINT. */
54     struct fmt_spec write;      /* Default format for WRITE. */
55     struct val_labs *val_labs;  /* Value labels. */
56     char *label;                /* Variable label. */
57     struct string name_and_label; /* The name and label in the same string */
58
59     /* GUI information. */
60     enum measure measure;       /* Nominal, ordinal, or continuous. */
61     int display_width;          /* Width of data editor column. */
62     enum alignment alignment;   /* Alignment of data in GUI. */
63
64     /* Case information. */
65     bool leave;                 /* Leave value from case to case? */
66
67     /* Data for use by containing dictionary. */
68     struct vardict_info *vardict;
69
70     /* Used only for system and portable file input and output.
71        See short-names.h. */
72     char **short_names;
73     size_t short_name_cnt;
74
75     /* Each command may use these fields as needed. */
76     void *aux;
77     void (*aux_dtor) (struct variable *);
78
79     /* Custom attributes. */
80     struct attrset attributes;
81   };
82 \f
83 /* Creates and returns a new variable with the given NAME and
84    WIDTH and other fields initialized to default values.  The
85    variable is not added to a dictionary; for that, use
86    dict_create_var instead. */
87 struct variable *
88 var_create (const char *name, int width)
89 {
90   struct variable *v;
91   enum val_type type;
92
93   assert (width >= 0 && width <= MAX_STRING);
94
95   v = xzalloc (sizeof *v);
96   var_set_name (v, name);
97   v->width = width;
98   mv_init (&v->miss, width);
99   v->leave = var_must_leave (v);
100   type = val_type_from_width (width);
101   v->alignment = var_default_alignment (type);
102   v->measure = var_default_measure (type);
103   v->display_width = var_default_display_width (width);
104   v->print = v->write = var_default_formats (width);
105   attrset_init (&v->attributes);
106   ds_init_empty (&v->name_and_label);
107
108   return v;
109 }
110
111 /* Creates and returns a clone of OLD_VAR.  Most properties of
112    the new variable are copied from OLD_VAR, except:
113
114     - The variable's short name is not copied, because there is
115       no reason to give a new variable with potentially a new
116       name the same short name.
117
118     - The new variable is not added to OLD_VAR's dictionary by
119       default.  Use dict_clone_var, instead, to do that.
120 */
121 struct variable *
122 var_clone (const struct variable *old_var)
123 {
124   struct variable *new_var = var_create (var_get_name (old_var),
125                                          var_get_width (old_var));
126
127   var_set_missing_values (new_var, var_get_missing_values (old_var));
128   var_set_print_format (new_var, var_get_print_format (old_var));
129   var_set_write_format (new_var, var_get_write_format (old_var));
130   var_set_value_labels (new_var, var_get_value_labels (old_var));
131   var_set_label (new_var, var_get_label (old_var), false);
132   var_set_measure (new_var, var_get_measure (old_var));
133   var_set_display_width (new_var, var_get_display_width (old_var));
134   var_set_alignment (new_var, var_get_alignment (old_var));
135   var_set_leave (new_var, var_get_leave (old_var));
136   var_set_attributes (new_var, var_get_attributes (old_var));
137
138   return new_var;
139 }
140
141 /* Destroys variable V.
142    V must not belong to a dictionary.  If it does, use
143    dict_delete_var instead. */
144 void
145 var_destroy (struct variable *v)
146 {
147   if (v != NULL)
148     {
149       assert (!var_has_vardict (v));
150       mv_destroy (&v->miss);
151       var_clear_short_names (v);
152       var_clear_aux (v);
153       val_labs_destroy (v->val_labs);
154       var_clear_label (v);
155       attrset_destroy (var_get_attributes (v));
156       free (v->name);
157       ds_destroy (&v->name_and_label);
158       free (v);
159     }
160 }
161 \f
162 /* Variable names. */
163
164 /* Return variable V's name, as a UTF-8 encoded string. */
165 const char *
166 var_get_name (const struct variable *v)
167 {
168   return v->name;
169 }
170
171
172
173 /* Sets V's name to NAME, a UTF-8 encoded string.
174    Do not use this function for a variable in a dictionary.  Use
175    dict_rename_var instead. */
176 void
177 var_set_name (struct variable *v, const char *name)
178 {
179   assert (!var_has_vardict (v));
180   assert (id_is_plausible (name, false));
181
182   free (v->name);
183   v->name = xstrdup (name);
184   ds_destroy (&v->name_and_label);
185   ds_init_empty (&v->name_and_label);
186   dict_var_changed (v);
187 }
188
189 /* Returns VAR's dictionary class. */
190 enum dict_class
191 var_get_dict_class (const struct variable *var)
192 {
193   return dict_class_from_id (var->name);
194 }
195
196 /* A hsh_compare_func that orders variables A and B by their
197    names. */
198 int
199 compare_vars_by_name (const void *a_, const void *b_, const void *aux UNUSED)
200 {
201   const struct variable *a = a_;
202   const struct variable *b = b_;
203
204   return strcasecmp (a->name, b->name);
205 }
206
207 /* A hsh_hash_func that hashes variable V based on its name. */
208 unsigned
209 hash_var_by_name (const void *v_, const void *aux UNUSED)
210 {
211   const struct variable *v = v_;
212
213   return hash_case_string (v->name, 0);
214 }
215
216 /* A hsh_compare_func that orders pointers to variables A and B
217    by their names. */
218 int
219 compare_var_ptrs_by_name (const void *a_, const void *b_,
220                           const void *aux UNUSED)
221 {
222   struct variable *const *a = a_;
223   struct variable *const *b = b_;
224
225   return strcasecmp (var_get_name (*a), var_get_name (*b));
226 }
227
228 /* A hsh_compare_func that orders pointers to variables A and B
229    by their dictionary indexes. */
230 int
231 compare_var_ptrs_by_dict_index (const void *a_, const void *b_,
232                                 const void *aux UNUSED)
233 {
234   struct variable *const *a = a_;
235   struct variable *const *b = b_;
236   size_t a_index = var_get_dict_index (*a);
237   size_t b_index = var_get_dict_index (*b);
238
239   return a_index < b_index ? -1 : a_index > b_index;
240 }
241
242 /* A hsh_hash_func that hashes pointer to variable V based on its
243    name. */
244 unsigned
245 hash_var_ptr_by_name (const void *v_, const void *aux UNUSED)
246 {
247   struct variable *const *v = v_;
248
249   return hash_case_string (var_get_name (*v), 0);
250 }
251 \f
252 /* Returns the type of variable V. */
253 enum val_type
254 var_get_type (const struct variable *v)
255 {
256   return val_type_from_width (v->width);
257 }
258
259 /* Returns the width of variable V. */
260 int
261 var_get_width (const struct variable *v)
262 {
263   return v->width;
264 }
265
266 /* Changes the width of V to NEW_WIDTH.
267    This function should be used cautiously. */
268 void
269 var_set_width (struct variable *v, int new_width)
270 {
271   const int old_width = v->width;
272
273   if (old_width == new_width)
274     return;
275
276   if (mv_is_resizable (&v->miss, new_width))
277     mv_resize (&v->miss, new_width);
278   else
279     {
280       mv_destroy (&v->miss);
281       mv_init (&v->miss, new_width);
282     }
283
284   if (v->val_labs != NULL)
285     {
286       if (val_labs_can_set_width (v->val_labs, new_width))
287         val_labs_set_width (v->val_labs, new_width);
288       else
289         {
290           val_labs_destroy (v->val_labs);
291           v->val_labs = NULL;
292         }
293     }
294
295   fmt_resize (&v->print, new_width);
296   fmt_resize (&v->write, new_width);
297
298   v->width = new_width;
299   dict_var_resized (v, old_width);
300   dict_var_changed (v);
301 }
302
303 /* Returns true if variable V is numeric, false otherwise. */
304 bool
305 var_is_numeric (const struct variable *v)
306 {
307   return var_get_type (v) == VAL_NUMERIC;
308 }
309
310 /* Returns true if variable V is a string variable, false
311    otherwise. */
312 bool
313 var_is_alpha (const struct variable *v)
314 {
315   return var_get_type (v) == VAL_STRING;
316 }
317 \f
318 /* Returns variable V's missing values. */
319 const struct missing_values *
320 var_get_missing_values (const struct variable *v)
321 {
322   return &v->miss;
323 }
324
325 /* Sets variable V's missing values to MISS, which must be of V's
326    width or at least resizable to V's width.
327    If MISS is null, then V's missing values, if any, are
328    cleared. */
329 void
330 var_set_missing_values (struct variable *v, const struct missing_values *miss)
331 {
332   if (miss != NULL)
333     {
334       assert (mv_is_resizable (miss, v->width));
335       mv_destroy (&v->miss);
336       mv_copy (&v->miss, miss);
337       mv_resize (&v->miss, v->width);
338     }
339   else
340     mv_clear (&v->miss);
341
342   dict_var_changed (v);
343 }
344
345 /* Sets variable V to have no user-missing values. */
346 void
347 var_clear_missing_values (struct variable *v)
348 {
349   var_set_missing_values (v, NULL);
350 }
351
352 /* Returns true if V has any user-missing values,
353    false otherwise. */
354 bool
355 var_has_missing_values (const struct variable *v)
356 {
357   return !mv_is_empty (&v->miss);
358 }
359
360 /* Returns true if VALUE is in the given CLASS of missing values
361    in V, false otherwise. */
362 bool
363 var_is_value_missing (const struct variable *v, const union value *value,
364                       enum mv_class class)
365 {
366   return mv_is_value_missing (&v->miss, value, class);
367 }
368
369 /* Returns true if D is in the given CLASS of missing values in
370    V, false otherwise.
371    V must be a numeric variable. */
372 bool
373 var_is_num_missing (const struct variable *v, double d, enum mv_class class)
374 {
375   return mv_is_num_missing (&v->miss, d, class);
376 }
377
378 /* Returns true if S[] is a missing value for V, false otherwise.
379    S[] must contain exactly as many characters as V's width.
380    V must be a string variable. */
381 bool
382 var_is_str_missing (const struct variable *v, const uint8_t s[],
383                     enum mv_class class)
384 {
385   return mv_is_str_missing (&v->miss, s, class);
386 }
387 \f
388 /* Returns variable V's value labels,
389    possibly a null pointer if it has none. */
390 const struct val_labs *
391 var_get_value_labels (const struct variable *v)
392 {
393   return v->val_labs;
394 }
395
396 /* Returns true if variable V has at least one value label. */
397 bool
398 var_has_value_labels (const struct variable *v)
399 {
400   return val_labs_count (v->val_labs) > 0;
401 }
402
403 /* Sets variable V's value labels to a copy of VLS,
404    which must have a width equal to V's width or one that can be
405    changed to V's width.
406    If VLS is null, then V's value labels, if any, are removed. */
407 void
408 var_set_value_labels (struct variable *v, const struct val_labs *vls)
409 {
410   val_labs_destroy (v->val_labs);
411   v->val_labs = NULL;
412
413   if (vls != NULL)
414     {
415       assert (val_labs_can_set_width (vls, v->width));
416       v->val_labs = val_labs_clone (vls);
417       val_labs_set_width (v->val_labs, v->width);
418       dict_var_changed (v);
419     }
420 }
421
422 /* Makes sure that V has a set of value labels,
423    by assigning one to it if necessary. */
424 static void
425 alloc_value_labels (struct variable *v)
426 {
427   if (v->val_labs == NULL)
428     v->val_labs = val_labs_create (v->width);
429 }
430
431 /* Attempts to add a value label with the given VALUE and UTF-8 encoded LABEL
432    to V.  Returns true if successful, false otherwise (probably due to an
433    existing label).
434
435    In LABEL, the two-byte sequence "\\n" is interpreted as a new-line. */
436 bool
437 var_add_value_label (struct variable *v,
438                      const union value *value, const char *label)
439 {
440   alloc_value_labels (v);
441   return val_labs_add (v->val_labs, value, label);
442 }
443
444 /* Adds or replaces a value label with the given VALUE and UTF-8 encoded LABEL
445    to V.
446
447    In LABEL, the two-byte sequence "\\n" is interpreted as a new-line. */
448 void
449 var_replace_value_label (struct variable *v,
450                          const union value *value, const char *label)
451 {
452   alloc_value_labels (v);
453   val_labs_replace (v->val_labs, value, label);
454 }
455
456 /* Removes V's value labels, if any. */
457 void
458 var_clear_value_labels (struct variable *v)
459 {
460   var_set_value_labels (v, NULL);
461 }
462
463 /* Returns the label associated with VALUE for variable V, as a UTF-8 string in
464    a format suitable for output, or a null pointer if none. */
465 const char *
466 var_lookup_value_label (const struct variable *v, const union value *value)
467 {
468   return val_labs_find (v->val_labs, value);
469 }
470
471 /*
472    Append to STR the string representation of VALUE for variable V.
473    STR must be a pointer to an initialised struct string.
474 */
475 static void
476 append_value (const struct variable *v, const union value *value,
477               struct string *str)
478 {
479   char *s = data_out (value, var_get_encoding (v), &v->print);
480   ds_put_cstr (str, s);
481   free (s);
482 }
483
484 /* Append STR with a string representing VALUE for variable V.
485    That is, if VALUE has a label, append that label,
486    otherwise format VALUE and append the formatted string.
487    STR must be a pointer to an initialised struct string.
488 */
489 void
490 var_append_value_name (const struct variable *v, const union value *value,
491                        struct string *str)
492 {
493   enum settings_value_style style = settings_get_value_style ();
494   const char *name = var_lookup_value_label (v, value);
495
496   switch (style)
497     {
498     case SETTINGS_VAL_STYLE_VALUES:
499       append_value (v, value, str);
500       break;
501       
502     case SETTINGS_VAL_STYLE_LABELS:
503       if (name == NULL)
504         append_value (v, value, str);
505       else
506         ds_put_cstr (str, name);
507       break;
508
509     case SETTINGS_VAL_STYLE_BOTH:
510     default:
511       append_value (v, value, str);
512       if (name != NULL)
513         {
514           ds_put_cstr (str, " (");
515           ds_put_cstr (str, name);
516           ds_put_cstr (str, ")");
517         }
518       break;
519     };
520 }
521 \f
522 /* Print and write formats. */
523
524 /* Returns V's print format specification. */
525 const struct fmt_spec *
526 var_get_print_format (const struct variable *v)
527 {
528   return &v->print;
529 }
530
531 /* Sets V's print format specification to PRINT, which must be a
532    valid format specification for a variable of V's width
533    (ordinarily an output format, but input formats are not
534    rejected). */
535 void
536 var_set_print_format (struct variable *v, const struct fmt_spec *print)
537 {
538   assert (fmt_check_width_compat (print, v->width));
539   v->print = *print;
540   dict_var_changed (v);
541 }
542
543 /* Returns V's write format specification. */
544 const struct fmt_spec *
545 var_get_write_format (const struct variable *v)
546 {
547   return &v->write;
548 }
549
550 /* Sets V's write format specification to WRITE, which must be a
551    valid format specification for a variable of V's width
552    (ordinarily an output format, but input formats are not
553    rejected). */
554 void
555 var_set_write_format (struct variable *v, const struct fmt_spec *write)
556 {
557   assert (fmt_check_width_compat (write, v->width));
558   v->write = *write;
559   dict_var_changed (v);
560 }
561
562 /* Sets V's print and write format specifications to FORMAT,
563    which must be a valid format specification for a variable of
564    V's width (ordinarily an output format, but input formats are
565    not rejected). */
566 void
567 var_set_both_formats (struct variable *v, const struct fmt_spec *format)
568 {
569   var_set_print_format (v, format);
570   var_set_write_format (v, format);
571 }
572
573 /* Returns the default print and write format for a variable of
574    the given TYPE, as set by var_create.  The return value can be
575    used to reset a variable's print and write formats to the
576    default. */
577 struct fmt_spec
578 var_default_formats (int width)
579 {
580   return (width == 0
581           ? fmt_for_output (FMT_F, 8, 2)
582           : fmt_for_output (FMT_A, width, 0));
583 }
584
585
586 \f
587
588 /* Update the combined name and label string if necessary */
589 static void
590 update_vl_string (const struct variable *v)
591 {
592   /* Cast away const! */
593   struct string *str = (struct string *) &v->name_and_label;
594
595   if (ds_is_empty (str))
596     {
597       if (v->label)
598         ds_put_format (str, _("%s (%s)"), v->label, v->name);
599       else
600         ds_put_cstr (str, v->name);
601     }
602 }
603
604
605 /* Return a string representing this variable, in the form most
606    appropriate from a human factors perspective, that is, its
607    variable label if it has one, otherwise its name. */
608 const char *
609 var_to_string (const struct variable *v)
610 {
611   enum settings_var_style style = settings_get_var_style ();
612
613   switch (style)
614   {
615     case SETTINGS_VAR_STYLE_NAMES:
616       return v->name;
617       break;
618     case SETTINGS_VAR_STYLE_LABELS:
619       return v->label != NULL ? v->label : v->name;
620       break;
621     case SETTINGS_VAR_STYLE_BOTH:
622       update_vl_string (v);
623       return ds_cstr (&v->name_and_label);
624       break;
625     default:
626       NOT_REACHED ();
627       break;
628   };
629 }
630
631 /* Returns V's variable label, or a null pointer if it has none. */
632 const char *
633 var_get_label (const struct variable *v)
634 {
635   return v->label;
636 }
637
638 /* Sets V's variable label to UTF-8 encoded string LABEL, stripping off leading
639    and trailing white space.  If LABEL is a null pointer or if LABEL is an
640    empty string (after stripping white space), then V's variable label (if any)
641    is removed.
642
643    Variable labels are limited to 255 bytes in V's encoding (as returned by
644    var_get_encoding()).  If LABEL fits within this limit, this function returns
645    true.  Otherwise, the variable label is set to a truncated value, this
646    function returns false and, if ISSUE_WARNING is true, issues a warning.  */
647 bool
648 var_set_label (struct variable *v, const char *label, bool issue_warning)
649 {
650   bool truncated = false;
651
652   free (v->label);
653   v->label = NULL;
654
655   if (label != NULL && label[strspn (label, CC_SPACES)])
656     {
657       const char *dict_encoding = var_get_encoding (v);
658       struct substring s = ss_cstr (label);
659       size_t trunc_len;
660
661       if (dict_encoding != NULL)
662         {
663           enum { MAX_LABEL_LEN = 255 };
664
665           trunc_len = utf8_encoding_trunc_len (label, dict_encoding,
666                                                MAX_LABEL_LEN);
667           if (ss_length (s) > trunc_len)
668             {
669               if (issue_warning)
670                 msg (SW, _("Truncating variable label for variable `%s' to %d "
671                            "bytes."), var_get_name (v), MAX_LABEL_LEN);
672               ss_truncate (&s, trunc_len);
673               truncated = true;
674             }
675         }
676
677         v->label = ss_xstrdup (s);
678     }
679
680   ds_destroy (&v->name_and_label);
681   ds_init_empty (&v->name_and_label);
682
683   dict_var_changed (v);
684
685   return truncated;
686 }
687
688 /* Removes any variable label from V. */
689 void
690 var_clear_label (struct variable *v)
691 {
692   var_set_label (v, NULL, false);
693 }
694
695 /* Returns true if V has a variable V,
696    false otherwise. */
697 bool
698 var_has_label (const struct variable *v)
699 {
700   return v->label != NULL;
701 }
702 \f
703 /* Returns true if M is a valid variable measurement level,
704    false otherwise. */
705 bool
706 measure_is_valid (enum measure m)
707 {
708   return m == MEASURE_NOMINAL || m == MEASURE_ORDINAL || m == MEASURE_SCALE;
709 }
710
711 /* Returns a string version of measurement level M, for display to a user. */
712 const char *
713 measure_to_string (enum measure m)
714 {
715   switch (m)
716     {
717     case MEASURE_NOMINAL:
718       return _("Nominal");
719
720     case MEASURE_ORDINAL:
721       return _("Ordinal");
722
723     case MEASURE_SCALE:
724       return _("Scale");
725
726     default:
727       return "Invalid";
728     }
729 }
730
731 /* Returns V's measurement level. */
732 enum measure
733 var_get_measure (const struct variable *v)
734 {
735   return v->measure;
736 }
737
738 /* Sets V's measurement level to MEASURE. */
739 void
740 var_set_measure (struct variable *v, enum measure measure)
741 {
742   assert (measure_is_valid (measure));
743   v->measure = measure;
744   dict_var_changed (v);
745 }
746
747 /* Returns the default measurement level for a variable of the
748    given TYPE, as set by var_create.  The return value can be
749    used to reset a variable's measurement level to the
750    default. */
751 enum measure
752 var_default_measure (enum val_type type)
753 {
754   return type == VAL_NUMERIC ? MEASURE_SCALE : MEASURE_NOMINAL;
755 }
756 \f
757 /* Returns V's display width, which applies only to GUIs. */
758 int
759 var_get_display_width (const struct variable *v)
760 {
761   return v->display_width;
762 }
763
764 /* Sets V's display width to DISPLAY_WIDTH. */
765 void
766 var_set_display_width (struct variable *v, int new_width)
767 {
768   if (v->display_width != new_width)
769     {
770       v->display_width = new_width;
771       dict_var_display_width_changed (v);
772       dict_var_changed (v);
773     }
774 }
775
776 /* Returns the default display width for a variable of the given
777    WIDTH, as set by var_create.  The return value can be used to
778    reset a variable's display width to the default. */
779 int
780 var_default_display_width (int width)
781 {
782   return width == 0 ? 8 : MIN (width, 32);
783 }
784 \f
785 /* Returns true if A is a valid alignment,
786    false otherwise. */
787 bool
788 alignment_is_valid (enum alignment a)
789 {
790   return a == ALIGN_LEFT || a == ALIGN_RIGHT || a == ALIGN_CENTRE;
791 }
792
793 /* Returns a string version of alignment A, for display to a user. */
794 const char *
795 alignment_to_string (enum alignment a)
796 {
797   switch (a)
798     {
799     case ALIGN_LEFT:
800       return _("Left");
801
802     case ALIGN_RIGHT:
803       return _("Right");
804
805     case ALIGN_CENTRE:
806       return _("Center");
807
808     default:
809       return "Invalid";
810     }
811 }
812
813 /* Returns V's display alignment, which applies only to GUIs. */
814 enum alignment
815 var_get_alignment (const struct variable *v)
816 {
817   return v->alignment;
818 }
819
820 /* Sets V's display alignment to ALIGNMENT. */
821 void
822 var_set_alignment (struct variable *v, enum alignment alignment)
823 {
824   assert (alignment_is_valid (alignment));
825   v->alignment = alignment;
826   dict_var_changed (v);
827 }
828
829 /* Returns the default display alignment for a variable of the
830    given TYPE, as set by var_create.  The return value can be
831    used to reset a variable's display alignment to the default. */
832 enum alignment
833 var_default_alignment (enum val_type type)
834 {
835   return type == VAL_NUMERIC ? ALIGN_RIGHT : ALIGN_LEFT;
836 }
837 \f
838 /* Whether variables' values should be preserved from case to
839    case. */
840
841 /* Returns true if variable V's value should be left from case to
842    case, instead of being reset to system-missing or blanks. */
843 bool
844 var_get_leave (const struct variable *v)
845 {
846   return v->leave;
847 }
848
849 /* Sets V's leave setting to LEAVE. */
850 void
851 var_set_leave (struct variable *v, bool leave)
852 {
853   assert (leave || !var_must_leave (v));
854   v->leave = leave;
855   dict_var_changed (v);
856 }
857
858 /* Returns true if V must be left from case to case,
859    false if it can be set either way. */
860 bool
861 var_must_leave (const struct variable *v)
862 {
863   return var_get_dict_class (v) == DC_SCRATCH;
864 }
865 \f
866 /* Returns the number of short names stored in VAR.
867
868    Short names are used only for system and portable file input
869    and output.  They are upper-case only, not necessarily unique,
870    and limited to SHORT_NAME_LEN characters (plus a null
871    terminator).  Ordinarily a variable has at most one short
872    name, but very long string variables (longer than 255 bytes)
873    may have more.  A variable might not have any short name at
874    all if it hasn't been saved to or read from a system or
875    portable file. */
876 size_t
877 var_get_short_name_cnt (const struct variable *var) 
878 {
879   return var->short_name_cnt;
880 }
881
882 /* Returns VAR's short name with the given IDX, if it has one
883    with that index, or a null pointer otherwise.  Short names may
884    be sparse: even if IDX is less than the number of short names
885    in VAR, this function may return a null pointer. */
886 const char *
887 var_get_short_name (const struct variable *var, size_t idx)
888 {
889   return idx < var->short_name_cnt ? var->short_names[idx] : NULL;
890 }
891
892 /* Sets VAR's short name with the given IDX to the UTF-8 string SHORT_NAME.
893    The caller must already have checked that, in the dictionary encoding,
894    SHORT_NAME is no more than SHORT_NAME_LEN bytes long.  The new short name
895    will be converted to uppercase.
896
897    Specifying a null pointer for SHORT_NAME clears the specified short name. */
898 void
899 var_set_short_name (struct variable *var, size_t idx, const char *short_name)
900 {
901   assert (short_name == NULL || id_is_plausible (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] = xstrdup (short_name);
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 (var_has_vardict (v));
952   return vardict_get_dict_index (v->vardict);
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 (var_has_vardict (v));
963   return vardict_get_case_index (v->vardict);
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 = CONST_CAST (struct variable *, v_);
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   if (v->aux != NULL)
1007     {
1008       if (v->aux_dtor != NULL)
1009         v->aux_dtor (v);
1010       v->aux = NULL;
1011     }
1012 }
1013
1014 /* This function is appropriate for use an auxiliary data
1015    destructor (passed as AUX_DTOR to var_attach_aux()) for the
1016    case where the auxiliary data should be passed to free(). */
1017 void
1018 var_dtor_free (struct variable *v)
1019 {
1020   free (v->aux);
1021 }
1022 \f
1023 /* Returns variable V's attribute set.  The caller may examine or
1024    modify the attribute set, but must not destroy it.  Destroying
1025    V, or calling var_set_attributes() on V, will also destroy its
1026    attribute set. */
1027 struct attrset *
1028 var_get_attributes (const struct variable *v) 
1029 {
1030   return CONST_CAST (struct attrset *, &v->attributes);
1031 }
1032
1033 /* Replaces variable V's attributes set by a copy of ATTRS. */
1034 void
1035 var_set_attributes (struct variable *v, const struct attrset *attrs) 
1036 {
1037   attrset_destroy (&v->attributes);
1038   attrset_clone (&v->attributes, attrs);
1039 }
1040
1041 /* Returns true if V has any custom attributes, false if it has none. */
1042 bool
1043 var_has_attributes (const struct variable *v)
1044 {
1045   return attrset_count (&v->attributes) > 0;
1046 }
1047 \f
1048 /* Returns the encoding of values of variable VAR.  (This is actually a
1049    property of the dictionary.)  Returns null if no specific encoding has been
1050    set.  */
1051 const char *
1052 var_get_encoding (const struct variable *var)
1053 {
1054   return (var_has_vardict (var)
1055           ? dict_get_encoding (vardict_get_dictionary (var->vardict))
1056           : NULL);
1057 }
1058 \f
1059 /* Returns V's vardict structure. */
1060 struct vardict_info *
1061 var_get_vardict (const struct variable *v)
1062 {
1063   return CONST_CAST (struct vardict_info *, v->vardict);
1064 }
1065
1066 /* Sets V's vardict data to VARDICT. */
1067 void
1068 var_set_vardict (struct variable *v, struct vardict_info *vardict)
1069 {
1070   v->vardict = vardict;
1071 }
1072
1073 /* Returns true if V has vardict data. */
1074 bool
1075 var_has_vardict (const struct variable *v)
1076 {
1077   return v->vardict != NULL;
1078 }
1079
1080 /* Clears V's vardict data. */
1081 void
1082 var_clear_vardict (struct variable *v)
1083 {
1084   v->vardict = NULL;
1085 }