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_UNKNOWN, "unknown", N_("Unknown")},
67 {MEASURE_NOMINAL, "nominal", N_("Nominal")},
68 {MEASURE_ORDINAL, "ordinal", N_("Ordinal")},
69 {MEASURE_SCALE, "scale", N_("Scale")},
73 const GEnumValue role[] =
75 {ROLE_INPUT, "input", N_("Input")},
76 {ROLE_TARGET, "output", N_("Output")},
77 {ROLE_BOTH, "both", N_("Both")},
78 {ROLE_NONE, "none", N_("None")},
79 {ROLE_PARTITION, "partition", N_("Partition")},
80 {ROLE_SPLIT, "split", N_("Split")},
88 /* Dictionary information. */
89 char *name; /* Variable name. Mixed case. */
90 int width; /* 0 for numeric, otherwise string width. */
91 struct missing_values miss; /* Missing values. */
92 struct fmt_spec print; /* Default format for PRINT. */
93 struct fmt_spec write; /* Default format for WRITE. */
94 struct val_labs *val_labs; /* Value labels. */
95 char *label; /* Variable label. */
96 struct string name_and_label; /* The name and label in the same string */
98 /* GUI information. */
99 enum measure measure; /* Nominal, ordinal, or continuous. */
100 enum var_role role; /* Intended use. */
101 int display_width; /* Width of data editor column. */
102 enum alignment alignment; /* Alignment of data in GUI. */
104 /* Case information. */
105 bool leave; /* Leave value from case to case? */
107 /* Data for use by containing dictionary. */
108 struct vardict_info *vardict;
110 /* Used only for system and portable file input and output.
111 See short-names.h. */
113 size_t n_short_names;
115 /* Custom attributes. */
116 struct attrset attributes;
120 static void var_set_print_format_quiet (struct variable *v, const struct fmt_spec *print);
121 static void var_set_write_format_quiet (struct variable *v, const struct fmt_spec *write);
122 static void var_set_label_quiet (struct variable *v, const char *label);
123 static void var_set_name_quiet (struct variable *v, const char *name);
125 /* Creates and returns a new variable with the given NAME and
126 WIDTH and other fields initialized to default values. The
127 variable is not added to a dictionary; for that, use
128 dict_create_var instead. */
130 var_create (const char *name, int width)
134 assert (width >= 0 && width <= MAX_STRING);
136 struct variable *v = XZALLOC (struct variable);
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_for_type (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 (mv_is_resizable (&v->miss, new_width))
311 mv_resize (&v->miss, new_width);
314 mv_destroy (&v->miss);
315 mv_init (&v->miss, new_width);
317 if (new_width != var_get_width (v))
318 traits |= VAR_TRAIT_MISSING_VALUES;
320 if (v->val_labs != NULL)
322 if (val_labs_can_set_width (v->val_labs, new_width))
323 val_labs_set_width (v->val_labs, new_width);
326 val_labs_destroy (v->val_labs);
329 traits |= VAR_TRAIT_VALUE_LABELS;
332 if (fmt_resize (&v->print, new_width))
333 traits |= VAR_TRAIT_PRINT_FORMAT;
335 if (fmt_resize (&v->write, new_width))
336 traits |= VAR_TRAIT_WRITE_FORMAT;
338 if (v->width != new_width)
340 v->width = new_width;
341 traits |= VAR_TRAIT_WIDTH;
346 var_set_print_format_quiet (v, print);
347 traits |= VAR_TRAIT_PRINT_FORMAT;
352 var_set_write_format_quiet (v, write);
353 traits |= VAR_TRAIT_WRITE_FORMAT;
357 dict_var_changed (v, traits, ov);
360 /* Changes the width of V to NEW_WIDTH.
361 This function should be used cautiously. */
363 var_set_width (struct variable *v, int new_width)
365 const int old_width = v->width;
367 if (old_width == new_width)
370 var_set_width_and_formats (v, new_width, NULL, NULL);
376 /* Returns true if variable V is numeric, false otherwise. */
378 var_is_numeric (const struct variable *v)
380 return var_get_type (v) == VAL_NUMERIC;
383 /* Returns true if variable V is a string variable, false
386 var_is_alpha (const struct variable *v)
388 return var_get_type (v) == VAL_STRING;
391 /* Returns variable V's missing values. */
392 const struct missing_values *
393 var_get_missing_values (const struct variable *v)
398 /* Sets variable V's missing values to MISS, which must be of V's
399 width or at least resizable to V's width.
400 If MISS is null, then V's missing values, if any, are
403 var_set_missing_values_quiet (struct variable *v, const struct missing_values *miss)
407 assert (mv_is_resizable (miss, v->width));
408 mv_destroy (&v->miss);
409 mv_copy (&v->miss, miss);
410 mv_resize (&v->miss, v->width);
416 /* Sets variable V's missing values to MISS, which must be of V's
417 width or at least resizable to V's width.
418 If MISS is null, then V's missing values, if any, are
421 var_set_missing_values (struct variable *v, const struct missing_values *miss)
423 struct variable *ov = var_clone (v);
424 var_set_missing_values_quiet (v, miss);
425 dict_var_changed (v, VAR_TRAIT_MISSING_VALUES, ov);
428 /* Sets variable V to have no user-missing values. */
430 var_clear_missing_values (struct variable *v)
432 var_set_missing_values (v, NULL);
435 /* Returns true if V has any user-missing values,
438 var_has_missing_values (const struct variable *v)
440 return !mv_is_empty (&v->miss);
443 /* Returns MV_SYSTEM if VALUE is system-missing, MV_USER if VALUE is
444 user-missing for V, and otherwise 0. */
446 var_is_value_missing (const struct variable *v, const union value *value)
448 return mv_is_value_missing (&v->miss, value);
451 /* Returns MV_SYSTEM if VALUE is system-missing, MV_USER if VALUE is
452 user-missing for V, and otherwise 0. V must be a numeric variable. */
454 var_is_num_missing (const struct variable *v, double d)
456 return mv_is_num_missing (&v->miss, d);
459 /* Returns MV_USER if VALUE is user-missing for V and otherwise 0. V must be
460 a string variable. */
462 var_is_str_missing (const struct variable *v, const uint8_t s[])
464 return mv_is_str_missing (&v->miss, s);
467 /* Returns variable V's value labels,
468 possibly a null pointer if it has none. */
469 const struct val_labs *
470 var_get_value_labels (const struct variable *v)
475 /* Returns true if variable V has at least one value label. */
477 var_has_value_labels (const struct variable *v)
479 return val_labs_count (v->val_labs) > 0;
482 /* Sets variable V's value labels to a copy of VLS,
483 which must have a width equal to V's width or one that can be
484 changed to V's width.
485 If VLS is null, then V's value labels, if any, are removed. */
487 var_set_value_labels_quiet (struct variable *v, const struct val_labs *vls)
489 val_labs_destroy (v->val_labs);
494 assert (val_labs_can_set_width (vls, v->width));
495 v->val_labs = val_labs_clone (vls);
496 val_labs_set_width (v->val_labs, v->width);
501 /* Sets variable V's value labels to a copy of VLS,
502 which must have a width equal to V's width or one that can be
503 changed to V's width.
504 If VLS is null, then V's value labels, if any, are removed. */
506 var_set_value_labels (struct variable *v, const struct val_labs *vls)
508 struct variable *ov = var_clone (v);
509 var_set_value_labels_quiet (v, vls);
510 dict_var_changed (v, VAR_TRAIT_LABEL, ov);
514 /* Makes sure that V has a set of value labels,
515 by assigning one to it if necessary. */
517 alloc_value_labels (struct variable *v)
519 if (v->val_labs == NULL)
520 v->val_labs = val_labs_create (v->width);
523 /* Attempts to add a value label with the given VALUE and UTF-8 encoded LABEL
524 to V. Returns true if successful, false otherwise (probably due to an
527 In LABEL, the two-byte sequence "\\n" is interpreted as a new-line. */
529 var_add_value_label (struct variable *v,
530 const union value *value, const char *label)
532 alloc_value_labels (v);
533 return val_labs_add (v->val_labs, value, label);
536 /* Adds or replaces a value label with the given VALUE and UTF-8 encoded LABEL
539 In LABEL, the two-byte sequence "\\n" is interpreted as a new-line. */
541 var_replace_value_label (struct variable *v,
542 const union value *value, const char *label)
544 alloc_value_labels (v);
545 val_labs_replace (v->val_labs, value, label);
548 /* Removes V's value labels, if any. */
550 var_clear_value_labels (struct variable *v)
552 var_set_value_labels (v, NULL);
555 /* Returns the label associated with VALUE for variable V, as a UTF-8 string in
556 a format suitable for output, or a null pointer if none. */
558 var_lookup_value_label (const struct variable *v, const union value *value)
560 return val_labs_find (v->val_labs, value);
564 Append to STR the string representation of VALUE for variable V.
565 STR must be a pointer to an initialised struct string.
568 append_value (const struct variable *v, const union value *value,
571 char *s = data_out (value, var_get_encoding (v), &v->print,
572 settings_get_fmt_settings ());
573 struct substring ss = ss_cstr (s);
574 ss_rtrim (&ss, ss_cstr (" "));
575 ds_put_substring (str, ss);
580 var_append_value_name__ (const struct variable *v, const union value *value,
581 enum settings_value_show show, struct string *str)
583 const char *label = var_lookup_value_label (v, value);
587 case SETTINGS_VALUE_SHOW_VALUE:
588 append_value (v, value, str);
592 case SETTINGS_VALUE_SHOW_LABEL:
594 ds_put_cstr (str, label);
596 append_value (v, value, str);
599 case SETTINGS_VALUE_SHOW_BOTH:
600 append_value (v, value, str);
602 ds_put_format (str, " %s", label);
607 /* Append STR with a string representing VALUE for variable V.
608 That is, if VALUE has a label, append that label,
609 otherwise format VALUE and append the formatted string.
610 STR must be a pointer to an initialised struct string.
613 var_append_value_name (const struct variable *v, const union value *value,
616 var_append_value_name__ (v, value, settings_get_show_values (), str);
619 /* Print and write formats. */
621 /* Returns V's print format specification. */
622 const struct fmt_spec *
623 var_get_print_format (const struct variable *v)
628 /* Sets V's print format specification to PRINT, which must be a
629 valid format specification for a variable of V's width
630 (ordinarily an output format, but input formats are not
633 var_set_print_format_quiet (struct variable *v, const struct fmt_spec *print)
635 if (!fmt_equal (&v->print, print))
637 assert (fmt_check_width_compat (print, v->width));
642 /* Sets V's print format specification to PRINT, which must be a
643 valid format specification for a variable of V's width
644 (ordinarily an output format, but input formats are not
647 var_set_print_format (struct variable *v, const struct fmt_spec *print)
649 struct variable *ov = var_clone (v);
650 var_set_print_format_quiet (v, print);
651 dict_var_changed (v, VAR_TRAIT_PRINT_FORMAT, ov);
654 /* Returns V's write format specification. */
655 const struct fmt_spec *
656 var_get_write_format (const struct variable *v)
661 /* Sets V's write format specification to WRITE, which must be a
662 valid format specification for a variable of V's width
663 (ordinarily an output format, but input formats are not
666 var_set_write_format_quiet (struct variable *v, const struct fmt_spec *write)
668 if (!fmt_equal (&v->write, write))
670 assert (fmt_check_width_compat (write, v->width));
675 /* Sets V's write format specification to WRITE, which must be a
676 valid format specification for a variable of V's width
677 (ordinarily an output format, but input formats are not
680 var_set_write_format (struct variable *v, const struct fmt_spec *write)
682 struct variable *ov = var_clone (v);
683 var_set_write_format_quiet (v, write);
684 dict_var_changed (v, VAR_TRAIT_WRITE_FORMAT, ov);
688 /* Sets V's print and write format specifications to FORMAT,
689 which must be a valid format specification for a variable of
690 V's width (ordinarily an output format, but input formats are
693 var_set_both_formats (struct variable *v, const struct fmt_spec *format)
695 struct variable *ov = var_clone (v);
696 var_set_print_format_quiet (v, format);
697 var_set_write_format_quiet (v, format);
698 dict_var_changed (v, VAR_TRAIT_PRINT_FORMAT | VAR_TRAIT_WRITE_FORMAT, ov);
701 /* Returns the default print and write format for a variable of
702 the given TYPE, as set by var_create. The return value can be
703 used to reset a variable's print and write formats to the
706 var_default_formats (int width)
709 ? fmt_for_output (FMT_F, 8, 2)
710 : fmt_for_output (FMT_A, width, 0));
716 /* Update the combined name and label string if necessary */
718 update_vl_string (const struct variable *v)
720 /* Cast away const! */
721 struct string *str = (struct string *) &v->name_and_label;
723 if (ds_is_empty (str))
726 ds_put_format (str, _("%s (%s)"), v->label, v->name);
728 ds_put_cstr (str, v->name);
733 /* Return a string representing this variable, in the form most
734 appropriate from a human factors perspective, that is, its
735 variable label if it has one, otherwise its name. */
737 var_to_string (const struct variable *v)
739 switch (settings_get_show_variables ())
741 case SETTINGS_VALUE_SHOW_VALUE:
744 case SETTINGS_VALUE_SHOW_LABEL:
746 return v->label != NULL ? v->label : v->name;
748 case SETTINGS_VALUE_SHOW_BOTH:
749 update_vl_string (v);
750 return ds_cstr (&v->name_and_label);
754 /* Returns V's variable label, or a null pointer if it has none. */
756 var_get_label (const struct variable *v)
761 /* Sets V's variable label to UTF-8 encoded string LABEL, stripping off leading
762 and trailing white space. If LABEL is a null pointer or if LABEL is an
763 empty string (after stripping white space), then V's variable label (if any)
766 var_set_label_quiet (struct variable *v, const char *label)
771 if (label != NULL && label[strspn (label, CC_SPACES)])
772 v->label = xstrdup (label);
774 ds_destroy (&v->name_and_label);
775 ds_init_empty (&v->name_and_label);
780 /* Sets V's variable label to UTF-8 encoded string LABEL, stripping off leading
781 and trailing white space. If LABEL is a null pointer or if LABEL is an
782 empty string (after stripping white space), then V's variable label (if any)
785 var_set_label (struct variable *v, const char *label)
787 struct variable *ov = var_clone (v);
788 var_set_label_quiet (v, label);
789 dict_var_changed (v, VAR_TRAIT_LABEL, ov);
793 /* Removes any variable label from V. */
795 var_clear_label (struct variable *v)
797 var_set_label (v, NULL);
800 /* Returns true if V has a variable V,
803 var_has_label (const struct variable *v)
805 return v->label != NULL;
808 /* Returns true if M is a valid variable measurement level,
811 measure_is_valid (enum measure m)
813 return (m == MEASURE_UNKNOWN || m == MEASURE_NOMINAL
814 || m == MEASURE_ORDINAL || m == MEASURE_SCALE);
817 /* Returns a string version of measurement level M, for display to a user.
818 The caller may translate the string by passing it to gettext(). */
820 measure_to_string (enum measure m)
822 assert (m == measure[m].value);
823 return measure[m].label;
826 /* Returns a string version of measurement level M, for use in PSPP command
829 measure_to_syntax (enum measure m)
833 case MEASURE_NOMINAL:
836 case MEASURE_ORDINAL:
847 /* Returns V's measurement level. */
849 var_get_measure (const struct variable *v)
854 /* Sets V's measurement level to MEASURE. */
856 var_set_measure_quiet (struct variable *v, enum measure measure)
858 assert (measure_is_valid (measure));
859 v->measure = measure;
863 /* Sets V's measurement level to MEASURE. */
865 var_set_measure (struct variable *v, enum measure measure)
867 struct variable *ov = var_clone (v);
868 var_set_measure_quiet (v, measure);
869 dict_var_changed (v, VAR_TRAIT_MEASURE, ov);
873 /* Returns the default measurement level for a variable of the
874 given TYPE, as set by var_create. The return value can be
875 used to reset a variable's measurement level to the
878 var_default_measure_for_type (enum val_type type)
880 return type == VAL_NUMERIC ? MEASURE_UNKNOWN : MEASURE_NOMINAL;
883 /* Returns the default measurement level for a variable with the given
884 FORMAT, or MEASURE_UNKNOWN if there is no good default. */
886 var_default_measure_for_format (enum fmt_type format)
888 if (format == FMT_DOLLAR)
889 return MEASURE_SCALE;
891 switch (fmt_get_category (format))
896 case FMT_CAT_HEXADECIMAL:
897 return MEASURE_UNKNOWN;
902 return MEASURE_SCALE;
904 case FMT_CAT_DATE_COMPONENT:
906 return MEASURE_NOMINAL;
912 /* Returns true if M is a valid variable role,
915 var_role_is_valid (enum var_role role)
932 /* Returns a string version of ROLE, for display to a user.
933 The caller may translate the string by passing it to gettext(). */
935 var_role_to_string (enum var_role r)
937 assert (r == role[r].value);
938 return role[r].label;
941 /* Returns a string version of ROLE, for use in PSPP comamnd syntax. */
943 var_role_to_syntax (enum var_role role)
970 /* Returns V's role. */
972 var_get_role (const struct variable *v)
977 /* Sets V's role to ROLE. */
979 var_set_role_quiet (struct variable *v, enum var_role role)
981 assert (var_role_is_valid (role));
986 /* Sets V's role to ROLE. */
988 var_set_role (struct variable *v, enum var_role role)
990 struct variable *ov = var_clone (v);
991 var_set_role_quiet (v, role);
992 dict_var_changed (v, VAR_TRAIT_ROLE, ov);
995 /* Returns V's display width, which applies only to GUIs. */
997 var_get_display_width (const struct variable *v)
999 return v->display_width;
1002 /* Sets V's display width to DISPLAY_WIDTH. */
1004 var_set_display_width_quiet (struct variable *v, int new_width)
1006 if (v->display_width != new_width)
1008 v->display_width = new_width;
1013 var_set_display_width (struct variable *v, int new_width)
1015 if (v->display_width != new_width)
1017 struct variable *ov = var_clone (v);
1018 var_set_display_width_quiet (v, new_width);
1019 dict_var_changed (v, VAR_TRAIT_DISPLAY_WIDTH, ov);
1023 /* Returns the default display width for a variable of the given
1024 WIDTH, as set by var_create. The return value can be used to
1025 reset a variable's display width to the default. */
1027 var_default_display_width (int width)
1029 return width == 0 ? 8 : MIN (width, 32);
1032 /* Returns true if A is a valid alignment,
1035 alignment_is_valid (enum alignment a)
1037 return a == ALIGN_LEFT || a == ALIGN_RIGHT || a == ALIGN_CENTRE;
1040 /* Returns a string version of alignment A, for display to a user.
1041 The caller may translate the string by passing it to gettext(). */
1043 alignment_to_string (enum alignment a)
1045 assert (a == align[a].value);
1046 return align[a].label;
1049 /* Returns a string version of alignment A, for use in PSPP command syntax. */
1051 alignment_to_syntax (enum alignment a)
1069 /* Returns V's display alignment, which applies only to GUIs. */
1071 var_get_alignment (const struct variable *v)
1073 return v->alignment;
1076 /* Sets V's display alignment to ALIGNMENT. */
1078 var_set_alignment_quiet (struct variable *v, enum alignment alignment)
1080 assert (alignment_is_valid (alignment));
1081 v->alignment = alignment;
1084 /* Sets V's display alignment to ALIGNMENT. */
1086 var_set_alignment (struct variable *v, enum alignment alignment)
1088 struct variable *ov = var_clone (v);
1089 var_set_alignment_quiet (v, alignment);
1090 dict_var_changed (v, VAR_TRAIT_ALIGNMENT, ov);
1094 /* Returns the default display alignment for a variable of the
1095 given TYPE, as set by var_create. The return value can be
1096 used to reset a variable's display alignment to the default. */
1098 var_default_alignment (enum val_type type)
1100 return type == VAL_NUMERIC ? ALIGN_RIGHT : ALIGN_LEFT;
1103 /* Whether variables' values should be preserved from case to
1106 /* Returns true if variable V's value should be left from case to
1107 case, instead of being reset to system-missing or blanks. */
1109 var_get_leave (const struct variable *v)
1114 /* Sets V's leave setting to LEAVE. */
1116 var_set_leave_quiet (struct variable *v, bool leave)
1118 assert (leave || !var_must_leave (v));
1123 /* Sets V's leave setting to LEAVE. */
1125 var_set_leave (struct variable *v, bool leave)
1127 struct variable *ov = var_clone (v);
1128 var_set_leave_quiet (v, leave);
1129 dict_var_changed (v, VAR_TRAIT_LEAVE, ov);
1133 /* Returns true if V must be left from case to case,
1134 false if it can be set either way. */
1136 var_must_leave (const struct variable *v)
1138 return var_get_dict_class (v) == DC_SCRATCH;
1141 /* Returns the number of short names stored in VAR.
1143 Short names are used only for system and portable file input
1144 and output. They are upper-case only, not necessarily unique,
1145 and limited to SHORT_NAME_LEN characters (plus a null
1146 terminator). Ordinarily a variable has at most one short
1147 name, but very long string variables (longer than 255 bytes)
1148 may have more. A variable might not have any short name at
1149 all if it hasn't been saved to or read from a system or
1152 var_get_n_short_names (const struct variable *var)
1154 return var->n_short_names;
1157 /* Returns VAR's short name with the given IDX, if it has one
1158 with that index, or a null pointer otherwise. Short names may
1159 be sparse: even if IDX is less than the number of short names
1160 in VAR, this function may return a null pointer. */
1162 var_get_short_name (const struct variable *var, size_t idx)
1164 return idx < var->n_short_names ? var->short_names[idx] : NULL;
1167 /* Sets VAR's short name with the given IDX to the UTF-8 string SHORT_NAME.
1168 The caller must already have checked that, in the dictionary encoding,
1169 SHORT_NAME is no more than SHORT_NAME_LEN bytes long. The new short name
1170 will be converted to uppercase.
1172 Specifying a null pointer for SHORT_NAME clears the specified short name. */
1174 var_set_short_name (struct variable *var, size_t idx, const char *short_name)
1176 struct variable *ov = var_clone (var);
1178 /* Clear old short name numbered IDX, if any. */
1179 if (idx < var->n_short_names)
1181 free (var->short_names[idx]);
1182 var->short_names[idx] = NULL;
1185 /* Install new short name for IDX. */
1186 if (short_name != NULL)
1188 if (idx >= var->n_short_names)
1190 size_t n_old = var->n_short_names;
1192 var->n_short_names = MAX (idx * 2, 1);
1193 var->short_names = xnrealloc (var->short_names, var->n_short_names,
1194 sizeof *var->short_names);
1195 for (i = n_old; i < var->n_short_names; i++)
1196 var->short_names[i] = NULL;
1198 var->short_names[idx] = utf8_to_upper (short_name);
1201 dict_var_changed (var, VAR_TRAIT_NAME, ov);
1204 /* Clears V's short names. */
1206 var_clear_short_names (struct variable *v)
1210 for (i = 0; i < v->n_short_names; i++)
1211 free (v->short_names[i]);
1212 free (v->short_names);
1213 v->short_names = NULL;
1214 v->n_short_names = 0;
1217 /* Relationship with dictionary. */
1219 /* Returns V's index within its dictionary, the value
1220 for which "dict_get_var (dict, index)" will return V.
1221 V must be in a dictionary. */
1223 var_get_dict_index (const struct variable *v)
1225 assert (var_has_vardict (v));
1226 return vardict_get_dict_index (v->vardict);
1229 /* Returns V's index within the case represented by its
1230 dictionary, that is, the value for which "case_data_idx (case,
1231 index)" will return the data for V in that case.
1232 V must be in a dictionary. */
1234 var_get_case_index (const struct variable *v)
1236 assert (var_has_vardict (v));
1237 return vardict_get_case_index (v->vardict);
1240 /* Returns variable V's attribute set. The caller may examine or
1241 modify the attribute set, but must not destroy it. Destroying
1242 V, or calling var_set_attributes() on V, will also destroy its
1245 var_get_attributes (const struct variable *v)
1247 return CONST_CAST (struct attrset *, &v->attributes);
1250 /* Replaces variable V's attributes set by a copy of ATTRS. */
1252 var_set_attributes_quiet (struct variable *v, const struct attrset *attrs)
1254 attrset_destroy (&v->attributes);
1255 attrset_clone (&v->attributes, attrs);
1258 /* Replaces variable V's attributes set by a copy of ATTRS. */
1260 var_set_attributes (struct variable *v, const struct attrset *attrs)
1262 struct variable *ov = var_clone (v);
1263 var_set_attributes_quiet (v, attrs);
1264 dict_var_changed (v, VAR_TRAIT_ATTRIBUTES, ov);
1268 /* Returns true if V has any custom attributes, false if it has none. */
1270 var_has_attributes (const struct variable *v)
1272 return attrset_count (&v->attributes) > 0;
1276 /* Creates and returns a clone of OLD_VAR. Most properties of
1277 the new variable are copied from OLD_VAR, except:
1279 - The variable's short name is not copied, because there is
1280 no reason to give a new variable with potentially a new
1281 name the same short name.
1283 - The new variable is not added to OLD_VAR's dictionary by
1284 default. Use dict_clone_var, instead, to do that.
1287 var_clone (const struct variable *old_var)
1289 struct variable *new_var = var_create (var_get_name (old_var),
1290 var_get_width (old_var));
1292 var_set_missing_values_quiet (new_var, var_get_missing_values (old_var));
1293 var_set_print_format_quiet (new_var, var_get_print_format (old_var));
1294 var_set_write_format_quiet (new_var, var_get_write_format (old_var));
1295 var_set_value_labels_quiet (new_var, var_get_value_labels (old_var));
1296 var_set_label_quiet (new_var, var_get_label (old_var));
1297 var_set_measure_quiet (new_var, var_get_measure (old_var));
1298 var_set_role_quiet (new_var, var_get_role (old_var));
1299 var_set_display_width_quiet (new_var, var_get_display_width (old_var));
1300 var_set_alignment_quiet (new_var, var_get_alignment (old_var));
1301 var_set_leave_quiet (new_var, var_get_leave (old_var));
1302 var_set_attributes_quiet (new_var, var_get_attributes (old_var));
1309 /* Returns the encoding of values of variable VAR. (This is actually a
1310 property of the dictionary.) Returns null if no specific encoding has been
1313 var_get_encoding (const struct variable *var)
1315 return (var_has_vardict (var)
1316 ? dict_get_encoding (vardict_get_dictionary (var->vardict))
1320 /* Returns V's vardict structure. */
1321 struct vardict_info *
1322 var_get_vardict (const struct variable *v)
1324 return CONST_CAST (struct vardict_info *, v->vardict);
1327 /* Sets V's vardict data to VARDICT. */
1329 var_set_vardict (struct variable *v, struct vardict_info *vardict)
1331 v->vardict = vardict;
1334 /* Returns true if V has vardict data. */
1336 var_has_vardict (const struct variable *v)
1338 return v->vardict != NULL;
1341 /* Clears V's vardict data. */
1343 var_clear_vardict (struct variable *v)
1350 Returns zero, if W is a missing value for WV or if it is less than zero.
1351 Typically used to force a numerical value into a valid weight.
1353 As a side effect, this function will emit a warning if the value
1354 WARN_ON_INVALID points to a bool which is TRUE. That bool will be then
1358 var_force_valid_weight (const struct variable *wv, double w, bool *warn_on_invalid)
1360 if (w <= 0.0 || (wv ? var_is_num_missing (wv, w) : w == SYSMIS))
1363 if (warn_on_invalid != NULL && *warn_on_invalid)
1365 *warn_on_invalid = false;
1366 msg (SW, _("At least one case in the data file had a weight value "
1367 "that was user-missing, system-missing, zero, or "
1368 "negative. These case(s) were ignored."));