1 /* PSPP - a program for statistical analysis.
2 Copyright (C) 1997-9, 2000, 2006, 2009, 2010, 2011, 2012, 2013, 2014, 2016 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)
45 #define N_(msgid) (msgid)
47 /* This should follow the definition in Gtk */
55 const GEnumValue align[] =
57 {ALIGN_LEFT, "left", N_("Left")},
58 {ALIGN_RIGHT, "right", N_("Right")},
59 {ALIGN_CENTRE, "center", N_("Center")},
63 const GEnumValue measure[] =
65 {MEASURE_NOMINAL, "nominal", N_("Nominal")},
66 {MEASURE_ORDINAL, "ordinal", N_("Ordinal")},
67 {MEASURE_SCALE, "scale", N_("Scale")},
71 const GEnumValue role[] =
73 {ROLE_INPUT, "input", N_("Input")},
74 {ROLE_TARGET, "output", N_("Output")},
75 {ROLE_BOTH, "both", N_("Both")},
76 {ROLE_NONE, "none", N_("None")},
77 {ROLE_PARTITION, "partition", N_("Partition")},
78 {ROLE_SPLIT, "split", N_("Split")},
85 /* Dictionary information. */
86 char *name; /* Variable name. Mixed case. */
87 int width; /* 0 for numeric, otherwise string width. */
88 struct missing_values miss; /* Missing values. */
89 struct fmt_spec print; /* Default format for PRINT. */
90 struct fmt_spec write; /* Default format for WRITE. */
91 struct val_labs *val_labs; /* Value labels. */
92 char *label; /* Variable label. */
93 struct string name_and_label; /* The name and label in the same string */
95 /* GUI information. */
96 enum measure measure; /* Nominal, ordinal, or continuous. */
97 enum var_role role; /* Intended use. */
98 int display_width; /* Width of data editor column. */
99 enum alignment alignment; /* Alignment of data in GUI. */
101 /* Case information. */
102 bool leave; /* Leave value from case to case? */
104 /* Data for use by containing dictionary. */
105 struct vardict_info *vardict;
107 /* Used only for system and portable file input and output.
108 See short-names.h. */
110 size_t short_name_cnt;
112 /* Custom attributes. */
113 struct attrset attributes;
117 static void var_set_print_format_quiet (struct variable *v, const struct fmt_spec *print);
118 static void var_set_write_format_quiet (struct variable *v, const struct fmt_spec *write);
119 static void var_set_label_quiet (struct variable *v, const char *label);
120 static void var_set_name_quiet (struct variable *v, const char *name);
122 /* Creates and returns a new variable with the given NAME and
123 WIDTH and other fields initialized to default values. The
124 variable is not added to a dictionary; for that, use
125 dict_create_var instead. */
127 var_create (const char *name, int width)
132 assert (width >= 0 && width <= MAX_STRING);
134 v = xzalloc (sizeof *v);
135 var_set_name_quiet (v, name);
137 mv_init (&v->miss, width);
138 v->leave = var_must_leave (v);
139 type = val_type_from_width (width);
140 v->alignment = var_default_alignment (type);
141 v->measure = var_default_measure (type);
142 v->role = ROLE_INPUT;
143 v->display_width = var_default_display_width (width);
144 v->print = v->write = var_default_formats (width);
145 attrset_init (&v->attributes);
146 ds_init_empty (&v->name_and_label);
151 /* Destroys variable V.
152 V must not belong to a dictionary. If it does, use
153 dict_delete_var instead. */
155 var_destroy (struct variable *v)
159 assert (!var_has_vardict (v));
160 mv_destroy (&v->miss);
161 var_clear_short_names (v);
162 val_labs_destroy (v->val_labs);
163 var_set_label_quiet (v, NULL);
164 attrset_destroy (var_get_attributes (v));
166 ds_destroy (&v->name_and_label);
171 /* Variable names. */
173 /* Return variable V's name, as a UTF-8 encoded string. */
175 var_get_name (const struct variable *v)
182 /* Sets V's name to NAME, a UTF-8 encoded string.
183 Do not use this function for a variable in a dictionary. Use
184 dict_rename_var instead. */
186 var_set_name_quiet (struct variable *v, const char *name)
188 assert (!var_has_vardict (v));
191 v->name = xstrdup (name);
192 ds_destroy (&v->name_and_label);
193 ds_init_empty (&v->name_and_label);
196 /* Sets V's name to NAME, a UTF-8 encoded string.
197 Do not use this function for a variable in a dictionary. Use
198 dict_rename_var instead. */
200 var_set_name (struct variable *v, const char *name)
202 struct variable *ov = var_clone (v);
203 var_set_name_quiet (v, name);
204 dict_var_changed (v, VAR_TRAIT_NAME, ov);
207 /* Returns VAR's dictionary class. */
209 var_get_dict_class (const struct variable *var)
211 return dict_class_from_id (var->name);
214 /* A hsh_compare_func that orders variables A and B by their
217 compare_vars_by_name (const void *a_, const void *b_, const void *aux UNUSED)
219 const struct variable *a = a_;
220 const struct variable *b = b_;
222 return utf8_strcasecmp (a->name, b->name);
225 /* A hsh_hash_func that hashes variable V based on its name. */
227 hash_var_by_name (const void *v_, const void *aux UNUSED)
229 const struct variable *v = v_;
231 return utf8_hash_case_string (v->name, 0);
234 /* A hsh_compare_func that orders pointers to variables A and B
237 compare_var_ptrs_by_name (const void *a_, const void *b_,
238 const void *aux UNUSED)
240 struct variable *const *a = a_;
241 struct variable *const *b = b_;
243 return utf8_strcasecmp (var_get_name (*a), var_get_name (*b));
246 /* A hsh_compare_func that orders pointers to variables A and B
247 by their dictionary indexes. */
249 compare_var_ptrs_by_dict_index (const void *a_, const void *b_,
250 const void *aux UNUSED)
252 struct variable *const *a = a_;
253 struct variable *const *b = b_;
254 size_t a_index = var_get_dict_index (*a);
255 size_t b_index = var_get_dict_index (*b);
257 return a_index < b_index ? -1 : a_index > b_index;
260 /* A hsh_hash_func that hashes pointer to variable V based on its
263 hash_var_ptr_by_name (const void *v_, const void *aux UNUSED)
265 struct variable *const *v = v_;
267 return utf8_hash_case_string (var_get_name (*v), 0);
270 /* Returns the type of variable V. */
272 var_get_type (const struct variable *v)
274 return val_type_from_width (v->width);
277 /* Returns the width of variable V. */
279 var_get_width (const struct variable *v)
285 var_set_width_and_formats (struct variable *v, int new_width,
286 const struct fmt_spec *print, const struct fmt_spec *write)
289 unsigned int traits = 0;
293 if (var_has_missing_values (v))
295 if (mv_is_resizable (&v->miss, new_width))
296 mv_resize (&v->miss, new_width);
299 mv_destroy (&v->miss);
300 mv_init (&v->miss, new_width);
302 traits |= VAR_TRAIT_MISSING_VALUES;
305 if (v->val_labs != NULL)
307 if (val_labs_can_set_width (v->val_labs, new_width))
308 val_labs_set_width (v->val_labs, new_width);
311 val_labs_destroy (v->val_labs);
314 traits |= VAR_TRAIT_VALUE_LABELS;
317 if (fmt_resize (&v->print, new_width))
318 traits |= VAR_TRAIT_PRINT_FORMAT;
320 if (fmt_resize (&v->write, new_width))
321 traits |= VAR_TRAIT_WRITE_FORMAT;
323 if (v->width != new_width)
325 v->width = new_width;
326 traits |= VAR_TRAIT_WIDTH;
331 var_set_print_format_quiet (v, print);
332 traits |= VAR_TRAIT_PRINT_FORMAT;
337 var_set_write_format_quiet (v, write);
338 traits |= VAR_TRAIT_WRITE_FORMAT;
342 dict_var_changed (v, traits, ov);
345 /* Changes the width of V to NEW_WIDTH.
346 This function should be used cautiously. */
348 var_set_width (struct variable *v, int new_width)
350 const int old_width = v->width;
352 if (old_width == new_width)
355 var_set_width_and_formats (v, new_width, NULL, NULL);
361 /* Returns true if variable V is numeric, false otherwise. */
363 var_is_numeric (const struct variable *v)
365 return var_get_type (v) == VAL_NUMERIC;
368 /* Returns true if variable V is a string variable, false
371 var_is_alpha (const struct variable *v)
373 return var_get_type (v) == VAL_STRING;
376 /* Returns variable V's missing values. */
377 const struct missing_values *
378 var_get_missing_values (const struct variable *v)
383 /* Sets variable V's missing values to MISS, which must be of V's
384 width or at least resizable to V's width.
385 If MISS is null, then V's missing values, if any, are
388 var_set_missing_values_quiet (struct variable *v, const struct missing_values *miss)
392 assert (mv_is_resizable (miss, v->width));
393 mv_destroy (&v->miss);
394 mv_copy (&v->miss, miss);
395 mv_resize (&v->miss, v->width);
401 /* Sets variable V's missing values to MISS, which must be of V's
402 width or at least resizable to V's width.
403 If MISS is null, then V's missing values, if any, are
406 var_set_missing_values (struct variable *v, const struct missing_values *miss)
408 struct variable *ov = var_clone (v);
409 var_set_missing_values_quiet (v, miss);
410 dict_var_changed (v, VAR_TRAIT_MISSING_VALUES, ov);
413 /* Sets variable V to have no user-missing values. */
415 var_clear_missing_values (struct variable *v)
417 var_set_missing_values (v, NULL);
420 /* Returns true if V has any user-missing values,
423 var_has_missing_values (const struct variable *v)
425 return !mv_is_empty (&v->miss);
428 /* Returns true if VALUE is in the given CLASS of missing values
429 in V, false otherwise. */
431 var_is_value_missing (const struct variable *v, const union value *value,
434 return mv_is_value_missing (&v->miss, value, class);
437 /* Returns true if D is in the given CLASS of missing values in
439 V must be a numeric variable. */
441 var_is_num_missing (const struct variable *v, double d, enum mv_class class)
443 return mv_is_num_missing (&v->miss, d, class);
446 /* Returns true if S[] is a missing value for V, false otherwise.
447 S[] must contain exactly as many characters as V's width.
448 V must be a string variable. */
450 var_is_str_missing (const struct variable *v, const uint8_t s[],
453 return mv_is_str_missing (&v->miss, s, class);
456 /* Returns variable V's value labels,
457 possibly a null pointer if it has none. */
458 const struct val_labs *
459 var_get_value_labels (const struct variable *v)
464 /* Returns true if variable V has at least one value label. */
466 var_has_value_labels (const struct variable *v)
468 return val_labs_count (v->val_labs) > 0;
471 /* Sets variable V's value labels to a copy of VLS,
472 which must have a width equal to V's width or one that can be
473 changed to V's width.
474 If VLS is null, then V's value labels, if any, are removed. */
476 var_set_value_labels_quiet (struct variable *v, const struct val_labs *vls)
478 val_labs_destroy (v->val_labs);
483 assert (val_labs_can_set_width (vls, v->width));
484 v->val_labs = val_labs_clone (vls);
485 val_labs_set_width (v->val_labs, v->width);
490 /* Sets variable V's value labels to a copy of VLS,
491 which must have a width equal to V's width or one that can be
492 changed to V's width.
493 If VLS is null, then V's value labels, if any, are removed. */
495 var_set_value_labels (struct variable *v, const struct val_labs *vls)
497 struct variable *ov = var_clone (v);
498 var_set_value_labels_quiet (v, vls);
499 dict_var_changed (v, VAR_TRAIT_LABEL, ov);
503 /* Makes sure that V has a set of value labels,
504 by assigning one to it if necessary. */
506 alloc_value_labels (struct variable *v)
508 if (v->val_labs == NULL)
509 v->val_labs = val_labs_create (v->width);
512 /* Attempts to add a value label with the given VALUE and UTF-8 encoded LABEL
513 to V. Returns true if successful, false otherwise (probably due to an
516 In LABEL, the two-byte sequence "\\n" is interpreted as a new-line. */
518 var_add_value_label (struct variable *v,
519 const union value *value, const char *label)
521 alloc_value_labels (v);
522 return val_labs_add (v->val_labs, value, label);
525 /* Adds or replaces a value label with the given VALUE and UTF-8 encoded LABEL
528 In LABEL, the two-byte sequence "\\n" is interpreted as a new-line. */
530 var_replace_value_label (struct variable *v,
531 const union value *value, const char *label)
533 alloc_value_labels (v);
534 val_labs_replace (v->val_labs, value, label);
537 /* Removes V's value labels, if any. */
539 var_clear_value_labels (struct variable *v)
541 var_set_value_labels (v, NULL);
544 /* Returns the label associated with VALUE for variable V, as a UTF-8 string in
545 a format suitable for output, or a null pointer if none. */
547 var_lookup_value_label (const struct variable *v, const union value *value)
549 return val_labs_find (v->val_labs, value);
553 Append to STR the string representation of VALUE for variable V.
554 STR must be a pointer to an initialised struct string.
557 append_value (const struct variable *v, const union value *value,
560 char *s = data_out (value, var_get_encoding (v), &v->print);
561 struct substring ss = ss_cstr (s);
562 ss_rtrim (&ss, ss_cstr (" "));
563 ds_put_substring (str, ss);
568 var_append_value_name__ (const struct variable *v, const union value *value,
569 enum settings_value_show show, struct string *str)
571 const char *label = var_lookup_value_label (v, value);
575 case SETTINGS_VALUE_SHOW_VALUE:
576 append_value (v, value, str);
580 case SETTINGS_VALUE_SHOW_LABEL:
582 ds_put_cstr (str, label);
584 append_value (v, value, str);
587 case SETTINGS_VALUE_SHOW_BOTH:
588 append_value (v, value, str);
590 ds_put_format (str, " %s", label);
595 /* Append STR with a string representing VALUE for variable V.
596 That is, if VALUE has a label, append that label,
597 otherwise format VALUE and append the formatted string.
598 STR must be a pointer to an initialised struct string.
601 var_append_value_name (const struct variable *v, const union value *value,
604 var_append_value_name__ (v, value, settings_get_show_values (), str);
607 /* Print and write formats. */
609 /* Returns V's print format specification. */
610 const struct fmt_spec *
611 var_get_print_format (const struct variable *v)
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_quiet (struct variable *v, const struct fmt_spec *print)
623 if (!fmt_equal (&v->print, print))
625 assert (fmt_check_width_compat (print, v->width));
630 /* Sets V's print format specification to PRINT, which must be a
631 valid format specification for a variable of V's width
632 (ordinarily an output format, but input formats are not
635 var_set_print_format (struct variable *v, const struct fmt_spec *print)
637 struct variable *ov = var_clone (v);
638 var_set_print_format_quiet (v, print);
639 dict_var_changed (v, VAR_TRAIT_PRINT_FORMAT, ov);
642 /* Returns V's write format specification. */
643 const struct fmt_spec *
644 var_get_write_format (const struct variable *v)
649 /* Sets V's write format specification to WRITE, which must be a
650 valid format specification for a variable of V's width
651 (ordinarily an output format, but input formats are not
654 var_set_write_format_quiet (struct variable *v, const struct fmt_spec *write)
656 if (!fmt_equal (&v->write, write))
658 assert (fmt_check_width_compat (write, v->width));
663 /* Sets V's write format specification to WRITE, which must be a
664 valid format specification for a variable of V's width
665 (ordinarily an output format, but input formats are not
668 var_set_write_format (struct variable *v, const struct fmt_spec *write)
670 struct variable *ov = var_clone (v);
671 var_set_write_format_quiet (v, write);
672 dict_var_changed (v, VAR_TRAIT_WRITE_FORMAT, ov);
676 /* Sets V's print and write format specifications to FORMAT,
677 which must be a valid format specification for a variable of
678 V's width (ordinarily an output format, but input formats are
681 var_set_both_formats (struct variable *v, const struct fmt_spec *format)
683 struct variable *ov = var_clone (v);
684 var_set_print_format_quiet (v, format);
685 var_set_write_format_quiet (v, format);
686 dict_var_changed (v, VAR_TRAIT_PRINT_FORMAT | VAR_TRAIT_WRITE_FORMAT, ov);
689 /* Returns the default print and write format for a variable of
690 the given TYPE, as set by var_create. The return value can be
691 used to reset a variable's print and write formats to the
694 var_default_formats (int width)
697 ? fmt_for_output (FMT_F, 8, 2)
698 : fmt_for_output (FMT_A, width, 0));
704 /* Update the combined name and label string if necessary */
706 update_vl_string (const struct variable *v)
708 /* Cast away const! */
709 struct string *str = (struct string *) &v->name_and_label;
711 if (ds_is_empty (str))
714 ds_put_format (str, _("%s (%s)"), v->label, v->name);
716 ds_put_cstr (str, v->name);
721 /* Return a string representing this variable, in the form most
722 appropriate from a human factors perspective, that is, its
723 variable label if it has one, otherwise its name. */
725 var_to_string (const struct variable *v)
727 switch (settings_get_show_variables ())
729 case SETTINGS_VALUE_SHOW_VALUE:
732 case SETTINGS_VALUE_SHOW_LABEL:
734 return v->label != NULL ? v->label : v->name;
736 case SETTINGS_VALUE_SHOW_BOTH:
737 update_vl_string (v);
738 return ds_cstr (&v->name_and_label);
742 /* Returns V's variable label, or a null pointer if it has none. */
744 var_get_label (const struct variable *v)
749 /* Sets V's variable label to UTF-8 encoded string LABEL, stripping off leading
750 and trailing white space. If LABEL is a null pointer or if LABEL is an
751 empty string (after stripping white space), then V's variable label (if any)
754 var_set_label_quiet (struct variable *v, const char *label)
759 if (label != NULL && label[strspn (label, CC_SPACES)])
760 v->label = xstrdup (label);
762 ds_destroy (&v->name_and_label);
763 ds_init_empty (&v->name_and_label);
768 /* Sets V's variable label to UTF-8 encoded string LABEL, stripping off leading
769 and trailing white space. If LABEL is a null pointer or if LABEL is an
770 empty string (after stripping white space), then V's variable label (if any)
773 var_set_label (struct variable *v, const char *label)
775 struct variable *ov = var_clone (v);
776 var_set_label_quiet (v, label);
777 dict_var_changed (v, VAR_TRAIT_LABEL, ov);
781 /* Removes any variable label from V. */
783 var_clear_label (struct variable *v)
785 var_set_label (v, NULL);
788 /* Returns true if V has a variable V,
791 var_has_label (const struct variable *v)
793 return v->label != NULL;
796 /* Returns true if M is a valid variable measurement level,
799 measure_is_valid (enum measure m)
801 return m == MEASURE_NOMINAL || m == MEASURE_ORDINAL || m == MEASURE_SCALE;
804 /* Returns a string version of measurement level M, for display to a user.
805 The caller may translate the string by passing it to gettext(). */
807 measure_to_string (enum measure m)
809 assert (m == measure[m].value);
810 return measure[m].label;
813 /* Returns a string version of measurement level M, for use in PSPP command
816 measure_to_syntax (enum measure m)
820 case MEASURE_NOMINAL:
823 case MEASURE_ORDINAL:
834 /* Returns V's measurement level. */
836 var_get_measure (const struct variable *v)
841 /* Sets V's measurement level to MEASURE. */
843 var_set_measure_quiet (struct variable *v, enum measure measure)
845 assert (measure_is_valid (measure));
846 v->measure = measure;
850 /* Sets V's measurement level to MEASURE. */
852 var_set_measure (struct variable *v, enum measure measure)
854 struct variable *ov = var_clone (v);
855 var_set_measure_quiet (v, measure);
856 dict_var_changed (v, VAR_TRAIT_MEASURE, ov);
860 /* Returns the default measurement level for a variable of the
861 given TYPE, as set by var_create. The return value can be
862 used to reset a variable's measurement level to the
865 var_default_measure (enum val_type type)
867 return type == VAL_NUMERIC ? MEASURE_SCALE : MEASURE_NOMINAL;
870 /* Returns true if M is a valid variable role,
873 var_role_is_valid (enum var_role role)
890 /* Returns a string version of ROLE, for display to a user.
891 The caller may translate the string by passing it to gettext(). */
893 var_role_to_string (enum var_role r)
895 assert (r == role[r].value);
896 return role[r].label;
899 /* Returns a string version of ROLE, for use in PSPP comamnd syntax. */
901 var_role_to_syntax (enum var_role role)
928 /* Returns V's role. */
930 var_get_role (const struct variable *v)
935 /* Sets V's role to ROLE. */
937 var_set_role_quiet (struct variable *v, enum var_role role)
939 assert (var_role_is_valid (role));
944 /* Sets V's role to ROLE. */
946 var_set_role (struct variable *v, enum var_role role)
948 struct variable *ov = var_clone (v);
949 var_set_role_quiet (v, role);
950 dict_var_changed (v, VAR_TRAIT_ROLE, ov);
953 /* Returns V's display width, which applies only to GUIs. */
955 var_get_display_width (const struct variable *v)
957 return v->display_width;
960 /* Sets V's display width to DISPLAY_WIDTH. */
962 var_set_display_width_quiet (struct variable *v, int new_width)
964 if (v->display_width != new_width)
966 v->display_width = new_width;
971 var_set_display_width (struct variable *v, int new_width)
973 if (v->display_width != new_width)
975 struct variable *ov = var_clone (v);
976 var_set_display_width_quiet (v, new_width);
977 dict_var_changed (v, VAR_TRAIT_DISPLAY_WIDTH, ov);
981 /* Returns the default display width for a variable of the given
982 WIDTH, as set by var_create. The return value can be used to
983 reset a variable's display width to the default. */
985 var_default_display_width (int width)
987 return width == 0 ? 8 : MIN (width, 32);
990 /* Returns true if A is a valid alignment,
993 alignment_is_valid (enum alignment a)
995 return a == ALIGN_LEFT || a == ALIGN_RIGHT || a == ALIGN_CENTRE;
998 /* Returns a string version of alignment A, for display to a user.
999 The caller may translate the string by passing it to gettext(). */
1001 alignment_to_string (enum alignment a)
1003 assert (a == align[a].value);
1004 return align[a].label;
1007 /* Returns a string version of alignment A, for use in PSPP command syntax. */
1009 alignment_to_syntax (enum alignment a)
1027 /* Returns V's display alignment, which applies only to GUIs. */
1029 var_get_alignment (const struct variable *v)
1031 return v->alignment;
1034 /* Sets V's display alignment to ALIGNMENT. */
1036 var_set_alignment_quiet (struct variable *v, enum alignment alignment)
1038 assert (alignment_is_valid (alignment));
1039 v->alignment = alignment;
1042 /* Sets V's display alignment to ALIGNMENT. */
1044 var_set_alignment (struct variable *v, enum alignment alignment)
1046 struct variable *ov = var_clone (v);
1047 var_set_alignment_quiet (v, alignment);
1048 dict_var_changed (v, VAR_TRAIT_ALIGNMENT, ov);
1052 /* Returns the default display alignment for a variable of the
1053 given TYPE, as set by var_create. The return value can be
1054 used to reset a variable's display alignment to the default. */
1056 var_default_alignment (enum val_type type)
1058 return type == VAL_NUMERIC ? ALIGN_RIGHT : ALIGN_LEFT;
1061 /* Whether variables' values should be preserved from case to
1064 /* Returns true if variable V's value should be left from case to
1065 case, instead of being reset to system-missing or blanks. */
1067 var_get_leave (const struct variable *v)
1072 /* Sets V's leave setting to LEAVE. */
1074 var_set_leave_quiet (struct variable *v, bool leave)
1076 assert (leave || !var_must_leave (v));
1081 /* Sets V's leave setting to LEAVE. */
1083 var_set_leave (struct variable *v, bool leave)
1085 struct variable *ov = var_clone (v);
1086 var_set_leave_quiet (v, leave);
1087 dict_var_changed (v, VAR_TRAIT_LEAVE, ov);
1091 /* Returns true if V must be left from case to case,
1092 false if it can be set either way. */
1094 var_must_leave (const struct variable *v)
1096 return var_get_dict_class (v) == DC_SCRATCH;
1099 /* Returns the number of short names stored in VAR.
1101 Short names are used only for system and portable file input
1102 and output. They are upper-case only, not necessarily unique,
1103 and limited to SHORT_NAME_LEN characters (plus a null
1104 terminator). Ordinarily a variable has at most one short
1105 name, but very long string variables (longer than 255 bytes)
1106 may have more. A variable might not have any short name at
1107 all if it hasn't been saved to or read from a system or
1110 var_get_short_name_cnt (const struct variable *var)
1112 return var->short_name_cnt;
1115 /* Returns VAR's short name with the given IDX, if it has one
1116 with that index, or a null pointer otherwise. Short names may
1117 be sparse: even if IDX is less than the number of short names
1118 in VAR, this function may return a null pointer. */
1120 var_get_short_name (const struct variable *var, size_t idx)
1122 return idx < var->short_name_cnt ? var->short_names[idx] : NULL;
1125 /* Sets VAR's short name with the given IDX to the UTF-8 string SHORT_NAME.
1126 The caller must already have checked that, in the dictionary encoding,
1127 SHORT_NAME is no more than SHORT_NAME_LEN bytes long. The new short name
1128 will be converted to uppercase.
1130 Specifying a null pointer for SHORT_NAME clears the specified short name. */
1132 var_set_short_name (struct variable *var, size_t idx, const char *short_name)
1134 struct variable *ov = var_clone (var);
1136 /* Clear old short name numbered IDX, if any. */
1137 if (idx < var->short_name_cnt)
1139 free (var->short_names[idx]);
1140 var->short_names[idx] = NULL;
1143 /* Install new short name for IDX. */
1144 if (short_name != NULL)
1146 if (idx >= var->short_name_cnt)
1148 size_t old_cnt = var->short_name_cnt;
1150 var->short_name_cnt = MAX (idx * 2, 1);
1151 var->short_names = xnrealloc (var->short_names, var->short_name_cnt,
1152 sizeof *var->short_names);
1153 for (i = old_cnt; i < var->short_name_cnt; i++)
1154 var->short_names[i] = NULL;
1156 var->short_names[idx] = utf8_to_upper (short_name);
1159 dict_var_changed (var, VAR_TRAIT_NAME, ov);
1162 /* Clears V's short names. */
1164 var_clear_short_names (struct variable *v)
1168 for (i = 0; i < v->short_name_cnt; i++)
1169 free (v->short_names[i]);
1170 free (v->short_names);
1171 v->short_names = NULL;
1172 v->short_name_cnt = 0;
1175 /* Relationship with dictionary. */
1177 /* Returns V's index within its dictionary, the value
1178 for which "dict_get_var (dict, index)" will return V.
1179 V must be in a dictionary. */
1181 var_get_dict_index (const struct variable *v)
1183 assert (var_has_vardict (v));
1184 return vardict_get_dict_index (v->vardict);
1187 /* Returns V's index within the case represented by its
1188 dictionary, that is, the value for which "case_data_idx (case,
1189 index)" will return the data for V in that case.
1190 V must be in a dictionary. */
1192 var_get_case_index (const struct variable *v)
1194 assert (var_has_vardict (v));
1195 return vardict_get_case_index (v->vardict);
1198 /* Returns variable V's attribute set. The caller may examine or
1199 modify the attribute set, but must not destroy it. Destroying
1200 V, or calling var_set_attributes() on V, will also destroy its
1203 var_get_attributes (const struct variable *v)
1205 return CONST_CAST (struct attrset *, &v->attributes);
1208 /* Replaces variable V's attributes set by a copy of ATTRS. */
1210 var_set_attributes_quiet (struct variable *v, const struct attrset *attrs)
1212 attrset_destroy (&v->attributes);
1213 attrset_clone (&v->attributes, attrs);
1216 /* Replaces variable V's attributes set by a copy of ATTRS. */
1218 var_set_attributes (struct variable *v, const struct attrset *attrs)
1220 struct variable *ov = var_clone (v);
1221 var_set_attributes_quiet (v, attrs);
1222 dict_var_changed (v, VAR_TRAIT_ATTRIBUTES, ov);
1226 /* Returns true if V has any custom attributes, false if it has none. */
1228 var_has_attributes (const struct variable *v)
1230 return attrset_count (&v->attributes) > 0;
1234 /* Creates and returns a clone of OLD_VAR. Most properties of
1235 the new variable are copied from OLD_VAR, except:
1237 - The variable's short name is not copied, because there is
1238 no reason to give a new variable with potentially a new
1239 name the same short name.
1241 - The new variable is not added to OLD_VAR's dictionary by
1242 default. Use dict_clone_var, instead, to do that.
1245 var_clone (const struct variable *old_var)
1247 struct variable *new_var = var_create (var_get_name (old_var),
1248 var_get_width (old_var));
1250 var_set_missing_values_quiet (new_var, var_get_missing_values (old_var));
1251 var_set_print_format_quiet (new_var, var_get_print_format (old_var));
1252 var_set_write_format_quiet (new_var, var_get_write_format (old_var));
1253 var_set_value_labels_quiet (new_var, var_get_value_labels (old_var));
1254 var_set_label_quiet (new_var, var_get_label (old_var));
1255 var_set_measure_quiet (new_var, var_get_measure (old_var));
1256 var_set_role_quiet (new_var, var_get_role (old_var));
1257 var_set_display_width_quiet (new_var, var_get_display_width (old_var));
1258 var_set_alignment_quiet (new_var, var_get_alignment (old_var));
1259 var_set_leave_quiet (new_var, var_get_leave (old_var));
1260 var_set_attributes_quiet (new_var, var_get_attributes (old_var));
1267 /* Returns the encoding of values of variable VAR. (This is actually a
1268 property of the dictionary.) Returns null if no specific encoding has been
1271 var_get_encoding (const struct variable *var)
1273 return (var_has_vardict (var)
1274 ? dict_get_encoding (vardict_get_dictionary (var->vardict))
1278 /* Returns V's vardict structure. */
1279 struct vardict_info *
1280 var_get_vardict (const struct variable *v)
1282 return CONST_CAST (struct vardict_info *, v->vardict);
1285 /* Sets V's vardict data to VARDICT. */
1287 var_set_vardict (struct variable *v, struct vardict_info *vardict)
1289 v->vardict = vardict;
1292 /* Returns true if V has vardict data. */
1294 var_has_vardict (const struct variable *v)
1296 return v->vardict != NULL;
1299 /* Clears V's vardict data. */
1301 var_clear_vardict (struct variable *v)
1308 Returns zero, if W is a missing value for WV or if it is less than zero.
1309 Typically used to force a numerical value into a valid weight.
1311 As a side effect, this function will emit a warning if the value
1312 WARN_ON_INVALID points to a bool which is TRUE. That bool will be then
1316 var_force_valid_weight (const struct variable *wv, double w, bool *warn_on_invalid)
1318 if (w < 0.0 || (wv && var_is_num_missing (wv, w, MV_ANY)))
1321 if (w == 0.0 && warn_on_invalid != NULL && *warn_on_invalid)
1323 *warn_on_invalid = false;
1324 msg (SW, _("At least one case in the data file had a weight value "
1325 "that was user-missing, system-missing, zero, or "
1326 "negative. These case(s) were ignored."));