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