better tests
[pspp] / src / data / variable.c
1 /* PSPP - a program for statistical analysis.
2    Copyright (C) 1997-9, 2000, 2006, 2009, 2010, 2011, 2012, 2013,
3    2014, 2016, 2020 Free Software Foundation, Inc.
4
5    This program is free software: you can redistribute it and/or modify
6    it under the terms of the GNU General Public License as published by
7    the Free Software Foundation, either version 3 of the License, or
8    (at your option) any later version.
9
10    This program is distributed in the hope that it will be useful,
11    but WITHOUT ANY WARRANTY; without even the implied warranty of
12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13    GNU 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, see <http://www.gnu.org/licenses/>. */
17
18 #include <config.h>
19
20 #include "data/variable.h"
21
22 #include <stdlib.h>
23
24 #include "data/attributes.h"
25 #include "data/data-out.h"
26 #include "data/dictionary.h"
27 #include "data/format.h"
28 #include "data/identifier.h"
29 #include "data/missing-values.h"
30 #include "data/settings.h"
31 #include "data/value-labels.h"
32 #include "data/vardict.h"
33 #include "libpspp/assertion.h"
34 #include "libpspp/compiler.h"
35 #include "libpspp/hash-functions.h"
36 #include "libpspp/i18n.h"
37 #include "libpspp/message.h"
38 #include "libpspp/misc.h"
39 #include "libpspp/str.h"
40
41 #include "gl/minmax.h"
42 #include "gl/xalloc.h"
43
44 #include "gettext.h"
45 #define _(msgid) gettext (msgid)
46 #define N_(msgid) (msgid)
47
48 /* This should follow the definition in Gtk */
49 typedef struct
50 {
51   int value;
52   const char *name;
53   const char *label;
54 } GEnumValue;
55
56 const GEnumValue align[] =
57   {
58     {ALIGN_LEFT,   "left", N_("Left")},
59     {ALIGN_RIGHT,  "right", N_("Right")},
60     {ALIGN_CENTRE, "center", N_("Center")},
61     {0,0,0}
62   };
63
64 const GEnumValue measure[] =
65   {
66     {MEASURE_NOMINAL, "nominal", N_("Nominal")},
67     {MEASURE_ORDINAL, "ordinal", N_("Ordinal")},
68     {MEASURE_SCALE,   "scale", N_("Scale")},
69     {0,0,0}
70   };
71
72 const GEnumValue role[] =
73   {
74     {ROLE_INPUT,  "input",    N_("Input")},
75     {ROLE_TARGET, "output",   N_("Output")},
76     {ROLE_BOTH,   "both",     N_("Both")},
77     {ROLE_NONE,   "none",     N_("None")},
78     {ROLE_PARTITION, "partition", N_("Partition")},
79     {ROLE_SPLIT,  "split",    N_("Split")},
80     {0,0,0}
81   };
82
83 /* A variable. */
84 struct variable
85   {
86     int ref_cnt;
87     /* Dictionary information. */
88     char *name;                 /* Variable name.  Mixed case. */
89     int width;                  /* 0 for numeric, otherwise string width. */
90     struct missing_values miss; /* Missing values. */
91     struct fmt_spec print;      /* Default format for PRINT. */
92     struct fmt_spec write;      /* Default format for WRITE. */
93     struct val_labs *val_labs;  /* Value labels. */
94     char *label;                /* Variable label. */
95     struct string name_and_label; /* The name and label in the same string */
96
97     /* GUI information. */
98     enum measure measure;       /* Nominal, ordinal, or continuous. */
99     enum var_role role;         /* Intended use. */
100     int display_width;          /* Width of data editor column. */
101     enum alignment alignment;   /* Alignment of data in GUI. */
102
103     /* Case information. */
104     bool leave;                 /* Leave value from case to case? */
105
106     /* Data for use by containing dictionary. */
107     struct vardict_info *vardict;
108
109     /* Used only for system and portable file input and output.
110        See short-names.h. */
111     char **short_names;
112     size_t n_short_names;
113
114     /* Custom attributes. */
115     struct attrset attributes;
116   };
117 \f
118
119 static void var_set_print_format_quiet (struct variable *v, const struct fmt_spec *print);
120 static void var_set_write_format_quiet (struct variable *v, const struct fmt_spec *write);
121 static void var_set_label_quiet (struct variable *v, const char *label);
122 static void var_set_name_quiet (struct variable *v, const char *name);
123
124 /* Creates and returns a new variable with the given NAME and
125    WIDTH and other fields initialized to default values.  The
126    variable is not added to a dictionary; for that, use
127    dict_create_var instead. */
128 struct variable *
129 var_create (const char *name, int width)
130 {
131   enum val_type type;
132
133   assert (width >= 0 && width <= MAX_STRING);
134
135   struct variable *v = XZALLOC (struct variable);
136   var_set_name_quiet (v, name);
137   v->width = width;
138   mv_init (&v->miss, width);
139   v->leave = var_must_leave (v);
140   type = val_type_from_width (width);
141   v->alignment = var_default_alignment (type);
142   v->measure = var_default_measure (type);
143   v->role = ROLE_INPUT;
144   v->display_width = var_default_display_width (width);
145   v->print = v->write = var_default_formats (width);
146   attrset_init (&v->attributes);
147   ds_init_empty (&v->name_and_label);
148
149   v->ref_cnt = 1;
150
151   return v;
152 }
153
154 /* Destroys variable V.
155    V must not belong to a dictionary.  If it does, use
156    dict_delete_var instead. */
157 static void
158 var_destroy__ (struct variable *v)
159 {
160   assert (!var_has_vardict (v));
161   mv_destroy (&v->miss);
162   var_clear_short_names (v);
163   val_labs_destroy (v->val_labs);
164   var_set_label_quiet (v, NULL);
165   attrset_destroy (var_get_attributes (v));
166   free (v->name);
167   ds_destroy (&v->name_and_label);
168   free (v);
169 }
170
171 struct variable *
172 var_ref (struct variable *v)
173 {
174   v->ref_cnt++;
175   return v;
176 }
177
178 void
179 var_unref (struct variable *v)
180 {
181   if (--v->ref_cnt == 0)
182     var_destroy__ (v);
183 }
184
185
186 \f
187 /* Variable names. */
188
189 /* Return variable V's name, as a UTF-8 encoded string. */
190 const char *
191 var_get_name (const struct variable *v)
192 {
193   return v->name;
194 }
195
196
197
198 /* Sets V's name to NAME, a UTF-8 encoded string.
199    Do not use this function for a variable in a dictionary.  Use
200    dict_rename_var instead. */
201 static void
202 var_set_name_quiet (struct variable *v, const char *name)
203 {
204   assert (!var_has_vardict (v));
205
206   free (v->name);
207   v->name = xstrdup (name);
208   ds_destroy (&v->name_and_label);
209   ds_init_empty (&v->name_and_label);
210 }
211
212 /* Sets V's name to NAME, a UTF-8 encoded string.
213    Do not use this function for a variable in a dictionary.  Use
214    dict_rename_var instead. */
215 void
216 var_set_name (struct variable *v, const char *name)
217 {
218   struct variable *ov = var_clone (v);
219   var_set_name_quiet (v, name);
220   dict_var_changed (v, VAR_TRAIT_NAME, ov);
221 }
222
223 /* Returns VAR's dictionary class. */
224 enum dict_class
225 var_get_dict_class (const struct variable *var)
226 {
227   return dict_class_from_id (var->name);
228 }
229
230 /* A hsh_compare_func that orders variables A and B by their
231    names. */
232 int
233 compare_vars_by_name (const void *a_, const void *b_, const void *aux UNUSED)
234 {
235   const struct variable *a = a_;
236   const struct variable *b = b_;
237
238   return utf8_strcasecmp (a->name, b->name);
239 }
240
241 /* A hsh_hash_func that hashes variable V based on its name. */
242 unsigned
243 hash_var_by_name (const void *v_, const void *aux UNUSED)
244 {
245   const struct variable *v = v_;
246
247   return utf8_hash_case_string (v->name, 0);
248 }
249
250 /* A hsh_compare_func that orders pointers to variables A and B
251    by their names. */
252 int
253 compare_var_ptrs_by_name (const void *a_, const void *b_,
254                           const void *aux UNUSED)
255 {
256   struct variable *const *a = a_;
257   struct variable *const *b = b_;
258
259   return utf8_strcasecmp (var_get_name (*a), var_get_name (*b));
260 }
261
262 /* A hsh_compare_func that orders pointers to variables A and B
263    by their dictionary indexes. */
264 int
265 compare_var_ptrs_by_dict_index (const void *a_, const void *b_,
266                                 const void *aux UNUSED)
267 {
268   struct variable *const *a = a_;
269   struct variable *const *b = b_;
270   size_t a_index = var_get_dict_index (*a);
271   size_t b_index = var_get_dict_index (*b);
272
273   return a_index < b_index ? -1 : a_index > b_index;
274 }
275
276 /* A hsh_hash_func that hashes pointer to variable V based on its
277    name. */
278 unsigned
279 hash_var_ptr_by_name (const void *v_, const void *aux UNUSED)
280 {
281   struct variable *const *v = v_;
282
283   return utf8_hash_case_string (var_get_name (*v), 0);
284 }
285 \f
286 /* Returns the type of variable V. */
287 enum val_type
288 var_get_type (const struct variable *v)
289 {
290   return val_type_from_width (v->width);
291 }
292
293 /* Returns the width of variable V. */
294 int
295 var_get_width (const struct variable *v)
296 {
297   return v->width;
298 }
299
300 void
301 var_set_width_and_formats (struct variable *v, int new_width,
302                            const struct fmt_spec *print, const struct fmt_spec *write)
303 {
304   struct variable *ov;
305   unsigned int traits = 0;
306
307   ov = var_clone (v);
308
309   if (mv_is_resizable (&v->miss, new_width))
310     mv_resize (&v->miss, new_width);
311   else
312     {
313       mv_destroy (&v->miss);
314       mv_init (&v->miss, new_width);
315     }
316   if (new_width != var_get_width (v))
317     traits |= VAR_TRAIT_MISSING_VALUES;
318
319   if (v->val_labs != NULL)
320     {
321       if (val_labs_can_set_width (v->val_labs, new_width))
322         val_labs_set_width (v->val_labs, new_width);
323       else
324         {
325           val_labs_destroy (v->val_labs);
326           v->val_labs = NULL;
327         }
328       traits |= VAR_TRAIT_VALUE_LABELS;
329     }
330
331   if (fmt_resize (&v->print, new_width))
332     traits |= VAR_TRAIT_PRINT_FORMAT;
333
334   if (fmt_resize (&v->write, new_width))
335     traits |= VAR_TRAIT_WRITE_FORMAT;
336
337   if (v->width != new_width)
338     {
339       v->width = new_width;
340       traits |= VAR_TRAIT_WIDTH;
341     }
342
343   if (print)
344     {
345       var_set_print_format_quiet (v, print);
346       traits |= VAR_TRAIT_PRINT_FORMAT;
347     }
348
349   if (write)
350     {
351       var_set_write_format_quiet (v, write);
352       traits |= VAR_TRAIT_WRITE_FORMAT;
353     }
354
355   if (traits != 0)
356     dict_var_changed (v, traits, ov);
357 }
358
359 /* Changes the width of V to NEW_WIDTH.
360    This function should be used cautiously. */
361 void
362 var_set_width (struct variable *v, int new_width)
363 {
364   const int old_width = v->width;
365
366   if (old_width == new_width)
367     return;
368
369   var_set_width_and_formats (v, new_width, NULL, NULL);
370 }
371
372
373
374
375 /* Returns true if variable V is numeric, false otherwise. */
376 bool
377 var_is_numeric (const struct variable *v)
378 {
379   return var_get_type (v) == VAL_NUMERIC;
380 }
381
382 /* Returns true if variable V is a string variable, false
383    otherwise. */
384 bool
385 var_is_alpha (const struct variable *v)
386 {
387   return var_get_type (v) == VAL_STRING;
388 }
389 \f
390 /* Returns variable V's missing values. */
391 const struct missing_values *
392 var_get_missing_values (const struct variable *v)
393 {
394   return &v->miss;
395 }
396
397 /* Sets variable V's missing values to MISS, which must be of V's
398    width or at least resizable to V's width.
399    If MISS is null, then V's missing values, if any, are
400    cleared. */
401 static void
402 var_set_missing_values_quiet (struct variable *v, const struct missing_values *miss)
403 {
404   if (miss != NULL)
405     {
406       assert (mv_is_resizable (miss, v->width));
407       mv_destroy (&v->miss);
408       mv_copy (&v->miss, miss);
409       mv_resize (&v->miss, v->width);
410     }
411   else
412     mv_clear (&v->miss);
413 }
414
415 /* Sets variable V's missing values to MISS, which must be of V's
416    width or at least resizable to V's width.
417    If MISS is null, then V's missing values, if any, are
418    cleared. */
419 void
420 var_set_missing_values (struct variable *v, const struct missing_values *miss)
421 {
422   struct variable *ov = var_clone (v);
423   var_set_missing_values_quiet (v, miss);
424   dict_var_changed (v, VAR_TRAIT_MISSING_VALUES, ov);
425 }
426
427 /* Sets variable V to have no user-missing values. */
428 void
429 var_clear_missing_values (struct variable *v)
430 {
431   var_set_missing_values (v, NULL);
432 }
433
434 /* Returns true if V has any user-missing values,
435    false otherwise. */
436 bool
437 var_has_missing_values (const struct variable *v)
438 {
439   return !mv_is_empty (&v->miss);
440 }
441
442 /* Returns true if VALUE is in the given CLASS of missing values
443    in V, false otherwise. */
444 bool
445 var_is_value_missing (const struct variable *v, const union value *value,
446                       enum mv_class class)
447 {
448   return mv_is_value_missing (&v->miss, value, class);
449 }
450
451 /* Returns true if D is in the given CLASS of missing values in
452    V, false otherwise.
453    V must be a numeric variable. */
454 bool
455 var_is_num_missing (const struct variable *v, double d, enum mv_class class)
456 {
457   return mv_is_num_missing (&v->miss, d, class);
458 }
459
460 /* Returns true if S[] is a missing value for V, false otherwise.
461    S[] must contain exactly as many characters as V's width.
462    V must be a string variable. */
463 bool
464 var_is_str_missing (const struct variable *v, const uint8_t s[],
465                     enum mv_class class)
466 {
467   return mv_is_str_missing (&v->miss, s, class);
468 }
469 \f
470 /* Returns variable V's value labels,
471    possibly a null pointer if it has none. */
472 const struct val_labs *
473 var_get_value_labels (const struct variable *v)
474 {
475   return v->val_labs;
476 }
477
478 /* Returns true if variable V has at least one value label. */
479 bool
480 var_has_value_labels (const struct variable *v)
481 {
482   return val_labs_count (v->val_labs) > 0;
483 }
484
485 /* Sets variable V's value labels to a copy of VLS,
486    which must have a width equal to V's width or one that can be
487    changed to V's width.
488    If VLS is null, then V's value labels, if any, are removed. */
489 static void
490 var_set_value_labels_quiet (struct variable *v, const struct val_labs *vls)
491 {
492   val_labs_destroy (v->val_labs);
493   v->val_labs = NULL;
494
495   if (vls != NULL)
496     {
497       assert (val_labs_can_set_width (vls, v->width));
498       v->val_labs = val_labs_clone (vls);
499       val_labs_set_width (v->val_labs, v->width);
500     }
501 }
502
503
504 /* Sets variable V's value labels to a copy of VLS,
505    which must have a width equal to V's width or one that can be
506    changed to V's width.
507    If VLS is null, then V's value labels, if any, are removed. */
508 void
509 var_set_value_labels (struct variable *v, const struct val_labs *vls)
510 {
511   struct variable *ov = var_clone (v);
512   var_set_value_labels_quiet (v, vls);
513   dict_var_changed (v, VAR_TRAIT_LABEL, ov);
514 }
515
516
517 /* Makes sure that V has a set of value labels,
518    by assigning one to it if necessary. */
519 static void
520 alloc_value_labels (struct variable *v)
521 {
522   if (v->val_labs == NULL)
523     v->val_labs = val_labs_create (v->width);
524 }
525
526 /* Attempts to add a value label with the given VALUE and UTF-8 encoded LABEL
527    to V.  Returns true if successful, false otherwise (probably due to an
528    existing label).
529
530    In LABEL, the two-byte sequence "\\n" is interpreted as a new-line. */
531 bool
532 var_add_value_label (struct variable *v,
533                      const union value *value, const char *label)
534 {
535   alloc_value_labels (v);
536   return val_labs_add (v->val_labs, value, label);
537 }
538
539 /* Adds or replaces a value label with the given VALUE and UTF-8 encoded LABEL
540    to V.
541
542    In LABEL, the two-byte sequence "\\n" is interpreted as a new-line. */
543 void
544 var_replace_value_label (struct variable *v,
545                          const union value *value, const char *label)
546 {
547   alloc_value_labels (v);
548   val_labs_replace (v->val_labs, value, label);
549 }
550
551 /* Removes V's value labels, if any. */
552 void
553 var_clear_value_labels (struct variable *v)
554 {
555   var_set_value_labels (v, NULL);
556 }
557
558 /* Returns the label associated with VALUE for variable V, as a UTF-8 string in
559    a format suitable for output, or a null pointer if none. */
560 const char *
561 var_lookup_value_label (const struct variable *v, const union value *value)
562 {
563   return val_labs_find (v->val_labs, value);
564 }
565
566 /*
567    Append to STR the string representation of VALUE for variable V.
568    STR must be a pointer to an initialised struct string.
569 */
570 static void
571 append_value (const struct variable *v, const union value *value,
572               struct string *str)
573 {
574   char *s = data_out (value, var_get_encoding (v), &v->print,
575                       settings_get_fmt_settings ());
576   struct substring ss = ss_cstr (s);
577   ss_rtrim (&ss, ss_cstr (" "));
578   ds_put_substring (str, ss);
579   free (s);
580 }
581
582 void
583 var_append_value_name__ (const struct variable *v, const union value *value,
584                          enum settings_value_show show, struct string *str)
585 {
586   const char *label = var_lookup_value_label (v, value);
587
588   switch (show)
589     {
590     case SETTINGS_VALUE_SHOW_VALUE:
591       append_value (v, value, str);
592       break;
593
594     default:
595     case SETTINGS_VALUE_SHOW_LABEL:
596       if (label)
597         ds_put_cstr (str, label);
598       else
599         append_value (v, value, str);
600       break;
601
602     case SETTINGS_VALUE_SHOW_BOTH:
603       append_value (v, value, str);
604       if (label != NULL)
605         ds_put_format (str, " %s", label);
606       break;
607     }
608 }
609
610 /* Append STR with a string representing VALUE for variable V.
611    That is, if VALUE has a label, append that label,
612    otherwise format VALUE and append the formatted string.
613    STR must be a pointer to an initialised struct string.
614 */
615 void
616 var_append_value_name (const struct variable *v, const union value *value,
617                        struct string *str)
618 {
619   var_append_value_name__ (v, value, settings_get_show_values (), str);
620 }
621 \f
622 /* Print and write formats. */
623
624 /* Returns V's print format specification. */
625 const struct fmt_spec *
626 var_get_print_format (const struct variable *v)
627 {
628   return &v->print;
629 }
630
631 /* Sets V's print format specification to PRINT, which must be a
632    valid format specification for a variable of V's width
633    (ordinarily an output format, but input formats are not
634    rejected). */
635 static void
636 var_set_print_format_quiet (struct variable *v, const struct fmt_spec *print)
637 {
638   if (!fmt_equal (&v->print, print))
639     {
640       assert (fmt_check_width_compat (print, v->width));
641       v->print = *print;
642     }
643 }
644
645 /* Sets V's print format specification to PRINT, which must be a
646    valid format specification for a variable of V's width
647    (ordinarily an output format, but input formats are not
648    rejected). */
649 void
650 var_set_print_format (struct variable *v, const struct fmt_spec *print)
651 {
652   struct variable *ov = var_clone (v);
653   var_set_print_format_quiet (v, print);
654   dict_var_changed (v, VAR_TRAIT_PRINT_FORMAT, ov);
655 }
656
657 /* Returns V's write format specification. */
658 const struct fmt_spec *
659 var_get_write_format (const struct variable *v)
660 {
661   return &v->write;
662 }
663
664 /* Sets V's write format specification to WRITE, which must be a
665    valid format specification for a variable of V's width
666    (ordinarily an output format, but input formats are not
667    rejected). */
668 static void
669 var_set_write_format_quiet (struct variable *v, const struct fmt_spec *write)
670 {
671   if (!fmt_equal (&v->write, write))
672     {
673       assert (fmt_check_width_compat (write, v->width));
674       v->write = *write;
675     }
676 }
677
678 /* Sets V's write format specification to WRITE, which must be a
679    valid format specification for a variable of V's width
680    (ordinarily an output format, but input formats are not
681    rejected). */
682 void
683 var_set_write_format (struct variable *v, const struct fmt_spec *write)
684 {
685   struct variable *ov = var_clone (v);
686   var_set_write_format_quiet (v, write);
687   dict_var_changed (v, VAR_TRAIT_WRITE_FORMAT, ov);
688 }
689
690
691 /* Sets V's print and write format specifications to FORMAT,
692    which must be a valid format specification for a variable of
693    V's width (ordinarily an output format, but input formats are
694    not rejected). */
695 void
696 var_set_both_formats (struct variable *v, const struct fmt_spec *format)
697 {
698   struct variable *ov = var_clone (v);
699   var_set_print_format_quiet (v, format);
700   var_set_write_format_quiet (v, format);
701   dict_var_changed (v, VAR_TRAIT_PRINT_FORMAT | VAR_TRAIT_WRITE_FORMAT, ov);
702 }
703
704 /* Returns the default print and write format for a variable of
705    the given TYPE, as set by var_create.  The return value can be
706    used to reset a variable's print and write formats to the
707    default. */
708 struct fmt_spec
709 var_default_formats (int width)
710 {
711   return (width == 0
712           ? fmt_for_output (FMT_F, 8, 2)
713           : fmt_for_output (FMT_A, width, 0));
714 }
715
716
717 \f
718
719 /* Update the combined name and label string if necessary */
720 static void
721 update_vl_string (const struct variable *v)
722 {
723   /* Cast away const! */
724   struct string *str = (struct string *) &v->name_and_label;
725
726   if (ds_is_empty (str))
727     {
728       if (v->label)
729         ds_put_format (str, _("%s (%s)"), v->label, v->name);
730       else
731         ds_put_cstr (str, v->name);
732     }
733 }
734
735
736 /* Return a string representing this variable, in the form most
737    appropriate from a human factors perspective, that is, its
738    variable label if it has one, otherwise its name. */
739 const char *
740 var_to_string (const struct variable *v)
741 {
742   switch (settings_get_show_variables ())
743     {
744     case SETTINGS_VALUE_SHOW_VALUE:
745       return v->name;
746
747     case SETTINGS_VALUE_SHOW_LABEL:
748     default:
749       return v->label != NULL ? v->label : v->name;
750
751     case SETTINGS_VALUE_SHOW_BOTH:
752       update_vl_string (v);
753       return ds_cstr (&v->name_and_label);
754     }
755 }
756
757 /* Returns V's variable label, or a null pointer if it has none. */
758 const char *
759 var_get_label (const struct variable *v)
760 {
761   return v->label;
762 }
763
764 /* Sets V's variable label to UTF-8 encoded string LABEL, stripping off leading
765    and trailing white space.  If LABEL is a null pointer or if LABEL is an
766    empty string (after stripping white space), then V's variable label (if any)
767    is removed. */
768 static void
769 var_set_label_quiet (struct variable *v, const char *label)
770 {
771   free (v->label);
772   v->label = NULL;
773
774   if (label != NULL && label[strspn (label, CC_SPACES)])
775     v->label = xstrdup (label);
776
777   ds_destroy (&v->name_and_label);
778   ds_init_empty (&v->name_and_label);
779 }
780
781
782
783 /* Sets V's variable label to UTF-8 encoded string LABEL, stripping off leading
784    and trailing white space.  If LABEL is a null pointer or if LABEL is an
785    empty string (after stripping white space), then V's variable label (if any)
786    is removed. */
787 void
788 var_set_label (struct variable *v, const char *label)
789 {
790   struct variable *ov = var_clone (v);
791   var_set_label_quiet (v, label);
792   dict_var_changed (v, VAR_TRAIT_LABEL, ov);
793 }
794
795
796 /* Removes any variable label from V. */
797 void
798 var_clear_label (struct variable *v)
799 {
800   var_set_label (v, NULL);
801 }
802
803 /* Returns true if V has a variable V,
804    false otherwise. */
805 bool
806 var_has_label (const struct variable *v)
807 {
808   return v->label != NULL;
809 }
810 \f
811 /* Returns true if M is a valid variable measurement level,
812    false otherwise. */
813 bool
814 measure_is_valid (enum measure m)
815 {
816   return m == MEASURE_NOMINAL || m == MEASURE_ORDINAL || m == MEASURE_SCALE;
817 }
818
819 /* Returns a string version of measurement level M, for display to a user.
820    The caller may translate the string by passing it to gettext(). */
821 const char *
822 measure_to_string (enum measure m)
823 {
824   assert (m == measure[m].value);
825   return measure[m].label;
826 }
827
828 /* Returns a string version of measurement level M, for use in PSPP command
829    syntax. */
830 const char *
831 measure_to_syntax (enum measure m)
832 {
833   switch (m)
834     {
835     case MEASURE_NOMINAL:
836       return "NOMINAL";
837
838     case MEASURE_ORDINAL:
839       return "ORDINAL";
840
841     case MEASURE_SCALE:
842       return "SCALE";
843
844     default:
845       return "Invalid";
846     }
847 }
848
849 /* Returns V's measurement level. */
850 enum measure
851 var_get_measure (const struct variable *v)
852 {
853   return v->measure;
854 }
855
856 /* Sets V's measurement level to MEASURE. */
857 static void
858 var_set_measure_quiet (struct variable *v, enum measure measure)
859 {
860   assert (measure_is_valid (measure));
861   v->measure = measure;
862 }
863
864
865 /* Sets V's measurement level to MEASURE. */
866 void
867 var_set_measure (struct variable *v, enum measure measure)
868 {
869   struct variable *ov = var_clone (v);
870   var_set_measure_quiet (v, measure);
871   dict_var_changed (v, VAR_TRAIT_MEASURE, ov);
872 }
873
874
875 /* Returns the default measurement level for a variable of the
876    given TYPE, as set by var_create.  The return value can be
877    used to reset a variable's measurement level to the
878    default. */
879 enum measure
880 var_default_measure (enum val_type type)
881 {
882   return type == VAL_NUMERIC ? MEASURE_SCALE : MEASURE_NOMINAL;
883 }
884 \f
885 /* Returns true if M is a valid variable role,
886    false otherwise. */
887 bool
888 var_role_is_valid (enum var_role role)
889 {
890   switch (role)
891     {
892     case ROLE_NONE:
893     case ROLE_INPUT:
894     case ROLE_TARGET:
895     case ROLE_BOTH:
896     case ROLE_PARTITION:
897     case ROLE_SPLIT:
898       return true;
899
900     default:
901       return false;
902     }
903 }
904
905 /* Returns a string version of ROLE, for display to a user.
906    The caller may translate the string by passing it to gettext(). */
907 const char *
908 var_role_to_string (enum var_role r)
909 {
910   assert (r == role[r].value);
911   return role[r].label;
912 }
913
914 /* Returns a string version of ROLE, for use in PSPP comamnd syntax. */
915 const char *
916 var_role_to_syntax (enum var_role role)
917 {
918   switch (role)
919     {
920     case ROLE_INPUT:
921       return "INPUT";
922
923     case ROLE_TARGET:
924       return "TARGET";
925
926     case ROLE_BOTH:
927       return "BOTH";
928
929     case ROLE_NONE:
930       return "NONE";
931
932     case ROLE_PARTITION:
933       return "PARTITION";
934
935     case ROLE_SPLIT:
936       return "SPLIT";
937
938     default:
939       return "<invalid>";
940     }
941 }
942
943 /* Returns V's role. */
944 enum var_role
945 var_get_role (const struct variable *v)
946 {
947   return v->role;
948 }
949
950 /* Sets V's role to ROLE. */
951 static void
952 var_set_role_quiet (struct variable *v, enum var_role role)
953 {
954   assert (var_role_is_valid (role));
955   v->role = role;
956 }
957
958
959 /* Sets V's role to ROLE. */
960 void
961 var_set_role (struct variable *v, enum var_role role)
962 {
963   struct variable *ov = var_clone (v);
964   var_set_role_quiet (v, role);
965   dict_var_changed (v, VAR_TRAIT_ROLE, ov);
966 }
967 \f
968 /* Returns V's display width, which applies only to GUIs. */
969 int
970 var_get_display_width (const struct variable *v)
971 {
972   return v->display_width;
973 }
974
975 /* Sets V's display width to DISPLAY_WIDTH. */
976 static void
977 var_set_display_width_quiet (struct variable *v, int new_width)
978 {
979   if (v->display_width != new_width)
980     {
981       v->display_width = new_width;
982     }
983 }
984
985 void
986 var_set_display_width (struct variable *v, int new_width)
987 {
988   if (v->display_width != new_width)
989     {
990       struct variable *ov = var_clone (v);
991       var_set_display_width_quiet (v, new_width);
992       dict_var_changed (v, VAR_TRAIT_DISPLAY_WIDTH, ov);
993     }
994 }
995
996 /* Returns the default display width for a variable of the given
997    WIDTH, as set by var_create.  The return value can be used to
998    reset a variable's display width to the default. */
999 int
1000 var_default_display_width (int width)
1001 {
1002   return width == 0 ? 8 : MIN (width, 32);
1003 }
1004 \f
1005 /* Returns true if A is a valid alignment,
1006    false otherwise. */
1007 bool
1008 alignment_is_valid (enum alignment a)
1009 {
1010   return a == ALIGN_LEFT || a == ALIGN_RIGHT || a == ALIGN_CENTRE;
1011 }
1012
1013 /* Returns a string version of alignment A, for display to a user.
1014    The caller may translate the string by passing it to gettext(). */
1015 const char *
1016 alignment_to_string (enum alignment a)
1017 {
1018   assert (a == align[a].value);
1019   return align[a].label;
1020 }
1021
1022 /* Returns a string version of alignment A, for use in PSPP command syntax. */
1023 const char *
1024 alignment_to_syntax (enum alignment a)
1025 {
1026   switch (a)
1027     {
1028     case ALIGN_LEFT:
1029       return "LEFT";
1030
1031     case ALIGN_RIGHT:
1032       return "RIGHT";
1033
1034     case ALIGN_CENTRE:
1035       return "CENTER";
1036
1037     default:
1038       return "Invalid";
1039     }
1040 }
1041
1042 /* Returns V's display alignment, which applies only to GUIs. */
1043 enum alignment
1044 var_get_alignment (const struct variable *v)
1045 {
1046   return v->alignment;
1047 }
1048
1049 /* Sets V's display alignment to ALIGNMENT. */
1050 static void
1051 var_set_alignment_quiet (struct variable *v, enum alignment alignment)
1052 {
1053   assert (alignment_is_valid (alignment));
1054   v->alignment = alignment;
1055 }
1056
1057 /* Sets V's display alignment to ALIGNMENT. */
1058 void
1059 var_set_alignment (struct variable *v, enum alignment alignment)
1060 {
1061   struct variable *ov = var_clone (v);
1062   var_set_alignment_quiet (v, alignment);
1063   dict_var_changed (v, VAR_TRAIT_ALIGNMENT, ov);
1064 }
1065
1066
1067 /* Returns the default display alignment for a variable of the
1068    given TYPE, as set by var_create.  The return value can be
1069    used to reset a variable's display alignment to the default. */
1070 enum alignment
1071 var_default_alignment (enum val_type type)
1072 {
1073   return type == VAL_NUMERIC ? ALIGN_RIGHT : ALIGN_LEFT;
1074 }
1075 \f
1076 /* Whether variables' values should be preserved from case to
1077    case. */
1078
1079 /* Returns true if variable V's value should be left from case to
1080    case, instead of being reset to system-missing or blanks. */
1081 bool
1082 var_get_leave (const struct variable *v)
1083 {
1084   return v->leave;
1085 }
1086
1087 /* Sets V's leave setting to LEAVE. */
1088 static void
1089 var_set_leave_quiet (struct variable *v, bool leave)
1090 {
1091   assert (leave || !var_must_leave (v));
1092   v->leave = leave;
1093 }
1094
1095
1096 /* Sets V's leave setting to LEAVE. */
1097 void
1098 var_set_leave (struct variable *v, bool leave)
1099 {
1100   struct variable *ov = var_clone (v);
1101   var_set_leave_quiet (v, leave);
1102   dict_var_changed (v, VAR_TRAIT_LEAVE, ov);
1103 }
1104
1105
1106 /* Returns true if V must be left from case to case,
1107    false if it can be set either way. */
1108 bool
1109 var_must_leave (const struct variable *v)
1110 {
1111   return var_get_dict_class (v) == DC_SCRATCH;
1112 }
1113 \f
1114 /* Returns the number of short names stored in VAR.
1115
1116    Short names are used only for system and portable file input
1117    and output.  They are upper-case only, not necessarily unique,
1118    and limited to SHORT_NAME_LEN characters (plus a null
1119    terminator).  Ordinarily a variable has at most one short
1120    name, but very long string variables (longer than 255 bytes)
1121    may have more.  A variable might not have any short name at
1122    all if it hasn't been saved to or read from a system or
1123    portable file. */
1124 size_t
1125 var_get_n_short_names (const struct variable *var)
1126 {
1127   return var->n_short_names;
1128 }
1129
1130 /* Returns VAR's short name with the given IDX, if it has one
1131    with that index, or a null pointer otherwise.  Short names may
1132    be sparse: even if IDX is less than the number of short names
1133    in VAR, this function may return a null pointer. */
1134 const char *
1135 var_get_short_name (const struct variable *var, size_t idx)
1136 {
1137   return idx < var->n_short_names ? var->short_names[idx] : NULL;
1138 }
1139
1140 /* Sets VAR's short name with the given IDX to the UTF-8 string SHORT_NAME.
1141    The caller must already have checked that, in the dictionary encoding,
1142    SHORT_NAME is no more than SHORT_NAME_LEN bytes long.  The new short name
1143    will be converted to uppercase.
1144
1145    Specifying a null pointer for SHORT_NAME clears the specified short name. */
1146 void
1147 var_set_short_name (struct variable *var, size_t idx, const char *short_name)
1148 {
1149   struct variable *ov = var_clone (var);
1150
1151   /* Clear old short name numbered IDX, if any. */
1152   if (idx < var->n_short_names)
1153     {
1154       free (var->short_names[idx]);
1155       var->short_names[idx] = NULL;
1156     }
1157
1158   /* Install new short name for IDX. */
1159   if (short_name != NULL)
1160     {
1161       if (idx >= var->n_short_names)
1162         {
1163           size_t n_old = var->n_short_names;
1164           size_t i;
1165           var->n_short_names = MAX (idx * 2, 1);
1166           var->short_names = xnrealloc (var->short_names, var->n_short_names,
1167                                         sizeof *var->short_names);
1168           for (i = n_old; i < var->n_short_names; i++)
1169             var->short_names[i] = NULL;
1170         }
1171       var->short_names[idx] = utf8_to_upper (short_name);
1172     }
1173
1174   dict_var_changed (var, VAR_TRAIT_NAME, ov);
1175 }
1176
1177 /* Clears V's short names. */
1178 void
1179 var_clear_short_names (struct variable *v)
1180 {
1181   size_t i;
1182
1183   for (i = 0; i < v->n_short_names; i++)
1184     free (v->short_names[i]);
1185   free (v->short_names);
1186   v->short_names = NULL;
1187   v->n_short_names = 0;
1188 }
1189 \f
1190 /* Relationship with dictionary. */
1191
1192 /* Returns V's index within its dictionary, the value
1193    for which "dict_get_var (dict, index)" will return V.
1194    V must be in a dictionary. */
1195 size_t
1196 var_get_dict_index (const struct variable *v)
1197 {
1198   assert (var_has_vardict (v));
1199   return vardict_get_dict_index (v->vardict);
1200 }
1201
1202 /* Returns V's index within the case represented by its
1203    dictionary, that is, the value for which "case_data_idx (case,
1204    index)" will return the data for V in that case.
1205    V must be in a dictionary. */
1206 size_t
1207 var_get_case_index (const struct variable *v)
1208 {
1209   assert (var_has_vardict (v));
1210   return vardict_get_case_index (v->vardict);
1211 }
1212 \f
1213 /* Returns variable V's attribute set.  The caller may examine or
1214    modify the attribute set, but must not destroy it.  Destroying
1215    V, or calling var_set_attributes() on V, will also destroy its
1216    attribute set. */
1217 struct attrset *
1218 var_get_attributes (const struct variable *v)
1219 {
1220   return CONST_CAST (struct attrset *, &v->attributes);
1221 }
1222
1223 /* Replaces variable V's attributes set by a copy of ATTRS. */
1224 static void
1225 var_set_attributes_quiet (struct variable *v, const struct attrset *attrs)
1226 {
1227   attrset_destroy (&v->attributes);
1228   attrset_clone (&v->attributes, attrs);
1229 }
1230
1231 /* Replaces variable V's attributes set by a copy of ATTRS. */
1232 void
1233 var_set_attributes (struct variable *v, const struct attrset *attrs)
1234 {
1235   struct variable *ov = var_clone (v);
1236   var_set_attributes_quiet (v, attrs);
1237   dict_var_changed (v, VAR_TRAIT_ATTRIBUTES, ov);
1238 }
1239
1240
1241 /* Returns true if V has any custom attributes, false if it has none. */
1242 bool
1243 var_has_attributes (const struct variable *v)
1244 {
1245   return attrset_count (&v->attributes) > 0;
1246 }
1247 \f
1248
1249 /* Creates and returns a clone of OLD_VAR.  Most properties of
1250    the new variable are copied from OLD_VAR, except:
1251
1252     - The variable's short name is not copied, because there is
1253       no reason to give a new variable with potentially a new
1254       name the same short name.
1255
1256     - The new variable is not added to OLD_VAR's dictionary by
1257       default.  Use dict_clone_var, instead, to do that.
1258 */
1259 struct variable *
1260 var_clone (const struct variable *old_var)
1261 {
1262   struct variable *new_var = var_create (var_get_name (old_var),
1263                                          var_get_width (old_var));
1264
1265   var_set_missing_values_quiet (new_var, var_get_missing_values (old_var));
1266   var_set_print_format_quiet (new_var, var_get_print_format (old_var));
1267   var_set_write_format_quiet (new_var, var_get_write_format (old_var));
1268   var_set_value_labels_quiet (new_var, var_get_value_labels (old_var));
1269   var_set_label_quiet (new_var, var_get_label (old_var));
1270   var_set_measure_quiet (new_var, var_get_measure (old_var));
1271   var_set_role_quiet (new_var, var_get_role (old_var));
1272   var_set_display_width_quiet (new_var, var_get_display_width (old_var));
1273   var_set_alignment_quiet (new_var, var_get_alignment (old_var));
1274   var_set_leave_quiet (new_var, var_get_leave (old_var));
1275   var_set_attributes_quiet (new_var, var_get_attributes (old_var));
1276
1277   return new_var;
1278 }
1279
1280
1281
1282 /* Returns the encoding of values of variable VAR.  (This is actually a
1283    property of the dictionary.)  Returns null if no specific encoding has been
1284    set.  */
1285 const char *
1286 var_get_encoding (const struct variable *var)
1287 {
1288   return (var_has_vardict (var)
1289           ? dict_get_encoding (vardict_get_dictionary (var->vardict))
1290           : NULL);
1291 }
1292 \f
1293 /* Returns V's vardict structure. */
1294 struct vardict_info *
1295 var_get_vardict (const struct variable *v)
1296 {
1297   return CONST_CAST (struct vardict_info *, v->vardict);
1298 }
1299
1300 /* Sets V's vardict data to VARDICT. */
1301 void
1302 var_set_vardict (struct variable *v, struct vardict_info *vardict)
1303 {
1304   v->vardict = vardict;
1305 }
1306
1307 /* Returns true if V has vardict data. */
1308 bool
1309 var_has_vardict (const struct variable *v)
1310 {
1311   return v->vardict != NULL;
1312 }
1313
1314 /* Clears V's vardict data. */
1315 void
1316 var_clear_vardict (struct variable *v)
1317 {
1318   v->vardict = NULL;
1319 }
1320
1321 \f
1322 /*
1323   Returns zero, if W is a missing value for WV or if it is less than zero.
1324   Typically used to force a numerical value into a valid weight.
1325
1326   As a side effect, this function will emit a warning if the value
1327   WARN_ON_INVALID points to a bool which is TRUE.  That bool will be then
1328   set to FALSE.
1329  */
1330 double
1331 var_force_valid_weight (const struct variable *wv, double w, bool *warn_on_invalid)
1332 {
1333   if (w < 0.0 || (wv && var_is_num_missing (wv, w, MV_ANY)))
1334     w = 0.0;
1335
1336   if (w == 0.0 && warn_on_invalid != NULL && *warn_on_invalid)
1337     {
1338       *warn_on_invalid = false;
1339       msg (SW, _("At least one case in the data file had a weight value "
1340                  "that was user-missing, system-missing, zero, or "
1341                  "negative.  These case(s) were ignored."));
1342     }
1343
1344   return w;
1345 }