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.
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.
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.
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/>. */
20 #include "data/variable.h"
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"
41 #include "gl/minmax.h"
42 #include "gl/xalloc.h"
45 #define _(msgid) gettext (msgid)
46 #define N_(msgid) (msgid)
48 /* This should follow the definition in Gtk */
56 const GEnumValue align[] =
58 {ALIGN_LEFT, "left", N_("Left")},
59 {ALIGN_RIGHT, "right", N_("Right")},
60 {ALIGN_CENTRE, "center", N_("Center")},
64 const GEnumValue measure[] =
66 {MEASURE_NOMINAL, "nominal", N_("Nominal")},
67 {MEASURE_ORDINAL, "ordinal", N_("Ordinal")},
68 {MEASURE_SCALE, "scale", N_("Scale")},
72 const GEnumValue role[] =
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")},
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 */
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. */
103 /* Case information. */
104 bool leave; /* Leave value from case to case? */
106 /* Data for use by containing dictionary. */
107 struct vardict_info *vardict;
109 /* Used only for system and portable file input and output.
110 See short-names.h. */
112 size_t short_name_cnt;
114 /* Custom attributes. */
115 struct attrset attributes;
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);
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. */
129 var_create (const char *name, int width)
134 assert (width >= 0 && width <= MAX_STRING);
136 v = xzalloc (sizeof *v);
137 var_set_name_quiet (v, name);
139 mv_init (&v->miss, width);
140 v->leave = var_must_leave (v);
141 type = val_type_from_width (width);
142 v->alignment = var_default_alignment (type);
143 v->measure = var_default_measure (type);
144 v->role = ROLE_INPUT;
145 v->display_width = var_default_display_width (width);
146 v->print = v->write = var_default_formats (width);
147 attrset_init (&v->attributes);
148 ds_init_empty (&v->name_and_label);
155 /* Destroys variable V.
156 V must not belong to a dictionary. If it does, use
157 dict_delete_var instead. */
159 var_destroy__ (struct variable *v)
161 assert (!var_has_vardict (v));
162 mv_destroy (&v->miss);
163 var_clear_short_names (v);
164 val_labs_destroy (v->val_labs);
165 var_set_label_quiet (v, NULL);
166 attrset_destroy (var_get_attributes (v));
168 ds_destroy (&v->name_and_label);
173 var_ref (struct variable *v)
180 var_unref (struct variable *v)
182 if (--v->ref_cnt == 0)
188 /* Variable names. */
190 /* Return variable V's name, as a UTF-8 encoded string. */
192 var_get_name (const struct variable *v)
199 /* Sets V's name to NAME, a UTF-8 encoded string.
200 Do not use this function for a variable in a dictionary. Use
201 dict_rename_var instead. */
203 var_set_name_quiet (struct variable *v, const char *name)
205 assert (!var_has_vardict (v));
208 v->name = xstrdup (name);
209 ds_destroy (&v->name_and_label);
210 ds_init_empty (&v->name_and_label);
213 /* Sets V's name to NAME, a UTF-8 encoded string.
214 Do not use this function for a variable in a dictionary. Use
215 dict_rename_var instead. */
217 var_set_name (struct variable *v, const char *name)
219 struct variable *ov = var_clone (v);
220 var_set_name_quiet (v, name);
221 dict_var_changed (v, VAR_TRAIT_NAME, ov);
224 /* Returns VAR's dictionary class. */
226 var_get_dict_class (const struct variable *var)
228 return dict_class_from_id (var->name);
231 /* A hsh_compare_func that orders variables A and B by their
234 compare_vars_by_name (const void *a_, const void *b_, const void *aux UNUSED)
236 const struct variable *a = a_;
237 const struct variable *b = b_;
239 return utf8_strcasecmp (a->name, b->name);
242 /* A hsh_hash_func that hashes variable V based on its name. */
244 hash_var_by_name (const void *v_, const void *aux UNUSED)
246 const struct variable *v = v_;
248 return utf8_hash_case_string (v->name, 0);
251 /* A hsh_compare_func that orders pointers to variables A and B
254 compare_var_ptrs_by_name (const void *a_, const void *b_,
255 const void *aux UNUSED)
257 struct variable *const *a = a_;
258 struct variable *const *b = b_;
260 return utf8_strcasecmp (var_get_name (*a), var_get_name (*b));
263 /* A hsh_compare_func that orders pointers to variables A and B
264 by their dictionary indexes. */
266 compare_var_ptrs_by_dict_index (const void *a_, const void *b_,
267 const void *aux UNUSED)
269 struct variable *const *a = a_;
270 struct variable *const *b = b_;
271 size_t a_index = var_get_dict_index (*a);
272 size_t b_index = var_get_dict_index (*b);
274 return a_index < b_index ? -1 : a_index > b_index;
277 /* A hsh_hash_func that hashes pointer to variable V based on its
280 hash_var_ptr_by_name (const void *v_, const void *aux UNUSED)
282 struct variable *const *v = v_;
284 return utf8_hash_case_string (var_get_name (*v), 0);
287 /* Returns the type of variable V. */
289 var_get_type (const struct variable *v)
291 return val_type_from_width (v->width);
294 /* Returns the width of variable V. */
296 var_get_width (const struct variable *v)
302 var_set_width_and_formats (struct variable *v, int new_width,
303 const struct fmt_spec *print, const struct fmt_spec *write)
306 unsigned int traits = 0;
310 if (var_has_missing_values (v))
312 if (mv_is_resizable (&v->miss, new_width))
313 mv_resize (&v->miss, new_width);
316 mv_destroy (&v->miss);
317 mv_init (&v->miss, new_width);
319 traits |= VAR_TRAIT_MISSING_VALUES;
322 if (v->val_labs != NULL)
324 if (val_labs_can_set_width (v->val_labs, new_width))
325 val_labs_set_width (v->val_labs, new_width);
328 val_labs_destroy (v->val_labs);
331 traits |= VAR_TRAIT_VALUE_LABELS;
334 if (fmt_resize (&v->print, new_width))
335 traits |= VAR_TRAIT_PRINT_FORMAT;
337 if (fmt_resize (&v->write, new_width))
338 traits |= VAR_TRAIT_WRITE_FORMAT;
340 if (v->width != new_width)
342 v->width = new_width;
343 traits |= VAR_TRAIT_WIDTH;
348 var_set_print_format_quiet (v, print);
349 traits |= VAR_TRAIT_PRINT_FORMAT;
354 var_set_write_format_quiet (v, write);
355 traits |= VAR_TRAIT_WRITE_FORMAT;
359 dict_var_changed (v, traits, ov);
362 /* Changes the width of V to NEW_WIDTH.
363 This function should be used cautiously. */
365 var_set_width (struct variable *v, int new_width)
367 const int old_width = v->width;
369 if (old_width == new_width)
372 var_set_width_and_formats (v, new_width, NULL, NULL);
378 /* Returns true if variable V is numeric, false otherwise. */
380 var_is_numeric (const struct variable *v)
382 return var_get_type (v) == VAL_NUMERIC;
385 /* Returns true if variable V is a string variable, false
388 var_is_alpha (const struct variable *v)
390 return var_get_type (v) == VAL_STRING;
393 /* Returns variable V's missing values. */
394 const struct missing_values *
395 var_get_missing_values (const struct variable *v)
400 /* Sets variable V's missing values to MISS, which must be of V's
401 width or at least resizable to V's width.
402 If MISS is null, then V's missing values, if any, are
405 var_set_missing_values_quiet (struct variable *v, const struct missing_values *miss)
409 assert (mv_is_resizable (miss, v->width));
410 mv_destroy (&v->miss);
411 mv_copy (&v->miss, miss);
412 mv_resize (&v->miss, v->width);
418 /* Sets variable V's missing values to MISS, which must be of V's
419 width or at least resizable to V's width.
420 If MISS is null, then V's missing values, if any, are
423 var_set_missing_values (struct variable *v, const struct missing_values *miss)
425 struct variable *ov = var_clone (v);
426 var_set_missing_values_quiet (v, miss);
427 dict_var_changed (v, VAR_TRAIT_MISSING_VALUES, ov);
430 /* Sets variable V to have no user-missing values. */
432 var_clear_missing_values (struct variable *v)
434 var_set_missing_values (v, NULL);
437 /* Returns true if V has any user-missing values,
440 var_has_missing_values (const struct variable *v)
442 return !mv_is_empty (&v->miss);
445 /* Returns true if VALUE is in the given CLASS of missing values
446 in V, false otherwise. */
448 var_is_value_missing (const struct variable *v, const union value *value,
451 return mv_is_value_missing (&v->miss, value, class);
454 /* Returns true if D is in the given CLASS of missing values in
456 V must be a numeric variable. */
458 var_is_num_missing (const struct variable *v, double d, enum mv_class class)
460 return mv_is_num_missing (&v->miss, d, class);
463 /* Returns true if S[] is a missing value for V, false otherwise.
464 S[] must contain exactly as many characters as V's width.
465 V must be a string variable. */
467 var_is_str_missing (const struct variable *v, const uint8_t s[],
470 return mv_is_str_missing (&v->miss, s, class);
473 /* Returns variable V's value labels,
474 possibly a null pointer if it has none. */
475 const struct val_labs *
476 var_get_value_labels (const struct variable *v)
481 /* Returns true if variable V has at least one value label. */
483 var_has_value_labels (const struct variable *v)
485 return val_labs_count (v->val_labs) > 0;
488 /* Sets variable V's value labels to a copy of VLS,
489 which must have a width equal to V's width or one that can be
490 changed to V's width.
491 If VLS is null, then V's value labels, if any, are removed. */
493 var_set_value_labels_quiet (struct variable *v, const struct val_labs *vls)
495 val_labs_destroy (v->val_labs);
500 assert (val_labs_can_set_width (vls, v->width));
501 v->val_labs = val_labs_clone (vls);
502 val_labs_set_width (v->val_labs, v->width);
507 /* Sets variable V's value labels to a copy of VLS,
508 which must have a width equal to V's width or one that can be
509 changed to V's width.
510 If VLS is null, then V's value labels, if any, are removed. */
512 var_set_value_labels (struct variable *v, const struct val_labs *vls)
514 struct variable *ov = var_clone (v);
515 var_set_value_labels_quiet (v, vls);
516 dict_var_changed (v, VAR_TRAIT_LABEL, ov);
520 /* Makes sure that V has a set of value labels,
521 by assigning one to it if necessary. */
523 alloc_value_labels (struct variable *v)
525 if (v->val_labs == NULL)
526 v->val_labs = val_labs_create (v->width);
529 /* Attempts to add a value label with the given VALUE and UTF-8 encoded LABEL
530 to V. Returns true if successful, false otherwise (probably due to an
533 In LABEL, the two-byte sequence "\\n" is interpreted as a new-line. */
535 var_add_value_label (struct variable *v,
536 const union value *value, const char *label)
538 alloc_value_labels (v);
539 return val_labs_add (v->val_labs, value, label);
542 /* Adds or replaces a value label with the given VALUE and UTF-8 encoded LABEL
545 In LABEL, the two-byte sequence "\\n" is interpreted as a new-line. */
547 var_replace_value_label (struct variable *v,
548 const union value *value, const char *label)
550 alloc_value_labels (v);
551 val_labs_replace (v->val_labs, value, label);
554 /* Removes V's value labels, if any. */
556 var_clear_value_labels (struct variable *v)
558 var_set_value_labels (v, NULL);
561 /* Returns the label associated with VALUE for variable V, as a UTF-8 string in
562 a format suitable for output, or a null pointer if none. */
564 var_lookup_value_label (const struct variable *v, const union value *value)
566 return val_labs_find (v->val_labs, value);
570 Append to STR the string representation of VALUE for variable V.
571 STR must be a pointer to an initialised struct string.
574 append_value (const struct variable *v, const union value *value,
577 char *s = data_out (value, var_get_encoding (v), &v->print);
578 struct substring ss = ss_cstr (s);
579 ss_rtrim (&ss, ss_cstr (" "));
580 ds_put_substring (str, ss);
585 var_append_value_name__ (const struct variable *v, const union value *value,
586 enum settings_value_show show, struct string *str)
588 const char *label = var_lookup_value_label (v, value);
592 case SETTINGS_VALUE_SHOW_VALUE:
593 append_value (v, value, str);
597 case SETTINGS_VALUE_SHOW_LABEL:
599 ds_put_cstr (str, label);
601 append_value (v, value, str);
604 case SETTINGS_VALUE_SHOW_BOTH:
605 append_value (v, value, str);
607 ds_put_format (str, " %s", label);
612 /* Append STR with a string representing VALUE for variable V.
613 That is, if VALUE has a label, append that label,
614 otherwise format VALUE and append the formatted string.
615 STR must be a pointer to an initialised struct string.
618 var_append_value_name (const struct variable *v, const union value *value,
621 var_append_value_name__ (v, value, settings_get_show_values (), str);
624 /* Print and write formats. */
626 /* Returns V's print format specification. */
627 const struct fmt_spec *
628 var_get_print_format (const struct variable *v)
633 /* Sets V's print format specification to PRINT, which must be a
634 valid format specification for a variable of V's width
635 (ordinarily an output format, but input formats are not
638 var_set_print_format_quiet (struct variable *v, const struct fmt_spec *print)
640 if (!fmt_equal (&v->print, print))
642 assert (fmt_check_width_compat (print, v->width));
647 /* Sets V's print format specification to PRINT, which must be a
648 valid format specification for a variable of V's width
649 (ordinarily an output format, but input formats are not
652 var_set_print_format (struct variable *v, const struct fmt_spec *print)
654 struct variable *ov = var_clone (v);
655 var_set_print_format_quiet (v, print);
656 dict_var_changed (v, VAR_TRAIT_PRINT_FORMAT, ov);
659 /* Returns V's write format specification. */
660 const struct fmt_spec *
661 var_get_write_format (const struct variable *v)
666 /* Sets V's write format specification to WRITE, which must be a
667 valid format specification for a variable of V's width
668 (ordinarily an output format, but input formats are not
671 var_set_write_format_quiet (struct variable *v, const struct fmt_spec *write)
673 if (!fmt_equal (&v->write, write))
675 assert (fmt_check_width_compat (write, v->width));
680 /* Sets V's write format specification to WRITE, which must be a
681 valid format specification for a variable of V's width
682 (ordinarily an output format, but input formats are not
685 var_set_write_format (struct variable *v, const struct fmt_spec *write)
687 struct variable *ov = var_clone (v);
688 var_set_write_format_quiet (v, write);
689 dict_var_changed (v, VAR_TRAIT_WRITE_FORMAT, ov);
693 /* Sets V's print and write format specifications to FORMAT,
694 which must be a valid format specification for a variable of
695 V's width (ordinarily an output format, but input formats are
698 var_set_both_formats (struct variable *v, const struct fmt_spec *format)
700 struct variable *ov = var_clone (v);
701 var_set_print_format_quiet (v, format);
702 var_set_write_format_quiet (v, format);
703 dict_var_changed (v, VAR_TRAIT_PRINT_FORMAT | VAR_TRAIT_WRITE_FORMAT, ov);
706 /* Returns the default print and write format for a variable of
707 the given TYPE, as set by var_create. The return value can be
708 used to reset a variable's print and write formats to the
711 var_default_formats (int width)
714 ? fmt_for_output (FMT_F, 8, 2)
715 : fmt_for_output (FMT_A, width, 0));
721 /* Update the combined name and label string if necessary */
723 update_vl_string (const struct variable *v)
725 /* Cast away const! */
726 struct string *str = (struct string *) &v->name_and_label;
728 if (ds_is_empty (str))
731 ds_put_format (str, _("%s (%s)"), v->label, v->name);
733 ds_put_cstr (str, v->name);
738 /* Return a string representing this variable, in the form most
739 appropriate from a human factors perspective, that is, its
740 variable label if it has one, otherwise its name. */
742 var_to_string (const struct variable *v)
744 switch (settings_get_show_variables ())
746 case SETTINGS_VALUE_SHOW_VALUE:
749 case SETTINGS_VALUE_SHOW_LABEL:
751 return v->label != NULL ? v->label : v->name;
753 case SETTINGS_VALUE_SHOW_BOTH:
754 update_vl_string (v);
755 return ds_cstr (&v->name_and_label);
759 /* Returns V's variable label, or a null pointer if it has none. */
761 var_get_label (const struct variable *v)
766 /* Sets V's variable label to UTF-8 encoded string LABEL, stripping off leading
767 and trailing white space. If LABEL is a null pointer or if LABEL is an
768 empty string (after stripping white space), then V's variable label (if any)
771 var_set_label_quiet (struct variable *v, const char *label)
776 if (label != NULL && label[strspn (label, CC_SPACES)])
777 v->label = xstrdup (label);
779 ds_destroy (&v->name_and_label);
780 ds_init_empty (&v->name_and_label);
785 /* Sets V's variable label to UTF-8 encoded string LABEL, stripping off leading
786 and trailing white space. If LABEL is a null pointer or if LABEL is an
787 empty string (after stripping white space), then V's variable label (if any)
790 var_set_label (struct variable *v, const char *label)
792 struct variable *ov = var_clone (v);
793 var_set_label_quiet (v, label);
794 dict_var_changed (v, VAR_TRAIT_LABEL, ov);
798 /* Removes any variable label from V. */
800 var_clear_label (struct variable *v)
802 var_set_label (v, NULL);
805 /* Returns true if V has a variable V,
808 var_has_label (const struct variable *v)
810 return v->label != NULL;
813 /* Returns true if M is a valid variable measurement level,
816 measure_is_valid (enum measure m)
818 return m == MEASURE_NOMINAL || m == MEASURE_ORDINAL || m == MEASURE_SCALE;
821 /* Returns a string version of measurement level M, for display to a user.
822 The caller may translate the string by passing it to gettext(). */
824 measure_to_string (enum measure m)
826 assert (m == measure[m].value);
827 return measure[m].label;
830 /* Returns a string version of measurement level M, for use in PSPP command
833 measure_to_syntax (enum measure m)
837 case MEASURE_NOMINAL:
840 case MEASURE_ORDINAL:
851 /* Returns V's measurement level. */
853 var_get_measure (const struct variable *v)
858 /* Sets V's measurement level to MEASURE. */
860 var_set_measure_quiet (struct variable *v, enum measure measure)
862 assert (measure_is_valid (measure));
863 v->measure = measure;
867 /* Sets V's measurement level to MEASURE. */
869 var_set_measure (struct variable *v, enum measure measure)
871 struct variable *ov = var_clone (v);
872 var_set_measure_quiet (v, measure);
873 dict_var_changed (v, VAR_TRAIT_MEASURE, ov);
877 /* Returns the default measurement level for a variable of the
878 given TYPE, as set by var_create. The return value can be
879 used to reset a variable's measurement level to the
882 var_default_measure (enum val_type type)
884 return type == VAL_NUMERIC ? MEASURE_SCALE : MEASURE_NOMINAL;
887 /* Returns true if M is a valid variable role,
890 var_role_is_valid (enum var_role role)
907 /* Returns a string version of ROLE, for display to a user.
908 The caller may translate the string by passing it to gettext(). */
910 var_role_to_string (enum var_role r)
912 assert (r == role[r].value);
913 return role[r].label;
916 /* Returns a string version of ROLE, for use in PSPP comamnd syntax. */
918 var_role_to_syntax (enum var_role role)
945 /* Returns V's role. */
947 var_get_role (const struct variable *v)
952 /* Sets V's role to ROLE. */
954 var_set_role_quiet (struct variable *v, enum var_role role)
956 assert (var_role_is_valid (role));
961 /* Sets V's role to ROLE. */
963 var_set_role (struct variable *v, enum var_role role)
965 struct variable *ov = var_clone (v);
966 var_set_role_quiet (v, role);
967 dict_var_changed (v, VAR_TRAIT_ROLE, ov);
970 /* Returns V's display width, which applies only to GUIs. */
972 var_get_display_width (const struct variable *v)
974 return v->display_width;
977 /* Sets V's display width to DISPLAY_WIDTH. */
979 var_set_display_width_quiet (struct variable *v, int new_width)
981 if (v->display_width != new_width)
983 v->display_width = new_width;
988 var_set_display_width (struct variable *v, int new_width)
990 if (v->display_width != new_width)
992 struct variable *ov = var_clone (v);
993 var_set_display_width_quiet (v, new_width);
994 dict_var_changed (v, VAR_TRAIT_DISPLAY_WIDTH, ov);
998 /* Returns the default display width for a variable of the given
999 WIDTH, as set by var_create. The return value can be used to
1000 reset a variable's display width to the default. */
1002 var_default_display_width (int width)
1004 return width == 0 ? 8 : MIN (width, 32);
1007 /* Returns true if A is a valid alignment,
1010 alignment_is_valid (enum alignment a)
1012 return a == ALIGN_LEFT || a == ALIGN_RIGHT || a == ALIGN_CENTRE;
1015 /* Returns a string version of alignment A, for display to a user.
1016 The caller may translate the string by passing it to gettext(). */
1018 alignment_to_string (enum alignment a)
1020 assert (a == align[a].value);
1021 return align[a].label;
1024 /* Returns a string version of alignment A, for use in PSPP command syntax. */
1026 alignment_to_syntax (enum alignment a)
1044 /* Returns V's display alignment, which applies only to GUIs. */
1046 var_get_alignment (const struct variable *v)
1048 return v->alignment;
1051 /* Sets V's display alignment to ALIGNMENT. */
1053 var_set_alignment_quiet (struct variable *v, enum alignment alignment)
1055 assert (alignment_is_valid (alignment));
1056 v->alignment = alignment;
1059 /* Sets V's display alignment to ALIGNMENT. */
1061 var_set_alignment (struct variable *v, enum alignment alignment)
1063 struct variable *ov = var_clone (v);
1064 var_set_alignment_quiet (v, alignment);
1065 dict_var_changed (v, VAR_TRAIT_ALIGNMENT, ov);
1069 /* Returns the default display alignment for a variable of the
1070 given TYPE, as set by var_create. The return value can be
1071 used to reset a variable's display alignment to the default. */
1073 var_default_alignment (enum val_type type)
1075 return type == VAL_NUMERIC ? ALIGN_RIGHT : ALIGN_LEFT;
1078 /* Whether variables' values should be preserved from case to
1081 /* Returns true if variable V's value should be left from case to
1082 case, instead of being reset to system-missing or blanks. */
1084 var_get_leave (const struct variable *v)
1089 /* Sets V's leave setting to LEAVE. */
1091 var_set_leave_quiet (struct variable *v, bool leave)
1093 assert (leave || !var_must_leave (v));
1098 /* Sets V's leave setting to LEAVE. */
1100 var_set_leave (struct variable *v, bool leave)
1102 struct variable *ov = var_clone (v);
1103 var_set_leave_quiet (v, leave);
1104 dict_var_changed (v, VAR_TRAIT_LEAVE, ov);
1108 /* Returns true if V must be left from case to case,
1109 false if it can be set either way. */
1111 var_must_leave (const struct variable *v)
1113 return var_get_dict_class (v) == DC_SCRATCH;
1116 /* Returns the number of short names stored in VAR.
1118 Short names are used only for system and portable file input
1119 and output. They are upper-case only, not necessarily unique,
1120 and limited to SHORT_NAME_LEN characters (plus a null
1121 terminator). Ordinarily a variable has at most one short
1122 name, but very long string variables (longer than 255 bytes)
1123 may have more. A variable might not have any short name at
1124 all if it hasn't been saved to or read from a system or
1127 var_get_short_name_cnt (const struct variable *var)
1129 return var->short_name_cnt;
1132 /* Returns VAR's short name with the given IDX, if it has one
1133 with that index, or a null pointer otherwise. Short names may
1134 be sparse: even if IDX is less than the number of short names
1135 in VAR, this function may return a null pointer. */
1137 var_get_short_name (const struct variable *var, size_t idx)
1139 return idx < var->short_name_cnt ? var->short_names[idx] : NULL;
1142 /* Sets VAR's short name with the given IDX to the UTF-8 string SHORT_NAME.
1143 The caller must already have checked that, in the dictionary encoding,
1144 SHORT_NAME is no more than SHORT_NAME_LEN bytes long. The new short name
1145 will be converted to uppercase.
1147 Specifying a null pointer for SHORT_NAME clears the specified short name. */
1149 var_set_short_name (struct variable *var, size_t idx, const char *short_name)
1151 struct variable *ov = var_clone (var);
1153 /* Clear old short name numbered IDX, if any. */
1154 if (idx < var->short_name_cnt)
1156 free (var->short_names[idx]);
1157 var->short_names[idx] = NULL;
1160 /* Install new short name for IDX. */
1161 if (short_name != NULL)
1163 if (idx >= var->short_name_cnt)
1165 size_t old_cnt = var->short_name_cnt;
1167 var->short_name_cnt = MAX (idx * 2, 1);
1168 var->short_names = xnrealloc (var->short_names, var->short_name_cnt,
1169 sizeof *var->short_names);
1170 for (i = old_cnt; i < var->short_name_cnt; i++)
1171 var->short_names[i] = NULL;
1173 var->short_names[idx] = utf8_to_upper (short_name);
1176 dict_var_changed (var, VAR_TRAIT_NAME, ov);
1179 /* Clears V's short names. */
1181 var_clear_short_names (struct variable *v)
1185 for (i = 0; i < v->short_name_cnt; i++)
1186 free (v->short_names[i]);
1187 free (v->short_names);
1188 v->short_names = NULL;
1189 v->short_name_cnt = 0;
1192 /* Relationship with dictionary. */
1194 /* Returns V's index within its dictionary, the value
1195 for which "dict_get_var (dict, index)" will return V.
1196 V must be in a dictionary. */
1198 var_get_dict_index (const struct variable *v)
1200 assert (var_has_vardict (v));
1201 return vardict_get_dict_index (v->vardict);
1204 /* Returns V's index within the case represented by its
1205 dictionary, that is, the value for which "case_data_idx (case,
1206 index)" will return the data for V in that case.
1207 V must be in a dictionary. */
1209 var_get_case_index (const struct variable *v)
1211 assert (var_has_vardict (v));
1212 return vardict_get_case_index (v->vardict);
1215 /* Returns variable V's attribute set. The caller may examine or
1216 modify the attribute set, but must not destroy it. Destroying
1217 V, or calling var_set_attributes() on V, will also destroy its
1220 var_get_attributes (const struct variable *v)
1222 return CONST_CAST (struct attrset *, &v->attributes);
1225 /* Replaces variable V's attributes set by a copy of ATTRS. */
1227 var_set_attributes_quiet (struct variable *v, const struct attrset *attrs)
1229 attrset_destroy (&v->attributes);
1230 attrset_clone (&v->attributes, attrs);
1233 /* Replaces variable V's attributes set by a copy of ATTRS. */
1235 var_set_attributes (struct variable *v, const struct attrset *attrs)
1237 struct variable *ov = var_clone (v);
1238 var_set_attributes_quiet (v, attrs);
1239 dict_var_changed (v, VAR_TRAIT_ATTRIBUTES, ov);
1243 /* Returns true if V has any custom attributes, false if it has none. */
1245 var_has_attributes (const struct variable *v)
1247 return attrset_count (&v->attributes) > 0;
1251 /* Creates and returns a clone of OLD_VAR. Most properties of
1252 the new variable are copied from OLD_VAR, except:
1254 - The variable's short name is not copied, because there is
1255 no reason to give a new variable with potentially a new
1256 name the same short name.
1258 - The new variable is not added to OLD_VAR's dictionary by
1259 default. Use dict_clone_var, instead, to do that.
1262 var_clone (const struct variable *old_var)
1264 struct variable *new_var = var_create (var_get_name (old_var),
1265 var_get_width (old_var));
1267 var_set_missing_values_quiet (new_var, var_get_missing_values (old_var));
1268 var_set_print_format_quiet (new_var, var_get_print_format (old_var));
1269 var_set_write_format_quiet (new_var, var_get_write_format (old_var));
1270 var_set_value_labels_quiet (new_var, var_get_value_labels (old_var));
1271 var_set_label_quiet (new_var, var_get_label (old_var));
1272 var_set_measure_quiet (new_var, var_get_measure (old_var));
1273 var_set_role_quiet (new_var, var_get_role (old_var));
1274 var_set_display_width_quiet (new_var, var_get_display_width (old_var));
1275 var_set_alignment_quiet (new_var, var_get_alignment (old_var));
1276 var_set_leave_quiet (new_var, var_get_leave (old_var));
1277 var_set_attributes_quiet (new_var, var_get_attributes (old_var));
1284 /* Returns the encoding of values of variable VAR. (This is actually a
1285 property of the dictionary.) Returns null if no specific encoding has been
1288 var_get_encoding (const struct variable *var)
1290 return (var_has_vardict (var)
1291 ? dict_get_encoding (vardict_get_dictionary (var->vardict))
1295 /* Returns V's vardict structure. */
1296 struct vardict_info *
1297 var_get_vardict (const struct variable *v)
1299 return CONST_CAST (struct vardict_info *, v->vardict);
1302 /* Sets V's vardict data to VARDICT. */
1304 var_set_vardict (struct variable *v, struct vardict_info *vardict)
1306 v->vardict = vardict;
1309 /* Returns true if V has vardict data. */
1311 var_has_vardict (const struct variable *v)
1313 return v->vardict != NULL;
1316 /* Clears V's vardict data. */
1318 var_clear_vardict (struct variable *v)
1325 Returns zero, if W is a missing value for WV or if it is less than zero.
1326 Typically used to force a numerical value into a valid weight.
1328 As a side effect, this function will emit a warning if the value
1329 WARN_ON_INVALID points to a bool which is TRUE. That bool will be then
1333 var_force_valid_weight (const struct variable *wv, double w, bool *warn_on_invalid)
1335 if (w < 0.0 || (wv && var_is_num_missing (wv, w, MV_ANY)))
1338 if (w == 0.0 && warn_on_invalid != NULL && *warn_on_invalid)
1340 *warn_on_invalid = false;
1341 msg (SW, _("At least one case in the data file had a weight value "
1342 "that was user-missing, system-missing, zero, or "
1343 "negative. These case(s) were ignored."));