1 /* PSPP - a program for statistical analysis.
2 Copyright (C) 1997-9, 2000, 2006, 2009, 2010, 2011, 2012, 2013,
3 2014, 2016, 2020 Free Software Foundation, Inc.
4
5 This program is free software: you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published by
7 the Free Software Foundation, either version 3 of the License, or
8 (at your option) any later version.
9
10 This program is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 GNU General Public License for more details.
14
15 You should have received a copy of the GNU General Public License
16 along with this program. If not, see <http://www.gnu.org/licenses/>. */
17
18 #include <config.h>
19
20 #include "data/variable.h"
21
22 #include <stdlib.h>
23
24 #include "data/attributes.h"
25 #include "data/data-out.h"
26 #include "data/dictionary.h"
27 #include "data/format.h"
28 #include "data/identifier.h"
29 #include "data/missing-values.h"
30 #include "data/settings.h"
31 #include "data/value-labels.h"
32 #include "data/vardict.h"
33 #include "libpspp/assertion.h"
34 #include "libpspp/compiler.h"
35 #include "libpspp/hash-functions.h"
36 #include "libpspp/i18n.h"
37 #include "libpspp/message.h"
38 #include "libpspp/misc.h"
39 #include "libpspp/str.h"
40
41 #include "gl/minmax.h"
42 #include "gl/xalloc.h"
43
44 #include "gettext.h"
45 #define _(msgid) gettext (msgid)
46 #define N_(msgid) (msgid)
47
48 /* This should follow the definition in Gtk */
49 typedef struct
50 {
51 int value;
52 const char *name;
53 const char *label;
54 } GEnumValue;
55
56 const GEnumValue align[] =
57 {
58 {ALIGN_LEFT, "left", N_("Left")},
59 {ALIGN_RIGHT, "right", N_("Right")},
60 {ALIGN_CENTRE, "center", N_("Center")},
61 {0,0,0}
62 };
63
64 const GEnumValue measure[] =
65 {
66 {MEASURE_NOMINAL, "nominal", N_("Nominal")},
67 {MEASURE_ORDINAL, "ordinal", N_("Ordinal")},
68 {MEASURE_SCALE, "scale", N_("Scale")},
69 {0,0,0}
70 };
71
72 const GEnumValue role[] =
73 {
74 {ROLE_INPUT, "input", N_("Input")},
75 {ROLE_TARGET, "output", N_("Output")},
76 {ROLE_BOTH, "both", N_("Both")},
77 {ROLE_NONE, "none", N_("None")},
78 {ROLE_PARTITION, "partition", N_("Partition")},
79 {ROLE_SPLIT, "split", N_("Split")},
80 {0,0,0}
81 };
82
83 /* A variable. */
84 struct variable
85 {
86 int ref_cnt;
87 /* Dictionary information. */
88 char *name; /* Variable name. Mixed case. */
89 int width; /* 0 for numeric, otherwise string width. */
90 struct missing_values miss; /* Missing values. */
91 struct fmt_spec print; /* Default format for PRINT. */
92 struct fmt_spec write; /* Default format for WRITE. */
93 struct val_labs *val_labs; /* Value labels. */
94 char *label; /* Variable label. */
95 struct string name_and_label; /* The name and label in the same string */
96
97 /* GUI information. */
98 enum measure measure; /* Nominal, ordinal, or continuous. */
99 enum var_role role; /* Intended use. */
100 int display_width; /* Width of data editor column. */
101 enum alignment alignment; /* Alignment of data in GUI. */
102
103 /* Case information. */
104 bool leave; /* Leave value from case to case? */
105
106 /* Data for use by containing dictionary. */
107 struct vardict_info *vardict;
108
109 /* Used only for system and portable file input and output.
110 See short-names.h. */
111 char **short_names;
112 size_t short_name_cnt;
113
114 /* Custom attributes. */
115 struct attrset attributes;
116 };
117
118
119 static void var_set_print_format_quiet (struct variable *v, const struct fmt_spec *print);
120 static void var_set_write_format_quiet (struct variable *v, const struct fmt_spec *write);
121 static void var_set_label_quiet (struct variable *v, const char *label);
122 static void var_set_name_quiet (struct variable *v, const char *name);
123
124 /* Creates and returns a new variable with the given NAME and
125 WIDTH and other fields initialized to default values. The
126 variable is not added to a dictionary; for that, use
127 dict_create_var instead. */
128 struct variable *
var_create(const char * name,int width)129 var_create (const char *name, int width)
130 {
131 struct variable *v;
132 enum val_type type;
133
134 assert (width >= 0 && width <= MAX_STRING);
135
136 v = xzalloc (sizeof *v);
137 var_set_name_quiet (v, name);
138 v->width = width;
139 mv_init (&v->miss, width);
140 v->leave = var_must_leave (v);
141 type = val_type_from_width (width);
142 v->alignment = var_default_alignment (type);
143 v->measure = var_default_measure (type);
144 v->role = ROLE_INPUT;
145 v->display_width = var_default_display_width (width);
146 v->print = v->write = var_default_formats (width);
147 attrset_init (&v->attributes);
148 ds_init_empty (&v->name_and_label);
149
150 v->ref_cnt = 1;
151
152 return v;
153 }
154
155 /* Destroys variable V.
156 V must not belong to a dictionary. If it does, use
157 dict_delete_var instead. */
158 static void
var_destroy__(struct variable * v)159 var_destroy__ (struct variable *v)
160 {
161 assert (!var_has_vardict (v));
162 mv_destroy (&v->miss);
163 var_clear_short_names (v);
164 val_labs_destroy (v->val_labs);
165 var_set_label_quiet (v, NULL);
166 attrset_destroy (var_get_attributes (v));
167 free (v->name);
168 ds_destroy (&v->name_and_label);
169 free (v);
170 }
171
172 struct variable *
var_ref(struct variable * v)173 var_ref (struct variable *v)
174 {
175 v->ref_cnt++;
176 return v;
177 }
178
179 void
var_unref(struct variable * v)180 var_unref (struct variable *v)
181 {
182 if (--v->ref_cnt == 0)
183 var_destroy__ (v);
184 }
185
186
187
188 /* Variable names. */
189
190 /* Return variable V's name, as a UTF-8 encoded string. */
191 const char *
var_get_name(const struct variable * v)192 var_get_name (const struct variable *v)
193 {
194 return v->name;
195 }
196
197
198
199 /* Sets V's name to NAME, a UTF-8 encoded string.
200 Do not use this function for a variable in a dictionary. Use
201 dict_rename_var instead. */
202 static void
var_set_name_quiet(struct variable * v,const char * name)203 var_set_name_quiet (struct variable *v, const char *name)
204 {
205 assert (!var_has_vardict (v));
206
207 free (v->name);
208 v->name = xstrdup (name);
209 ds_destroy (&v->name_and_label);
210 ds_init_empty (&v->name_and_label);
211 }
212
213 /* Sets V's name to NAME, a UTF-8 encoded string.
214 Do not use this function for a variable in a dictionary. Use
215 dict_rename_var instead. */
216 void
var_set_name(struct variable * v,const char * name)217 var_set_name (struct variable *v, const char *name)
218 {
219 struct variable *ov = var_clone (v);
220 var_set_name_quiet (v, name);
221 dict_var_changed (v, VAR_TRAIT_NAME, ov);
222 }
223
224 /* Returns VAR's dictionary class. */
225 enum dict_class
var_get_dict_class(const struct variable * var)226 var_get_dict_class (const struct variable *var)
227 {
228 return dict_class_from_id (var->name);
229 }
230
231 /* A hsh_compare_func that orders variables A and B by their
232 names. */
233 int
compare_vars_by_name(const void * a_,const void * b_,const void * aux UNUSED)234 compare_vars_by_name (const void *a_, const void *b_, const void *aux UNUSED)
235 {
236 const struct variable *a = a_;
237 const struct variable *b = b_;
238
239 return utf8_strcasecmp (a->name, b->name);
240 }
241
242 /* A hsh_hash_func that hashes variable V based on its name. */
243 unsigned
hash_var_by_name(const void * v_,const void * aux UNUSED)244 hash_var_by_name (const void *v_, const void *aux UNUSED)
245 {
246 const struct variable *v = v_;
247
248 return utf8_hash_case_string (v->name, 0);
249 }
250
251 /* A hsh_compare_func that orders pointers to variables A and B
252 by their names. */
253 int
compare_var_ptrs_by_name(const void * a_,const void * b_,const void * aux UNUSED)254 compare_var_ptrs_by_name (const void *a_, const void *b_,
255 const void *aux UNUSED)
256 {
257 struct variable *const *a = a_;
258 struct variable *const *b = b_;
259
260 return utf8_strcasecmp (var_get_name (*a), var_get_name (*b));
261 }
262
263 /* A hsh_compare_func that orders pointers to variables A and B
264 by their dictionary indexes. */
265 int
compare_var_ptrs_by_dict_index(const void * a_,const void * b_,const void * aux UNUSED)266 compare_var_ptrs_by_dict_index (const void *a_, const void *b_,
267 const void *aux UNUSED)
268 {
269 struct variable *const *a = a_;
270 struct variable *const *b = b_;
271 size_t a_index = var_get_dict_index (*a);
272 size_t b_index = var_get_dict_index (*b);
273
274 return a_index < b_index ? -1 : a_index > b_index;
275 }
276
277 /* A hsh_hash_func that hashes pointer to variable V based on its
278 name. */
279 unsigned
hash_var_ptr_by_name(const void * v_,const void * aux UNUSED)280 hash_var_ptr_by_name (const void *v_, const void *aux UNUSED)
281 {
282 struct variable *const *v = v_;
283
284 return utf8_hash_case_string (var_get_name (*v), 0);
285 }
286
287 /* Returns the type of variable V. */
288 enum val_type
var_get_type(const struct variable * v)289 var_get_type (const struct variable *v)
290 {
291 return val_type_from_width (v->width);
292 }
293
294 /* Returns the width of variable V. */
295 int
var_get_width(const struct variable * v)296 var_get_width (const struct variable *v)
297 {
298 return v->width;
299 }
300
301 void
var_set_width_and_formats(struct variable * v,int new_width,const struct fmt_spec * print,const struct fmt_spec * write)302 var_set_width_and_formats (struct variable *v, int new_width,
303 const struct fmt_spec *print, const struct fmt_spec *write)
304 {
305 struct variable *ov;
306 unsigned int traits = 0;
307
308 ov = var_clone (v);
309
310 if (mv_is_resizable (&v->miss, new_width))
311 mv_resize (&v->miss, new_width);
312 else
313 {
314 mv_destroy (&v->miss);
315 mv_init (&v->miss, new_width);
316 }
317 if (new_width != var_get_width (v))
318 traits |= VAR_TRAIT_MISSING_VALUES;
319
320 if (v->val_labs != NULL)
321 {
322 if (val_labs_can_set_width (v->val_labs, new_width))
323 val_labs_set_width (v->val_labs, new_width);
324 else
325 {
326 val_labs_destroy (v->val_labs);
327 v->val_labs = NULL;
328 }
329 traits |= VAR_TRAIT_VALUE_LABELS;
330 }
331
332 if (fmt_resize (&v->print, new_width))
333 traits |= VAR_TRAIT_PRINT_FORMAT;
334
335 if (fmt_resize (&v->write, new_width))
336 traits |= VAR_TRAIT_WRITE_FORMAT;
337
338 if (v->width != new_width)
339 {
340 v->width = new_width;
341 traits |= VAR_TRAIT_WIDTH;
342 }
343
344 if (print)
345 {
346 var_set_print_format_quiet (v, print);
347 traits |= VAR_TRAIT_PRINT_FORMAT;
348 }
349
350 if (write)
351 {
352 var_set_write_format_quiet (v, write);
353 traits |= VAR_TRAIT_WRITE_FORMAT;
354 }
355
356 if (traits != 0)
357 dict_var_changed (v, traits, ov);
358 }
359
360 /* Changes the width of V to NEW_WIDTH.
361 This function should be used cautiously. */
362 void
var_set_width(struct variable * v,int new_width)363 var_set_width (struct variable *v, int new_width)
364 {
365 const int old_width = v->width;
366
367 if (old_width == new_width)
368 return;
369
370 var_set_width_and_formats (v, new_width, NULL, NULL);
371 }
372
373
374
375
376 /* Returns true if variable V is numeric, false otherwise. */
377 bool
var_is_numeric(const struct variable * v)378 var_is_numeric (const struct variable *v)
379 {
380 return var_get_type (v) == VAL_NUMERIC;
381 }
382
383 /* Returns true if variable V is a string variable, false
384 otherwise. */
385 bool
var_is_alpha(const struct variable * v)386 var_is_alpha (const struct variable *v)
387 {
388 return var_get_type (v) == VAL_STRING;
389 }
390
391 /* Returns variable V's missing values. */
392 const struct missing_values *
var_get_missing_values(const struct variable * v)393 var_get_missing_values (const struct variable *v)
394 {
395 return &v->miss;
396 }
397
398 /* Sets variable V's missing values to MISS, which must be of V's
399 width or at least resizable to V's width.
400 If MISS is null, then V's missing values, if any, are
401 cleared. */
402 static void
var_set_missing_values_quiet(struct variable * v,const struct missing_values * miss)403 var_set_missing_values_quiet (struct variable *v, const struct missing_values *miss)
404 {
405 if (miss != NULL)
406 {
407 assert (mv_is_resizable (miss, v->width));
408 mv_destroy (&v->miss);
409 mv_copy (&v->miss, miss);
410 mv_resize (&v->miss, v->width);
411 }
412 else
413 mv_clear (&v->miss);
414 }
415
416 /* Sets variable V's missing values to MISS, which must be of V's
417 width or at least resizable to V's width.
418 If MISS is null, then V's missing values, if any, are
419 cleared. */
420 void
var_set_missing_values(struct variable * v,const struct missing_values * miss)421 var_set_missing_values (struct variable *v, const struct missing_values *miss)
422 {
423 struct variable *ov = var_clone (v);
424 var_set_missing_values_quiet (v, miss);
425 dict_var_changed (v, VAR_TRAIT_MISSING_VALUES, ov);
426 }
427
428 /* Sets variable V to have no user-missing values. */
429 void
var_clear_missing_values(struct variable * v)430 var_clear_missing_values (struct variable *v)
431 {
432 var_set_missing_values (v, NULL);
433 }
434
435 /* Returns true if V has any user-missing values,
436 false otherwise. */
437 bool
var_has_missing_values(const struct variable * v)438 var_has_missing_values (const struct variable *v)
439 {
440 return !mv_is_empty (&v->miss);
441 }
442
443 /* Returns true if VALUE is in the given CLASS of missing values
444 in V, false otherwise. */
445 bool
var_is_value_missing(const struct variable * v,const union value * value,enum mv_class class)446 var_is_value_missing (const struct variable *v, const union value *value,
447 enum mv_class class)
448 {
449 return mv_is_value_missing (&v->miss, value, class);
450 }
451
452 /* Returns true if D is in the given CLASS of missing values in
453 V, false otherwise.
454 V must be a numeric variable. */
455 bool
var_is_num_missing(const struct variable * v,double d,enum mv_class class)456 var_is_num_missing (const struct variable *v, double d, enum mv_class class)
457 {
458 return mv_is_num_missing (&v->miss, d, class);
459 }
460
461 /* Returns true if S[] is a missing value for V, false otherwise.
462 S[] must contain exactly as many characters as V's width.
463 V must be a string variable. */
464 bool
var_is_str_missing(const struct variable * v,const uint8_t s[],enum mv_class class)465 var_is_str_missing (const struct variable *v, const uint8_t s[],
466 enum mv_class class)
467 {
468 return mv_is_str_missing (&v->miss, s, class);
469 }
470
471 /* Returns variable V's value labels,
472 possibly a null pointer if it has none. */
473 const struct val_labs *
var_get_value_labels(const struct variable * v)474 var_get_value_labels (const struct variable *v)
475 {
476 return v->val_labs;
477 }
478
479 /* Returns true if variable V has at least one value label. */
480 bool
var_has_value_labels(const struct variable * v)481 var_has_value_labels (const struct variable *v)
482 {
483 return val_labs_count (v->val_labs) > 0;
484 }
485
486 /* Sets variable V's value labels to a copy of VLS,
487 which must have a width equal to V's width or one that can be
488 changed to V's width.
489 If VLS is null, then V's value labels, if any, are removed. */
490 static void
var_set_value_labels_quiet(struct variable * v,const struct val_labs * vls)491 var_set_value_labels_quiet (struct variable *v, const struct val_labs *vls)
492 {
493 val_labs_destroy (v->val_labs);
494 v->val_labs = NULL;
495
496 if (vls != NULL)
497 {
498 assert (val_labs_can_set_width (vls, v->width));
499 v->val_labs = val_labs_clone (vls);
500 val_labs_set_width (v->val_labs, v->width);
501 }
502 }
503
504
505 /* Sets variable V's value labels to a copy of VLS,
506 which must have a width equal to V's width or one that can be
507 changed to V's width.
508 If VLS is null, then V's value labels, if any, are removed. */
509 void
var_set_value_labels(struct variable * v,const struct val_labs * vls)510 var_set_value_labels (struct variable *v, const struct val_labs *vls)
511 {
512 struct variable *ov = var_clone (v);
513 var_set_value_labels_quiet (v, vls);
514 dict_var_changed (v, VAR_TRAIT_LABEL, ov);
515 }
516
517
518 /* Makes sure that V has a set of value labels,
519 by assigning one to it if necessary. */
520 static void
alloc_value_labels(struct variable * v)521 alloc_value_labels (struct variable *v)
522 {
523 if (v->val_labs == NULL)
524 v->val_labs = val_labs_create (v->width);
525 }
526
527 /* Attempts to add a value label with the given VALUE and UTF-8 encoded LABEL
528 to V. Returns true if successful, false otherwise (probably due to an
529 existing label).
530
531 In LABEL, the two-byte sequence "\\n" is interpreted as a new-line. */
532 bool
var_add_value_label(struct variable * v,const union value * value,const char * label)533 var_add_value_label (struct variable *v,
534 const union value *value, const char *label)
535 {
536 alloc_value_labels (v);
537 return val_labs_add (v->val_labs, value, label);
538 }
539
540 /* Adds or replaces a value label with the given VALUE and UTF-8 encoded LABEL
541 to V.
542
543 In LABEL, the two-byte sequence "\\n" is interpreted as a new-line. */
544 void
var_replace_value_label(struct variable * v,const union value * value,const char * label)545 var_replace_value_label (struct variable *v,
546 const union value *value, const char *label)
547 {
548 alloc_value_labels (v);
549 val_labs_replace (v->val_labs, value, label);
550 }
551
552 /* Removes V's value labels, if any. */
553 void
var_clear_value_labels(struct variable * v)554 var_clear_value_labels (struct variable *v)
555 {
556 var_set_value_labels (v, NULL);
557 }
558
559 /* Returns the label associated with VALUE for variable V, as a UTF-8 string in
560 a format suitable for output, or a null pointer if none. */
561 const char *
var_lookup_value_label(const struct variable * v,const union value * value)562 var_lookup_value_label (const struct variable *v, const union value *value)
563 {
564 return val_labs_find (v->val_labs, value);
565 }
566
567 /*
568 Append to STR the string representation of VALUE for variable V.
569 STR must be a pointer to an initialised struct string.
570 */
571 static void
append_value(const struct variable * v,const union value * value,struct string * str)572 append_value (const struct variable *v, const union value *value,
573 struct string *str)
574 {
575 char *s = data_out (value, var_get_encoding (v), &v->print);
576 struct substring ss = ss_cstr (s);
577 ss_rtrim (&ss, ss_cstr (" "));
578 ds_put_substring (str, ss);
579 free (s);
580 }
581
582 void
var_append_value_name__(const struct variable * v,const union value * value,enum settings_value_show show,struct string * str)583 var_append_value_name__ (const struct variable *v, const union value *value,
584 enum settings_value_show show, struct string *str)
585 {
586 const char *label = var_lookup_value_label (v, value);
587
588 switch (show)
589 {
590 case SETTINGS_VALUE_SHOW_VALUE:
591 append_value (v, value, str);
592 break;
593
594 default:
595 case SETTINGS_VALUE_SHOW_LABEL:
596 if (label)
597 ds_put_cstr (str, label);
598 else
599 append_value (v, value, str);
600 break;
601
602 case SETTINGS_VALUE_SHOW_BOTH:
603 append_value (v, value, str);
604 if (label != NULL)
605 ds_put_format (str, " %s", label);
606 break;
607 }
608 }
609
610 /* Append STR with a string representing VALUE for variable V.
611 That is, if VALUE has a label, append that label,
612 otherwise format VALUE and append the formatted string.
613 STR must be a pointer to an initialised struct string.
614 */
615 void
var_append_value_name(const struct variable * v,const union value * value,struct string * str)616 var_append_value_name (const struct variable *v, const union value *value,
617 struct string *str)
618 {
619 var_append_value_name__ (v, value, settings_get_show_values (), str);
620 }
621
622 /* Print and write formats. */
623
624 /* Returns V's print format specification. */
625 const struct fmt_spec *
var_get_print_format(const struct variable * v)626 var_get_print_format (const struct variable *v)
627 {
628 return &v->print;
629 }
630
631 /* Sets V's print format specification to PRINT, which must be a
632 valid format specification for a variable of V's width
633 (ordinarily an output format, but input formats are not
634 rejected). */
635 static void
var_set_print_format_quiet(struct variable * v,const struct fmt_spec * print)636 var_set_print_format_quiet (struct variable *v, const struct fmt_spec *print)
637 {
638 if (!fmt_equal (&v->print, print))
639 {
640 assert (fmt_check_width_compat (print, v->width));
641 v->print = *print;
642 }
643 }
644
645 /* Sets V's print format specification to PRINT, which must be a
646 valid format specification for a variable of V's width
647 (ordinarily an output format, but input formats are not
648 rejected). */
649 void
var_set_print_format(struct variable * v,const struct fmt_spec * print)650 var_set_print_format (struct variable *v, const struct fmt_spec *print)
651 {
652 struct variable *ov = var_clone (v);
653 var_set_print_format_quiet (v, print);
654 dict_var_changed (v, VAR_TRAIT_PRINT_FORMAT, ov);
655 }
656
657 /* Returns V's write format specification. */
658 const struct fmt_spec *
var_get_write_format(const struct variable * v)659 var_get_write_format (const struct variable *v)
660 {
661 return &v->write;
662 }
663
664 /* Sets V's write format specification to WRITE, which must be a
665 valid format specification for a variable of V's width
666 (ordinarily an output format, but input formats are not
667 rejected). */
668 static void
var_set_write_format_quiet(struct variable * v,const struct fmt_spec * write)669 var_set_write_format_quiet (struct variable *v, const struct fmt_spec *write)
670 {
671 if (!fmt_equal (&v->write, write))
672 {
673 assert (fmt_check_width_compat (write, v->width));
674 v->write = *write;
675 }
676 }
677
678 /* Sets V's write format specification to WRITE, which must be a
679 valid format specification for a variable of V's width
680 (ordinarily an output format, but input formats are not
681 rejected). */
682 void
var_set_write_format(struct variable * v,const struct fmt_spec * write)683 var_set_write_format (struct variable *v, const struct fmt_spec *write)
684 {
685 struct variable *ov = var_clone (v);
686 var_set_write_format_quiet (v, write);
687 dict_var_changed (v, VAR_TRAIT_WRITE_FORMAT, ov);
688 }
689
690
691 /* Sets V's print and write format specifications to FORMAT,
692 which must be a valid format specification for a variable of
693 V's width (ordinarily an output format, but input formats are
694 not rejected). */
695 void
var_set_both_formats(struct variable * v,const struct fmt_spec * format)696 var_set_both_formats (struct variable *v, const struct fmt_spec *format)
697 {
698 struct variable *ov = var_clone (v);
699 var_set_print_format_quiet (v, format);
700 var_set_write_format_quiet (v, format);
701 dict_var_changed (v, VAR_TRAIT_PRINT_FORMAT | VAR_TRAIT_WRITE_FORMAT, ov);
702 }
703
704 /* Returns the default print and write format for a variable of
705 the given TYPE, as set by var_create. The return value can be
706 used to reset a variable's print and write formats to the
707 default. */
708 struct fmt_spec
var_default_formats(int width)709 var_default_formats (int width)
710 {
711 return (width == 0
712 ? fmt_for_output (FMT_F, 8, 2)
713 : fmt_for_output (FMT_A, width, 0));
714 }
715
716
717
718
719 /* Update the combined name and label string if necessary */
720 static void
update_vl_string(const struct variable * v)721 update_vl_string (const struct variable *v)
722 {
723 /* Cast away const! */
724 struct string *str = (struct string *) &v->name_and_label;
725
726 if (ds_is_empty (str))
727 {
728 if (v->label)
729 ds_put_format (str, _("%s (%s)"), v->label, v->name);
730 else
731 ds_put_cstr (str, v->name);
732 }
733 }
734
735
736 /* Return a string representing this variable, in the form most
737 appropriate from a human factors perspective, that is, its
738 variable label if it has one, otherwise its name. */
739 const char *
var_to_string(const struct variable * v)740 var_to_string (const struct variable *v)
741 {
742 switch (settings_get_show_variables ())
743 {
744 case SETTINGS_VALUE_SHOW_VALUE:
745 return v->name;
746
747 case SETTINGS_VALUE_SHOW_LABEL:
748 default:
749 return v->label != NULL ? v->label : v->name;
750
751 case SETTINGS_VALUE_SHOW_BOTH:
752 update_vl_string (v);
753 return ds_cstr (&v->name_and_label);
754 }
755 }
756
757 /* Returns V's variable label, or a null pointer if it has none. */
758 const char *
var_get_label(const struct variable * v)759 var_get_label (const struct variable *v)
760 {
761 return v->label;
762 }
763
764 /* Sets V's variable label to UTF-8 encoded string LABEL, stripping off leading
765 and trailing white space. If LABEL is a null pointer or if LABEL is an
766 empty string (after stripping white space), then V's variable label (if any)
767 is removed. */
768 static void
var_set_label_quiet(struct variable * v,const char * label)769 var_set_label_quiet (struct variable *v, const char *label)
770 {
771 free (v->label);
772 v->label = NULL;
773
774 if (label != NULL && label[strspn (label, CC_SPACES)])
775 v->label = xstrdup (label);
776
777 ds_destroy (&v->name_and_label);
778 ds_init_empty (&v->name_and_label);
779 }
780
781
782
783 /* Sets V's variable label to UTF-8 encoded string LABEL, stripping off leading
784 and trailing white space. If LABEL is a null pointer or if LABEL is an
785 empty string (after stripping white space), then V's variable label (if any)
786 is removed. */
787 void
var_set_label(struct variable * v,const char * label)788 var_set_label (struct variable *v, const char *label)
789 {
790 struct variable *ov = var_clone (v);
791 var_set_label_quiet (v, label);
792 dict_var_changed (v, VAR_TRAIT_LABEL, ov);
793 }
794
795
796 /* Removes any variable label from V. */
797 void
var_clear_label(struct variable * v)798 var_clear_label (struct variable *v)
799 {
800 var_set_label (v, NULL);
801 }
802
803 /* Returns true if V has a variable V,
804 false otherwise. */
805 bool
var_has_label(const struct variable * v)806 var_has_label (const struct variable *v)
807 {
808 return v->label != NULL;
809 }
810
811 /* Returns true if M is a valid variable measurement level,
812 false otherwise. */
813 bool
measure_is_valid(enum measure m)814 measure_is_valid (enum measure m)
815 {
816 return m == MEASURE_NOMINAL || m == MEASURE_ORDINAL || m == MEASURE_SCALE;
817 }
818
819 /* Returns a string version of measurement level M, for display to a user.
820 The caller may translate the string by passing it to gettext(). */
821 const char *
measure_to_string(enum measure m)822 measure_to_string (enum measure m)
823 {
824 assert (m == measure[m].value);
825 return measure[m].label;
826 }
827
828 /* Returns a string version of measurement level M, for use in PSPP command
829 syntax. */
830 const char *
measure_to_syntax(enum measure m)831 measure_to_syntax (enum measure m)
832 {
833 switch (m)
834 {
835 case MEASURE_NOMINAL:
836 return "NOMINAL";
837
838 case MEASURE_ORDINAL:
839 return "ORDINAL";
840
841 case MEASURE_SCALE:
842 return "SCALE";
843
844 default:
845 return "Invalid";
846 }
847 }
848
849 /* Returns V's measurement level. */
850 enum measure
var_get_measure(const struct variable * v)851 var_get_measure (const struct variable *v)
852 {
853 return v->measure;
854 }
855
856 /* Sets V's measurement level to MEASURE. */
857 static void
var_set_measure_quiet(struct variable * v,enum measure measure)858 var_set_measure_quiet (struct variable *v, enum measure measure)
859 {
860 assert (measure_is_valid (measure));
861 v->measure = measure;
862 }
863
864
865 /* Sets V's measurement level to MEASURE. */
866 void
var_set_measure(struct variable * v,enum measure measure)867 var_set_measure (struct variable *v, enum measure measure)
868 {
869 struct variable *ov = var_clone (v);
870 var_set_measure_quiet (v, measure);
871 dict_var_changed (v, VAR_TRAIT_MEASURE, ov);
872 }
873
874
875 /* Returns the default measurement level for a variable of the
876 given TYPE, as set by var_create. The return value can be
877 used to reset a variable's measurement level to the
878 default. */
879 enum measure
var_default_measure(enum val_type type)880 var_default_measure (enum val_type type)
881 {
882 return type == VAL_NUMERIC ? MEASURE_SCALE : MEASURE_NOMINAL;
883 }
884
885 /* Returns true if M is a valid variable role,
886 false otherwise. */
887 bool
var_role_is_valid(enum var_role role)888 var_role_is_valid (enum var_role role)
889 {
890 switch (role)
891 {
892 case ROLE_NONE:
893 case ROLE_INPUT:
894 case ROLE_TARGET:
895 case ROLE_BOTH:
896 case ROLE_PARTITION:
897 case ROLE_SPLIT:
898 return true;
899
900 default:
901 return false;
902 }
903 }
904
905 /* Returns a string version of ROLE, for display to a user.
906 The caller may translate the string by passing it to gettext(). */
907 const char *
var_role_to_string(enum var_role r)908 var_role_to_string (enum var_role r)
909 {
910 assert (r == role[r].value);
911 return role[r].label;
912 }
913
914 /* Returns a string version of ROLE, for use in PSPP comamnd syntax. */
915 const char *
var_role_to_syntax(enum var_role role)916 var_role_to_syntax (enum var_role role)
917 {
918 switch (role)
919 {
920 case ROLE_INPUT:
921 return "INPUT";
922
923 case ROLE_TARGET:
924 return "TARGET";
925
926 case ROLE_BOTH:
927 return "BOTH";
928
929 case ROLE_NONE:
930 return "NONE";
931
932 case ROLE_PARTITION:
933 return "PARTITION";
934
935 case ROLE_SPLIT:
936 return "SPLIT";
937
938 default:
939 return "<invalid>";
940 }
941 }
942
943 /* Returns V's role. */
944 enum var_role
var_get_role(const struct variable * v)945 var_get_role (const struct variable *v)
946 {
947 return v->role;
948 }
949
950 /* Sets V's role to ROLE. */
951 static void
var_set_role_quiet(struct variable * v,enum var_role role)952 var_set_role_quiet (struct variable *v, enum var_role role)
953 {
954 assert (var_role_is_valid (role));
955 v->role = role;
956 }
957
958
959 /* Sets V's role to ROLE. */
960 void
var_set_role(struct variable * v,enum var_role role)961 var_set_role (struct variable *v, enum var_role role)
962 {
963 struct variable *ov = var_clone (v);
964 var_set_role_quiet (v, role);
965 dict_var_changed (v, VAR_TRAIT_ROLE, ov);
966 }
967
968 /* Returns V's display width, which applies only to GUIs. */
969 int
var_get_display_width(const struct variable * v)970 var_get_display_width (const struct variable *v)
971 {
972 return v->display_width;
973 }
974
975 /* Sets V's display width to DISPLAY_WIDTH. */
976 static void
var_set_display_width_quiet(struct variable * v,int new_width)977 var_set_display_width_quiet (struct variable *v, int new_width)
978 {
979 if (v->display_width != new_width)
980 {
981 v->display_width = new_width;
982 }
983 }
984
985 void
var_set_display_width(struct variable * v,int new_width)986 var_set_display_width (struct variable *v, int new_width)
987 {
988 if (v->display_width != new_width)
989 {
990 struct variable *ov = var_clone (v);
991 var_set_display_width_quiet (v, new_width);
992 dict_var_changed (v, VAR_TRAIT_DISPLAY_WIDTH, ov);
993 }
994 }
995
996 /* Returns the default display width for a variable of the given
997 WIDTH, as set by var_create. The return value can be used to
998 reset a variable's display width to the default. */
999 int
var_default_display_width(int width)1000 var_default_display_width (int width)
1001 {
1002 return width == 0 ? 8 : MIN (width, 32);
1003 }
1004
1005 /* Returns true if A is a valid alignment,
1006 false otherwise. */
1007 bool
alignment_is_valid(enum alignment a)1008 alignment_is_valid (enum alignment a)
1009 {
1010 return a == ALIGN_LEFT || a == ALIGN_RIGHT || a == ALIGN_CENTRE;
1011 }
1012
1013 /* Returns a string version of alignment A, for display to a user.
1014 The caller may translate the string by passing it to gettext(). */
1015 const char *
alignment_to_string(enum alignment a)1016 alignment_to_string (enum alignment a)
1017 {
1018 assert (a == align[a].value);
1019 return align[a].label;
1020 }
1021
1022 /* Returns a string version of alignment A, for use in PSPP command syntax. */
1023 const char *
alignment_to_syntax(enum alignment a)1024 alignment_to_syntax (enum alignment a)
1025 {
1026 switch (a)
1027 {
1028 case ALIGN_LEFT:
1029 return "LEFT";
1030
1031 case ALIGN_RIGHT:
1032 return "RIGHT";
1033
1034 case ALIGN_CENTRE:
1035 return "CENTER";
1036
1037 default:
1038 return "Invalid";
1039 }
1040 }
1041
1042 /* Returns V's display alignment, which applies only to GUIs. */
1043 enum alignment
var_get_alignment(const struct variable * v)1044 var_get_alignment (const struct variable *v)
1045 {
1046 return v->alignment;
1047 }
1048
1049 /* Sets V's display alignment to ALIGNMENT. */
1050 static void
var_set_alignment_quiet(struct variable * v,enum alignment alignment)1051 var_set_alignment_quiet (struct variable *v, enum alignment alignment)
1052 {
1053 assert (alignment_is_valid (alignment));
1054 v->alignment = alignment;
1055 }
1056
1057 /* Sets V's display alignment to ALIGNMENT. */
1058 void
var_set_alignment(struct variable * v,enum alignment alignment)1059 var_set_alignment (struct variable *v, enum alignment alignment)
1060 {
1061 struct variable *ov = var_clone (v);
1062 var_set_alignment_quiet (v, alignment);
1063 dict_var_changed (v, VAR_TRAIT_ALIGNMENT, ov);
1064 }
1065
1066
1067 /* Returns the default display alignment for a variable of the
1068 given TYPE, as set by var_create. The return value can be
1069 used to reset a variable's display alignment to the default. */
1070 enum alignment
var_default_alignment(enum val_type type)1071 var_default_alignment (enum val_type type)
1072 {
1073 return type == VAL_NUMERIC ? ALIGN_RIGHT : ALIGN_LEFT;
1074 }
1075
1076 /* Whether variables' values should be preserved from case to
1077 case. */
1078
1079 /* Returns true if variable V's value should be left from case to
1080 case, instead of being reset to system-missing or blanks. */
1081 bool
var_get_leave(const struct variable * v)1082 var_get_leave (const struct variable *v)
1083 {
1084 return v->leave;
1085 }
1086
1087 /* Sets V's leave setting to LEAVE. */
1088 static void
var_set_leave_quiet(struct variable * v,bool leave)1089 var_set_leave_quiet (struct variable *v, bool leave)
1090 {
1091 assert (leave || !var_must_leave (v));
1092 v->leave = leave;
1093 }
1094
1095
1096 /* Sets V's leave setting to LEAVE. */
1097 void
var_set_leave(struct variable * v,bool leave)1098 var_set_leave (struct variable *v, bool leave)
1099 {
1100 struct variable *ov = var_clone (v);
1101 var_set_leave_quiet (v, leave);
1102 dict_var_changed (v, VAR_TRAIT_LEAVE, ov);
1103 }
1104
1105
1106 /* Returns true if V must be left from case to case,
1107 false if it can be set either way. */
1108 bool
var_must_leave(const struct variable * v)1109 var_must_leave (const struct variable *v)
1110 {
1111 return var_get_dict_class (v) == DC_SCRATCH;
1112 }
1113
1114 /* Returns the number of short names stored in VAR.
1115
1116 Short names are used only for system and portable file input
1117 and output. They are upper-case only, not necessarily unique,
1118 and limited to SHORT_NAME_LEN characters (plus a null
1119 terminator). Ordinarily a variable has at most one short
1120 name, but very long string variables (longer than 255 bytes)
1121 may have more. A variable might not have any short name at
1122 all if it hasn't been saved to or read from a system or
1123 portable file. */
1124 size_t
var_get_short_name_cnt(const struct variable * var)1125 var_get_short_name_cnt (const struct variable *var)
1126 {
1127 return var->short_name_cnt;
1128 }
1129
1130 /* Returns VAR's short name with the given IDX, if it has one
1131 with that index, or a null pointer otherwise. Short names may
1132 be sparse: even if IDX is less than the number of short names
1133 in VAR, this function may return a null pointer. */
1134 const char *
var_get_short_name(const struct variable * var,size_t idx)1135 var_get_short_name (const struct variable *var, size_t idx)
1136 {
1137 return idx < var->short_name_cnt ? var->short_names[idx] : NULL;
1138 }
1139
1140 /* Sets VAR's short name with the given IDX to the UTF-8 string SHORT_NAME.
1141 The caller must already have checked that, in the dictionary encoding,
1142 SHORT_NAME is no more than SHORT_NAME_LEN bytes long. The new short name
1143 will be converted to uppercase.
1144
1145 Specifying a null pointer for SHORT_NAME clears the specified short name. */
1146 void
var_set_short_name(struct variable * var,size_t idx,const char * short_name)1147 var_set_short_name (struct variable *var, size_t idx, const char *short_name)
1148 {
1149 struct variable *ov = var_clone (var);
1150
1151 /* Clear old short name numbered IDX, if any. */
1152 if (idx < var->short_name_cnt)
1153 {
1154 free (var->short_names[idx]);
1155 var->short_names[idx] = NULL;
1156 }
1157
1158 /* Install new short name for IDX. */
1159 if (short_name != NULL)
1160 {
1161 if (idx >= var->short_name_cnt)
1162 {
1163 size_t old_cnt = var->short_name_cnt;
1164 size_t i;
1165 var->short_name_cnt = MAX (idx * 2, 1);
1166 var->short_names = xnrealloc (var->short_names, var->short_name_cnt,
1167 sizeof *var->short_names);
1168 for (i = old_cnt; i < var->short_name_cnt; i++)
1169 var->short_names[i] = NULL;
1170 }
1171 var->short_names[idx] = utf8_to_upper (short_name);
1172 }
1173
1174 dict_var_changed (var, VAR_TRAIT_NAME, ov);
1175 }
1176
1177 /* Clears V's short names. */
1178 void
var_clear_short_names(struct variable * v)1179 var_clear_short_names (struct variable *v)
1180 {
1181 size_t i;
1182
1183 for (i = 0; i < v->short_name_cnt; i++)
1184 free (v->short_names[i]);
1185 free (v->short_names);
1186 v->short_names = NULL;
1187 v->short_name_cnt = 0;
1188 }
1189
1190 /* Relationship with dictionary. */
1191
1192 /* Returns V's index within its dictionary, the value
1193 for which "dict_get_var (dict, index)" will return V.
1194 V must be in a dictionary. */
1195 size_t
var_get_dict_index(const struct variable * v)1196 var_get_dict_index (const struct variable *v)
1197 {
1198 assert (var_has_vardict (v));
1199 return vardict_get_dict_index (v->vardict);
1200 }
1201
1202 /* Returns V's index within the case represented by its
1203 dictionary, that is, the value for which "case_data_idx (case,
1204 index)" will return the data for V in that case.
1205 V must be in a dictionary. */
1206 size_t
var_get_case_index(const struct variable * v)1207 var_get_case_index (const struct variable *v)
1208 {
1209 assert (var_has_vardict (v));
1210 return vardict_get_case_index (v->vardict);
1211 }
1212
1213 /* Returns variable V's attribute set. The caller may examine or
1214 modify the attribute set, but must not destroy it. Destroying
1215 V, or calling var_set_attributes() on V, will also destroy its
1216 attribute set. */
1217 struct attrset *
var_get_attributes(const struct variable * v)1218 var_get_attributes (const struct variable *v)
1219 {
1220 return CONST_CAST (struct attrset *, &v->attributes);
1221 }
1222
1223 /* Replaces variable V's attributes set by a copy of ATTRS. */
1224 static void
var_set_attributes_quiet(struct variable * v,const struct attrset * attrs)1225 var_set_attributes_quiet (struct variable *v, const struct attrset *attrs)
1226 {
1227 attrset_destroy (&v->attributes);
1228 attrset_clone (&v->attributes, attrs);
1229 }
1230
1231 /* Replaces variable V's attributes set by a copy of ATTRS. */
1232 void
var_set_attributes(struct variable * v,const struct attrset * attrs)1233 var_set_attributes (struct variable *v, const struct attrset *attrs)
1234 {
1235 struct variable *ov = var_clone (v);
1236 var_set_attributes_quiet (v, attrs);
1237 dict_var_changed (v, VAR_TRAIT_ATTRIBUTES, ov);
1238 }
1239
1240
1241 /* Returns true if V has any custom attributes, false if it has none. */
1242 bool
var_has_attributes(const struct variable * v)1243 var_has_attributes (const struct variable *v)
1244 {
1245 return attrset_count (&v->attributes) > 0;
1246 }
1247
1248
1249 /* Creates and returns a clone of OLD_VAR. Most properties of
1250 the new variable are copied from OLD_VAR, except:
1251
1252 - The variable's short name is not copied, because there is
1253 no reason to give a new variable with potentially a new
1254 name the same short name.
1255
1256 - The new variable is not added to OLD_VAR's dictionary by
1257 default. Use dict_clone_var, instead, to do that.
1258 */
1259 struct variable *
var_clone(const struct variable * old_var)1260 var_clone (const struct variable *old_var)
1261 {
1262 struct variable *new_var = var_create (var_get_name (old_var),
1263 var_get_width (old_var));
1264
1265 var_set_missing_values_quiet (new_var, var_get_missing_values (old_var));
1266 var_set_print_format_quiet (new_var, var_get_print_format (old_var));
1267 var_set_write_format_quiet (new_var, var_get_write_format (old_var));
1268 var_set_value_labels_quiet (new_var, var_get_value_labels (old_var));
1269 var_set_label_quiet (new_var, var_get_label (old_var));
1270 var_set_measure_quiet (new_var, var_get_measure (old_var));
1271 var_set_role_quiet (new_var, var_get_role (old_var));
1272 var_set_display_width_quiet (new_var, var_get_display_width (old_var));
1273 var_set_alignment_quiet (new_var, var_get_alignment (old_var));
1274 var_set_leave_quiet (new_var, var_get_leave (old_var));
1275 var_set_attributes_quiet (new_var, var_get_attributes (old_var));
1276
1277 return new_var;
1278 }
1279
1280
1281
1282 /* Returns the encoding of values of variable VAR. (This is actually a
1283 property of the dictionary.) Returns null if no specific encoding has been
1284 set. */
1285 const char *
var_get_encoding(const struct variable * var)1286 var_get_encoding (const struct variable *var)
1287 {
1288 return (var_has_vardict (var)
1289 ? dict_get_encoding (vardict_get_dictionary (var->vardict))
1290 : NULL);
1291 }
1292
1293 /* Returns V's vardict structure. */
1294 struct vardict_info *
var_get_vardict(const struct variable * v)1295 var_get_vardict (const struct variable *v)
1296 {
1297 return CONST_CAST (struct vardict_info *, v->vardict);
1298 }
1299
1300 /* Sets V's vardict data to VARDICT. */
1301 void
var_set_vardict(struct variable * v,struct vardict_info * vardict)1302 var_set_vardict (struct variable *v, struct vardict_info *vardict)
1303 {
1304 v->vardict = vardict;
1305 }
1306
1307 /* Returns true if V has vardict data. */
1308 bool
var_has_vardict(const struct variable * v)1309 var_has_vardict (const struct variable *v)
1310 {
1311 return v->vardict != NULL;
1312 }
1313
1314 /* Clears V's vardict data. */
1315 void
var_clear_vardict(struct variable * v)1316 var_clear_vardict (struct variable *v)
1317 {
1318 v->vardict = NULL;
1319 }
1320
1321
1322 /*
1323 Returns zero, if W is a missing value for WV or if it is less than zero.
1324 Typically used to force a numerical value into a valid weight.
1325
1326 As a side effect, this function will emit a warning if the value
1327 WARN_ON_INVALID points to a bool which is TRUE. That bool will be then
1328 set to FALSE.
1329 */
1330 double
var_force_valid_weight(const struct variable * wv,double w,bool * warn_on_invalid)1331 var_force_valid_weight (const struct variable *wv, double w, bool *warn_on_invalid)
1332 {
1333 if (w < 0.0 || (wv && var_is_num_missing (wv, w, MV_ANY)))
1334 w = 0.0;
1335
1336 if (w == 0.0 && warn_on_invalid != NULL && *warn_on_invalid)
1337 {
1338 *warn_on_invalid = false;
1339 msg (SW, _("At least one case in the data file had a weight value "
1340 "that was user-missing, system-missing, zero, or "
1341 "negative. These case(s) were ignored."));
1342 }
1343
1344 return w;
1345 }
1346