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), NULL, 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 LABEL
 431    to V.  Returns true if successful, false otherwise (probably
 432    due to an existing label). */
 433 bool
 434 var_add_value_label (struct variable *v,
 435                      const union value *value, const char *label)
 436 {
 437   alloc_value_labels (v);
 438   return val_labs_add (v->val_labs, value, label);
 439 }
 440
 441 /* Adds or replaces a value label with the given VALUE and LABEL
 442    to V.
 443 */
 444 void
 445 var_replace_value_label (struct variable *v,
 446                          const union value *value, const char *label)
 447 {
 448   alloc_value_labels (v);
 449   val_labs_replace (v->val_labs, value, label);
 450 }
 451
 452 /* Removes V's value labels, if any. */
 453 void
 454 var_clear_value_labels (struct variable *v)
 455 {
 456   var_set_value_labels (v, NULL);
 457 }
 458
 459 /* Returns the label associated with VALUE for variable V,
 460    or a null pointer if none. */
 461 const char *
 462 var_lookup_value_label (const struct variable *v, const union value *value)
 463 {
 464   return val_labs_find (v->val_labs, value);
 465 }
 466
 467 /* Append STR with a string representing VALUE for variable V.
 468    That is, if VALUE has a label, append that label,
 469    otherwise format VALUE and append the formatted string.
 470    STR must be a pointer to an initialised struct string.
 471 */
 472 void
 473 var_append_value_name (const struct variable *v, const union value *value,
 474                        struct string *str)
 475 {
 476   const char *name = var_lookup_value_label (v, value);
 477   if (name == NULL)
 478     {
 479       char *s = data_out (value, var_get_encoding (v), &v->print);
 480       ds_put_cstr (str, s);
 481       free (s);
 482     }
 483   else
 484     ds_put_cstr (str, name);
 485 }
 486 \f
 487 /* Print and write formats. */
 488
 489 /* Returns V's print format specification. */
 490 const struct fmt_spec *
 491 var_get_print_format (const struct variable *v)
 492 {
 493   return &v->print;
 494 }
 495
 496 /* Sets V's print format specification to PRINT, which must be a
 497    valid format specification for a variable of V's width
 498    (ordinarily an output format, but input formats are not
 499    rejected). */
 500 void
 501 var_set_print_format (struct variable *v, const struct fmt_spec *print)
 502 {
 503   assert (fmt_check_width_compat (print, v->width));
 504   v->print = *print;
 505   dict_var_changed (v);
 506 }
 507
 508 /* Returns V's write format specification. */
 509 const struct fmt_spec *
 510 var_get_write_format (const struct variable *v)
 511 {
 512   return &v->write;
 513 }
 514
 515 /* Sets V's write format specification to WRITE, which must be a
 516    valid format specification for a variable of V's width
 517    (ordinarily an output format, but input formats are not
 518    rejected). */
 519 void
 520 var_set_write_format (struct variable *v, const struct fmt_spec *write)
 521 {
 522   assert (fmt_check_width_compat (write, v->width));
 523   v->write = *write;
 524   dict_var_changed (v);
 525 }
 526
 527 /* Sets V's print and write format specifications to FORMAT,
 528    which must be a valid format specification for a variable of
 529    V's width (ordinarily an output format, but input formats are
 530    not rejected). */
 531 void
 532 var_set_both_formats (struct variable *v, const struct fmt_spec *format)
 533 {
 534   var_set_print_format (v, format);
 535   var_set_write_format (v, format);
 536 }
 537
 538 /* Returns the default print and write format for a variable of
 539    the given TYPE, as set by var_create.  The return value can be
 540    used to reset a variable's print and write formats to the
 541    default. */
 542 struct fmt_spec
 543 var_default_formats (int width)
 544 {
 545   return (width == 0
 546           ? fmt_for_output (FMT_F, 8, 2)
 547           : fmt_for_output (FMT_A, width, 0));
 548 }
 549 \f
 550 /* Return a string representing this variable, in the form most
 551    appropriate from a human factors perspective, that is, its
 552    variable label if it has one, otherwise its name. */
 553 const char *
 554 var_to_string (const struct variable *v)
 555 {
 556   return v->label != NULL ? v->label : v->name;
 557 }
 558
 559 /* Returns V's variable label, or a null pointer if it has none. */
 560 const char *
 561 var_get_label (const struct variable *v)
 562 {
 563   return v->label;
 564 }
 565
 566 /* Sets V's variable label to UTF-8 encoded string LABEL, stripping off leading
 567    and trailing white space.  If LABEL is a null pointer or if LABEL is an
 568    empty string (after stripping white space), then V's variable label (if any)
 569    is removed.
 570
 571    Variable labels are limited to 255 bytes in the dictionary encoding, which
 572    should be specified as DICT_ENCODING.  If LABEL fits within this limit, this
 573    function returns true.  Otherwise, the variable label is set to a truncated
 574    value, this function returns false and, if ISSUE_WARNING is true, issues a
 575    warning.  */
 576 bool
 577 var_set_label (struct variable *v, const char *label,
 578                const char *dict_encoding, bool issue_warning)
 579 {
 580   bool truncated = false;
 581
 582   free (v->label);
 583   v->label = NULL;
 584
 585   if (label != NULL)
 586     {
 587       struct substring s = ss_cstr (label);
 588       size_t trunc_len;
 589
 590       if (dict_encoding != NULL)
 591         {
 592           enum { MAX_LABEL_LEN = 255 };
 593
 594           trunc_len = utf8_encoding_trunc_len (label, dict_encoding,
 595                                                MAX_LABEL_LEN);
 596           if (ss_length (s) > trunc_len)
 597             {
 598               if (issue_warning)
 599                 msg (SW, _("Truncating variable label for variable `%s' to %d "
 600                            "bytes."), var_get_name (v), MAX_LABEL_LEN);
 601               ss_truncate (&s, trunc_len);
 602               truncated = true;
 603             }
 604         }
 605
 606       ss_trim (&s, ss_cstr (CC_SPACES));
 607       if (!ss_is_empty (s))
 608         v->label = ss_xstrdup (s);
 609     }
 610
 611   dict_var_changed (v);
 612
 613   return truncated;
 614 }
 615
 616 /* Removes any variable label from V. */
 617 void
 618 var_clear_label (struct variable *v)
 619 {
 620   var_set_label (v, NULL, NULL, false);
 621 }
 622
 623 /* Returns true if V has a variable V,
 624    false otherwise. */
 625 bool
 626 var_has_label (const struct variable *v)
 627 {
 628   return v->label != NULL;
 629 }
 630 \f
 631 /* Returns true if M is a valid variable measurement level,
 632    false otherwise. */
 633 bool
 634 measure_is_valid (enum measure m)
 635 {
 636   return m == MEASURE_NOMINAL || m == MEASURE_ORDINAL || m == MEASURE_SCALE;
 637 }
 638
 639 /* Returns V's measurement level. */
 640 enum measure
 641 var_get_measure (const struct variable *v)
 642 {
 643   return v->measure;
 644 }
 645
 646 /* Sets V's measurement level to MEASURE. */
 647 void
 648 var_set_measure (struct variable *v, enum measure measure)
 649 {
 650   assert (measure_is_valid (measure));
 651   v->measure = measure;
 652   dict_var_changed (v);
 653 }
 654
 655 /* Returns the default measurement level for a variable of the
 656    given TYPE, as set by var_create.  The return value can be
 657    used to reset a variable's measurement level to the
 658    default. */
 659 enum measure
 660 var_default_measure (enum val_type type)
 661 {
 662   return type == VAL_NUMERIC ? MEASURE_SCALE : MEASURE_NOMINAL;
 663 }
 664 \f
 665 /* Returns V's display width, which applies only to GUIs. */
 666 int
 667 var_get_display_width (const struct variable *v)
 668 {
 669   return v->display_width;
 670 }
 671
 672 /* Sets V's display width to DISPLAY_WIDTH. */
 673 void
 674 var_set_display_width (struct variable *v, int new_width)
 675 {
 676   int old_width = v->display_width;
 677
 678   v->display_width = new_width;
 679
 680   if ( old_width != new_width)
 681     dict_var_display_width_changed (v);
 682
 683   dict_var_changed (v);
 684 }
 685
 686 /* Returns the default display width for a variable of the given
 687    WIDTH, as set by var_create.  The return value can be used to
 688    reset a variable's display width to the default. */
 689 int
 690 var_default_display_width (int width)
 691 {
 692   return width == 0 ? 8 : MIN (width, 32);
 693 }
 694 \f
 695 /* Returns true if A is a valid alignment,
 696    false otherwise. */
 697 bool
 698 alignment_is_valid (enum alignment a)
 699 {
 700   return a == ALIGN_LEFT || a == ALIGN_RIGHT || a == ALIGN_CENTRE;
 701 }
 702
 703 /* Returns V's display alignment, which applies only to GUIs. */
 704 enum alignment
 705 var_get_alignment (const struct variable *v)
 706 {
 707   return v->alignment;
 708 }
 709
 710 /* Sets V's display alignment to ALIGNMENT. */
 711 void
 712 var_set_alignment (struct variable *v, enum alignment alignment)
 713 {
 714   assert (alignment_is_valid (alignment));
 715   v->alignment = alignment;
 716   dict_var_changed (v);
 717 }
 718
 719 /* Returns the default display alignment for a variable of the
 720    given TYPE, as set by var_create.  The return value can be
 721    used to reset a variable's display alignment to the default. */
 722 enum alignment
 723 var_default_alignment (enum val_type type)
 724 {
 725   return type == VAL_NUMERIC ? ALIGN_RIGHT : ALIGN_LEFT;
 726 }
 727 \f
 728 /* Whether variables' values should be preserved from case to
 729    case. */
 730
 731 /* Returns true if variable V's value should be left from case to
 732    case, instead of being reset to system-missing or blanks. */
 733 bool
 734 var_get_leave (const struct variable *v)
 735 {
 736   return v->leave;
 737 }
 738
 739 /* Sets V's leave setting to LEAVE. */
 740 void
 741 var_set_leave (struct variable *v, bool leave)
 742 {
 743   assert (leave || !var_must_leave (v));
 744   v->leave = leave;
 745   dict_var_changed (v);
 746 }
 747
 748 /* Returns true if V must be left from case to case,
 749    false if it can be set either way. */
 750 bool
 751 var_must_leave (const struct variable *v)
 752 {
 753   return var_get_dict_class (v) == DC_SCRATCH;
 754 }
 755 \f
 756 /* Returns the number of short names stored in VAR.
 757
 758    Short names are used only for system and portable file input
 759    and output.  They are upper-case only, not necessarily unique,
 760    and limited to SHORT_NAME_LEN characters (plus a null
 761    terminator).  Ordinarily a variable has at most one short
 762    name, but very long string variables (longer than 255 bytes)
 763    may have more.  A variable might not have any short name at
 764    all if it hasn't been saved to or read from a system or
 765    portable file. */
 766 size_t
 767 var_get_short_name_cnt (const struct variable *var)
 768 {
 769   return var->short_name_cnt;
 770 }
 771
 772 /* Returns VAR's short name with the given IDX, if it has one
 773    with that index, or a null pointer otherwise.  Short names may
 774    be sparse: even if IDX is less than the number of short names
 775    in VAR, this function may return a null pointer. */
 776 const char *
 777 var_get_short_name (const struct variable *var, size_t idx)
 778 {
 779   return idx < var->short_name_cnt ? var->short_names[idx] : NULL;
 780 }
 781
 782 /* Sets VAR's short name with the given IDX to SHORT_NAME,
 783    truncating it to SHORT_NAME_LEN characters and converting it
 784    to uppercase in the process.  Specifying a null pointer for
 785    SHORT_NAME clears the specified short name. */
 786 void
 787 var_set_short_name (struct variable *var, size_t idx, const char *short_name)
 788 {
 789   assert (short_name == NULL || id_is_plausible (short_name, false));
 790
 791   /* Clear old short name numbered IDX, if any. */
 792   if (idx < var->short_name_cnt)
 793     {
 794       free (var->short_names[idx]);
 795       var->short_names[idx] = NULL;
 796     }
 797
 798   /* Install new short name for IDX. */
 799   if (short_name != NULL)
 800     {
 801       if (idx >= var->short_name_cnt)
 802         {
 803           size_t old_cnt = var->short_name_cnt;
 804           size_t i;
 805           var->short_name_cnt = MAX (idx * 2, 1);
 806           var->short_names = xnrealloc (var->short_names, var->short_name_cnt,
 807                                         sizeof *var->short_names);
 808           for (i = old_cnt; i < var->short_name_cnt; i++)
 809             var->short_names[i] = NULL;
 810         }
 811       var->short_names[idx] = xstrndup (short_name, MAX_SHORT_STRING);
 812       str_uppercase (var->short_names[idx]);
 813     }
 814
 815   dict_var_changed (var);
 816 }
 817
 818 /* Clears V's short names. */
 819 void
 820 var_clear_short_names (struct variable *v)
 821 {
 822   size_t i;
 823
 824   for (i = 0; i < v->short_name_cnt; i++)
 825     free (v->short_names[i]);
 826   free (v->short_names);
 827   v->short_names = NULL;
 828   v->short_name_cnt = 0;
 829 }
 830 \f
 831 /* Relationship with dictionary. */
 832
 833 /* Returns V's index within its dictionary, the value
 834    for which "dict_get_var (dict, index)" will return V.
 835    V must be in a dictionary. */
 836 size_t
 837 var_get_dict_index (const struct variable *v)
 838 {
 839   assert (var_has_vardict (v));
 840   return vardict_get_dict_index (v->vardict);
 841 }
 842
 843 /* Returns V's index within the case represented by its
 844    dictionary, that is, the value for which "case_data_idx (case,
 845    index)" will return the data for V in that case.
 846    V must be in a dictionary. */
 847 size_t
 848 var_get_case_index (const struct variable *v)
 849 {
 850   assert (var_has_vardict (v));
 851   return vardict_get_case_index (v->vardict);
 852 }
 853 \f
 854 /* Returns V's auxiliary data, or a null pointer if none has been
 855    attached. */
 856 void *
 857 var_get_aux (const struct variable *v)
 858 {
 859   return v->aux;
 860 }
 861
 862 /* Assign auxiliary data AUX to variable V, which must not
 863    already have auxiliary data.  Before V's auxiliary data is
 864    cleared, AUX_DTOR(V) will be called.  (var_dtor_free, below,
 865    may be appropriate for use as AUX_DTOR.) */
 866 void *
 867 var_attach_aux (const struct variable *v_,
 868                 void *aux, void (*aux_dtor) (struct variable *))
 869 {
 870   struct variable *v = CONST_CAST (struct variable *, v_);
 871   assert (v->aux == NULL);
 872   assert (aux != NULL);
 873   v->aux = aux;
 874   v->aux_dtor = aux_dtor;
 875   return aux;
 876 }
 877
 878 /* Remove auxiliary data, if any, from V, and return it, without
 879    calling any associated destructor. */
 880 void *
 881 var_detach_aux (struct variable *v)
 882 {
 883   void *aux = v->aux;
 884   assert (aux != NULL);
 885   v->aux = NULL;
 886   return aux;
 887 }
 888
 889 /* Clears auxiliary data, if any, from V, and calls any
 890    associated destructor. */
 891 void
 892 var_clear_aux (struct variable *v)
 893 {
 894   if (v->aux != NULL)
 895     {
 896       if (v->aux_dtor != NULL)
 897         v->aux_dtor (v);
 898       v->aux = NULL;
 899     }
 900 }
 901
 902 /* This function is appropriate for use an auxiliary data
 903    destructor (passed as AUX_DTOR to var_attach_aux()) for the
 904    case where the auxiliary data should be passed to free(). */
 905 void
 906 var_dtor_free (struct variable *v)
 907 {
 908   free (v->aux);
 909 }
 910 \f
 911 /* Returns variable V's attribute set.  The caller may examine or
 912    modify the attribute set, but must not destroy it.  Destroying
 913    V, or calling var_set_attributes() on V, will also destroy its
 914    attribute set. */
 915 struct attrset *
 916 var_get_attributes (const struct variable *v)
 917 {
 918   return CONST_CAST (struct attrset *, &v->attributes);
 919 }
 920
 921 /* Replaces variable V's attributes set by a copy of ATTRS. */
 922 void
 923 var_set_attributes (struct variable *v, const struct attrset *attrs)
 924 {
 925   attrset_destroy (&v->attributes);
 926   attrset_clone (&v->attributes, attrs);
 927 }
 928
 929 /* Returns true if V has any custom attributes, false if it has none. */
 930 bool
 931 var_has_attributes (const struct variable *v)
 932 {
 933   return attrset_count (&v->attributes) > 0;
 934 }
 935 \f
 936 /* Returns the encoding of values of variable VAR.  (This is actually a
 937    property of the dictionary.)  Returns null if no specific encoding has been
 938    set.  */
 939 const char *
 940 var_get_encoding (const struct variable *var)
 941 {
 942   return (var_has_vardict (var)
 943           ? dict_get_encoding (vardict_get_dictionary (var->vardict))
 944           : NULL);
 945 }
 946 \f
 947 /* Returns V's vardict structure. */
 948 struct vardict_info *
 949 var_get_vardict (const struct variable *v)
 950 {
 951   return CONST_CAST (struct vardict_info *, v->vardict);
 952 }
 953
 954 /* Sets V's vardict data to VARDICT. */
 955 void
 956 var_set_vardict (struct variable *v, struct vardict_info *vardict)
 957 {
 958   v->vardict = vardict;
 959 }
 960
 961 /* Returns true if V has vardict data. */
 962 bool
 963 var_has_vardict (const struct variable *v)
 964 {
 965   return v->vardict != NULL;
 966 }
 967
 968 /* Clears V's vardict data. */
 969 void
 970 var_clear_vardict (struct variable *v)
 971 {
 972   v->vardict = NULL;
 973 }