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