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