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 n_short_names;
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)
133 assert (width >= 0 && width <= MAX_STRING);
135 struct variable *v = XZALLOC (struct variable);
136 var_set_name_quiet (v, name);
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);
154 /* Destroys variable V.
155 V must not belong to a dictionary. If it does, use
156 dict_delete_var instead. */
158 var_destroy__ (struct variable *v)
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));
167 ds_destroy (&v->name_and_label);
172 var_ref (struct variable *v)
179 var_unref (struct variable *v)
181 if (--v->ref_cnt == 0)
187 /* Variable names. */
189 /* Return variable V's name, as a UTF-8 encoded string. */
191 var_get_name (const struct variable *v)
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. */
202 var_set_name_quiet (struct variable *v, const char *name)
204 assert (!var_has_vardict (v));
207 v->name = xstrdup (name);
208 ds_destroy (&v->name_and_label);
209 ds_init_empty (&v->name_and_label);
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. */
216 var_set_name (struct variable *v, const char *name)
218 struct variable *ov = var_clone (v);
219 var_set_name_quiet (v, name);
220 dict_var_changed (v, VAR_TRAIT_NAME, ov);
223 /* Returns VAR's dictionary class. */
225 var_get_dict_class (const struct variable *var)
227 return dict_class_from_id (var->name);
230 /* A hsh_compare_func that orders variables A and B by their
233 compare_vars_by_name (const void *a_, const void *b_, const void *aux UNUSED)
235 const struct variable *a = a_;
236 const struct variable *b = b_;
238 return utf8_strcasecmp (a->name, b->name);
241 /* A hsh_hash_func that hashes variable V based on its name. */
243 hash_var_by_name (const void *v_, const void *aux UNUSED)
245 const struct variable *v = v_;
247 return utf8_hash_case_string (v->name, 0);
250 /* A hsh_compare_func that orders pointers to variables A and B
253 compare_var_ptrs_by_name (const void *a_, const void *b_,
254 const void *aux UNUSED)
256 struct variable *const *a = a_;
257 struct variable *const *b = b_;
259 return utf8_strcasecmp (var_get_name (*a), var_get_name (*b));
262 /* A hsh_compare_func that orders pointers to variables A and B
263 by their dictionary indexes. */
265 compare_var_ptrs_by_dict_index (const void *a_, const void *b_,
266 const void *aux UNUSED)
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);
273 return a_index < b_index ? -1 : a_index > b_index;
276 /* A hsh_hash_func that hashes pointer to variable V based on its
279 hash_var_ptr_by_name (const void *v_, const void *aux UNUSED)
281 struct variable *const *v = v_;
283 return utf8_hash_case_string (var_get_name (*v), 0);
286 /* Returns the type of variable V. */
288 var_get_type (const struct variable *v)
290 return val_type_from_width (v->width);
293 /* Returns the width of variable V. */
295 var_get_width (const struct variable *v)
301 var_set_width_and_formats (struct variable *v, int new_width,
302 const struct fmt_spec *print, const struct fmt_spec *write)
305 unsigned int traits = 0;
309 if (mv_is_resizable (&v->miss, new_width))
310 mv_resize (&v->miss, new_width);
313 mv_destroy (&v->miss);
314 mv_init (&v->miss, new_width);
316 if (new_width != var_get_width (v))
317 traits |= VAR_TRAIT_MISSING_VALUES;
319 if (v->val_labs != NULL)
321 if (val_labs_can_set_width (v->val_labs, new_width))
322 val_labs_set_width (v->val_labs, new_width);
325 val_labs_destroy (v->val_labs);
328 traits |= VAR_TRAIT_VALUE_LABELS;
331 if (fmt_resize (&v->print, new_width))
332 traits |= VAR_TRAIT_PRINT_FORMAT;
334 if (fmt_resize (&v->write, new_width))
335 traits |= VAR_TRAIT_WRITE_FORMAT;
337 if (v->width != new_width)
339 v->width = new_width;
340 traits |= VAR_TRAIT_WIDTH;
345 var_set_print_format_quiet (v, print);
346 traits |= VAR_TRAIT_PRINT_FORMAT;
351 var_set_write_format_quiet (v, write);
352 traits |= VAR_TRAIT_WRITE_FORMAT;
356 dict_var_changed (v, traits, ov);
359 /* Changes the width of V to NEW_WIDTH.
360 This function should be used cautiously. */
362 var_set_width (struct variable *v, int new_width)
364 const int old_width = v->width;
366 if (old_width == new_width)
369 var_set_width_and_formats (v, new_width, NULL, NULL);
375 /* Returns true if variable V is numeric, false otherwise. */
377 var_is_numeric (const struct variable *v)
379 return var_get_type (v) == VAL_NUMERIC;
382 /* Returns true if variable V is a string variable, false
385 var_is_alpha (const struct variable *v)
387 return var_get_type (v) == VAL_STRING;
390 /* Returns variable V's missing values. */
391 const struct missing_values *
392 var_get_missing_values (const struct variable *v)
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
402 var_set_missing_values_quiet (struct variable *v, const struct missing_values *miss)
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);
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
420 var_set_missing_values (struct variable *v, const struct missing_values *miss)
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);
427 /* Sets variable V to have no user-missing values. */
429 var_clear_missing_values (struct variable *v)
431 var_set_missing_values (v, NULL);
434 /* Returns true if V has any user-missing values,
437 var_has_missing_values (const struct variable *v)
439 return !mv_is_empty (&v->miss);
442 /* Returns MV_SYSTEM if VALUE is system-missing, MV_USER if VALUE is
443 user-missing for V, and otherwise 0. */
445 var_is_value_missing (const struct variable *v, const union value *value)
447 return mv_is_value_missing (&v->miss, value);
450 /* Returns MV_SYSTEM if VALUE is system-missing, MV_USER if VALUE is
451 user-missing for V, and otherwise 0. V must be a numeric variable. */
453 var_is_num_missing (const struct variable *v, double d)
455 return mv_is_num_missing (&v->miss, d);
458 /* Returns MV_USER if VALUE is user-missing for V and otherwise 0. V must be
459 a string variable. */
461 var_is_str_missing (const struct variable *v, const uint8_t s[])
463 return mv_is_str_missing (&v->miss, s);
466 /* Returns variable V's value labels,
467 possibly a null pointer if it has none. */
468 const struct val_labs *
469 var_get_value_labels (const struct variable *v)
474 /* Returns true if variable V has at least one value label. */
476 var_has_value_labels (const struct variable *v)
478 return val_labs_count (v->val_labs) > 0;
481 /* Sets variable V's value labels to a copy of VLS,
482 which must have a width equal to V's width or one that can be
483 changed to V's width.
484 If VLS is null, then V's value labels, if any, are removed. */
486 var_set_value_labels_quiet (struct variable *v, const struct val_labs *vls)
488 val_labs_destroy (v->val_labs);
493 assert (val_labs_can_set_width (vls, v->width));
494 v->val_labs = val_labs_clone (vls);
495 val_labs_set_width (v->val_labs, v->width);
500 /* Sets variable V's value labels to a copy of VLS,
501 which must have a width equal to V's width or one that can be
502 changed to V's width.
503 If VLS is null, then V's value labels, if any, are removed. */
505 var_set_value_labels (struct variable *v, const struct val_labs *vls)
507 struct variable *ov = var_clone (v);
508 var_set_value_labels_quiet (v, vls);
509 dict_var_changed (v, VAR_TRAIT_LABEL, ov);
513 /* Makes sure that V has a set of value labels,
514 by assigning one to it if necessary. */
516 alloc_value_labels (struct variable *v)
518 if (v->val_labs == NULL)
519 v->val_labs = val_labs_create (v->width);
522 /* Attempts to add a value label with the given VALUE and UTF-8 encoded LABEL
523 to V. Returns true if successful, false otherwise (probably due to an
526 In LABEL, the two-byte sequence "\\n" is interpreted as a new-line. */
528 var_add_value_label (struct variable *v,
529 const union value *value, const char *label)
531 alloc_value_labels (v);
532 return val_labs_add (v->val_labs, value, label);
535 /* Adds or replaces a value label with the given VALUE and UTF-8 encoded LABEL
538 In LABEL, the two-byte sequence "\\n" is interpreted as a new-line. */
540 var_replace_value_label (struct variable *v,
541 const union value *value, const char *label)
543 alloc_value_labels (v);
544 val_labs_replace (v->val_labs, value, label);
547 /* Removes V's value labels, if any. */
549 var_clear_value_labels (struct variable *v)
551 var_set_value_labels (v, NULL);
554 /* Returns the label associated with VALUE for variable V, as a UTF-8 string in
555 a format suitable for output, or a null pointer if none. */
557 var_lookup_value_label (const struct variable *v, const union value *value)
559 return val_labs_find (v->val_labs, value);
563 Append to STR the string representation of VALUE for variable V.
564 STR must be a pointer to an initialised struct string.
567 append_value (const struct variable *v, const union value *value,
570 char *s = data_out (value, var_get_encoding (v), &v->print,
571 settings_get_fmt_settings ());
572 struct substring ss = ss_cstr (s);
573 ss_rtrim (&ss, ss_cstr (" "));
574 ds_put_substring (str, ss);
579 var_append_value_name__ (const struct variable *v, const union value *value,
580 enum settings_value_show show, struct string *str)
582 const char *label = var_lookup_value_label (v, value);
586 case SETTINGS_VALUE_SHOW_VALUE:
587 append_value (v, value, str);
591 case SETTINGS_VALUE_SHOW_LABEL:
593 ds_put_cstr (str, label);
595 append_value (v, value, str);
598 case SETTINGS_VALUE_SHOW_BOTH:
599 append_value (v, value, str);
601 ds_put_format (str, " %s", label);
606 /* Append STR with a string representing VALUE for variable V.
607 That is, if VALUE has a label, append that label,
608 otherwise format VALUE and append the formatted string.
609 STR must be a pointer to an initialised struct string.
612 var_append_value_name (const struct variable *v, const union value *value,
615 var_append_value_name__ (v, value, settings_get_show_values (), str);
618 /* Print and write formats. */
620 /* Returns V's print format specification. */
621 const struct fmt_spec *
622 var_get_print_format (const struct variable *v)
627 /* Sets V's print format specification to PRINT, which must be a
628 valid format specification for a variable of V's width
629 (ordinarily an output format, but input formats are not
632 var_set_print_format_quiet (struct variable *v, const struct fmt_spec *print)
634 if (!fmt_equal (&v->print, print))
636 assert (fmt_check_width_compat (print, v->width));
641 /* Sets V's print format specification to PRINT, which must be a
642 valid format specification for a variable of V's width
643 (ordinarily an output format, but input formats are not
646 var_set_print_format (struct variable *v, const struct fmt_spec *print)
648 struct variable *ov = var_clone (v);
649 var_set_print_format_quiet (v, print);
650 dict_var_changed (v, VAR_TRAIT_PRINT_FORMAT, ov);
653 /* Returns V's write format specification. */
654 const struct fmt_spec *
655 var_get_write_format (const struct variable *v)
660 /* Sets V's write format specification to WRITE, which must be a
661 valid format specification for a variable of V's width
662 (ordinarily an output format, but input formats are not
665 var_set_write_format_quiet (struct variable *v, const struct fmt_spec *write)
667 if (!fmt_equal (&v->write, write))
669 assert (fmt_check_width_compat (write, v->width));
674 /* Sets V's write format specification to WRITE, which must be a
675 valid format specification for a variable of V's width
676 (ordinarily an output format, but input formats are not
679 var_set_write_format (struct variable *v, const struct fmt_spec *write)
681 struct variable *ov = var_clone (v);
682 var_set_write_format_quiet (v, write);
683 dict_var_changed (v, VAR_TRAIT_WRITE_FORMAT, ov);
687 /* Sets V's print and write format specifications to FORMAT,
688 which must be a valid format specification for a variable of
689 V's width (ordinarily an output format, but input formats are
692 var_set_both_formats (struct variable *v, const struct fmt_spec *format)
694 struct variable *ov = var_clone (v);
695 var_set_print_format_quiet (v, format);
696 var_set_write_format_quiet (v, format);
697 dict_var_changed (v, VAR_TRAIT_PRINT_FORMAT | VAR_TRAIT_WRITE_FORMAT, ov);
700 /* Returns the default print and write format for a variable of
701 the given TYPE, as set by var_create. The return value can be
702 used to reset a variable's print and write formats to the
705 var_default_formats (int width)
708 ? fmt_for_output (FMT_F, 8, 2)
709 : fmt_for_output (FMT_A, width, 0));
715 /* Update the combined name and label string if necessary */
717 update_vl_string (const struct variable *v)
719 /* Cast away const! */
720 struct string *str = (struct string *) &v->name_and_label;
722 if (ds_is_empty (str))
725 ds_put_format (str, _("%s (%s)"), v->label, v->name);
727 ds_put_cstr (str, v->name);
732 /* Return a string representing this variable, in the form most
733 appropriate from a human factors perspective, that is, its
734 variable label if it has one, otherwise its name. */
736 var_to_string (const struct variable *v)
738 switch (settings_get_show_variables ())
740 case SETTINGS_VALUE_SHOW_VALUE:
743 case SETTINGS_VALUE_SHOW_LABEL:
745 return v->label != NULL ? v->label : v->name;
747 case SETTINGS_VALUE_SHOW_BOTH:
748 update_vl_string (v);
749 return ds_cstr (&v->name_and_label);
753 /* Returns V's variable label, or a null pointer if it has none. */
755 var_get_label (const struct variable *v)
760 /* Sets V's variable label to UTF-8 encoded string LABEL, stripping off leading
761 and trailing white space. If LABEL is a null pointer or if LABEL is an
762 empty string (after stripping white space), then V's variable label (if any)
765 var_set_label_quiet (struct variable *v, const char *label)
770 if (label != NULL && label[strspn (label, CC_SPACES)])
771 v->label = xstrdup (label);
773 ds_destroy (&v->name_and_label);
774 ds_init_empty (&v->name_and_label);
779 /* Sets V's variable label to UTF-8 encoded string LABEL, stripping off leading
780 and trailing white space. If LABEL is a null pointer or if LABEL is an
781 empty string (after stripping white space), then V's variable label (if any)
784 var_set_label (struct variable *v, const char *label)
786 struct variable *ov = var_clone (v);
787 var_set_label_quiet (v, label);
788 dict_var_changed (v, VAR_TRAIT_LABEL, ov);
792 /* Removes any variable label from V. */
794 var_clear_label (struct variable *v)
796 var_set_label (v, NULL);
799 /* Returns true if V has a variable V,
802 var_has_label (const struct variable *v)
804 return v->label != NULL;
807 /* Returns true if M is a valid variable measurement level,
810 measure_is_valid (enum measure m)
812 return m == MEASURE_NOMINAL || m == MEASURE_ORDINAL || m == MEASURE_SCALE;
815 /* Returns a string version of measurement level M, for display to a user.
816 The caller may translate the string by passing it to gettext(). */
818 measure_to_string (enum measure m)
820 assert (m == measure[m].value);
821 return measure[m].label;
824 /* Returns a string version of measurement level M, for use in PSPP command
827 measure_to_syntax (enum measure m)
831 case MEASURE_NOMINAL:
834 case MEASURE_ORDINAL:
845 /* Returns V's measurement level. */
847 var_get_measure (const struct variable *v)
852 /* Sets V's measurement level to MEASURE. */
854 var_set_measure_quiet (struct variable *v, enum measure measure)
856 assert (measure_is_valid (measure));
857 v->measure = measure;
861 /* Sets V's measurement level to MEASURE. */
863 var_set_measure (struct variable *v, enum measure measure)
865 struct variable *ov = var_clone (v);
866 var_set_measure_quiet (v, measure);
867 dict_var_changed (v, VAR_TRAIT_MEASURE, ov);
871 /* Returns the default measurement level for a variable of the
872 given TYPE, as set by var_create. The return value can be
873 used to reset a variable's measurement level to the
876 var_default_measure (enum val_type type)
878 return type == VAL_NUMERIC ? MEASURE_SCALE : MEASURE_NOMINAL;
881 /* Returns true if M is a valid variable role,
884 var_role_is_valid (enum var_role role)
901 /* Returns a string version of ROLE, for display to a user.
902 The caller may translate the string by passing it to gettext(). */
904 var_role_to_string (enum var_role r)
906 assert (r == role[r].value);
907 return role[r].label;
910 /* Returns a string version of ROLE, for use in PSPP comamnd syntax. */
912 var_role_to_syntax (enum var_role role)
939 /* Returns V's role. */
941 var_get_role (const struct variable *v)
946 /* Sets V's role to ROLE. */
948 var_set_role_quiet (struct variable *v, enum var_role role)
950 assert (var_role_is_valid (role));
955 /* Sets V's role to ROLE. */
957 var_set_role (struct variable *v, enum var_role role)
959 struct variable *ov = var_clone (v);
960 var_set_role_quiet (v, role);
961 dict_var_changed (v, VAR_TRAIT_ROLE, ov);
964 /* Returns V's display width, which applies only to GUIs. */
966 var_get_display_width (const struct variable *v)
968 return v->display_width;
971 /* Sets V's display width to DISPLAY_WIDTH. */
973 var_set_display_width_quiet (struct variable *v, int new_width)
975 if (v->display_width != new_width)
977 v->display_width = new_width;
982 var_set_display_width (struct variable *v, int new_width)
984 if (v->display_width != new_width)
986 struct variable *ov = var_clone (v);
987 var_set_display_width_quiet (v, new_width);
988 dict_var_changed (v, VAR_TRAIT_DISPLAY_WIDTH, ov);
992 /* Returns the default display width for a variable of the given
993 WIDTH, as set by var_create. The return value can be used to
994 reset a variable's display width to the default. */
996 var_default_display_width (int width)
998 return width == 0 ? 8 : MIN (width, 32);
1001 /* Returns true if A is a valid alignment,
1004 alignment_is_valid (enum alignment a)
1006 return a == ALIGN_LEFT || a == ALIGN_RIGHT || a == ALIGN_CENTRE;
1009 /* Returns a string version of alignment A, for display to a user.
1010 The caller may translate the string by passing it to gettext(). */
1012 alignment_to_string (enum alignment a)
1014 assert (a == align[a].value);
1015 return align[a].label;
1018 /* Returns a string version of alignment A, for use in PSPP command syntax. */
1020 alignment_to_syntax (enum alignment a)
1038 /* Returns V's display alignment, which applies only to GUIs. */
1040 var_get_alignment (const struct variable *v)
1042 return v->alignment;
1045 /* Sets V's display alignment to ALIGNMENT. */
1047 var_set_alignment_quiet (struct variable *v, enum alignment alignment)
1049 assert (alignment_is_valid (alignment));
1050 v->alignment = alignment;
1053 /* Sets V's display alignment to ALIGNMENT. */
1055 var_set_alignment (struct variable *v, enum alignment alignment)
1057 struct variable *ov = var_clone (v);
1058 var_set_alignment_quiet (v, alignment);
1059 dict_var_changed (v, VAR_TRAIT_ALIGNMENT, ov);
1063 /* Returns the default display alignment for a variable of the
1064 given TYPE, as set by var_create. The return value can be
1065 used to reset a variable's display alignment to the default. */
1067 var_default_alignment (enum val_type type)
1069 return type == VAL_NUMERIC ? ALIGN_RIGHT : ALIGN_LEFT;
1072 /* Whether variables' values should be preserved from case to
1075 /* Returns true if variable V's value should be left from case to
1076 case, instead of being reset to system-missing or blanks. */
1078 var_get_leave (const struct variable *v)
1083 /* Sets V's leave setting to LEAVE. */
1085 var_set_leave_quiet (struct variable *v, bool leave)
1087 assert (leave || !var_must_leave (v));
1092 /* Sets V's leave setting to LEAVE. */
1094 var_set_leave (struct variable *v, bool leave)
1096 struct variable *ov = var_clone (v);
1097 var_set_leave_quiet (v, leave);
1098 dict_var_changed (v, VAR_TRAIT_LEAVE, ov);
1102 /* Returns true if V must be left from case to case,
1103 false if it can be set either way. */
1105 var_must_leave (const struct variable *v)
1107 return var_get_dict_class (v) == DC_SCRATCH;
1110 /* Returns the number of short names stored in VAR.
1112 Short names are used only for system and portable file input
1113 and output. They are upper-case only, not necessarily unique,
1114 and limited to SHORT_NAME_LEN characters (plus a null
1115 terminator). Ordinarily a variable has at most one short
1116 name, but very long string variables (longer than 255 bytes)
1117 may have more. A variable might not have any short name at
1118 all if it hasn't been saved to or read from a system or
1121 var_get_n_short_names (const struct variable *var)
1123 return var->n_short_names;
1126 /* Returns VAR's short name with the given IDX, if it has one
1127 with that index, or a null pointer otherwise. Short names may
1128 be sparse: even if IDX is less than the number of short names
1129 in VAR, this function may return a null pointer. */
1131 var_get_short_name (const struct variable *var, size_t idx)
1133 return idx < var->n_short_names ? var->short_names[idx] : NULL;
1136 /* Sets VAR's short name with the given IDX to the UTF-8 string SHORT_NAME.
1137 The caller must already have checked that, in the dictionary encoding,
1138 SHORT_NAME is no more than SHORT_NAME_LEN bytes long. The new short name
1139 will be converted to uppercase.
1141 Specifying a null pointer for SHORT_NAME clears the specified short name. */
1143 var_set_short_name (struct variable *var, size_t idx, const char *short_name)
1145 struct variable *ov = var_clone (var);
1147 /* Clear old short name numbered IDX, if any. */
1148 if (idx < var->n_short_names)
1150 free (var->short_names[idx]);
1151 var->short_names[idx] = NULL;
1154 /* Install new short name for IDX. */
1155 if (short_name != NULL)
1157 if (idx >= var->n_short_names)
1159 size_t n_old = var->n_short_names;
1161 var->n_short_names = MAX (idx * 2, 1);
1162 var->short_names = xnrealloc (var->short_names, var->n_short_names,
1163 sizeof *var->short_names);
1164 for (i = n_old; i < var->n_short_names; i++)
1165 var->short_names[i] = NULL;
1167 var->short_names[idx] = utf8_to_upper (short_name);
1170 dict_var_changed (var, VAR_TRAIT_NAME, ov);
1173 /* Clears V's short names. */
1175 var_clear_short_names (struct variable *v)
1179 for (i = 0; i < v->n_short_names; i++)
1180 free (v->short_names[i]);
1181 free (v->short_names);
1182 v->short_names = NULL;
1183 v->n_short_names = 0;
1186 /* Relationship with dictionary. */
1188 /* Returns V's index within its dictionary, the value
1189 for which "dict_get_var (dict, index)" will return V.
1190 V must be in a dictionary. */
1192 var_get_dict_index (const struct variable *v)
1194 assert (var_has_vardict (v));
1195 return vardict_get_dict_index (v->vardict);
1198 /* Returns V's index within the case represented by its
1199 dictionary, that is, the value for which "case_data_idx (case,
1200 index)" will return the data for V in that case.
1201 V must be in a dictionary. */
1203 var_get_case_index (const struct variable *v)
1205 assert (var_has_vardict (v));
1206 return vardict_get_case_index (v->vardict);
1209 /* Returns variable V's attribute set. The caller may examine or
1210 modify the attribute set, but must not destroy it. Destroying
1211 V, or calling var_set_attributes() on V, will also destroy its
1214 var_get_attributes (const struct variable *v)
1216 return CONST_CAST (struct attrset *, &v->attributes);
1219 /* Replaces variable V's attributes set by a copy of ATTRS. */
1221 var_set_attributes_quiet (struct variable *v, const struct attrset *attrs)
1223 attrset_destroy (&v->attributes);
1224 attrset_clone (&v->attributes, attrs);
1227 /* Replaces variable V's attributes set by a copy of ATTRS. */
1229 var_set_attributes (struct variable *v, const struct attrset *attrs)
1231 struct variable *ov = var_clone (v);
1232 var_set_attributes_quiet (v, attrs);
1233 dict_var_changed (v, VAR_TRAIT_ATTRIBUTES, ov);
1237 /* Returns true if V has any custom attributes, false if it has none. */
1239 var_has_attributes (const struct variable *v)
1241 return attrset_count (&v->attributes) > 0;
1245 /* Creates and returns a clone of OLD_VAR. Most properties of
1246 the new variable are copied from OLD_VAR, except:
1248 - The variable's short name is not copied, because there is
1249 no reason to give a new variable with potentially a new
1250 name the same short name.
1252 - The new variable is not added to OLD_VAR's dictionary by
1253 default. Use dict_clone_var, instead, to do that.
1256 var_clone (const struct variable *old_var)
1258 struct variable *new_var = var_create (var_get_name (old_var),
1259 var_get_width (old_var));
1261 var_set_missing_values_quiet (new_var, var_get_missing_values (old_var));
1262 var_set_print_format_quiet (new_var, var_get_print_format (old_var));
1263 var_set_write_format_quiet (new_var, var_get_write_format (old_var));
1264 var_set_value_labels_quiet (new_var, var_get_value_labels (old_var));
1265 var_set_label_quiet (new_var, var_get_label (old_var));
1266 var_set_measure_quiet (new_var, var_get_measure (old_var));
1267 var_set_role_quiet (new_var, var_get_role (old_var));
1268 var_set_display_width_quiet (new_var, var_get_display_width (old_var));
1269 var_set_alignment_quiet (new_var, var_get_alignment (old_var));
1270 var_set_leave_quiet (new_var, var_get_leave (old_var));
1271 var_set_attributes_quiet (new_var, var_get_attributes (old_var));
1278 /* Returns the encoding of values of variable VAR. (This is actually a
1279 property of the dictionary.) Returns null if no specific encoding has been
1282 var_get_encoding (const struct variable *var)
1284 return (var_has_vardict (var)
1285 ? dict_get_encoding (vardict_get_dictionary (var->vardict))
1289 /* Returns V's vardict structure. */
1290 struct vardict_info *
1291 var_get_vardict (const struct variable *v)
1293 return CONST_CAST (struct vardict_info *, v->vardict);
1296 /* Sets V's vardict data to VARDICT. */
1298 var_set_vardict (struct variable *v, struct vardict_info *vardict)
1300 v->vardict = vardict;
1303 /* Returns true if V has vardict data. */
1305 var_has_vardict (const struct variable *v)
1307 return v->vardict != NULL;
1310 /* Clears V's vardict data. */
1312 var_clear_vardict (struct variable *v)
1319 Returns zero, if W is a missing value for WV or if it is less than zero.
1320 Typically used to force a numerical value into a valid weight.
1322 As a side effect, this function will emit a warning if the value
1323 WARN_ON_INVALID points to a bool which is TRUE. That bool will be then
1327 var_force_valid_weight (const struct variable *wv, double w, bool *warn_on_invalid)
1329 if (w < 0.0 || (wv && var_is_num_missing (wv, w)))
1332 if (w == 0.0 && warn_on_invalid != NULL && *warn_on_invalid)
1334 *warn_on_invalid = false;
1335 msg (SW, _("At least one case in the data file had a weight value "
1336 "that was user-missing, system-missing, zero, or "
1337 "negative. These case(s) were ignored."));