src/data/variable.c

   1 /* PSPP - a program for statistical analysis.
   2    Copyright (C) 1997-9, 2000, 2006 Free Software Foundation, Inc.
   3
   4    This program is free software: you can redistribute it and/or modify
   5    it under the terms of the GNU General Public License as published by
   6    the Free Software Foundation, either version 3 of the License, or
   7    (at your option) any later version.
   8
   9    This program is distributed in the hope that it will be useful,
  10    but WITHOUT ANY WARRANTY; without even the implied warranty of
  11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12    GNU General Public License for more details.
  13
  14    You should have received a copy of the GNU General Public License
  15    along with this program.  If not, see <http://www.gnu.org/licenses/>. */
  16
  17 #include <config.h>
  18 #include "variable.h"
  19
  20 #include <stdlib.h>
  21
  22 #include "category.h"
  23 #include "data-out.h"
  24 #include "format.h"
  25 #include "dictionary.h"
  26 #include "identifier.h"
  27 #include "missing-values.h"
  28 #include "value-labels.h"
  29 #include "vardict.h"
  30
  31 #include <libpspp/misc.h>
  32 #include <libpspp/assertion.h>
  33 #include <libpspp/compiler.h>
  34 #include <libpspp/hash.h>
  35 #include <libpspp/message.h>
  36 #include <libpspp/str.h>
  37
  38 #include "xalloc.h"
  39
  40 #include "gettext.h"
  41 #define _(msgid) gettext (msgid)
  42
  43 /* A variable. */
  44 struct variable
  45   {
  46     /* Dictionary information. */
  47     char name[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     /* Used only for system and portable file input and output.
  67        See short-names.h. */
  68     char **short_names;
  69     size_t short_name_cnt;
  70
  71     /* Each command may use these fields as needed. */
  72     void *aux;
  73     void (*aux_dtor) (struct variable *);
  74
  75     /* Values of a categorical variable.  Procedures need
  76        vectors with binary entries, so any variable of type ALPHA will
  77        have its values stored here. */
  78     struct cat_vals *obs_vals;
  79   };
  80
  81 /* Returns true if VAR_TYPE is a valid variable type. */
  82 bool
  83 var_type_is_valid (enum var_type var_type)
  84 {
  85   return var_type == VAR_NUMERIC || var_type == VAR_STRING;
  86 }
  87
  88 /* Returns the variable type for the given width. */
  89 enum var_type
  90 var_type_from_width (int width)
  91 {
  92   return width != 0 ? VAR_STRING : VAR_NUMERIC;
  93 }
  94 \f
  95 /* Creates and returns a new variable with the given NAME and
  96    WIDTH and other fields initialized to default values.  The
  97    variable is not added to a dictionary; for that, use
  98    dict_create_var instead. */
  99 struct variable *
 100 var_create (const char *name, int width)
 101 {
 102   struct variable *v;
 103
 104   assert (width >= 0 && width <= MAX_STRING);
 105
 106   v = xmalloc (sizeof *v);
 107   v->vardict.dict_index = v->vardict.case_index = -1;
 108   var_set_name (v, name);
 109   v->width = width;
 110   mv_init (&v->miss, width);
 111   v->leave = var_must_leave (v);
 112   if (var_is_numeric (v))
 113     {
 114       v->print = fmt_for_output (FMT_F, 8, 2);
 115       v->alignment = ALIGN_RIGHT;
 116       v->measure = MEASURE_SCALE;
 117     }
 118   else
 119     {
 120       v->print = fmt_for_output (FMT_A, var_get_width (v), 0);
 121       v->alignment = ALIGN_LEFT;
 122       v->measure = MEASURE_NOMINAL;
 123     }
 124   v->display_width = var_default_display_width (width);
 125   v->write = v->print;
 126   v->val_labs = NULL;
 127   v->label = NULL;
 128   v->short_names = NULL;
 129   v->short_name_cnt = 0;
 130   v->aux = NULL;
 131   v->aux_dtor = NULL;
 132   v->obs_vals = NULL;
 133
 134   return v;
 135 }
 136
 137 /* Creates and returns a clone of OLD_VAR.  Most properties of
 138    the new variable are copied from OLD_VAR, except:
 139
 140     - The variable's short name is not copied, because there is
 141       no reason to give a new variable with potentially a new
 142       name the same short name.
 143
 144     - The new variable is not added to OLD_VAR's dictionary by
 145       default.  Use dict_clone_var, instead, to do that.
 146
 147     - Auxiliary data and obs_vals are not copied. */
 148 struct variable *
 149 var_clone (const struct variable *old_var)
 150 {
 151   struct variable *new_var = var_create (var_get_name (old_var),
 152                                          var_get_width (old_var));
 153
 154   var_set_missing_values (new_var, var_get_missing_values (old_var));
 155   var_set_print_format (new_var, var_get_print_format (old_var));
 156   var_set_write_format (new_var, var_get_write_format (old_var));
 157   var_set_value_labels (new_var, var_get_value_labels (old_var));
 158   var_set_label (new_var, var_get_label (old_var));
 159   var_set_measure (new_var, var_get_measure (old_var));
 160   var_set_display_width (new_var, var_get_display_width (old_var));
 161   var_set_alignment (new_var, var_get_alignment (old_var));
 162   var_set_leave (new_var, var_get_leave (old_var));
 163
 164   return new_var;
 165 }
 166
 167 /* Destroys variable V.
 168    V must not belong to a dictionary.  If it does, use
 169    dict_delete_var instead. */
 170 void
 171 var_destroy (struct variable *v)
 172 {
 173   if (v != NULL)
 174     {
 175       assert (!var_has_vardict (v));
 176       cat_stored_values_destroy (v->obs_vals);
 177       var_clear_short_names (v);
 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 /* Sets V's display width to DISPLAY_WIDTH. */
 727 void
 728 var_set_display_width (struct variable *v, int display_width)
 729 {
 730   v->display_width = display_width;
 731   dict_var_changed (v);
 732 }
 733
 734 /* Returns the default display width for a variable of the given
 735    WIDTH, as set by var_create.  The return value can be used to
 736    reset a variable's display width to the default. */
 737 int
 738 var_default_display_width (int width)
 739 {
 740   return width == 0 ? 8 : MIN (width, 32);
 741 }
 742 \f
 743 /* Returns true if A is a valid alignment,
 744    false otherwise. */
 745 bool
 746 alignment_is_valid (enum alignment a)
 747 {
 748   return a == ALIGN_LEFT || a == ALIGN_RIGHT || a == ALIGN_CENTRE;
 749 }
 750
 751 /* Returns V's display alignment, which applies only to GUIs. */
 752 enum alignment
 753 var_get_alignment (const struct variable *v)
 754 {
 755   return v->alignment;
 756 }
 757
 758 /* Sets V's display alignment to ALIGNMENT. */
 759 void
 760 var_set_alignment (struct variable *v, enum alignment alignment)
 761 {
 762   assert (alignment_is_valid (alignment));
 763   v->alignment = alignment;
 764   dict_var_changed (v);
 765 }
 766 \f
 767 /* Whether variables' values should be preserved from case to
 768    case. */
 769
 770 /* Returns true if variable V's value should be left from case to
 771    case, instead of being reset to 0, system-missing, or blanks. */
 772 bool
 773 var_get_leave (const struct variable *v)
 774 {
 775   return v->leave;
 776 }
 777
 778 /* Sets V's leave setting to LEAVE. */
 779 void
 780 var_set_leave (struct variable *v, bool leave)
 781 {
 782   assert (leave || !var_must_leave (v));
 783   v->leave = leave;
 784   dict_var_changed (v);
 785 }
 786
 787 /* Returns true if V must be left from case to case,
 788    false if it can be set either way. */
 789 bool
 790 var_must_leave (const struct variable *v)
 791 {
 792   return dict_class_from_id (v->name) == DC_SCRATCH;
 793 }
 794 \f
 795 /* Returns the number of short names stored in VAR.
 796
 797    Short names are used only for system and portable file input
 798    and output.  They are upper-case only, not necessarily unique,
 799    and limited to SHORT_NAME_LEN characters (plus a null
 800    terminator).  Ordinarily a variable has at most one short
 801    name, but very long string variables (longer than 255 bytes)
 802    may have more.  A variable might not have any short name at
 803    all if it hasn't been saved to or read from a system or
 804    portable file. */
 805 size_t
 806 var_get_short_name_cnt (const struct variable *var)
 807 {
 808   return var->short_name_cnt;
 809 }
 810
 811 /* Returns VAR's short name with the given IDX, if it has one
 812    with that index, or a null pointer otherwise.  Short names may
 813    be sparse: even if IDX is less than the number of short names
 814    in VAR, this function may return a null pointer. */
 815 const char *
 816 var_get_short_name (const struct variable *var, size_t idx)
 817 {
 818   return idx < var->short_name_cnt ? var->short_names[idx] : NULL;
 819 }
 820
 821 /* Sets VAR's short name with the given IDX to SHORT_NAME,
 822    truncating it to SHORT_NAME_LEN characters and converting it
 823    to uppercase in the process.  Specifying a null pointer for
 824    SHORT_NAME clears the specified short name. */
 825 void
 826 var_set_short_name (struct variable *var, size_t idx, const char *short_name)
 827 {
 828   assert (var != NULL);
 829   assert (short_name == NULL || var_is_plausible_name (short_name, false));
 830
 831   /* Clear old short name numbered IDX, if any. */
 832   if (idx < var->short_name_cnt)
 833     {
 834       free (var->short_names[idx]);
 835       var->short_names[idx] = NULL;
 836     }
 837
 838   /* Install new short name for IDX. */
 839   if (short_name != NULL)
 840     {
 841       if (idx >= var->short_name_cnt)
 842         {
 843           size_t old_cnt = var->short_name_cnt;
 844           size_t i;
 845           var->short_name_cnt = MAX (idx * 2, 1);
 846           var->short_names = xnrealloc (var->short_names, var->short_name_cnt,
 847                                         sizeof *var->short_names);
 848           for (i = old_cnt; i < var->short_name_cnt; i++)
 849             var->short_names[i] = NULL;
 850         }
 851       var->short_names[idx] = xstrndup (short_name, MAX_SHORT_STRING);
 852       str_uppercase (var->short_names[idx]);
 853     }
 854
 855   dict_var_changed (var);
 856 }
 857
 858 /* Clears V's short names. */
 859 void
 860 var_clear_short_names (struct variable *v)
 861 {
 862   size_t i;
 863
 864   for (i = 0; i < v->short_name_cnt; i++)
 865     free (v->short_names[i]);
 866   free (v->short_names);
 867   v->short_names = NULL;
 868   v->short_name_cnt = 0;
 869 }
 870 \f
 871 /* Relationship with dictionary. */
 872
 873 /* Returns V's index within its dictionary, the value
 874    for which "dict_get_var (dict, index)" will return V.
 875    V must be in a dictionary. */
 876 size_t
 877 var_get_dict_index (const struct variable *v)
 878 {
 879   assert (v->vardict.dict_index != -1);
 880   return v->vardict.dict_index;
 881 }
 882
 883 /* Returns V's index within the case represented by its
 884    dictionary, that is, the value for which "case_data_idx (case,
 885    index)" will return the data for V in that case.
 886    V must be in a dictionary. */
 887 size_t
 888 var_get_case_index (const struct variable *v)
 889 {
 890   assert (v->vardict.case_index != -1);
 891   return v->vardict.case_index;
 892 }
 893 \f
 894 /* Returns V's auxiliary data, or a null pointer if none has been
 895    attached. */
 896 void *
 897 var_get_aux (const struct variable *v)
 898 {
 899   return v->aux;
 900 }
 901
 902 /* Assign auxiliary data AUX to variable V, which must not
 903    already have auxiliary data.  Before V's auxiliary data is
 904    cleared, AUX_DTOR(V) will be called.  (var_dtor_free, below,
 905    may be appropriate for use as AUX_DTOR.) */
 906 void *
 907 var_attach_aux (const struct variable *v_,
 908                 void *aux, void (*aux_dtor) (struct variable *))
 909 {
 910   struct variable *v = (struct variable *) v_ ; /* cast away const  */
 911   assert (v->aux == NULL);
 912   assert (aux != NULL);
 913   v->aux = aux;
 914   v->aux_dtor = aux_dtor;
 915   return aux;
 916 }
 917
 918 /* Remove auxiliary data, if any, from V, and return it, without
 919    calling any associated destructor. */
 920 void *
 921 var_detach_aux (struct variable *v)
 922 {
 923   void *aux = v->aux;
 924   assert (aux != NULL);
 925   v->aux = NULL;
 926   return aux;
 927 }
 928
 929 /* Clears auxiliary data, if any, from V, and calls any
 930    associated destructor. */
 931 void
 932 var_clear_aux (struct variable *v)
 933 {
 934   assert (v != NULL);
 935   if (v->aux != NULL)
 936     {
 937       if (v->aux_dtor != NULL)
 938         v->aux_dtor (v);
 939       v->aux = NULL;
 940     }
 941 }
 942
 943 /* This function is appropriate for use an auxiliary data
 944    destructor (passed as AUX_DTOR to var_attach_aux()) for the
 945    case where the auxiliary data should be passed to free(). */
 946 void
 947 var_dtor_free (struct variable *v)
 948 {
 949   free (v->aux);
 950 }
 951 \f
 952 /* Observed categorical values. */
 953
 954 /* Returns V's observed categorical values,
 955    which V must have. */
 956 struct cat_vals *
 957 var_get_obs_vals (const struct variable *v)
 958 {
 959   assert (v->obs_vals != NULL);
 960   return v->obs_vals;
 961 }
 962
 963 /* Sets V's observed categorical values to CAT_VALS. */
 964 void
 965 var_set_obs_vals (const struct variable *v_, struct cat_vals *cat_vals)
 966 {
 967   struct variable *v = (struct variable *) v_ ; /* cast away const */
 968   cat_stored_values_destroy (v->obs_vals);
 969   v->obs_vals = cat_vals;
 970 }
 971
 972 /* Returns true if V has observed categorical values,
 973    false otherwise. */
 974 bool
 975 var_has_obs_vals (const struct variable *v)
 976 {
 977   return v->obs_vals != NULL;
 978 }
 979 \f
 980 /* Returns the dictionary class corresponding to a variable named
 981    NAME. */
 982 enum dict_class
 983 dict_class_from_id (const char *name)
 984 {
 985   switch (name[0])
 986     {
 987     default:
 988       return DC_ORDINARY;
 989     case '$':
 990       return DC_SYSTEM;
 991     case '#':
 992       return DC_SCRATCH;
 993     }
 994 }
 995
 996 /* Returns the name of dictionary class DICT_CLASS. */
 997 const char *
 998 dict_class_to_name (enum dict_class dict_class)
 999 {
1000   switch (dict_class)
1001     {
1002     case DC_ORDINARY:
1003       return _("ordinary");
1004     case DC_SYSTEM:
1005       return _("system");
1006     case DC_SCRATCH:
1007       return _("scratch");
1008     default:
1009       NOT_REACHED ();
1010     }
1011 }
1012 \f
1013 /* Returns V's vardict structure. */
1014 const struct vardict_info *
1015 var_get_vardict (const struct variable *v)
1016 {
1017   assert (var_has_vardict (v));
1018   return &v->vardict;
1019 }
1020
1021 /* Sets V's vardict data to VARDICT. */
1022 void
1023 var_set_vardict (struct variable *v, const struct vardict_info *vardict)
1024 {
1025   assert (vardict->dict_index >= 0);
1026   assert (vardict->case_index >= 0);
1027   v->vardict = *vardict;
1028 }
1029
1030 /* Returns true if V has vardict data. */
1031 bool
1032 var_has_vardict (const struct variable *v)
1033 {
1034   return v->vardict.dict_index != -1;
1035 }
1036
1037 /* Clears V's vardict data. */
1038 void
1039 var_clear_vardict (struct variable *v)
1040 {
1041   v->vardict.dict_index = v->vardict.case_index = -1;
1042 }