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