1 /* PSPP - a program for statistical analysis.
2 Copyright (C) 1997-9, 2000, 2006, 2009, 2010, 2011, 2012, 2013 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/message.h"
37 #include "libpspp/misc.h"
38 #include "libpspp/str.h"
40 #include "gl/minmax.h"
41 #include "gl/xalloc.h"
44 #define _(msgid) gettext (msgid)
49 /* Dictionary information. */
50 char *name; /* Variable name. Mixed case. */
51 int width; /* 0 for numeric, otherwise string width. */
52 struct missing_values miss; /* Missing values. */
53 struct fmt_spec print; /* Default format for PRINT. */
54 struct fmt_spec write; /* Default format for WRITE. */
55 struct val_labs *val_labs; /* Value labels. */
56 char *label; /* Variable label. */
57 struct string name_and_label; /* The name and label in the same string */
59 /* GUI information. */
60 enum measure measure; /* Nominal, ordinal, or continuous. */
61 enum var_role role; /* Intended use. */
62 int display_width; /* Width of data editor column. */
63 enum alignment alignment; /* Alignment of data in GUI. */
65 /* Case information. */
66 bool leave; /* Leave value from case to case? */
68 /* Data for use by containing dictionary. */
69 struct vardict_info *vardict;
71 /* Used only for system and portable file input and output.
74 size_t short_name_cnt;
76 /* Custom attributes. */
77 struct attrset attributes;
81 static void var_set_print_format_quiet (struct variable *v, const struct fmt_spec *print);
82 static void var_set_write_format_quiet (struct variable *v, const struct fmt_spec *write);
83 static bool var_set_label_quiet (struct variable *v, const char *label, bool issue_warning);
84 static void var_set_name_quiet (struct variable *v, const char *name);
86 /* Creates and returns a new variable with the given NAME and
87 WIDTH and other fields initialized to default values. The
88 variable is not added to a dictionary; for that, use
89 dict_create_var instead. */
91 var_create (const char *name, int width)
96 assert (width >= 0 && width <= MAX_STRING);
98 v = xzalloc (sizeof *v);
99 var_set_name_quiet (v, name);
101 mv_init (&v->miss, width);
102 v->leave = var_must_leave (v);
103 type = val_type_from_width (width);
104 v->alignment = var_default_alignment (type);
105 v->measure = var_default_measure (type);
106 v->role = ROLE_INPUT;
107 v->display_width = var_default_display_width (width);
108 v->print = v->write = var_default_formats (width);
109 attrset_init (&v->attributes);
110 ds_init_empty (&v->name_and_label);
115 /* Destroys variable V.
116 V must not belong to a dictionary. If it does, use
117 dict_delete_var instead. */
119 var_destroy (struct variable *v)
123 assert (!var_has_vardict (v));
124 mv_destroy (&v->miss);
125 var_clear_short_names (v);
126 val_labs_destroy (v->val_labs);
127 var_set_label_quiet (v, NULL, false);
128 attrset_destroy (var_get_attributes (v));
130 ds_destroy (&v->name_and_label);
135 /* Variable names. */
137 /* Return variable V's name, as a UTF-8 encoded string. */
139 var_get_name (const struct variable *v)
146 /* Sets V's name to NAME, a UTF-8 encoded string.
147 Do not use this function for a variable in a dictionary. Use
148 dict_rename_var instead. */
150 var_set_name_quiet (struct variable *v, const char *name)
152 assert (!var_has_vardict (v));
153 assert (id_is_plausible (name, false));
156 v->name = xstrdup (name);
157 ds_destroy (&v->name_and_label);
158 ds_init_empty (&v->name_and_label);
161 /* Sets V's name to NAME, a UTF-8 encoded string.
162 Do not use this function for a variable in a dictionary. Use
163 dict_rename_var instead. */
165 var_set_name (struct variable *v, const char *name)
167 struct variable *ov = var_clone (v);
168 var_set_name_quiet (v, name);
169 dict_var_changed (v, VAR_TRAIT_NAME, ov);
172 /* Returns VAR's dictionary class. */
174 var_get_dict_class (const struct variable *var)
176 return dict_class_from_id (var->name);
179 /* A hsh_compare_func that orders variables A and B by their
182 compare_vars_by_name (const void *a_, const void *b_, const void *aux UNUSED)
184 const struct variable *a = a_;
185 const struct variable *b = b_;
187 return utf8_strcasecmp (a->name, b->name);
190 /* A hsh_hash_func that hashes variable V based on its name. */
192 hash_var_by_name (const void *v_, const void *aux UNUSED)
194 const struct variable *v = v_;
196 return utf8_hash_case_string (v->name, 0);
199 /* A hsh_compare_func that orders pointers to variables A and B
202 compare_var_ptrs_by_name (const void *a_, const void *b_,
203 const void *aux UNUSED)
205 struct variable *const *a = a_;
206 struct variable *const *b = b_;
208 return utf8_strcasecmp (var_get_name (*a), var_get_name (*b));
211 /* A hsh_compare_func that orders pointers to variables A and B
212 by their dictionary indexes. */
214 compare_var_ptrs_by_dict_index (const void *a_, const void *b_,
215 const void *aux UNUSED)
217 struct variable *const *a = a_;
218 struct variable *const *b = b_;
219 size_t a_index = var_get_dict_index (*a);
220 size_t b_index = var_get_dict_index (*b);
222 return a_index < b_index ? -1 : a_index > b_index;
225 /* A hsh_hash_func that hashes pointer to variable V based on its
228 hash_var_ptr_by_name (const void *v_, const void *aux UNUSED)
230 struct variable *const *v = v_;
232 return utf8_hash_case_string (var_get_name (*v), 0);
235 /* Returns the type of variable V. */
237 var_get_type (const struct variable *v)
239 return val_type_from_width (v->width);
242 /* Returns the width of variable V. */
244 var_get_width (const struct variable *v)
250 var_set_width_and_formats (struct variable *v, int new_width,
251 const struct fmt_spec *print, const struct fmt_spec *write)
254 unsigned int traits = 0;
258 if (var_has_missing_values (v))
260 if (mv_is_resizable (&v->miss, new_width))
261 mv_resize (&v->miss, new_width);
264 mv_destroy (&v->miss);
265 mv_init (&v->miss, new_width);
267 traits |= VAR_TRAIT_MISSING_VALUES;
270 if (v->val_labs != NULL)
272 if (val_labs_can_set_width (v->val_labs, new_width))
273 val_labs_set_width (v->val_labs, new_width);
276 val_labs_destroy (v->val_labs);
279 traits |= VAR_TRAIT_VALUE_LABELS;
282 if (fmt_resize (&v->print, new_width))
283 traits |= VAR_TRAIT_PRINT_FORMAT;
285 if (fmt_resize (&v->write, new_width))
286 traits |= VAR_TRAIT_WRITE_FORMAT;
288 if (v->width != new_width)
290 v->width = new_width;
291 traits |= VAR_TRAIT_WIDTH;
296 var_set_print_format_quiet (v, print);
297 traits |= VAR_TRAIT_PRINT_FORMAT;
302 var_set_write_format_quiet (v, write);
303 traits |= VAR_TRAIT_WRITE_FORMAT;
307 dict_var_changed (v, traits, ov);
310 /* Changes the width of V to NEW_WIDTH.
311 This function should be used cautiously. */
313 var_set_width (struct variable *v, int new_width)
315 const int old_width = v->width;
317 if (old_width == new_width)
320 var_set_width_and_formats (v, new_width, NULL, NULL);
326 /* Returns true if variable V is numeric, false otherwise. */
328 var_is_numeric (const struct variable *v)
330 return var_get_type (v) == VAL_NUMERIC;
333 /* Returns true if variable V is a string variable, false
336 var_is_alpha (const struct variable *v)
338 return var_get_type (v) == VAL_STRING;
341 /* Returns variable V's missing values. */
342 const struct missing_values *
343 var_get_missing_values (const struct variable *v)
348 /* Sets variable V's missing values to MISS, which must be of V's
349 width or at least resizable to V's width.
350 If MISS is null, then V's missing values, if any, are
353 var_set_missing_values_quiet (struct variable *v, const struct missing_values *miss)
357 assert (mv_is_resizable (miss, v->width));
358 mv_destroy (&v->miss);
359 mv_copy (&v->miss, miss);
360 mv_resize (&v->miss, v->width);
366 /* Sets variable V's missing values to MISS, which must be of V's
367 width or at least resizable to V's width.
368 If MISS is null, then V's missing values, if any, are
371 var_set_missing_values (struct variable *v, const struct missing_values *miss)
373 struct variable *ov = var_clone (v);
374 var_set_missing_values_quiet (v, miss);
375 dict_var_changed (v, VAR_TRAIT_MISSING_VALUES, ov);
378 /* Sets variable V to have no user-missing values. */
380 var_clear_missing_values (struct variable *v)
382 var_set_missing_values (v, NULL);
385 /* Returns true if V has any user-missing values,
388 var_has_missing_values (const struct variable *v)
390 return !mv_is_empty (&v->miss);
393 /* Returns true if VALUE is in the given CLASS of missing values
394 in V, false otherwise. */
396 var_is_value_missing (const struct variable *v, const union value *value,
399 return mv_is_value_missing (&v->miss, value, class);
402 /* Returns true if D is in the given CLASS of missing values in
404 V must be a numeric variable. */
406 var_is_num_missing (const struct variable *v, double d, enum mv_class class)
408 return mv_is_num_missing (&v->miss, d, class);
411 /* Returns true if S[] is a missing value for V, false otherwise.
412 S[] must contain exactly as many characters as V's width.
413 V must be a string variable. */
415 var_is_str_missing (const struct variable *v, const uint8_t s[],
418 return mv_is_str_missing (&v->miss, s, class);
421 /* Returns variable V's value labels,
422 possibly a null pointer if it has none. */
423 const struct val_labs *
424 var_get_value_labels (const struct variable *v)
429 /* Returns true if variable V has at least one value label. */
431 var_has_value_labels (const struct variable *v)
433 return val_labs_count (v->val_labs) > 0;
436 /* Sets variable V's value labels to a copy of VLS,
437 which must have a width equal to V's width or one that can be
438 changed to V's width.
439 If VLS is null, then V's value labels, if any, are removed. */
441 var_set_value_labels_quiet (struct variable *v, const struct val_labs *vls)
443 val_labs_destroy (v->val_labs);
448 assert (val_labs_can_set_width (vls, v->width));
449 v->val_labs = val_labs_clone (vls);
450 val_labs_set_width (v->val_labs, v->width);
455 /* Sets variable V's value labels to a copy of VLS,
456 which must have a width equal to V's width or one that can be
457 changed to V's width.
458 If VLS is null, then V's value labels, if any, are removed. */
460 var_set_value_labels (struct variable *v, const struct val_labs *vls)
462 struct variable *ov = var_clone (v);
463 var_set_value_labels_quiet (v, vls);
464 dict_var_changed (v, VAR_TRAIT_LABEL, ov);
468 /* Makes sure that V has a set of value labels,
469 by assigning one to it if necessary. */
471 alloc_value_labels (struct variable *v)
473 if (v->val_labs == NULL)
474 v->val_labs = val_labs_create (v->width);
477 /* Attempts to add a value label with the given VALUE and UTF-8 encoded LABEL
478 to V. Returns true if successful, false otherwise (probably due to an
481 In LABEL, the two-byte sequence "\\n" is interpreted as a new-line. */
483 var_add_value_label (struct variable *v,
484 const union value *value, const char *label)
486 alloc_value_labels (v);
487 return val_labs_add (v->val_labs, value, label);
490 /* Adds or replaces a value label with the given VALUE and UTF-8 encoded LABEL
493 In LABEL, the two-byte sequence "\\n" is interpreted as a new-line. */
495 var_replace_value_label (struct variable *v,
496 const union value *value, const char *label)
498 alloc_value_labels (v);
499 val_labs_replace (v->val_labs, value, label);
502 /* Removes V's value labels, if any. */
504 var_clear_value_labels (struct variable *v)
506 var_set_value_labels (v, NULL);
509 /* Returns the label associated with VALUE for variable V, as a UTF-8 string in
510 a format suitable for output, or a null pointer if none. */
512 var_lookup_value_label (const struct variable *v, const union value *value)
514 return val_labs_find (v->val_labs, value);
518 Append to STR the string representation of VALUE for variable V.
519 STR must be a pointer to an initialised struct string.
522 append_value (const struct variable *v, const union value *value,
525 char *s = data_out (value, var_get_encoding (v), &v->print);
526 ds_put_cstr (str, s);
530 /* Append STR with a string representing VALUE for variable V.
531 That is, if VALUE has a label, append that label,
532 otherwise format VALUE and append the formatted string.
533 STR must be a pointer to an initialised struct string.
536 var_append_value_name (const struct variable *v, const union value *value,
539 enum settings_value_style style = settings_get_value_style ();
540 const char *name = var_lookup_value_label (v, value);
544 case SETTINGS_VAL_STYLE_VALUES:
545 append_value (v, value, str);
548 case SETTINGS_VAL_STYLE_LABELS:
550 append_value (v, value, str);
552 ds_put_cstr (str, name);
555 case SETTINGS_VAL_STYLE_BOTH:
557 append_value (v, value, str);
560 ds_put_cstr (str, " (");
561 ds_put_cstr (str, name);
562 ds_put_cstr (str, ")");
568 /* Print and write formats. */
570 /* Returns V's print format specification. */
571 const struct fmt_spec *
572 var_get_print_format (const struct variable *v)
577 /* Sets V's print format specification to PRINT, which must be a
578 valid format specification for a variable of V's width
579 (ordinarily an output format, but input formats are not
582 var_set_print_format_quiet (struct variable *v, const struct fmt_spec *print)
584 if (!fmt_equal (&v->print, print))
586 assert (fmt_check_width_compat (print, v->width));
591 /* Sets V's print format specification to PRINT, which must be a
592 valid format specification for a variable of V's width
593 (ordinarily an output format, but input formats are not
596 var_set_print_format (struct variable *v, const struct fmt_spec *print)
598 struct variable *ov = var_clone (v);
599 var_set_print_format_quiet (v, print);
600 dict_var_changed (v, VAR_TRAIT_PRINT_FORMAT, ov);
603 /* Returns V's write format specification. */
604 const struct fmt_spec *
605 var_get_write_format (const struct variable *v)
610 /* Sets V's write format specification to WRITE, which must be a
611 valid format specification for a variable of V's width
612 (ordinarily an output format, but input formats are not
615 var_set_write_format_quiet (struct variable *v, const struct fmt_spec *write)
617 if (!fmt_equal (&v->write, write))
619 assert (fmt_check_width_compat (write, v->width));
624 /* Sets V's write format specification to WRITE, which must be a
625 valid format specification for a variable of V's width
626 (ordinarily an output format, but input formats are not
629 var_set_write_format (struct variable *v, const struct fmt_spec *write)
631 struct variable *ov = var_clone (v);
632 var_set_write_format_quiet (v, write);
633 dict_var_changed (v, VAR_TRAIT_WRITE_FORMAT, ov);
637 /* Sets V's print and write format specifications to FORMAT,
638 which must be a valid format specification for a variable of
639 V's width (ordinarily an output format, but input formats are
642 var_set_both_formats (struct variable *v, const struct fmt_spec *format)
644 struct variable *ov = var_clone (v);
645 var_set_print_format_quiet (v, format);
646 var_set_write_format_quiet (v, format);
647 dict_var_changed (v, VAR_TRAIT_PRINT_FORMAT | VAR_TRAIT_WRITE_FORMAT, ov);
650 /* Returns the default print and write format for a variable of
651 the given TYPE, as set by var_create. The return value can be
652 used to reset a variable's print and write formats to the
655 var_default_formats (int width)
658 ? fmt_for_output (FMT_F, 8, 2)
659 : fmt_for_output (FMT_A, width, 0));
665 /* Update the combined name and label string if necessary */
667 update_vl_string (const struct variable *v)
669 /* Cast away const! */
670 struct string *str = (struct string *) &v->name_and_label;
672 if (ds_is_empty (str))
675 ds_put_format (str, _("%s (%s)"), v->label, v->name);
677 ds_put_cstr (str, v->name);
682 /* Return a string representing this variable, in the form most
683 appropriate from a human factors perspective, that is, its
684 variable label if it has one, otherwise its name. */
686 var_to_string (const struct variable *v)
688 enum settings_var_style style = settings_get_var_style ();
692 case SETTINGS_VAR_STYLE_NAMES:
695 case SETTINGS_VAR_STYLE_LABELS:
696 return v->label != NULL ? v->label : v->name;
698 case SETTINGS_VAR_STYLE_BOTH:
699 update_vl_string (v);
700 return ds_cstr (&v->name_and_label);
708 /* Returns V's variable label, or a null pointer if it has none. */
710 var_get_label (const struct variable *v)
715 /* Sets V's variable label to UTF-8 encoded string LABEL, stripping off leading
716 and trailing white space. If LABEL is a null pointer or if LABEL is an
717 empty string (after stripping white space), then V's variable label (if any)
720 Variable labels are limited to 255 bytes in V's encoding (as returned by
721 var_get_encoding()). If LABEL fits within this limit, this function returns
722 true. Otherwise, the variable label is set to a truncated value, this
723 function returns false and, if ISSUE_WARNING is true, issues a warning. */
725 var_set_label_quiet (struct variable *v, const char *label, bool issue_warning)
727 bool truncated = false;
732 if (label != NULL && label[strspn (label, CC_SPACES)])
734 const char *dict_encoding = var_get_encoding (v);
735 struct substring s = ss_cstr (label);
738 if (dict_encoding != NULL)
740 enum { MAX_LABEL_LEN = 255 };
742 trunc_len = utf8_encoding_trunc_len (label, dict_encoding,
744 if (ss_length (s) > trunc_len)
747 msg (SW, _("Truncating variable label for variable `%s' to %d "
748 "bytes."), var_get_name (v), MAX_LABEL_LEN);
749 ss_truncate (&s, trunc_len);
754 v->label = ss_xstrdup (s);
757 ds_destroy (&v->name_and_label);
758 ds_init_empty (&v->name_and_label);
765 /* Sets V's variable label to UTF-8 encoded string LABEL, stripping off leading
766 and trailing white space. If LABEL is a null pointer or if LABEL is an
767 empty string (after stripping white space), then V's variable label (if any)
770 Variable labels are limited to 255 bytes in V's encoding (as returned by
771 var_get_encoding()). If LABEL fits within this limit, this function returns
772 true. Otherwise, the variable label is set to a truncated value, this
773 function returns false and, if ISSUE_WARNING is true, issues a warning. */
775 var_set_label (struct variable *v, const char *label, bool issue_warning)
777 struct variable *ov = var_clone (v);
778 bool truncated = var_set_label_quiet (v, label, issue_warning);
780 dict_var_changed (v, VAR_TRAIT_LABEL, ov);
786 /* Removes any variable label from V. */
788 var_clear_label (struct variable *v)
790 var_set_label (v, NULL, false);
793 /* Returns true if V has a variable V,
796 var_has_label (const struct variable *v)
798 return v->label != NULL;
801 /* Returns true if M is a valid variable measurement level,
804 measure_is_valid (enum measure m)
806 return m == MEASURE_NOMINAL || m == MEASURE_ORDINAL || m == MEASURE_SCALE;
809 /* Returns a string version of measurement level M, for display to a user. */
811 measure_to_string (enum measure m)
815 case MEASURE_NOMINAL:
818 case MEASURE_ORDINAL:
829 /* Returns a string version of measurement level M, for use in PSPP command
832 measure_to_syntax (enum measure m)
836 case MEASURE_NOMINAL:
839 case MEASURE_ORDINAL:
850 /* Returns V's measurement level. */
852 var_get_measure (const struct variable *v)
857 /* Sets V's measurement level to MEASURE. */
859 var_set_measure_quiet (struct variable *v, enum measure measure)
861 assert (measure_is_valid (measure));
862 v->measure = measure;
866 /* Sets V's measurement level to MEASURE. */
868 var_set_measure (struct variable *v, enum measure measure)
870 struct variable *ov = var_clone (v);
871 var_set_measure_quiet (v, measure);
872 dict_var_changed (v, VAR_TRAIT_MEASURE, ov);
876 /* Returns the default measurement level for a variable of the
877 given TYPE, as set by var_create. The return value can be
878 used to reset a variable's measurement level to the
881 var_default_measure (enum val_type type)
883 return type == VAL_NUMERIC ? MEASURE_SCALE : MEASURE_NOMINAL;
886 /* Returns true if M is a valid variable role,
889 var_role_is_valid (enum var_role role)
906 /* Returns a string version of ROLE, for display to a user. */
908 var_role_to_string (enum var_role role)
925 return _("Partition");
935 /* Returns a string version of ROLE, for use in PSPP comamnd syntax. */
937 var_role_to_syntax (enum var_role role)
964 /* Returns V's role. */
966 var_get_role (const struct variable *v)
971 /* Sets V's role to ROLE. */
973 var_set_role_quiet (struct variable *v, enum var_role role)
975 assert (var_role_is_valid (role));
980 /* Sets V's role to ROLE. */
982 var_set_role (struct variable *v, enum var_role role)
984 struct variable *ov = var_clone (v);
985 var_set_role_quiet (v, role);
986 dict_var_changed (v, VAR_TRAIT_ROLE, ov);
989 /* Returns V's display width, which applies only to GUIs. */
991 var_get_display_width (const struct variable *v)
993 return v->display_width;
996 /* Sets V's display width to DISPLAY_WIDTH. */
998 var_set_display_width_quiet (struct variable *v, int new_width)
1000 if (v->display_width != new_width)
1002 v->display_width = new_width;
1007 var_set_display_width (struct variable *v, int new_width)
1009 struct variable *ov = var_clone (v);
1010 var_set_display_width_quiet (v, new_width);
1011 dict_var_changed (v, VAR_TRAIT_DISPLAY_WIDTH, ov);
1015 /* Returns the default display width for a variable of the given
1016 WIDTH, as set by var_create. The return value can be used to
1017 reset a variable's display width to the default. */
1019 var_default_display_width (int width)
1021 return width == 0 ? 8 : MIN (width, 32);
1024 /* Returns true if A is a valid alignment,
1027 alignment_is_valid (enum alignment a)
1029 return a == ALIGN_LEFT || a == ALIGN_RIGHT || a == ALIGN_CENTRE;
1032 /* Returns a string version of alignment A, for display to a user. */
1034 alignment_to_string (enum alignment a)
1052 /* Returns a string version of alignment A, for use in PSPP command syntax. */
1054 alignment_to_syntax (enum alignment a)
1072 /* Returns V's display alignment, which applies only to GUIs. */
1074 var_get_alignment (const struct variable *v)
1076 return v->alignment;
1079 /* Sets V's display alignment to ALIGNMENT. */
1081 var_set_alignment_quiet (struct variable *v, enum alignment alignment)
1083 assert (alignment_is_valid (alignment));
1084 v->alignment = alignment;
1087 /* Sets V's display alignment to ALIGNMENT. */
1089 var_set_alignment (struct variable *v, enum alignment alignment)
1091 struct variable *ov = var_clone (v);
1092 var_set_alignment_quiet (v, alignment);
1093 dict_var_changed (v, VAR_TRAIT_ALIGNMENT, ov);
1097 /* Returns the default display alignment for a variable of the
1098 given TYPE, as set by var_create. The return value can be
1099 used to reset a variable's display alignment to the default. */
1101 var_default_alignment (enum val_type type)
1103 return type == VAL_NUMERIC ? ALIGN_RIGHT : ALIGN_LEFT;
1106 /* Whether variables' values should be preserved from case to
1109 /* Returns true if variable V's value should be left from case to
1110 case, instead of being reset to system-missing or blanks. */
1112 var_get_leave (const struct variable *v)
1117 /* Sets V's leave setting to LEAVE. */
1119 var_set_leave_quiet (struct variable *v, bool leave)
1121 assert (leave || !var_must_leave (v));
1126 /* Sets V's leave setting to LEAVE. */
1128 var_set_leave (struct variable *v, bool leave)
1130 struct variable *ov = var_clone (v);
1131 var_set_leave_quiet (v, leave);
1132 dict_var_changed (v, VAR_TRAIT_LEAVE, ov);
1136 /* Returns true if V must be left from case to case,
1137 false if it can be set either way. */
1139 var_must_leave (const struct variable *v)
1141 return var_get_dict_class (v) == DC_SCRATCH;
1144 /* Returns the number of short names stored in VAR.
1146 Short names are used only for system and portable file input
1147 and output. They are upper-case only, not necessarily unique,
1148 and limited to SHORT_NAME_LEN characters (plus a null
1149 terminator). Ordinarily a variable has at most one short
1150 name, but very long string variables (longer than 255 bytes)
1151 may have more. A variable might not have any short name at
1152 all if it hasn't been saved to or read from a system or
1155 var_get_short_name_cnt (const struct variable *var)
1157 return var->short_name_cnt;
1160 /* Returns VAR's short name with the given IDX, if it has one
1161 with that index, or a null pointer otherwise. Short names may
1162 be sparse: even if IDX is less than the number of short names
1163 in VAR, this function may return a null pointer. */
1165 var_get_short_name (const struct variable *var, size_t idx)
1167 return idx < var->short_name_cnt ? var->short_names[idx] : NULL;
1170 /* Sets VAR's short name with the given IDX to the UTF-8 string SHORT_NAME.
1171 The caller must already have checked that, in the dictionary encoding,
1172 SHORT_NAME is no more than SHORT_NAME_LEN bytes long. The new short name
1173 will be converted to uppercase.
1175 Specifying a null pointer for SHORT_NAME clears the specified short name. */
1177 var_set_short_name (struct variable *var, size_t idx, const char *short_name)
1179 struct variable *ov = var_clone (var);
1181 assert (short_name == NULL || id_is_plausible (short_name, false));
1183 /* Clear old short name numbered IDX, if any. */
1184 if (idx < var->short_name_cnt)
1186 free (var->short_names[idx]);
1187 var->short_names[idx] = NULL;
1190 /* Install new short name for IDX. */
1191 if (short_name != NULL)
1193 if (idx >= var->short_name_cnt)
1195 size_t old_cnt = var->short_name_cnt;
1197 var->short_name_cnt = MAX (idx * 2, 1);
1198 var->short_names = xnrealloc (var->short_names, var->short_name_cnt,
1199 sizeof *var->short_names);
1200 for (i = old_cnt; i < var->short_name_cnt; i++)
1201 var->short_names[i] = NULL;
1203 var->short_names[idx] = utf8_to_upper (short_name);
1206 dict_var_changed (var, VAR_TRAIT_NAME, ov);
1209 /* Clears V's short names. */
1211 var_clear_short_names (struct variable *v)
1215 for (i = 0; i < v->short_name_cnt; i++)
1216 free (v->short_names[i]);
1217 free (v->short_names);
1218 v->short_names = NULL;
1219 v->short_name_cnt = 0;
1222 /* Relationship with dictionary. */
1224 /* Returns V's index within its dictionary, the value
1225 for which "dict_get_var (dict, index)" will return V.
1226 V must be in a dictionary. */
1228 var_get_dict_index (const struct variable *v)
1230 assert (var_has_vardict (v));
1231 return vardict_get_dict_index (v->vardict);
1234 /* Returns V's index within the case represented by its
1235 dictionary, that is, the value for which "case_data_idx (case,
1236 index)" will return the data for V in that case.
1237 V must be in a dictionary. */
1239 var_get_case_index (const struct variable *v)
1241 assert (var_has_vardict (v));
1242 return vardict_get_case_index (v->vardict);
1245 /* Returns variable V's attribute set. The caller may examine or
1246 modify the attribute set, but must not destroy it. Destroying
1247 V, or calling var_set_attributes() on V, will also destroy its
1250 var_get_attributes (const struct variable *v)
1252 return CONST_CAST (struct attrset *, &v->attributes);
1255 /* Replaces variable V's attributes set by a copy of ATTRS. */
1257 var_set_attributes_quiet (struct variable *v, const struct attrset *attrs)
1259 attrset_destroy (&v->attributes);
1260 attrset_clone (&v->attributes, attrs);
1263 /* Replaces variable V's attributes set by a copy of ATTRS. */
1265 var_set_attributes (struct variable *v, const struct attrset *attrs)
1267 struct variable *ov = var_clone (v);
1268 var_set_attributes_quiet (v, attrs);
1269 dict_var_changed (v, VAR_TRAIT_ATTRIBUTES, ov);
1273 /* Returns true if V has any custom attributes, false if it has none. */
1275 var_has_attributes (const struct variable *v)
1277 return attrset_count (&v->attributes) > 0;
1281 /* Creates and returns a clone of OLD_VAR. Most properties of
1282 the new variable are copied from OLD_VAR, except:
1284 - The variable's short name is not copied, because there is
1285 no reason to give a new variable with potentially a new
1286 name the same short name.
1288 - The new variable is not added to OLD_VAR's dictionary by
1289 default. Use dict_clone_var, instead, to do that.
1292 var_clone (const struct variable *old_var)
1294 struct variable *new_var = var_create (var_get_name (old_var),
1295 var_get_width (old_var));
1297 var_set_missing_values_quiet (new_var, var_get_missing_values (old_var));
1298 var_set_print_format_quiet (new_var, var_get_print_format (old_var));
1299 var_set_write_format_quiet (new_var, var_get_write_format (old_var));
1300 var_set_value_labels_quiet (new_var, var_get_value_labels (old_var));
1301 var_set_label_quiet (new_var, var_get_label (old_var), false);
1302 var_set_measure_quiet (new_var, var_get_measure (old_var));
1303 var_set_role_quiet (new_var, var_get_role (old_var));
1304 var_set_display_width_quiet (new_var, var_get_display_width (old_var));
1305 var_set_alignment_quiet (new_var, var_get_alignment (old_var));
1306 var_set_leave_quiet (new_var, var_get_leave (old_var));
1307 var_set_attributes_quiet (new_var, var_get_attributes (old_var));
1314 /* Returns the encoding of values of variable VAR. (This is actually a
1315 property of the dictionary.) Returns null if no specific encoding has been
1318 var_get_encoding (const struct variable *var)
1320 return (var_has_vardict (var)
1321 ? dict_get_encoding (vardict_get_dictionary (var->vardict))
1325 /* Returns V's vardict structure. */
1326 struct vardict_info *
1327 var_get_vardict (const struct variable *v)
1329 return CONST_CAST (struct vardict_info *, v->vardict);
1332 /* Sets V's vardict data to VARDICT. */
1334 var_set_vardict (struct variable *v, struct vardict_info *vardict)
1336 v->vardict = vardict;
1339 /* Returns true if V has vardict data. */
1341 var_has_vardict (const struct variable *v)
1343 return v->vardict != NULL;
1346 /* Clears V's vardict data. */
1348 var_clear_vardict (struct variable *v)