src/data/variable.c

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