src/data/variable.c

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