1 /* PSPP - a program for statistical analysis.
2 Copyright (C) 1997-9, 2000, 2006, 2009-2015 Free Software Foundation, Inc.
4 This program is free software: you can redistribute it and/or modify
5 it under the terms of the GNU General Public License as published by
6 the Free Software Foundation, either version 3 of the License, or
7 (at your option) any later version.
9 This program is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 GNU General Public License for more details.
14 You should have received a copy of the GNU General Public License
15 along with this program. If not, see <http://www.gnu.org/licenses/>. */
19 #include "data/variable.h"
23 #include "data/attributes.h"
24 #include "data/data-out.h"
25 #include "data/dictionary.h"
26 #include "data/format.h"
27 #include "data/identifier.h"
28 #include "data/missing-values.h"
29 #include "data/settings.h"
30 #include "data/value-labels.h"
31 #include "data/vardict.h"
32 #include "libpspp/assertion.h"
33 #include "libpspp/compiler.h"
34 #include "libpspp/hash-functions.h"
35 #include "libpspp/i18n.h"
36 #include "libpspp/intern.h"
37 #include "libpspp/message.h"
38 #include "libpspp/misc.h"
39 #include "libpspp/pxd.h"
40 #include "libpspp/str.h"
42 #include "gl/minmax.h"
43 #include "gl/xalloc.h"
46 #define _(msgid) gettext (msgid)
51 /* Dictionary information. */
52 char *name; /* Variable name. Mixed case. */
53 int width; /* 0 for numeric, otherwise string width. */
54 struct missing_values miss; /* Missing values. */
55 struct fmt_spec print; /* Default format for PRINT. */
56 struct fmt_spec write; /* Default format for WRITE. */
57 struct val_labs *val_labs; /* Value labels. */
58 char *label; /* Variable label. */
59 struct string name_and_label; /* The name and label in the same string */
61 /* GUI information. */
62 enum measure measure; /* Nominal, ordinal, or continuous. */
63 enum var_role role; /* Intended use. */
64 int display_width; /* Width of data editor column. */
65 enum alignment alignment; /* Alignment of data in GUI. */
67 /* Case information. */
68 bool leave; /* Leave value from case to case? */
70 /* Data for use by containing dictionary. */
71 struct vardict_info *vardict;
73 /* Used only for system and portable file input and output.
76 size_t short_name_cnt;
78 /* Custom attributes. */
79 struct attrset attributes;
82 static void var_uncache (struct variable *);
85 static void var_set_print_format_quiet (struct variable *v, const struct fmt_spec *print);
86 static void var_set_write_format_quiet (struct variable *v, const struct fmt_spec *write);
87 static void var_set_label_quiet (struct variable *v, const char *label);
88 static void var_set_name_quiet (struct variable *v, const char *name);
90 /* Creates and returns a new variable with the given NAME and
91 WIDTH and other fields initialized to default values. The
92 variable is not added to a dictionary; for that, use
93 dict_create_var instead. */
95 var_create (const char *name, int width)
100 assert (width >= 0 && width <= MAX_STRING);
102 v = xzalloc (sizeof *v);
103 var_set_name_quiet (v, name);
105 mv_init (&v->miss, width);
106 v->leave = var_must_leave (v);
107 type = val_type_from_width (width);
108 v->alignment = var_default_alignment (type);
109 v->measure = var_default_measure (type);
110 v->role = ROLE_INPUT;
111 v->display_width = var_default_display_width (width);
112 v->print = v->write = var_default_formats (width);
113 attrset_init (&v->attributes);
114 ds_init_empty (&v->name_and_label);
119 /* Destroys variable V.
120 V must not belong to a dictionary. If it does, use
121 dict_delete_var instead. */
123 var_destroy (struct variable *v)
127 assert (!var_has_vardict (v));
129 mv_destroy (&v->miss);
130 var_clear_short_names (v);
131 val_labs_destroy (v->val_labs);
132 var_set_label_quiet (v, NULL);
133 attrset_destroy (var_get_attributes (v));
135 ds_destroy (&v->name_and_label);
140 /* Variable names. */
142 /* Return variable V's name, as a UTF-8 encoded string. */
144 var_get_name (const struct variable *v)
151 /* Sets V's name to NAME, a UTF-8 encoded string.
152 Do not use this function for a variable in a dictionary. Use
153 dict_rename_var instead. */
155 var_set_name_quiet (struct variable *v, const char *name)
157 assert (!var_has_vardict (v));
158 assert (id_is_plausible (name, false));
161 v->name = xstrdup (name);
162 ds_destroy (&v->name_and_label);
163 ds_init_empty (&v->name_and_label);
167 /* Sets V's name to NAME, a UTF-8 encoded string.
168 Do not use this function for a variable in a dictionary. Use
169 dict_rename_var instead. */
171 var_set_name (struct variable *v, const char *name)
173 struct variable *ov = var_clone (v);
174 var_set_name_quiet (v, name);
175 dict_var_changed (v, VAR_TRAIT_NAME, ov);
178 /* Returns VAR's dictionary class. */
180 var_get_dict_class (const struct variable *var)
182 return dict_class_from_id (var->name);
185 /* A hsh_compare_func that orders variables A and B by their
188 compare_vars_by_name (const void *a_, const void *b_, const void *aux UNUSED)
190 const struct variable *a = a_;
191 const struct variable *b = b_;
193 return utf8_strcasecmp (a->name, b->name);
196 /* A hsh_hash_func that hashes variable V based on its name. */
198 hash_var_by_name (const void *v_, const void *aux UNUSED)
200 const struct variable *v = v_;
202 return utf8_hash_case_string (v->name, 0);
205 /* A hsh_compare_func that orders pointers to variables A and B
208 compare_var_ptrs_by_name (const void *a_, const void *b_,
209 const void *aux UNUSED)
211 struct variable *const *a = a_;
212 struct variable *const *b = b_;
214 return utf8_strcasecmp (var_get_name (*a), var_get_name (*b));
217 /* A hsh_compare_func that orders pointers to variables A and B
218 by their dictionary indexes. */
220 compare_var_ptrs_by_dict_index (const void *a_, const void *b_,
221 const void *aux UNUSED)
223 struct variable *const *a = a_;
224 struct variable *const *b = b_;
225 size_t a_index = var_get_dict_index (*a);
226 size_t b_index = var_get_dict_index (*b);
228 return a_index < b_index ? -1 : a_index > b_index;
231 /* A hsh_hash_func that hashes pointer to variable V based on its
234 hash_var_ptr_by_name (const void *v_, const void *aux UNUSED)
236 struct variable *const *v = v_;
238 return utf8_hash_case_string (var_get_name (*v), 0);
241 /* Returns the type of variable V. */
243 var_get_type (const struct variable *v)
245 return val_type_from_width (v->width);
248 /* Returns the width of variable V. */
250 var_get_width (const struct variable *v)
256 var_set_width_and_formats (struct variable *v, int new_width,
257 const struct fmt_spec *print, const struct fmt_spec *write)
260 unsigned int traits = 0;
264 if (var_has_missing_values (v))
266 if (mv_is_resizable (&v->miss, new_width))
267 mv_resize (&v->miss, new_width);
270 mv_destroy (&v->miss);
271 mv_init (&v->miss, new_width);
273 traits |= VAR_TRAIT_MISSING_VALUES;
276 if (v->val_labs != NULL)
278 if (val_labs_can_set_width (v->val_labs, new_width))
279 val_labs_set_width (v->val_labs, new_width);
282 val_labs_destroy (v->val_labs);
285 traits |= VAR_TRAIT_VALUE_LABELS;
288 if (fmt_resize (&v->print, new_width))
289 traits |= VAR_TRAIT_PRINT_FORMAT;
291 if (fmt_resize (&v->write, new_width))
292 traits |= VAR_TRAIT_WRITE_FORMAT;
294 if (v->width != new_width)
296 v->width = new_width;
297 traits |= VAR_TRAIT_WIDTH;
302 var_set_print_format_quiet (v, print);
303 traits |= VAR_TRAIT_PRINT_FORMAT;
308 var_set_write_format_quiet (v, write);
309 traits |= VAR_TRAIT_WRITE_FORMAT;
313 dict_var_changed (v, traits, ov);
318 /* Changes the width of V to NEW_WIDTH.
319 This function should be used cautiously. */
321 var_set_width (struct variable *v, int new_width)
323 const int old_width = v->width;
325 if (old_width == new_width)
328 var_set_width_and_formats (v, new_width, NULL, NULL);
334 /* Returns true if variable V is numeric, false otherwise. */
336 var_is_numeric (const struct variable *v)
338 return var_get_type (v) == VAL_NUMERIC;
341 /* Returns true if variable V is a string variable, false
344 var_is_alpha (const struct variable *v)
346 return var_get_type (v) == VAL_STRING;
349 /* Returns variable V's missing values. */
350 const struct missing_values *
351 var_get_missing_values (const struct variable *v)
356 /* Sets variable V's missing values to MISS, which must be of V's
357 width or at least resizable to V's width.
358 If MISS is null, then V's missing values, if any, are
361 var_set_missing_values_quiet (struct variable *v, const struct missing_values *miss)
365 assert (mv_is_resizable (miss, v->width));
366 mv_destroy (&v->miss);
367 mv_copy (&v->miss, miss);
368 mv_resize (&v->miss, v->width);
374 /* Sets variable V's missing values to MISS, which must be of V's
375 width or at least resizable to V's width.
376 If MISS is null, then V's missing values, if any, are
379 var_set_missing_values (struct variable *v, const struct missing_values *miss)
381 struct variable *ov = var_clone (v);
382 var_set_missing_values_quiet (v, miss);
383 dict_var_changed (v, VAR_TRAIT_MISSING_VALUES, ov);
386 /* Sets variable V to have no user-missing values. */
388 var_clear_missing_values (struct variable *v)
390 var_set_missing_values (v, NULL);
393 /* Returns true if V has any user-missing values,
396 var_has_missing_values (const struct variable *v)
398 return !mv_is_empty (&v->miss);
401 /* Returns true if VALUE is in the given CLASS of missing values
402 in V, false otherwise. */
404 var_is_value_missing (const struct variable *v, const union value *value,
407 return mv_is_value_missing (&v->miss, value, class);
410 /* Returns true if D is in the given CLASS of missing values in
412 V must be a numeric variable. */
414 var_is_num_missing (const struct variable *v, double d, enum mv_class class)
416 return mv_is_num_missing (&v->miss, d, class);
419 /* Returns true if S[] is a missing value for V, false otherwise.
420 S[] must contain exactly as many characters as V's width.
421 V must be a string variable. */
423 var_is_str_missing (const struct variable *v, const uint8_t s[],
426 return mv_is_str_missing (&v->miss, s, class);
429 /* Returns variable V's value labels,
430 possibly a null pointer if it has none. */
431 const struct val_labs *
432 var_get_value_labels (const struct variable *v)
437 /* Returns true if variable V has at least one value label. */
439 var_has_value_labels (const struct variable *v)
441 return val_labs_count (v->val_labs) > 0;
444 /* Sets variable V's value labels to a copy of VLS,
445 which must have a width equal to V's width or one that can be
446 changed to V's width.
447 If VLS is null, then V's value labels, if any, are removed. */
449 var_set_value_labels_quiet (struct variable *v, const struct val_labs *vls)
451 bool changed = false;
453 if (v->val_labs != NULL)
455 val_labs_destroy (v->val_labs);
462 assert (val_labs_can_set_width (vls, v->width));
463 v->val_labs = val_labs_clone (vls);
464 val_labs_set_width (v->val_labs, v->width);
472 /* Sets variable V's value labels to a copy of VLS,
473 which must have a width equal to V's width or one that can be
474 changed to V's width.
475 If VLS is null, then V's value labels, if any, are removed. */
477 var_set_value_labels (struct variable *v, const struct val_labs *vls)
479 struct variable *ov = var_clone (v);
480 var_set_value_labels_quiet (v, vls);
481 dict_var_changed (v, VAR_TRAIT_LABEL, ov);
485 /* Makes sure that V has a set of value labels,
486 by assigning one to it if necessary. */
488 alloc_value_labels (struct variable *v)
490 if (v->val_labs == NULL)
491 v->val_labs = val_labs_create (v->width);
494 /* Attempts to add a value label with the given VALUE and UTF-8 encoded LABEL
495 to V. Returns true if successful, false otherwise (probably due to an
498 In LABEL, the two-byte sequence "\\n" is interpreted as a new-line. */
500 var_add_value_label (struct variable *v,
501 const union value *value, const char *label)
505 alloc_value_labels (v);
507 changed = val_labs_add (v->val_labs, value, label);
513 /* Adds or replaces a value label with the given VALUE and UTF-8 encoded LABEL
516 In LABEL, the two-byte sequence "\\n" is interpreted as a new-line. */
518 var_replace_value_label (struct variable *v,
519 const union value *value, const char *label)
521 alloc_value_labels (v);
522 val_labs_replace (v->val_labs, value, label);
526 /* Removes V's value labels, if any. */
528 var_clear_value_labels (struct variable *v)
530 var_set_value_labels (v, NULL);
533 /* Returns the label associated with VALUE for variable V, as a UTF-8 string in
534 a format suitable for output, or a null pointer if none. */
536 var_lookup_value_label (const struct variable *v, const union value *value)
538 return val_labs_find (v->val_labs, value);
542 Append to STR the string representation of VALUE for variable V.
543 STR must be a pointer to an initialised struct string.
546 append_value (const struct variable *v, const union value *value,
549 char *s = data_out (value, var_get_encoding (v), &v->print);
550 ds_put_cstr (str, s);
554 /* Append STR with a string representing VALUE for variable V.
555 That is, if VALUE has a label, append that label,
556 otherwise format VALUE and append the formatted string.
557 STR must be a pointer to an initialised struct string.
560 var_append_value_name (const struct variable *v, const union value *value,
563 enum settings_value_style style = settings_get_value_style ();
564 const char *name = var_lookup_value_label (v, value);
568 case SETTINGS_VAL_STYLE_VALUES:
569 append_value (v, value, str);
572 case SETTINGS_VAL_STYLE_LABELS:
574 append_value (v, value, str);
576 ds_put_cstr (str, name);
579 case SETTINGS_VAL_STYLE_BOTH:
581 append_value (v, value, str);
584 ds_put_cstr (str, " (");
585 ds_put_cstr (str, name);
586 ds_put_cstr (str, ")");
592 /* Print and write formats. */
594 /* Returns V's print format specification. */
595 const struct fmt_spec *
596 var_get_print_format (const struct variable *v)
601 /* Sets V's print format specification to PRINT, which must be a
602 valid format specification for a variable of V's width
603 (ordinarily an output format, but input formats are not
606 var_set_print_format_quiet (struct variable *v, const struct fmt_spec *print)
608 if (!fmt_equal (&v->print, print))
610 assert (fmt_check_width_compat (print, v->width));
616 /* Sets V's print format specification to PRINT, which must be a
617 valid format specification for a variable of V's width
618 (ordinarily an output format, but input formats are not
621 var_set_print_format (struct variable *v, const struct fmt_spec *print)
623 struct variable *ov = var_clone (v);
624 var_set_print_format_quiet (v, print);
625 dict_var_changed (v, VAR_TRAIT_PRINT_FORMAT, ov);
629 /* Returns V's write format specification. */
630 const struct fmt_spec *
631 var_get_write_format (const struct variable *v)
636 /* Sets V's write format specification to WRITE, which must be a
637 valid format specification for a variable of V's width
638 (ordinarily an output format, but input formats are not
641 var_set_write_format_quiet (struct variable *v, const struct fmt_spec *write)
643 if (!fmt_equal (&v->write, write))
645 assert (fmt_check_width_compat (write, v->width));
651 /* Sets V's write format specification to WRITE, which must be a
652 valid format specification for a variable of V's width
653 (ordinarily an output format, but input formats are not
656 var_set_write_format (struct variable *v, const struct fmt_spec *write)
658 struct variable *ov = var_clone (v);
659 var_set_write_format_quiet (v, write);
660 dict_var_changed (v, VAR_TRAIT_WRITE_FORMAT, ov);
664 /* Sets V's print and write format specifications to FORMAT,
665 which must be a valid format specification for a variable of
666 V's width (ordinarily an output format, but input formats are
669 var_set_both_formats (struct variable *v, const struct fmt_spec *format)
671 struct variable *ov = var_clone (v);
672 var_set_print_format_quiet (v, format);
673 var_set_write_format_quiet (v, format);
674 dict_var_changed (v, VAR_TRAIT_PRINT_FORMAT | VAR_TRAIT_WRITE_FORMAT, ov);
677 /* Returns the default print and write format for a variable of
678 the given TYPE, as set by var_create. The return value can be
679 used to reset a variable's print and write formats to the
682 var_default_formats (int width)
685 ? fmt_for_output (FMT_F, 8, 2)
686 : fmt_for_output (FMT_A, width, 0));
692 /* Update the combined name and label string if necessary */
694 update_vl_string (const struct variable *v)
696 /* Cast away const! */
697 struct string *str = (struct string *) &v->name_and_label;
699 if (ds_is_empty (str))
702 ds_put_format (str, _("%s (%s)"), v->label, v->name);
704 ds_put_cstr (str, v->name);
709 /* Return a string representing this variable, in the form most
710 appropriate from a human factors perspective, that is, its
711 variable label if it has one, otherwise its name. */
713 var_to_string (const struct variable *v)
715 enum settings_var_style style = settings_get_var_style ();
719 case SETTINGS_VAR_STYLE_NAMES:
722 case SETTINGS_VAR_STYLE_LABELS:
723 return v->label != NULL ? v->label : v->name;
725 case SETTINGS_VAR_STYLE_BOTH:
726 update_vl_string (v);
727 return ds_cstr (&v->name_and_label);
735 /* Returns V's variable label, or a null pointer if it has none. */
737 var_get_label (const struct variable *v)
742 /* Sets V's variable label to UTF-8 encoded string LABEL, stripping off leading
743 and trailing white space. If LABEL is a null pointer or if LABEL is an
744 empty string (after stripping white space), then V's variable label (if any)
747 var_set_label_quiet (struct variable *v, const char *label)
752 if (label != NULL && label[strspn (label, CC_SPACES)])
753 v->label = xstrdup (label);
755 ds_destroy (&v->name_and_label);
756 ds_init_empty (&v->name_and_label);
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 (struct variable *v, const char *label)
767 struct variable *ov = var_clone (v);
768 var_set_label_quiet (v, label);
769 dict_var_changed (v, VAR_TRAIT_LABEL, ov);
773 /* Removes any variable label from V. */
775 var_clear_label (struct variable *v)
777 var_set_label (v, NULL);
780 /* Returns true if V has a variable V,
783 var_has_label (const struct variable *v)
785 return v->label != NULL;
788 /* Returns true if M is a valid variable measurement level,
791 measure_is_valid (enum measure m)
793 return m == MEASURE_NOMINAL || m == MEASURE_ORDINAL || m == MEASURE_SCALE;
796 /* Returns a string version of measurement level M, for display to a user. */
798 measure_to_string (enum measure m)
802 case MEASURE_NOMINAL:
805 case MEASURE_ORDINAL:
816 /* Returns a string version of measurement level M, for use in PSPP command
819 measure_to_syntax (enum measure m)
823 case MEASURE_NOMINAL:
826 case MEASURE_ORDINAL:
837 /* Returns V's measurement level. */
839 var_get_measure (const struct variable *v)
844 /* Sets V's measurement level to MEASURE. */
846 var_set_measure_quiet (struct variable *v, enum measure measure)
848 assert (measure_is_valid (measure));
849 v->measure = measure;
852 /* Sets V's measurement level to MEASURE. */
854 var_set_measure (struct variable *v, enum measure measure)
856 struct variable *ov = var_clone (v);
857 var_set_measure_quiet (v, measure);
858 dict_var_changed (v, VAR_TRAIT_MEASURE, ov);
862 /* Returns the default measurement level for a variable of the
863 given TYPE, as set by var_create. The return value can be
864 used to reset a variable's measurement level to the
867 var_default_measure (enum val_type type)
869 return type == VAL_NUMERIC ? MEASURE_SCALE : MEASURE_NOMINAL;
872 /* Returns true if M is a valid variable role,
875 var_role_is_valid (enum var_role role)
892 /* Returns a string version of ROLE, for display to a user. */
894 var_role_to_string (enum var_role role)
911 return _("Partition");
921 /* Returns a string version of ROLE, for use in PSPP comamnd syntax. */
923 var_role_to_syntax (enum var_role role)
950 /* Returns V's role. */
952 var_get_role (const struct variable *v)
957 /* Sets V's role to ROLE. */
959 var_set_role_quiet (struct variable *v, enum var_role role)
961 assert (var_role_is_valid (role));
966 /* Sets V's role to ROLE. */
968 var_set_role (struct variable *v, enum var_role role)
970 struct variable *ov = var_clone (v);
971 var_set_role_quiet (v, role);
972 dict_var_changed (v, VAR_TRAIT_ROLE, ov);
975 /* Returns V's display width, which applies only to GUIs. */
977 var_get_display_width (const struct variable *v)
979 return v->display_width;
982 /* Sets V's display width to DISPLAY_WIDTH. */
984 var_set_display_width_quiet (struct variable *v, int new_width)
986 if (v->display_width != new_width)
988 v->display_width = new_width;
993 var_set_display_width (struct variable *v, int new_width)
995 if (v->display_width != new_width)
997 struct variable *ov = var_clone (v);
998 var_set_display_width_quiet (v, new_width);
999 dict_var_changed (v, VAR_TRAIT_DISPLAY_WIDTH, ov);
1003 /* Returns the default display width for a variable of the given
1004 WIDTH, as set by var_create. The return value can be used to
1005 reset a variable's display width to the default. */
1007 var_default_display_width (int width)
1009 return width == 0 ? 8 : MIN (width, 32);
1012 /* Returns true if A is a valid alignment,
1015 alignment_is_valid (enum alignment a)
1017 return a == ALIGN_LEFT || a == ALIGN_RIGHT || a == ALIGN_CENTRE;
1020 /* Returns a string version of alignment A, for display to a user. */
1022 alignment_to_string (enum alignment a)
1040 /* Returns a string version of alignment A, for use in PSPP command syntax. */
1042 alignment_to_syntax (enum alignment a)
1060 /* Returns V's display alignment, which applies only to GUIs. */
1062 var_get_alignment (const struct variable *v)
1064 return v->alignment;
1067 /* Sets V's display alignment to ALIGNMENT. */
1069 var_set_alignment_quiet (struct variable *v, enum alignment alignment)
1071 assert (alignment_is_valid (alignment));
1072 v->alignment = alignment;
1075 /* Sets V's display alignment to ALIGNMENT. */
1077 var_set_alignment (struct variable *v, enum alignment alignment)
1079 struct variable *ov = var_clone (v);
1080 var_set_alignment_quiet (v, alignment);
1081 dict_var_changed (v, VAR_TRAIT_ALIGNMENT, ov);
1085 /* Returns the default display alignment for a variable of the
1086 given TYPE, as set by var_create. The return value can be
1087 used to reset a variable's display alignment to the default. */
1089 var_default_alignment (enum val_type type)
1091 return type == VAL_NUMERIC ? ALIGN_RIGHT : ALIGN_LEFT;
1094 /* Whether variables' values should be preserved from case to
1097 /* Returns true if variable V's value should be left from case to
1098 case, instead of being reset to system-missing or blanks. */
1100 var_get_leave (const struct variable *v)
1105 /* Sets V's leave setting to LEAVE. */
1107 var_set_leave_quiet (struct variable *v, bool leave)
1109 assert (leave || !var_must_leave (v));
1114 /* Sets V's leave setting to LEAVE. */
1116 var_set_leave (struct variable *v, bool leave)
1118 struct variable *ov = var_clone (v);
1119 var_set_leave_quiet (v, leave);
1120 dict_var_changed (v, VAR_TRAIT_LEAVE, ov);
1124 /* Returns true if V must be left from case to case,
1125 false if it can be set either way. */
1127 var_must_leave (const struct variable *v)
1129 return var_get_dict_class (v) == DC_SCRATCH;
1132 /* Returns the number of short names stored in VAR.
1134 Short names are used only for system and portable file input
1135 and output. They are upper-case only, not necessarily unique,
1136 and limited to SHORT_NAME_LEN characters (plus a null
1137 terminator). Ordinarily a variable has at most one short
1138 name, but very long string variables (longer than 255 bytes)
1139 may have more. A variable might not have any short name at
1140 all if it hasn't been saved to or read from a system or
1143 var_get_short_name_cnt (const struct variable *var)
1145 return var->short_name_cnt;
1148 /* Returns VAR's short name with the given IDX, if it has one
1149 with that index, or a null pointer otherwise. Short names may
1150 be sparse: even if IDX is less than the number of short names
1151 in VAR, this function may return a null pointer. */
1153 var_get_short_name (const struct variable *var, size_t idx)
1155 return idx < var->short_name_cnt ? var->short_names[idx] : NULL;
1158 /* Sets VAR's short name with the given IDX to the UTF-8 string SHORT_NAME.
1159 The caller must already have checked that, in the dictionary encoding,
1160 SHORT_NAME is no more than SHORT_NAME_LEN bytes long. The new short name
1161 will be converted to uppercase.
1163 Specifying a null pointer for SHORT_NAME clears the specified short name. */
1165 var_set_short_name (struct variable *var, size_t idx, const char *short_name)
1167 struct variable *ov = var_clone (var);
1169 assert (short_name == NULL || id_is_plausible (short_name, false));
1171 /* Clear old short name numbered IDX, if any. */
1172 if (idx < var->short_name_cnt)
1174 free (var->short_names[idx]);
1175 var->short_names[idx] = NULL;
1178 /* Install new short name for IDX. */
1179 if (short_name != NULL)
1181 if (idx >= var->short_name_cnt)
1183 size_t old_cnt = var->short_name_cnt;
1185 var->short_name_cnt = MAX (idx * 2, 1);
1186 var->short_names = xnrealloc (var->short_names, var->short_name_cnt,
1187 sizeof *var->short_names);
1188 for (i = old_cnt; i < var->short_name_cnt; i++)
1189 var->short_names[i] = NULL;
1191 var->short_names[idx] = utf8_to_upper (short_name);
1194 dict_var_changed (var, VAR_TRAIT_NAME, ov);
1197 /* Clears V's short names. */
1199 var_clear_short_names (struct variable *v)
1201 if (v->short_name_cnt > 0)
1205 for (i = 0; i < v->short_name_cnt; i++)
1206 free (v->short_names[i]);
1207 free (v->short_names);
1208 v->short_names = NULL;
1209 v->short_name_cnt = 0;
1214 /* Relationship with dictionary. */
1216 /* Returns V's index within its dictionary, the value
1217 for which "dict_get_var (dict, index)" will return V.
1218 V must be in a dictionary. */
1220 var_get_dict_index (const struct variable *v)
1222 assert (var_has_vardict (v));
1223 return vardict_get_dict_index (v->vardict);
1226 /* Returns V's index within the case represented by its
1227 dictionary, that is, the value for which "case_data_idx (case,
1228 index)" will return the data for V in that case.
1229 V must be in a dictionary. */
1231 var_get_case_index (const struct variable *v)
1233 assert (var_has_vardict (v));
1234 return vardict_get_case_index (v->vardict);
1237 /* Returns variable V's attribute set. The caller may examine or
1238 modify the attribute set, but must not destroy it. Destroying
1239 V, or calling var_set_attributes() on V, will also destroy its
1242 var_get_attributes (const struct variable *v)
1244 return CONST_CAST (struct attrset *, &v->attributes);
1247 /* Replaces variable V's attributes set by a copy of ATTRS. */
1249 var_set_attributes_quiet (struct variable *v, const struct attrset *attrs)
1251 attrset_destroy (&v->attributes);
1252 attrset_clone (&v->attributes, attrs);
1256 /* Replaces variable V's attributes set by a copy of ATTRS. */
1258 var_set_attributes (struct variable *v, const struct attrset *attrs)
1260 struct variable *ov = var_clone (v);
1261 var_set_attributes_quiet (v, attrs);
1262 dict_var_changed (v, VAR_TRAIT_ATTRIBUTES, ov);
1266 /* Returns true if V has any custom attributes, false if it has none. */
1268 var_has_attributes (const struct variable *v)
1270 return attrset_count (&v->attributes) > 0;
1274 /* Creates and returns a clone of OLD_VAR. Most properties of
1275 the new variable are copied from OLD_VAR, except:
1277 - The variable's short name is not copied, because there is
1278 no reason to give a new variable with potentially a new
1279 name the same short name.
1281 - The new variable is not added to OLD_VAR's dictionary by
1282 default. Use dict_clone_var, instead, to do that.
1285 var_clone (const struct variable *old_var)
1287 struct variable *new_var = var_create (var_get_name (old_var),
1288 var_get_width (old_var));
1290 var_set_missing_values_quiet (new_var, var_get_missing_values (old_var));
1291 var_set_print_format_quiet (new_var, var_get_print_format (old_var));
1292 var_set_write_format_quiet (new_var, var_get_write_format (old_var));
1293 var_set_value_labels_quiet (new_var, var_get_value_labels (old_var));
1294 var_set_label_quiet (new_var, var_get_label (old_var));
1295 var_set_measure_quiet (new_var, var_get_measure (old_var));
1296 var_set_role_quiet (new_var, var_get_role (old_var));
1297 var_set_display_width_quiet (new_var, var_get_display_width (old_var));
1298 var_set_alignment_quiet (new_var, var_get_alignment (old_var));
1299 var_set_leave_quiet (new_var, var_get_leave (old_var));
1300 var_set_attributes_quiet (new_var, var_get_attributes (old_var));
1307 /* Returns the encoding of values of variable VAR. (This is actually a
1308 property of the dictionary.) Returns null if no specific encoding has been
1311 var_get_encoding (const struct variable *var)
1313 return (var_has_vardict (var)
1314 ? dict_get_encoding (vardict_get_dictionary (var->vardict))
1318 /* Returns V's vardict structure. */
1319 struct vardict_info *
1320 var_get_vardict (const struct variable *v)
1322 return CONST_CAST (struct vardict_info *, v->vardict);
1325 /* Sets V's vardict data to VARDICT. */
1327 var_set_vardict (struct variable *v, struct vardict_info *vardict)
1329 v->vardict = vardict;
1332 /* Returns true if V has vardict data. */
1334 var_has_vardict (const struct variable *v)
1336 return v->vardict != NULL;
1339 /* Clears V's vardict data. */
1341 var_clear_vardict (struct variable *v)
1347 var_save (const struct variable *var, struct pxd *pxd)
1349 struct pxd_builder b;
1352 pxd_builder_init (&b, pxd);
1354 pxd_builder_put_string (&b, var->name);
1355 pxd_builder_put_u16 (&b, var->width);
1356 pxd_builder_put_link (&b, mv_save (&var->miss, pxd));
1357 pxd_builder_put_u32 (&b, fmt_to_uint (&var->print));
1358 pxd_builder_put_u32 (&b, fmt_to_uint (&var->write));
1360 if (var_has_value_labels (var))
1362 pxd_builder_put_bool (&b, true);
1363 pxd_builder_put_link (&b, val_labs_save (var->val_labs, pxd));
1366 pxd_builder_put_bool (&b, false);
1368 pxd_builder_put_string (&b, var->label != NULL ? var->label : "");
1370 pxd_builder_put_u8 (&b, var->measure);
1371 pxd_builder_put_u32 (&b, var->display_width);
1372 pxd_builder_put_u8 (&b, var->alignment);
1374 pxd_builder_put_bool (&b, var->leave);
1376 pxd_builder_put_size_t (&b, var->short_name_cnt);
1377 for (i = 0; i < var->short_name_cnt; i++)
1378 pxd_builder_put_string (&b, var->short_names[i]);
1380 pxd_builder_put_link (&b, attrset_save (&var->attributes, pxd));
1382 return pxd_builder_commit (&b);
1386 var_load (struct pxd_object *object, const struct pxd *pxd)
1388 struct fmt_spec print, write;
1389 struct missing_values mv;
1390 struct variable *var;
1391 struct pxd_parser p;
1398 cached_var = pxd_cache_search (&var_cache, pxd_object_id (object));
1399 if (cached_var != NULL)
1403 var = var_clone (cached_var);
1405 /* var_clone() doesn't copy short names, so we need to. */
1406 n = cached_var->short_name_cnt;
1411 var->short_name_cnt = n;
1412 var->short_names = xmalloc (n * sizeof *var->short_names);
1413 for (i = 0; i < n; i++)
1414 var->short_names[i] = xstrdup (cached_var->short_names[i]);
1421 pxd_parser_init (&p, object, pxd);
1423 name = pxd_parser_get_string (&p);
1424 width = pxd_parser_get_u16 (&p);
1425 var = var_create (name, width);
1427 mv_load (&mv, pxd_parser_get_link (&p), pxd);
1428 var_set_missing_values (var, &mv);
1431 fmt_from_uint (&print, pxd_parser_get_u32 (&p));
1432 var_set_print_format (var, &print);
1434 fmt_from_uint (&write, pxd_parser_get_u32 (&p));
1435 var_set_write_format (var, &write);
1437 if (pxd_parser_get_bool (&p))
1438 var->val_labs = val_labs_load (pxd_parser_get_link (&p), pxd);
1440 label = pxd_parser_get_string (&p);
1442 var_set_label (var, label);
1445 var->measure = pxd_parser_get_u8 (&p);
1446 var->display_width = pxd_parser_get_u32 (&p);
1447 var->alignment = pxd_parser_get_u8 (&p);
1449 var->leave = pxd_parser_get_bool (&p);
1451 var->short_name_cnt = pxd_parser_get_size_t (&p);
1452 var->short_names = xmalloc (var->short_name_cnt * sizeof *var->short_names);
1453 for (i = 0; i < var->short_name_cnt; i++)
1454 var->short_names[i] = pxd_parser_get_string (&p);
1456 attrset_load (&var->attributes, pxd_parser_get_link (&p), pxd);
1458 pxd_parser_destroy (&p);
1464 var_uncache (struct variable *var UNUSED)