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