src/data/variable.c

   1 /* PSPP - a program for statistical analysis.
   2    Copyright (C) 1997-9, 2000, 2006, 2009, 2010, 2011 Free Software Foundation, Inc.
   3
   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.
   8
   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.
  13
  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/>. */
  16
  17 #include <config.h>
  18
  19 #include "data/variable.h"
  20
  21 #include <stdlib.h>
  22
  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"
  39
  40 #include "gl/minmax.h"
  41 #include "gl/xalloc.h"
  42
  43 #include "gettext.h"
  44 #define _(msgid) gettext (msgid)
  45
  46 /* A variable. */
  47 struct variable
  48   {
  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
  58     /* GUI information. */
  59     enum measure measure;       /* Nominal, ordinal, or continuous. */
  60     int display_width;          /* Width of data editor column. */
  61     enum alignment alignment;   /* Alignment of data in GUI. */
  62
  63     /* Case information. */
  64     bool leave;                 /* Leave value from case to case? */
  65
  66     /* Data for use by containing dictionary. */
  67     struct vardict_info *vardict;
  68
  69     /* Used only for system and portable file input and output.
  70        See short-names.h. */
  71     char **short_names;
  72     size_t short_name_cnt;
  73
  74     /* Each command may use these fields as needed. */
  75     void *aux;
  76     void (*aux_dtor) (struct variable *);
  77
  78     /* Custom attributes. */
  79     struct attrset attributes;
  80   };
  81 \f
  82 /* Creates and returns a new variable with the given NAME and
  83    WIDTH and other fields initialized to default values.  The
  84    variable is not added to a dictionary; for that, use
  85    dict_create_var instead. */
  86 struct variable *
  87 var_create (const char *name, int width)
  88 {
  89   struct variable *v;
  90   enum val_type type;
  91
  92   assert (width >= 0 && width <= MAX_STRING);
  93
  94   v = xmalloc (sizeof *v);
  95   v->vardict = NULL;
  96   v->name = NULL;
  97   var_set_name (v, name);
  98   v->width = width;
  99   mv_init (&v->miss, width);
 100   v->leave = var_must_leave (v);
 101   type = val_type_from_width (width);
 102   v->alignment = var_default_alignment (type);
 103   v->measure = var_default_measure (type);
 104   v->display_width = var_default_display_width (width);
 105   v->print = v->write = var_default_formats (width);
 106   v->val_labs = NULL;
 107   v->label = NULL;
 108   v->short_names = NULL;
 109   v->short_name_cnt = 0;
 110   v->aux = NULL;
 111   v->aux_dtor = NULL;
 112   attrset_init (&v->attributes);
 113
 114   return v;
 115 }
 116
 117 /* Creates and returns a clone of OLD_VAR.  Most properties of
 118    the new variable are copied from OLD_VAR, except:
 119
 120     - The variable's short name is not copied, because there is
 121       no reason to give a new variable with potentially a new
 122       name the same short name.
 123
 124     - The new variable is not added to OLD_VAR's dictionary by
 125       default.  Use dict_clone_var, instead, to do that.
 126 */
 127 struct variable *
 128 var_clone (const struct variable *old_var)
 129 {
 130   struct variable *new_var = var_create (var_get_name (old_var),
 131                                          var_get_width (old_var));
 132
 133   var_set_missing_values (new_var, var_get_missing_values (old_var));
 134   var_set_print_format (new_var, var_get_print_format (old_var));
 135   var_set_write_format (new_var, var_get_write_format (old_var));
 136   var_set_value_labels (new_var, var_get_value_labels (old_var));
 137   var_set_label (new_var, var_get_label (old_var), false);
 138   var_set_measure (new_var, var_get_measure (old_var));
 139   var_set_display_width (new_var, var_get_display_width (old_var));
 140   var_set_alignment (new_var, var_get_alignment (old_var));
 141   var_set_leave (new_var, var_get_leave (old_var));
 142   var_set_attributes (new_var, var_get_attributes (old_var));
 143
 144   return new_var;
 145 }
 146
 147 /* Destroys variable V.
 148    V must not belong to a dictionary.  If it does, use
 149    dict_delete_var instead. */
 150 void
 151 var_destroy (struct variable *v)
 152 {
 153   if (v != NULL)
 154     {
 155       assert (!var_has_vardict (v));
 156       mv_destroy (&v->miss);
 157       var_clear_short_names (v);
 158       var_clear_aux (v);
 159       val_labs_destroy (v->val_labs);
 160       var_clear_label (v);
 161       attrset_destroy (var_get_attributes (v));
 162       free (v->name);
 163       free (v);
 164     }
 165 }
 166 \f
 167 /* Variable names. */
 168
 169 /* Return variable V's name, as a UTF-8 encoded string. */
 170 const char *
 171 var_get_name (const struct variable *v)
 172 {
 173   return v->name;
 174 }
 175
 176 /* Sets V's name to NAME, a UTF-8 encoded string.
 177    Do not use this function for a variable in a dictionary.  Use
 178    dict_rename_var instead. */
 179 void
 180 var_set_name (struct variable *v, const char *name)
 181 {
 182   assert (!var_has_vardict (v));
 183   assert (id_is_plausible (name, false));
 184
 185   free (v->name);
 186   v->name = xstrdup (name);
 187   dict_var_changed (v);
 188 }
 189
 190 /* Returns VAR's dictionary class. */
 191 enum dict_class
 192 var_get_dict_class (const struct variable *var)
 193 {
 194   return dict_class_from_id (var->name);
 195 }
 196
 197 /* A hsh_compare_func that orders variables A and B by their
 198    names. */
 199 int
 200 compare_vars_by_name (const void *a_, const void *b_, const void *aux UNUSED)
 201 {
 202   const struct variable *a = a_;
 203   const struct variable *b = b_;
 204
 205   return strcasecmp (a->name, b->name);
 206 }
 207
 208 /* A hsh_hash_func that hashes variable V based on its name. */
 209 unsigned
 210 hash_var_by_name (const void *v_, const void *aux UNUSED)
 211 {
 212   const struct variable *v = v_;
 213
 214   return hash_case_string (v->name, 0);
 215 }
 216
 217 /* A hsh_compare_func that orders pointers to variables A and B
 218    by their names. */
 219 int
 220 compare_var_ptrs_by_name (const void *a_, const void *b_,
 221                           const void *aux UNUSED)
 222 {
 223   struct variable *const *a = a_;
 224   struct variable *const *b = b_;
 225
 226   return strcasecmp (var_get_name (*a), var_get_name (*b));
 227 }
 228
 229 /* A hsh_compare_func that orders pointers to variables A and B
 230    by their dictionary indexes. */
 231 int
 232 compare_var_ptrs_by_dict_index (const void *a_, const void *b_,
 233                                 const void *aux UNUSED)
 234 {
 235   struct variable *const *a = a_;
 236   struct variable *const *b = b_;
 237   size_t a_index = var_get_dict_index (*a);
 238   size_t b_index = var_get_dict_index (*b);
 239
 240   return a_index < b_index ? -1 : a_index > b_index;
 241 }
 242
 243 /* A hsh_hash_func that hashes pointer to variable V based on its
 244    name. */
 245 unsigned
 246 hash_var_ptr_by_name (const void *v_, const void *aux UNUSED)
 247 {
 248   struct variable *const *v = v_;
 249
 250   return hash_case_string (var_get_name (*v), 0);
 251 }
 252 \f
 253 /* Returns the type of variable V. */
 254 enum val_type
 255 var_get_type (const struct variable *v)
 256 {
 257   return val_type_from_width (v->width);
 258 }
 259
 260 /* Returns the width of variable V. */
 261 int
 262 var_get_width (const struct variable *v)
 263 {
 264   return v->width;
 265 }
 266
 267 /* Changes the width of V to NEW_WIDTH.
 268    This function should be used cautiously. */
 269 void
 270 var_set_width (struct variable *v, int new_width)
 271 {
 272   const int old_width = v->width;
 273
 274   if (old_width == new_width)
 275     return;
 276
 277   if (mv_is_resizable (&v->miss, new_width))
 278     mv_resize (&v->miss, new_width);
 279   else
 280     {
 281       mv_destroy (&v->miss);
 282       mv_init (&v->miss, new_width);
 283     }
 284
 285   if (v->val_labs != NULL)
 286     {
 287       if (val_labs_can_set_width (v->val_labs, new_width))
 288         val_labs_set_width (v->val_labs, new_width);
 289       else
 290         {
 291           val_labs_destroy (v->val_labs);
 292           v->val_labs = NULL;
 293         }
 294     }
 295
 296   fmt_resize (&v->print, new_width);
 297   fmt_resize (&v->write, new_width);
 298
 299   v->width = new_width;
 300   dict_var_resized (v, old_width);
 301   dict_var_changed (v);
 302 }
 303
 304 /* Returns true if variable V is numeric, false otherwise. */
 305 bool
 306 var_is_numeric (const struct variable *v)
 307 {
 308   return var_get_type (v) == VAL_NUMERIC;
 309 }
 310
 311 /* Returns true if variable V is a string variable, false
 312    otherwise. */
 313 bool
 314 var_is_alpha (const struct variable *v)
 315 {
 316   return var_get_type (v) == VAL_STRING;
 317 }
 318 \f
 319 /* Returns variable V's missing values. */
 320 const struct missing_values *
 321 var_get_missing_values (const struct variable *v)
 322 {
 323   return &v->miss;
 324 }
 325
 326 /* Sets variable V's missing values to MISS, which must be of V's
 327    width or at least resizable to V's width.
 328    If MISS is null, then V's missing values, if any, are
 329    cleared. */
 330 void
 331 var_set_missing_values (struct variable *v, const struct missing_values *miss)
 332 {
 333   if (miss != NULL)
 334     {
 335       assert (mv_is_resizable (miss, v->width));
 336       mv_destroy (&v->miss);
 337       mv_copy (&v->miss, miss);
 338       mv_resize (&v->miss, v->width);
 339     }
 340   else
 341     mv_clear (&v->miss);
 342
 343   dict_var_changed (v);
 344 }
 345
 346 /* Sets variable V to have no user-missing values. */
 347 void
 348 var_clear_missing_values (struct variable *v)
 349 {
 350   var_set_missing_values (v, NULL);
 351 }
 352
 353 /* Returns true if V has any user-missing values,
 354    false otherwise. */
 355 bool
 356 var_has_missing_values (const struct variable *v)
 357 {
 358   return !mv_is_empty (&v->miss);
 359 }
 360
 361 /* Returns true if VALUE is in the given CLASS of missing values
 362    in V, false otherwise. */
 363 bool
 364 var_is_value_missing (const struct variable *v, const union value *value,
 365                       enum mv_class class)
 366 {
 367   return mv_is_value_missing (&v->miss, value, class);
 368 }
 369
 370 /* Returns true if D is in the given CLASS of missing values in
 371    V, false otherwise.
 372    V must be a numeric variable. */
 373 bool
 374 var_is_num_missing (const struct variable *v, double d, enum mv_class class)
 375 {
 376   return mv_is_num_missing (&v->miss, d, class);
 377 }
 378
 379 /* Returns true if S[] is a missing value for V, false otherwise.
 380    S[] must contain exactly as many characters as V's width.
 381    V must be a string variable. */
 382 bool
 383 var_is_str_missing (const struct variable *v, const uint8_t s[],
 384                     enum mv_class class)
 385 {
 386   return mv_is_str_missing (&v->miss, s, class);
 387 }
 388 \f
 389 /* Returns variable V's value labels,
 390    possibly a null pointer if it has none. */
 391 const struct val_labs *
 392 var_get_value_labels (const struct variable *v)
 393 {
 394   return v->val_labs;
 395 }
 396
 397 /* Returns true if variable V has at least one value label. */
 398 bool
 399 var_has_value_labels (const struct variable *v)
 400 {
 401   return val_labs_count (v->val_labs) > 0;
 402 }
 403
 404 /* Sets variable V's value labels to a copy of VLS,
 405    which must have a width equal to V's width or one that can be
 406    changed to V's width.
 407    If VLS is null, then V's value labels, if any, are removed. */
 408 void
 409 var_set_value_labels (struct variable *v, const struct val_labs *vls)
 410 {
 411   val_labs_destroy (v->val_labs);
 412   v->val_labs = NULL;
 413
 414   if (vls != NULL)
 415     {
 416       assert (val_labs_can_set_width (vls, v->width));
 417       v->val_labs = val_labs_clone (vls);
 418       val_labs_set_width (v->val_labs, v->width);
 419       dict_var_changed (v);
 420     }
 421 }
 422
 423 /* Makes sure that V has a set of value labels,
 424    by assigning one to it if necessary. */
 425 static void
 426 alloc_value_labels (struct variable *v)
 427 {
 428   if (v->val_labs == NULL)
 429     v->val_labs = val_labs_create (v->width);
 430 }
 431
 432 /* Attempts to add a value label with the given VALUE and UTF-8 encoded LABEL
 433    to V.  Returns true if successful, false otherwise (probably due to an
 434    existing label).
 435
 436    In LABEL, the two-byte sequence "\\n" is interpreted as a new-line. */
 437 bool
 438 var_add_value_label (struct variable *v,
 439                      const union value *value, const char *label)
 440 {
 441   alloc_value_labels (v);
 442   return val_labs_add (v->val_labs, value, label);
 443 }
 444
 445 /* Adds or replaces a value label with the given VALUE and UTF-8 encoded LABEL
 446    to V.
 447
 448    In LABEL, the two-byte sequence "\\n" is interpreted as a new-line. */
 449 void
 450 var_replace_value_label (struct variable *v,
 451                          const union value *value, const char *label)
 452 {
 453   alloc_value_labels (v);
 454   val_labs_replace (v->val_labs, value, label);
 455 }
 456
 457 /* Removes V's value labels, if any. */
 458 void
 459 var_clear_value_labels (struct variable *v)
 460 {
 461   var_set_value_labels (v, NULL);
 462 }
 463
 464 /* Returns the label associated with VALUE for variable V, as a UTF-8 string in
 465    a format suitable for output, or a null pointer if none. */
 466 const char *
 467 var_lookup_value_label (const struct variable *v, const union value *value)
 468 {
 469   return val_labs_find (v->val_labs, value);
 470 }
 471
 472 /*
 473    Append to STR the string representation of VALUE for variable V.
 474    STR must be a pointer to an initialised struct string.
 475 */
 476 static void
 477 append_value (const struct variable *v, const union value *value,
 478               struct string *str)
 479 {
 480   char *s = data_out (value, var_get_encoding (v), &v->print);
 481   ds_put_cstr (str, s);
 482   free (s);
 483 }
 484
 485 /* Append STR with a string representing VALUE for variable V.
 486    That is, if VALUE has a label, append that label,
 487    otherwise format VALUE and append the formatted string.
 488    STR must be a pointer to an initialised struct string.
 489 */
 490 void
 491 var_append_value_name (const struct variable *v, const union value *value,
 492                        struct string *str)
 493 {
 494   enum settings_value_style style = settings_get_value_style ();
 495   const char *name = var_lookup_value_label (v, value);
 496
 497   switch (style)
 498     {
 499     case SETTINGS_VAL_STYLE_VALUES:
 500       append_value (v, value, str);
 501       break;
 502
 503     case SETTINGS_VAL_STYLE_LABELS:
 504       if (name == NULL)
 505         append_value (v, value, str);
 506       else
 507         ds_put_cstr (str, name);
 508       break;
 509
 510     case SETTINGS_VAL_STYLE_BOTH:
 511     default:
 512       append_value (v, value, str);
 513       if (name != NULL)
 514         {
 515           ds_put_cstr (str, " (");
 516           ds_put_cstr (str, name);
 517           ds_put_cstr (str, ")");
 518         }
 519       break;
 520     };
 521 }
 522 \f
 523 /* Print and write formats. */
 524
 525 /* Returns V's print format specification. */
 526 const struct fmt_spec *
 527 var_get_print_format (const struct variable *v)
 528 {
 529   return &v->print;
 530 }
 531
 532 /* Sets V's print format specification to PRINT, which must be a
 533    valid format specification for a variable of V's width
 534    (ordinarily an output format, but input formats are not
 535    rejected). */
 536 void
 537 var_set_print_format (struct variable *v, const struct fmt_spec *print)
 538 {
 539   assert (fmt_check_width_compat (print, v->width));
 540   v->print = *print;
 541   dict_var_changed (v);
 542 }
 543
 544 /* Returns V's write format specification. */
 545 const struct fmt_spec *
 546 var_get_write_format (const struct variable *v)
 547 {
 548   return &v->write;
 549 }
 550
 551 /* Sets V's write format specification to WRITE, which must be a
 552    valid format specification for a variable of V's width
 553    (ordinarily an output format, but input formats are not
 554    rejected). */
 555 void
 556 var_set_write_format (struct variable *v, const struct fmt_spec *write)
 557 {
 558   assert (fmt_check_width_compat (write, v->width));
 559   v->write = *write;
 560   dict_var_changed (v);
 561 }
 562
 563 /* Sets V's print and write format specifications to FORMAT,
 564    which must be a valid format specification for a variable of
 565    V's width (ordinarily an output format, but input formats are
 566    not rejected). */
 567 void
 568 var_set_both_formats (struct variable *v, const struct fmt_spec *format)
 569 {
 570   var_set_print_format (v, format);
 571   var_set_write_format (v, format);
 572 }
 573
 574 /* Returns the default print and write format for a variable of
 575    the given TYPE, as set by var_create.  The return value can be
 576    used to reset a variable's print and write formats to the
 577    default. */
 578 struct fmt_spec
 579 var_default_formats (int width)
 580 {
 581   return (width == 0
 582           ? fmt_for_output (FMT_F, 8, 2)
 583           : fmt_for_output (FMT_A, width, 0));
 584 }
 585 \f
 586 /* Return a string representing this variable, in the form most
 587    appropriate from a human factors perspective, that is, its
 588    variable label if it has one, otherwise its name. */
 589 const char *
 590 var_to_string (const struct variable *v)
 591 {
 592   return v->label != NULL ? v->label : v->name;
 593 }
 594
 595 /* Returns V's variable label, or a null pointer if it has none. */
 596 const char *
 597 var_get_label (const struct variable *v)
 598 {
 599   return v->label;
 600 }
 601
 602 /* Sets V's variable label to UTF-8 encoded string LABEL, stripping off leading
 603    and trailing white space.  If LABEL is a null pointer or if LABEL is an
 604    empty string (after stripping white space), then V's variable label (if any)
 605    is removed.
 606
 607    Variable labels are limited to 255 bytes in V's encoding (as returned by
 608    var_get_encoding()).  If LABEL fits within this limit, this function returns
 609    true.  Otherwise, the variable label is set to a truncated value, this
 610    function returns false and, if ISSUE_WARNING is true, issues a warning.  */
 611 bool
 612 var_set_label (struct variable *v, const char *label, bool issue_warning)
 613 {
 614   bool truncated = false;
 615
 616   free (v->label);
 617   v->label = NULL;
 618
 619   if (label != NULL && label[strspn (label, CC_SPACES)])
 620     {
 621       const char *dict_encoding = var_get_encoding (v);
 622       struct substring s = ss_cstr (label);
 623       size_t trunc_len;
 624
 625       if (dict_encoding != NULL)
 626         {
 627           enum { MAX_LABEL_LEN = 255 };
 628
 629           trunc_len = utf8_encoding_trunc_len (label, dict_encoding,
 630                                                MAX_LABEL_LEN);
 631           if (ss_length (s) > trunc_len)
 632             {
 633               if (issue_warning)
 634                 msg (SW, _("Truncating variable label for variable `%s' to %d "
 635                            "bytes."), var_get_name (v), MAX_LABEL_LEN);
 636               ss_truncate (&s, trunc_len);
 637               truncated = true;
 638             }
 639         }
 640
 641         v->label = ss_xstrdup (s);
 642     }
 643
 644   dict_var_changed (v);
 645
 646   return truncated;
 647 }
 648
 649 /* Removes any variable label from V. */
 650 void
 651 var_clear_label (struct variable *v)
 652 {
 653   var_set_label (v, NULL, false);
 654 }
 655
 656 /* Returns true if V has a variable V,
 657    false otherwise. */
 658 bool
 659 var_has_label (const struct variable *v)
 660 {
 661   return v->label != NULL;
 662 }
 663 \f
 664 /* Returns true if M is a valid variable measurement level,
 665    false otherwise. */
 666 bool
 667 measure_is_valid (enum measure m)
 668 {
 669   return m == MEASURE_NOMINAL || m == MEASURE_ORDINAL || m == MEASURE_SCALE;
 670 }
 671
 672 /* Returns a string version of measurement level M, for display to a user. */
 673 const char *
 674 measure_to_string (enum measure m)
 675 {
 676   switch (m)
 677     {
 678     case MEASURE_NOMINAL:
 679       return _("Nominal");
 680
 681     case MEASURE_ORDINAL:
 682       return _("Ordinal");
 683
 684     case MEASURE_SCALE:
 685       return _("Scale");
 686
 687     default:
 688       return "Invalid";
 689     }
 690 }
 691
 692 /* Returns V's measurement level. */
 693 enum measure
 694 var_get_measure (const struct variable *v)
 695 {
 696   return v->measure;
 697 }
 698
 699 /* Sets V's measurement level to MEASURE. */
 700 void
 701 var_set_measure (struct variable *v, enum measure measure)
 702 {
 703   assert (measure_is_valid (measure));
 704   v->measure = measure;
 705   dict_var_changed (v);
 706 }
 707
 708 /* Returns the default measurement level for a variable of the
 709    given TYPE, as set by var_create.  The return value can be
 710    used to reset a variable's measurement level to the
 711    default. */
 712 enum measure
 713 var_default_measure (enum val_type type)
 714 {
 715   return type == VAL_NUMERIC ? MEASURE_SCALE : MEASURE_NOMINAL;
 716 }
 717 \f
 718 /* Returns V's display width, which applies only to GUIs. */
 719 int
 720 var_get_display_width (const struct variable *v)
 721 {
 722   return v->display_width;
 723 }
 724
 725 /* Sets V's display width to DISPLAY_WIDTH. */
 726 void
 727 var_set_display_width (struct variable *v, int new_width)
 728 {
 729   if (v->display_width != new_width)
 730     {
 731       v->display_width = new_width;
 732       dict_var_display_width_changed (v);
 733       dict_var_changed (v);
 734     }
 735 }
 736
 737 /* Returns the default display width for a variable of the given
 738    WIDTH, as set by var_create.  The return value can be used to
 739    reset a variable's display width to the default. */
 740 int
 741 var_default_display_width (int width)
 742 {
 743   return width == 0 ? 8 : MIN (width, 32);
 744 }
 745 \f
 746 /* Returns true if A is a valid alignment,
 747    false otherwise. */
 748 bool
 749 alignment_is_valid (enum alignment a)
 750 {
 751   return a == ALIGN_LEFT || a == ALIGN_RIGHT || a == ALIGN_CENTRE;
 752 }
 753
 754 /* Returns a string version of alignment A, for display to a user. */
 755 const char *
 756 alignment_to_string (enum alignment a)
 757 {
 758   switch (a)
 759     {
 760     case ALIGN_LEFT:
 761       return _("Left");
 762
 763     case ALIGN_RIGHT:
 764       return _("Right");
 765
 766     case ALIGN_CENTRE:
 767       return _("Center");
 768
 769     default:
 770       return "Invalid";
 771     }
 772 }
 773
 774 /* Returns V's display alignment, which applies only to GUIs. */
 775 enum alignment
 776 var_get_alignment (const struct variable *v)
 777 {
 778   return v->alignment;
 779 }
 780
 781 /* Sets V's display alignment to ALIGNMENT. */
 782 void
 783 var_set_alignment (struct variable *v, enum alignment alignment)
 784 {
 785   assert (alignment_is_valid (alignment));
 786   v->alignment = alignment;
 787   dict_var_changed (v);
 788 }
 789
 790 /* Returns the default display alignment for a variable of the
 791    given TYPE, as set by var_create.  The return value can be
 792    used to reset a variable's display alignment to the default. */
 793 enum alignment
 794 var_default_alignment (enum val_type type)
 795 {
 796   return type == VAL_NUMERIC ? ALIGN_RIGHT : ALIGN_LEFT;
 797 }
 798 \f
 799 /* Whether variables' values should be preserved from case to
 800    case. */
 801
 802 /* Returns true if variable V's value should be left from case to
 803    case, instead of being reset to system-missing or blanks. */
 804 bool
 805 var_get_leave (const struct variable *v)
 806 {
 807   return v->leave;
 808 }
 809
 810 /* Sets V's leave setting to LEAVE. */
 811 void
 812 var_set_leave (struct variable *v, bool leave)
 813 {
 814   assert (leave || !var_must_leave (v));
 815   v->leave = leave;
 816   dict_var_changed (v);
 817 }
 818
 819 /* Returns true if V must be left from case to case,
 820    false if it can be set either way. */
 821 bool
 822 var_must_leave (const struct variable *v)
 823 {
 824   return var_get_dict_class (v) == DC_SCRATCH;
 825 }
 826 \f
 827 /* Returns the number of short names stored in VAR.
 828
 829    Short names are used only for system and portable file input
 830    and output.  They are upper-case only, not necessarily unique,
 831    and limited to SHORT_NAME_LEN characters (plus a null
 832    terminator).  Ordinarily a variable has at most one short
 833    name, but very long string variables (longer than 255 bytes)
 834    may have more.  A variable might not have any short name at
 835    all if it hasn't been saved to or read from a system or
 836    portable file. */
 837 size_t
 838 var_get_short_name_cnt (const struct variable *var)
 839 {
 840   return var->short_name_cnt;
 841 }
 842
 843 /* Returns VAR's short name with the given IDX, if it has one
 844    with that index, or a null pointer otherwise.  Short names may
 845    be sparse: even if IDX is less than the number of short names
 846    in VAR, this function may return a null pointer. */
 847 const char *
 848 var_get_short_name (const struct variable *var, size_t idx)
 849 {
 850   return idx < var->short_name_cnt ? var->short_names[idx] : NULL;
 851 }
 852
 853 /* Sets VAR's short name with the given IDX to the UTF-8 string SHORT_NAME.
 854    The caller must already have checked that, in the dictionary encoding,
 855    SHORT_NAME is no more than SHORT_NAME_LEN bytes long.  The new short name
 856    will be converted to uppercase.
 857
 858    Specifying a null pointer for SHORT_NAME clears the specified short name. */
 859 void
 860 var_set_short_name (struct variable *var, size_t idx, const char *short_name)
 861 {
 862   assert (short_name == NULL || id_is_plausible (short_name, false));
 863
 864   /* Clear old short name numbered IDX, if any. */
 865   if (idx < var->short_name_cnt)
 866     {
 867       free (var->short_names[idx]);
 868       var->short_names[idx] = NULL;
 869     }
 870
 871   /* Install new short name for IDX. */
 872   if (short_name != NULL)
 873     {
 874       if (idx >= var->short_name_cnt)
 875         {
 876           size_t old_cnt = var->short_name_cnt;
 877           size_t i;
 878           var->short_name_cnt = MAX (idx * 2, 1);
 879           var->short_names = xnrealloc (var->short_names, var->short_name_cnt,
 880                                         sizeof *var->short_names);
 881           for (i = old_cnt; i < var->short_name_cnt; i++)
 882             var->short_names[i] = NULL;
 883         }
 884       var->short_names[idx] = xstrdup (short_name);
 885       str_uppercase (var->short_names[idx]);
 886     }
 887
 888   dict_var_changed (var);
 889 }
 890
 891 /* Clears V's short names. */
 892 void
 893 var_clear_short_names (struct variable *v)
 894 {
 895   size_t i;
 896
 897   for (i = 0; i < v->short_name_cnt; i++)
 898     free (v->short_names[i]);
 899   free (v->short_names);
 900   v->short_names = NULL;
 901   v->short_name_cnt = 0;
 902 }
 903 \f
 904 /* Relationship with dictionary. */
 905
 906 /* Returns V's index within its dictionary, the value
 907    for which "dict_get_var (dict, index)" will return V.
 908    V must be in a dictionary. */
 909 size_t
 910 var_get_dict_index (const struct variable *v)
 911 {
 912   assert (var_has_vardict (v));
 913   return vardict_get_dict_index (v->vardict);
 914 }
 915
 916 /* Returns V's index within the case represented by its
 917    dictionary, that is, the value for which "case_data_idx (case,
 918    index)" will return the data for V in that case.
 919    V must be in a dictionary. */
 920 size_t
 921 var_get_case_index (const struct variable *v)
 922 {
 923   assert (var_has_vardict (v));
 924   return vardict_get_case_index (v->vardict);
 925 }
 926 \f
 927 /* Returns V's auxiliary data, or a null pointer if none has been
 928    attached. */
 929 void *
 930 var_get_aux (const struct variable *v)
 931 {
 932   return v->aux;
 933 }
 934
 935 /* Assign auxiliary data AUX to variable V, which must not
 936    already have auxiliary data.  Before V's auxiliary data is
 937    cleared, AUX_DTOR(V) will be called.  (var_dtor_free, below,
 938    may be appropriate for use as AUX_DTOR.) */
 939 void *
 940 var_attach_aux (const struct variable *v_,
 941                 void *aux, void (*aux_dtor) (struct variable *))
 942 {
 943   struct variable *v = CONST_CAST (struct variable *, v_);
 944   assert (v->aux == NULL);
 945   assert (aux != NULL);
 946   v->aux = aux;
 947   v->aux_dtor = aux_dtor;
 948   return aux;
 949 }
 950
 951 /* Remove auxiliary data, if any, from V, and return it, without
 952    calling any associated destructor. */
 953 void *
 954 var_detach_aux (struct variable *v)
 955 {
 956   void *aux = v->aux;
 957   assert (aux != NULL);
 958   v->aux = NULL;
 959   return aux;
 960 }
 961
 962 /* Clears auxiliary data, if any, from V, and calls any
 963    associated destructor. */
 964 void
 965 var_clear_aux (struct variable *v)
 966 {
 967   if (v->aux != NULL)
 968     {
 969       if (v->aux_dtor != NULL)
 970         v->aux_dtor (v);
 971       v->aux = NULL;
 972     }
 973 }
 974
 975 /* This function is appropriate for use an auxiliary data
 976    destructor (passed as AUX_DTOR to var_attach_aux()) for the
 977    case where the auxiliary data should be passed to free(). */
 978 void
 979 var_dtor_free (struct variable *v)
 980 {
 981   free (v->aux);
 982 }
 983 \f
 984 /* Returns variable V's attribute set.  The caller may examine or
 985    modify the attribute set, but must not destroy it.  Destroying
 986    V, or calling var_set_attributes() on V, will also destroy its
 987    attribute set. */
 988 struct attrset *
 989 var_get_attributes (const struct variable *v)
 990 {
 991   return CONST_CAST (struct attrset *, &v->attributes);
 992 }
 993
 994 /* Replaces variable V's attributes set by a copy of ATTRS. */
 995 void
 996 var_set_attributes (struct variable *v, const struct attrset *attrs)
 997 {
 998   attrset_destroy (&v->attributes);
 999   attrset_clone (&v->attributes, attrs);
1000 }
1001
1002 /* Returns true if V has any custom attributes, false if it has none. */
1003 bool
1004 var_has_attributes (const struct variable *v)
1005 {
1006   return attrset_count (&v->attributes) > 0;
1007 }
1008 \f
1009 /* Returns the encoding of values of variable VAR.  (This is actually a
1010    property of the dictionary.)  Returns null if no specific encoding has been
1011    set.  */
1012 const char *
1013 var_get_encoding (const struct variable *var)
1014 {
1015   return (var_has_vardict (var)
1016           ? dict_get_encoding (vardict_get_dictionary (var->vardict))
1017           : NULL);
1018 }
1019 \f
1020 /* Returns V's vardict structure. */
1021 struct vardict_info *
1022 var_get_vardict (const struct variable *v)
1023 {
1024   return CONST_CAST (struct vardict_info *, v->vardict);
1025 }
1026
1027 /* Sets V's vardict data to VARDICT. */
1028 void
1029 var_set_vardict (struct variable *v, struct vardict_info *vardict)
1030 {
1031   v->vardict = vardict;
1032 }
1033
1034 /* Returns true if V has vardict data. */
1035 bool
1036 var_has_vardict (const struct variable *v)
1037 {
1038   return v->vardict != NULL;
1039 }
1040
1041 /* Clears V's vardict data. */
1042 void
1043 var_clear_vardict (struct variable *v)
1044 {
1045   v->vardict = NULL;
1046 }