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