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 int display_width; /* Width of data editor column. */
62 enum alignment alignment; /* Alignment of data in GUI. */
64 /* Case information. */
65 bool leave; /* Leave value from case to case? */
67 /* Data for use by containing dictionary. */
68 struct vardict_info *vardict;
70 /* Used only for system and portable file input and output.
73 size_t short_name_cnt;
75 /* Custom attributes. */
76 struct attrset attributes;
80 static void var_set_print_format_quiet (struct variable *v, const struct fmt_spec *print);
81 static void var_set_write_format_quiet (struct variable *v, const struct fmt_spec *write);
82 static bool var_set_label_quiet (struct variable *v, const char *label, bool issue_warning);
83 static void var_set_name_quiet (struct variable *v, const char *name);
85 /* Creates and returns a new variable with the given NAME and
86 WIDTH and other fields initialized to default values. The
87 variable is not added to a dictionary; for that, use
88 dict_create_var instead. */
90 var_create (const char *name, int width)
95 assert (width >= 0 && width <= MAX_STRING);
97 v = xzalloc (sizeof *v);
98 var_set_name_quiet (v, name);
100 mv_init (&v->miss, width);
101 v->leave = var_must_leave (v);
102 type = val_type_from_width (width);
103 v->alignment = var_default_alignment (type);
104 v->measure = var_default_measure (type);
105 v->display_width = var_default_display_width (width);
106 v->print = v->write = var_default_formats (width);
107 attrset_init (&v->attributes);
108 ds_init_empty (&v->name_and_label);
113 /* Destroys variable V.
114 V must not belong to a dictionary. If it does, use
115 dict_delete_var instead. */
117 var_destroy (struct variable *v)
121 assert (!var_has_vardict (v));
122 mv_destroy (&v->miss);
123 var_clear_short_names (v);
124 val_labs_destroy (v->val_labs);
125 var_set_label_quiet (v, NULL, false);
126 attrset_destroy (var_get_attributes (v));
128 ds_destroy (&v->name_and_label);
133 /* Variable names. */
135 /* Return variable V's name, as a UTF-8 encoded string. */
137 var_get_name (const struct variable *v)
144 /* Sets V's name to NAME, a UTF-8 encoded string.
145 Do not use this function for a variable in a dictionary. Use
146 dict_rename_var instead. */
148 var_set_name_quiet (struct variable *v, const char *name)
150 assert (!var_has_vardict (v));
151 assert (id_is_plausible (name, false));
154 v->name = xstrdup (name);
155 ds_destroy (&v->name_and_label);
156 ds_init_empty (&v->name_and_label);
159 /* Sets V's name to NAME, a UTF-8 encoded string.
160 Do not use this function for a variable in a dictionary. Use
161 dict_rename_var instead. */
163 var_set_name (struct variable *v, const char *name)
165 struct variable *ov = var_clone (v);
166 var_set_name_quiet (v, name);
167 dict_var_changed (v, VAR_TRAIT_NAME, ov);
170 /* Returns VAR's dictionary class. */
172 var_get_dict_class (const struct variable *var)
174 return dict_class_from_id (var->name);
177 /* A hsh_compare_func that orders variables A and B by their
180 compare_vars_by_name (const void *a_, const void *b_, const void *aux UNUSED)
182 const struct variable *a = a_;
183 const struct variable *b = b_;
185 return utf8_strcasecmp (a->name, b->name);
188 /* A hsh_hash_func that hashes variable V based on its name. */
190 hash_var_by_name (const void *v_, const void *aux UNUSED)
192 const struct variable *v = v_;
194 return utf8_hash_case_string (v->name, 0);
197 /* A hsh_compare_func that orders pointers to variables A and B
200 compare_var_ptrs_by_name (const void *a_, const void *b_,
201 const void *aux UNUSED)
203 struct variable *const *a = a_;
204 struct variable *const *b = b_;
206 return utf8_strcasecmp (var_get_name (*a), var_get_name (*b));
209 /* A hsh_compare_func that orders pointers to variables A and B
210 by their dictionary indexes. */
212 compare_var_ptrs_by_dict_index (const void *a_, const void *b_,
213 const void *aux UNUSED)
215 struct variable *const *a = a_;
216 struct variable *const *b = b_;
217 size_t a_index = var_get_dict_index (*a);
218 size_t b_index = var_get_dict_index (*b);
220 return a_index < b_index ? -1 : a_index > b_index;
223 /* A hsh_hash_func that hashes pointer to variable V based on its
226 hash_var_ptr_by_name (const void *v_, const void *aux UNUSED)
228 struct variable *const *v = v_;
230 return utf8_hash_case_string (var_get_name (*v), 0);
233 /* Returns the type of variable V. */
235 var_get_type (const struct variable *v)
237 return val_type_from_width (v->width);
240 /* Returns the width of variable V. */
242 var_get_width (const struct variable *v)
248 var_set_width_and_formats (struct variable *v, int new_width,
249 const struct fmt_spec *print, const struct fmt_spec *write)
252 unsigned int traits = 0;
256 if (var_has_missing_values (v))
258 if (mv_is_resizable (&v->miss, new_width))
259 mv_resize (&v->miss, new_width);
262 mv_destroy (&v->miss);
263 mv_init (&v->miss, new_width);
265 traits |= VAR_TRAIT_MISSING_VALUES;
268 if (v->val_labs != NULL)
270 if (val_labs_can_set_width (v->val_labs, new_width))
271 val_labs_set_width (v->val_labs, new_width);
274 val_labs_destroy (v->val_labs);
277 traits |= VAR_TRAIT_VALUE_LABELS;
280 if (fmt_resize (&v->print, new_width))
281 traits |= VAR_TRAIT_PRINT_FORMAT;
283 if (fmt_resize (&v->write, new_width))
284 traits |= VAR_TRAIT_WRITE_FORMAT;
286 v->width = new_width;
287 traits |= VAR_TRAIT_WIDTH;
291 var_set_print_format_quiet (v, print);
292 traits |= VAR_TRAIT_PRINT_FORMAT;
297 var_set_write_format_quiet (v, write);
298 traits |= VAR_TRAIT_WRITE_FORMAT;
301 dict_var_changed (v, traits, ov);
304 /* Changes the width of V to NEW_WIDTH.
305 This function should be used cautiously. */
307 var_set_width (struct variable *v, int new_width)
309 const int old_width = v->width;
311 if (old_width == new_width)
314 var_set_width_and_formats (v, new_width, NULL, NULL);
320 /* Returns true if variable V is numeric, false otherwise. */
322 var_is_numeric (const struct variable *v)
324 return var_get_type (v) == VAL_NUMERIC;
327 /* Returns true if variable V is a string variable, false
330 var_is_alpha (const struct variable *v)
332 return var_get_type (v) == VAL_STRING;
335 /* Returns variable V's missing values. */
336 const struct missing_values *
337 var_get_missing_values (const struct variable *v)
342 /* Sets variable V's missing values to MISS, which must be of V's
343 width or at least resizable to V's width.
344 If MISS is null, then V's missing values, if any, are
347 var_set_missing_values_quiet (struct variable *v, const struct missing_values *miss)
351 assert (mv_is_resizable (miss, v->width));
352 mv_destroy (&v->miss);
353 mv_copy (&v->miss, miss);
354 mv_resize (&v->miss, v->width);
360 /* Sets variable V's missing values to MISS, which must be of V's
361 width or at least resizable to V's width.
362 If MISS is null, then V's missing values, if any, are
365 var_set_missing_values (struct variable *v, const struct missing_values *miss)
367 struct variable *ov = var_clone (v);
368 var_set_missing_values_quiet (v, miss);
369 dict_var_changed (v, VAR_TRAIT_MISSING_VALUES, ov);
372 /* Sets variable V to have no user-missing values. */
374 var_clear_missing_values (struct variable *v)
376 var_set_missing_values (v, NULL);
379 /* Returns true if V has any user-missing values,
382 var_has_missing_values (const struct variable *v)
384 return !mv_is_empty (&v->miss);
387 /* Returns true if VALUE is in the given CLASS of missing values
388 in V, false otherwise. */
390 var_is_value_missing (const struct variable *v, const union value *value,
393 return mv_is_value_missing (&v->miss, value, class);
396 /* Returns true if D is in the given CLASS of missing values in
398 V must be a numeric variable. */
400 var_is_num_missing (const struct variable *v, double d, enum mv_class class)
402 return mv_is_num_missing (&v->miss, d, class);
405 /* Returns true if S[] is a missing value for V, false otherwise.
406 S[] must contain exactly as many characters as V's width.
407 V must be a string variable. */
409 var_is_str_missing (const struct variable *v, const uint8_t s[],
412 return mv_is_str_missing (&v->miss, s, class);
415 /* Returns variable V's value labels,
416 possibly a null pointer if it has none. */
417 const struct val_labs *
418 var_get_value_labels (const struct variable *v)
423 /* Returns true if variable V has at least one value label. */
425 var_has_value_labels (const struct variable *v)
427 return val_labs_count (v->val_labs) > 0;
430 /* Sets variable V's value labels to a copy of VLS,
431 which must have a width equal to V's width or one that can be
432 changed to V's width.
433 If VLS is null, then V's value labels, if any, are removed. */
435 var_set_value_labels_quiet (struct variable *v, const struct val_labs *vls)
437 val_labs_destroy (v->val_labs);
442 assert (val_labs_can_set_width (vls, v->width));
443 v->val_labs = val_labs_clone (vls);
444 val_labs_set_width (v->val_labs, v->width);
449 /* Sets variable V's value labels to a copy of VLS,
450 which must have a width equal to V's width or one that can be
451 changed to V's width.
452 If VLS is null, then V's value labels, if any, are removed. */
454 var_set_value_labels (struct variable *v, const struct val_labs *vls)
456 struct variable *ov = var_clone (v);
457 var_set_value_labels_quiet (v, vls);
458 dict_var_changed (v, VAR_TRAIT_LABEL, ov);
462 /* Makes sure that V has a set of value labels,
463 by assigning one to it if necessary. */
465 alloc_value_labels (struct variable *v)
467 if (v->val_labs == NULL)
468 v->val_labs = val_labs_create (v->width);
471 /* Attempts to add a value label with the given VALUE and UTF-8 encoded LABEL
472 to V. Returns true if successful, false otherwise (probably due to an
475 In LABEL, the two-byte sequence "\\n" is interpreted as a new-line. */
477 var_add_value_label (struct variable *v,
478 const union value *value, const char *label)
480 alloc_value_labels (v);
481 return val_labs_add (v->val_labs, value, label);
484 /* Adds or replaces a value label with the given VALUE and UTF-8 encoded LABEL
487 In LABEL, the two-byte sequence "\\n" is interpreted as a new-line. */
489 var_replace_value_label (struct variable *v,
490 const union value *value, const char *label)
492 alloc_value_labels (v);
493 val_labs_replace (v->val_labs, value, label);
496 /* Removes V's value labels, if any. */
498 var_clear_value_labels (struct variable *v)
500 var_set_value_labels (v, NULL);
503 /* Returns the label associated with VALUE for variable V, as a UTF-8 string in
504 a format suitable for output, or a null pointer if none. */
506 var_lookup_value_label (const struct variable *v, const union value *value)
508 return val_labs_find (v->val_labs, value);
512 Append to STR the string representation of VALUE for variable V.
513 STR must be a pointer to an initialised struct string.
516 append_value (const struct variable *v, const union value *value,
519 char *s = data_out (value, var_get_encoding (v), &v->print);
520 ds_put_cstr (str, s);
524 /* Append STR with a string representing VALUE for variable V.
525 That is, if VALUE has a label, append that label,
526 otherwise format VALUE and append the formatted string.
527 STR must be a pointer to an initialised struct string.
530 var_append_value_name (const struct variable *v, const union value *value,
533 enum settings_value_style style = settings_get_value_style ();
534 const char *name = var_lookup_value_label (v, value);
538 case SETTINGS_VAL_STYLE_VALUES:
539 append_value (v, value, str);
542 case SETTINGS_VAL_STYLE_LABELS:
544 append_value (v, value, str);
546 ds_put_cstr (str, name);
549 case SETTINGS_VAL_STYLE_BOTH:
551 append_value (v, value, str);
554 ds_put_cstr (str, " (");
555 ds_put_cstr (str, name);
556 ds_put_cstr (str, ")");
562 /* Print and write formats. */
564 /* Returns V's print format specification. */
565 const struct fmt_spec *
566 var_get_print_format (const struct variable *v)
571 /* Sets V's print format specification to PRINT, which must be a
572 valid format specification for a variable of V's width
573 (ordinarily an output format, but input formats are not
576 var_set_print_format_quiet (struct variable *v, const struct fmt_spec *print)
578 if (!fmt_equal (&v->print, print))
580 assert (fmt_check_width_compat (print, v->width));
585 /* Sets V's print format specification to PRINT, which must be a
586 valid format specification for a variable of V's width
587 (ordinarily an output format, but input formats are not
590 var_set_print_format (struct variable *v, const struct fmt_spec *print)
592 struct variable *ov = var_clone (v);
593 var_set_print_format_quiet (v, print);
594 dict_var_changed (v, VAR_TRAIT_PRINT_FORMAT, ov);
597 /* Returns V's write format specification. */
598 const struct fmt_spec *
599 var_get_write_format (const struct variable *v)
604 /* Sets V's write format specification to WRITE, which must be a
605 valid format specification for a variable of V's width
606 (ordinarily an output format, but input formats are not
609 var_set_write_format_quiet (struct variable *v, const struct fmt_spec *write)
611 if (!fmt_equal (&v->write, write))
613 assert (fmt_check_width_compat (write, v->width));
618 /* Sets V's write format specification to WRITE, which must be a
619 valid format specification for a variable of V's width
620 (ordinarily an output format, but input formats are not
623 var_set_write_format (struct variable *v, const struct fmt_spec *write)
625 struct variable *ov = var_clone (v);
626 var_set_write_format_quiet (v, write);
627 dict_var_changed (v, VAR_TRAIT_WRITE_FORMAT, ov);
631 /* Sets V's print and write format specifications to FORMAT,
632 which must be a valid format specification for a variable of
633 V's width (ordinarily an output format, but input formats are
636 var_set_both_formats (struct variable *v, const struct fmt_spec *format)
638 struct variable *ov = var_clone (v);
639 var_set_print_format_quiet (v, format);
640 var_set_write_format_quiet (v, format);
641 dict_var_changed (v, VAR_TRAIT_PRINT_FORMAT | VAR_TRAIT_WRITE_FORMAT, ov);
644 /* Returns the default print and write format for a variable of
645 the given TYPE, as set by var_create. The return value can be
646 used to reset a variable's print and write formats to the
649 var_default_formats (int width)
652 ? fmt_for_output (FMT_F, 8, 2)
653 : fmt_for_output (FMT_A, width, 0));
659 /* Update the combined name and label string if necessary */
661 update_vl_string (const struct variable *v)
663 /* Cast away const! */
664 struct string *str = (struct string *) &v->name_and_label;
666 if (ds_is_empty (str))
669 ds_put_format (str, _("%s (%s)"), v->label, v->name);
671 ds_put_cstr (str, v->name);
676 /* Return a string representing this variable, in the form most
677 appropriate from a human factors perspective, that is, its
678 variable label if it has one, otherwise its name. */
680 var_to_string (const struct variable *v)
682 enum settings_var_style style = settings_get_var_style ();
686 case SETTINGS_VAR_STYLE_NAMES:
689 case SETTINGS_VAR_STYLE_LABELS:
690 return v->label != NULL ? v->label : v->name;
692 case SETTINGS_VAR_STYLE_BOTH:
693 update_vl_string (v);
694 return ds_cstr (&v->name_and_label);
702 /* Returns V's variable label, or a null pointer if it has none. */
704 var_get_label (const struct variable *v)
709 /* Sets V's variable label to UTF-8 encoded string LABEL, stripping off leading
710 and trailing white space. If LABEL is a null pointer or if LABEL is an
711 empty string (after stripping white space), then V's variable label (if any)
714 Variable labels are limited to 255 bytes in V's encoding (as returned by
715 var_get_encoding()). If LABEL fits within this limit, this function returns
716 true. Otherwise, the variable label is set to a truncated value, this
717 function returns false and, if ISSUE_WARNING is true, issues a warning. */
719 var_set_label_quiet (struct variable *v, const char *label, bool issue_warning)
721 bool truncated = false;
726 if (label != NULL && label[strspn (label, CC_SPACES)])
728 const char *dict_encoding = var_get_encoding (v);
729 struct substring s = ss_cstr (label);
732 if (dict_encoding != NULL)
734 enum { MAX_LABEL_LEN = 255 };
736 trunc_len = utf8_encoding_trunc_len (label, dict_encoding,
738 if (ss_length (s) > trunc_len)
741 msg (SW, _("Truncating variable label for variable `%s' to %d "
742 "bytes."), var_get_name (v), MAX_LABEL_LEN);
743 ss_truncate (&s, trunc_len);
748 v->label = ss_xstrdup (s);
751 ds_destroy (&v->name_and_label);
752 ds_init_empty (&v->name_and_label);
759 /* Sets V's variable label to UTF-8 encoded string LABEL, stripping off leading
760 and trailing white space. If LABEL is a null pointer or if LABEL is an
761 empty string (after stripping white space), then V's variable label (if any)
764 Variable labels are limited to 255 bytes in V's encoding (as returned by
765 var_get_encoding()). If LABEL fits within this limit, this function returns
766 true. Otherwise, the variable label is set to a truncated value, this
767 function returns false and, if ISSUE_WARNING is true, issues a warning. */
769 var_set_label (struct variable *v, const char *label, bool issue_warning)
771 struct variable *ov = var_clone (v);
772 bool truncated = var_set_label_quiet (v, label, issue_warning);
774 dict_var_changed (v, VAR_TRAIT_LABEL, ov);
780 /* Removes any variable label from V. */
782 var_clear_label (struct variable *v)
784 var_set_label (v, NULL, false);
787 /* Returns true if V has a variable V,
790 var_has_label (const struct variable *v)
792 return v->label != NULL;
795 /* Returns true if M is a valid variable measurement level,
798 measure_is_valid (enum measure m)
800 return m == MEASURE_NOMINAL || m == MEASURE_ORDINAL || m == MEASURE_SCALE;
803 /* Returns a string version of measurement level M, for display to a user. */
805 measure_to_string (enum measure m)
809 case MEASURE_NOMINAL:
812 case MEASURE_ORDINAL:
823 /* Returns V's measurement level. */
825 var_get_measure (const struct variable *v)
830 /* Sets V's measurement level to MEASURE. */
832 var_set_measure_quiet (struct variable *v, enum measure measure)
834 assert (measure_is_valid (measure));
835 v->measure = measure;
839 /* Sets V's measurement level to MEASURE. */
841 var_set_measure (struct variable *v, enum measure measure)
843 struct variable *ov = var_clone (v);
844 var_set_measure_quiet (v, measure);
845 dict_var_changed (v, VAR_TRAIT_MEASURE, ov);
849 /* Returns the default measurement level for a variable of the
850 given TYPE, as set by var_create. The return value can be
851 used to reset a variable's measurement level to the
854 var_default_measure (enum val_type type)
856 return type == VAL_NUMERIC ? MEASURE_SCALE : MEASURE_NOMINAL;
859 /* Returns V's display width, which applies only to GUIs. */
861 var_get_display_width (const struct variable *v)
863 return v->display_width;
866 /* Sets V's display width to DISPLAY_WIDTH. */
868 var_set_display_width_quiet (struct variable *v, int new_width)
870 if (v->display_width != new_width)
872 v->display_width = new_width;
877 var_set_display_width (struct variable *v, int new_width)
879 struct variable *ov = var_clone (v);
880 var_set_display_width_quiet (v, new_width);
881 dict_var_changed (v, VAR_TRAIT_DISPLAY_WIDTH, ov);
885 /* Returns the default display width for a variable of the given
886 WIDTH, as set by var_create. The return value can be used to
887 reset a variable's display width to the default. */
889 var_default_display_width (int width)
891 return width == 0 ? 8 : MIN (width, 32);
894 /* Returns true if A is a valid alignment,
897 alignment_is_valid (enum alignment a)
899 return a == ALIGN_LEFT || a == ALIGN_RIGHT || a == ALIGN_CENTRE;
902 /* Returns a string version of alignment A, for display to a user. */
904 alignment_to_string (enum alignment a)
922 /* Returns V's display alignment, which applies only to GUIs. */
924 var_get_alignment (const struct variable *v)
929 /* Sets V's display alignment to ALIGNMENT. */
931 var_set_alignment_quiet (struct variable *v, enum alignment alignment)
933 assert (alignment_is_valid (alignment));
934 v->alignment = alignment;
937 /* Sets V's display alignment to ALIGNMENT. */
939 var_set_alignment (struct variable *v, enum alignment alignment)
941 struct variable *ov = var_clone (v);
942 var_set_alignment_quiet (v, alignment);
943 dict_var_changed (v, VAR_TRAIT_ALIGNMENT, ov);
947 /* Returns the default display alignment for a variable of the
948 given TYPE, as set by var_create. The return value can be
949 used to reset a variable's display alignment to the default. */
951 var_default_alignment (enum val_type type)
953 return type == VAL_NUMERIC ? ALIGN_RIGHT : ALIGN_LEFT;
956 /* Whether variables' values should be preserved from case to
959 /* Returns true if variable V's value should be left from case to
960 case, instead of being reset to system-missing or blanks. */
962 var_get_leave (const struct variable *v)
967 /* Sets V's leave setting to LEAVE. */
969 var_set_leave_quiet (struct variable *v, bool leave)
971 assert (leave || !var_must_leave (v));
976 /* Sets V's leave setting to LEAVE. */
978 var_set_leave (struct variable *v, bool leave)
980 struct variable *ov = var_clone (v);
981 var_set_leave_quiet (v, leave);
982 dict_var_changed (v, VAR_TRAIT_LEAVE, ov);
986 /* Returns true if V must be left from case to case,
987 false if it can be set either way. */
989 var_must_leave (const struct variable *v)
991 return var_get_dict_class (v) == DC_SCRATCH;
994 /* Returns the number of short names stored in VAR.
996 Short names are used only for system and portable file input
997 and output. They are upper-case only, not necessarily unique,
998 and limited to SHORT_NAME_LEN characters (plus a null
999 terminator). Ordinarily a variable has at most one short
1000 name, but very long string variables (longer than 255 bytes)
1001 may have more. A variable might not have any short name at
1002 all if it hasn't been saved to or read from a system or
1005 var_get_short_name_cnt (const struct variable *var)
1007 return var->short_name_cnt;
1010 /* Returns VAR's short name with the given IDX, if it has one
1011 with that index, or a null pointer otherwise. Short names may
1012 be sparse: even if IDX is less than the number of short names
1013 in VAR, this function may return a null pointer. */
1015 var_get_short_name (const struct variable *var, size_t idx)
1017 return idx < var->short_name_cnt ? var->short_names[idx] : NULL;
1020 /* Sets VAR's short name with the given IDX to the UTF-8 string SHORT_NAME.
1021 The caller must already have checked that, in the dictionary encoding,
1022 SHORT_NAME is no more than SHORT_NAME_LEN bytes long. The new short name
1023 will be converted to uppercase.
1025 Specifying a null pointer for SHORT_NAME clears the specified short name. */
1027 var_set_short_name (struct variable *var, size_t idx, const char *short_name)
1029 struct variable *ov = var_clone (var);
1031 assert (short_name == NULL || id_is_plausible (short_name, false));
1033 /* Clear old short name numbered IDX, if any. */
1034 if (idx < var->short_name_cnt)
1036 free (var->short_names[idx]);
1037 var->short_names[idx] = NULL;
1040 /* Install new short name for IDX. */
1041 if (short_name != NULL)
1043 if (idx >= var->short_name_cnt)
1045 size_t old_cnt = var->short_name_cnt;
1047 var->short_name_cnt = MAX (idx * 2, 1);
1048 var->short_names = xnrealloc (var->short_names, var->short_name_cnt,
1049 sizeof *var->short_names);
1050 for (i = old_cnt; i < var->short_name_cnt; i++)
1051 var->short_names[i] = NULL;
1053 var->short_names[idx] = utf8_to_upper (short_name);
1056 dict_var_changed (var, VAR_TRAIT_NAME, ov);
1059 /* Clears V's short names. */
1061 var_clear_short_names (struct variable *v)
1065 for (i = 0; i < v->short_name_cnt; i++)
1066 free (v->short_names[i]);
1067 free (v->short_names);
1068 v->short_names = NULL;
1069 v->short_name_cnt = 0;
1072 /* Relationship with dictionary. */
1074 /* Returns V's index within its dictionary, the value
1075 for which "dict_get_var (dict, index)" will return V.
1076 V must be in a dictionary. */
1078 var_get_dict_index (const struct variable *v)
1080 assert (var_has_vardict (v));
1081 return vardict_get_dict_index (v->vardict);
1084 /* Returns V's index within the case represented by its
1085 dictionary, that is, the value for which "case_data_idx (case,
1086 index)" will return the data for V in that case.
1087 V must be in a dictionary. */
1089 var_get_case_index (const struct variable *v)
1091 assert (var_has_vardict (v));
1092 return vardict_get_case_index (v->vardict);
1095 /* Returns variable V's attribute set. The caller may examine or
1096 modify the attribute set, but must not destroy it. Destroying
1097 V, or calling var_set_attributes() on V, will also destroy its
1100 var_get_attributes (const struct variable *v)
1102 return CONST_CAST (struct attrset *, &v->attributes);
1105 /* Replaces variable V's attributes set by a copy of ATTRS. */
1107 var_set_attributes_quiet (struct variable *v, const struct attrset *attrs)
1109 attrset_destroy (&v->attributes);
1110 attrset_clone (&v->attributes, attrs);
1113 /* Replaces variable V's attributes set by a copy of ATTRS. */
1115 var_set_attributes (struct variable *v, const struct attrset *attrs)
1117 struct variable *ov = var_clone (v);
1118 var_set_attributes_quiet (v, attrs);
1119 dict_var_changed (v, VAR_TRAIT_ATTRIBUTES, ov);
1123 /* Returns true if V has any custom attributes, false if it has none. */
1125 var_has_attributes (const struct variable *v)
1127 return attrset_count (&v->attributes) > 0;
1131 /* Creates and returns a clone of OLD_VAR. Most properties of
1132 the new variable are copied from OLD_VAR, except:
1134 - The variable's short name is not copied, because there is
1135 no reason to give a new variable with potentially a new
1136 name the same short name.
1138 - The new variable is not added to OLD_VAR's dictionary by
1139 default. Use dict_clone_var, instead, to do that.
1142 var_clone (const struct variable *old_var)
1144 struct variable *new_var = var_create (var_get_name (old_var),
1145 var_get_width (old_var));
1147 var_set_missing_values_quiet (new_var, var_get_missing_values (old_var));
1148 var_set_print_format_quiet (new_var, var_get_print_format (old_var));
1149 var_set_write_format_quiet (new_var, var_get_write_format (old_var));
1150 var_set_value_labels_quiet (new_var, var_get_value_labels (old_var));
1151 var_set_label_quiet (new_var, var_get_label (old_var), false);
1152 var_set_measure_quiet (new_var, var_get_measure (old_var));
1153 var_set_display_width_quiet (new_var, var_get_display_width (old_var));
1154 var_set_alignment_quiet (new_var, var_get_alignment (old_var));
1155 var_set_leave_quiet (new_var, var_get_leave (old_var));
1156 var_set_attributes_quiet (new_var, var_get_attributes (old_var));
1163 /* Returns the encoding of values of variable VAR. (This is actually a
1164 property of the dictionary.) Returns null if no specific encoding has been
1167 var_get_encoding (const struct variable *var)
1169 return (var_has_vardict (var)
1170 ? dict_get_encoding (vardict_get_dictionary (var->vardict))
1174 /* Returns V's vardict structure. */
1175 struct vardict_info *
1176 var_get_vardict (const struct variable *v)
1178 return CONST_CAST (struct vardict_info *, v->vardict);
1181 /* Sets V's vardict data to VARDICT. */
1183 var_set_vardict (struct variable *v, struct vardict_info *vardict)
1185 v->vardict = vardict;
1188 /* Returns true if V has vardict data. */
1190 var_has_vardict (const struct variable *v)
1192 return v->vardict != NULL;
1195 /* Clears V's vardict data. */
1197 var_clear_vardict (struct variable *v)