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 new_width)
 782 {
 783   int old_width = v->display_width;
 784
 785   v->display_width = new_width;
 786
 787   if ( old_width != new_width)
 788     dict_var_display_width_changed (v);
 789
 790   dict_var_changed (v);
 791 }
 792
 793 /* Returns the default display width for a variable of the given
 794    WIDTH, as set by var_create.  The return value can be used to
 795    reset a variable's display width to the default. */
 796 int
 797 var_default_display_width (int width)
 798 {
 799   return width == 0 ? 8 : MIN (width, 32);
 800 }
 801 \f
 802 /* Returns true if A is a valid alignment,
 803    false otherwise. */
 804 bool
 805 alignment_is_valid (enum alignment a)
 806 {
 807   return a == ALIGN_LEFT || a == ALIGN_RIGHT || a == ALIGN_CENTRE;
 808 }
 809
 810 /* Returns V's display alignment, which applies only to GUIs. */
 811 enum alignment
 812 var_get_alignment (const struct variable *v)
 813 {
 814   return v->alignment;
 815 }
 816
 817 /* Sets V's display alignment to ALIGNMENT. */
 818 void
 819 var_set_alignment (struct variable *v, enum alignment alignment)
 820 {
 821   assert (alignment_is_valid (alignment));
 822   v->alignment = alignment;
 823   dict_var_changed (v);
 824 }
 825
 826 /* Returns the default display alignment for a variable of the
 827    given TYPE, as set by var_create.  The return value can be
 828    used to reset a variable's display alignment to the default. */
 829 enum alignment
 830 var_default_alignment (enum val_type type)
 831 {
 832   return type == VAL_NUMERIC ? ALIGN_RIGHT : ALIGN_LEFT;
 833 }
 834 \f
 835 /* Whether variables' values should be preserved from case to
 836    case. */
 837
 838 /* Returns true if variable V's value should be left from case to
 839    case, instead of being reset to system-missing or blanks. */
 840 bool
 841 var_get_leave (const struct variable *v)
 842 {
 843   return v->leave;
 844 }
 845
 846 /* Sets V's leave setting to LEAVE. */
 847 void
 848 var_set_leave (struct variable *v, bool leave)
 849 {
 850   assert (leave || !var_must_leave (v));
 851   v->leave = leave;
 852   dict_var_changed (v);
 853 }
 854
 855 /* Returns true if V must be left from case to case,
 856    false if it can be set either way. */
 857 bool
 858 var_must_leave (const struct variable *v)
 859 {
 860   return var_get_dict_class (v) == DC_SCRATCH;
 861 }
 862 \f
 863 /* Returns the number of short names stored in VAR.
 864
 865    Short names are used only for system and portable file input
 866    and output.  They are upper-case only, not necessarily unique,
 867    and limited to SHORT_NAME_LEN characters (plus a null
 868    terminator).  Ordinarily a variable has at most one short
 869    name, but very long string variables (longer than 255 bytes)
 870    may have more.  A variable might not have any short name at
 871    all if it hasn't been saved to or read from a system or
 872    portable file. */
 873 size_t
 874 var_get_short_name_cnt (const struct variable *var)
 875 {
 876   return var->short_name_cnt;
 877 }
 878
 879 /* Returns VAR's short name with the given IDX, if it has one
 880    with that index, or a null pointer otherwise.  Short names may
 881    be sparse: even if IDX is less than the number of short names
 882    in VAR, this function may return a null pointer. */
 883 const char *
 884 var_get_short_name (const struct variable *var, size_t idx)
 885 {
 886   return idx < var->short_name_cnt ? var->short_names[idx] : NULL;
 887 }
 888
 889 /* Sets VAR's short name with the given IDX to SHORT_NAME,
 890    truncating it to SHORT_NAME_LEN characters and converting it
 891    to uppercase in the process.  Specifying a null pointer for
 892    SHORT_NAME clears the specified short name. */
 893 void
 894 var_set_short_name (struct variable *var, size_t idx, const char *short_name)
 895 {
 896   assert (var != NULL);
 897   assert (short_name == NULL || var_is_plausible_name (short_name, false));
 898
 899   /* Clear old short name numbered IDX, if any. */
 900   if (idx < var->short_name_cnt)
 901     {
 902       free (var->short_names[idx]);
 903       var->short_names[idx] = NULL;
 904     }
 905
 906   /* Install new short name for IDX. */
 907   if (short_name != NULL)
 908     {
 909       if (idx >= var->short_name_cnt)
 910         {
 911           size_t old_cnt = var->short_name_cnt;
 912           size_t i;
 913           var->short_name_cnt = MAX (idx * 2, 1);
 914           var->short_names = xnrealloc (var->short_names, var->short_name_cnt,
 915                                         sizeof *var->short_names);
 916           for (i = old_cnt; i < var->short_name_cnt; i++)
 917             var->short_names[i] = NULL;
 918         }
 919       var->short_names[idx] = xstrndup (short_name, MAX_SHORT_STRING);
 920       str_uppercase (var->short_names[idx]);
 921     }
 922
 923   dict_var_changed (var);
 924 }
 925
 926 /* Clears V's short names. */
 927 void
 928 var_clear_short_names (struct variable *v)
 929 {
 930   size_t i;
 931
 932   for (i = 0; i < v->short_name_cnt; i++)
 933     free (v->short_names[i]);
 934   free (v->short_names);
 935   v->short_names = NULL;
 936   v->short_name_cnt = 0;
 937 }
 938 \f
 939 /* Relationship with dictionary. */
 940
 941 /* Returns V's index within its dictionary, the value
 942    for which "dict_get_var (dict, index)" will return V.
 943    V must be in a dictionary. */
 944 size_t
 945 var_get_dict_index (const struct variable *v)
 946 {
 947   assert (v->vardict.dict_index != -1);
 948   return v->vardict.dict_index;
 949 }
 950
 951 /* Returns V's index within the case represented by its
 952    dictionary, that is, the value for which "case_data_idx (case,
 953    index)" will return the data for V in that case.
 954    V must be in a dictionary. */
 955 size_t
 956 var_get_case_index (const struct variable *v)
 957 {
 958   assert (v->vardict.case_index != -1);
 959   return v->vardict.case_index;
 960 }
 961 \f
 962 /* Returns V's auxiliary data, or a null pointer if none has been
 963    attached. */
 964 void *
 965 var_get_aux (const struct variable *v)
 966 {
 967   return v->aux;
 968 }
 969
 970 /* Assign auxiliary data AUX to variable V, which must not
 971    already have auxiliary data.  Before V's auxiliary data is
 972    cleared, AUX_DTOR(V) will be called.  (var_dtor_free, below,
 973    may be appropriate for use as AUX_DTOR.) */
 974 void *
 975 var_attach_aux (const struct variable *v_,
 976                 void *aux, void (*aux_dtor) (struct variable *))
 977 {
 978   struct variable *v = (struct variable *) v_ ; /* cast away const  */
 979   assert (v->aux == NULL);
 980   assert (aux != NULL);
 981   v->aux = aux;
 982   v->aux_dtor = aux_dtor;
 983   return aux;
 984 }
 985
 986 /* Remove auxiliary data, if any, from V, and return it, without
 987    calling any associated destructor. */
 988 void *
 989 var_detach_aux (struct variable *v)
 990 {
 991   void *aux = v->aux;
 992   assert (aux != NULL);
 993   v->aux = NULL;
 994   return aux;
 995 }
 996
 997 /* Clears auxiliary data, if any, from V, and calls any
 998    associated destructor. */
 999 void
1000 var_clear_aux (struct variable *v)
1001 {
1002   assert (v != NULL);
1003   if (v->aux != NULL)
1004     {
1005       if (v->aux_dtor != NULL)
1006         v->aux_dtor (v);
1007       v->aux = NULL;
1008     }
1009 }
1010
1011 /* This function is appropriate for use an auxiliary data
1012    destructor (passed as AUX_DTOR to var_attach_aux()) for the
1013    case where the auxiliary data should be passed to free(). */
1014 void
1015 var_dtor_free (struct variable *v)
1016 {
1017   free (v->aux);
1018 }
1019 \f
1020 /* Observed categorical values. */
1021
1022 /* Returns V's observed categorical values,
1023    which V must have. */
1024 struct cat_vals *
1025 var_get_obs_vals (const struct variable *v)
1026 {
1027   assert (v->obs_vals != NULL);
1028   return v->obs_vals;
1029 }
1030
1031 /* Sets V's observed categorical values to CAT_VALS.
1032    V becomes the owner of CAT_VALS. */
1033 void
1034 var_set_obs_vals (const struct variable *v_, struct cat_vals *cat_vals)
1035 {
1036   struct variable *v = (struct variable *) v_ ; /* cast away const */
1037   cat_stored_values_destroy (v->obs_vals);
1038   v->obs_vals = cat_vals;
1039 }
1040
1041 /* Returns true if V has observed categorical values,
1042    false otherwise. */
1043 bool
1044 var_has_obs_vals (const struct variable *v)
1045 {
1046   return v->obs_vals != NULL;
1047 }
1048 \f
1049 /* Returns variable V's attribute set.  The caller may examine or
1050    modify the attribute set, but must not destroy it.  Destroying
1051    V, or calling var_set_attributes() on V, will also destroy its
1052    attribute set. */
1053 struct attrset *
1054 var_get_attributes (const struct variable *v)
1055 {
1056   return (struct attrset *) &v->attributes;
1057 }
1058
1059 /* Replaces variable V's attributes set by a copy of ATTRS. */
1060 void
1061 var_set_attributes (struct variable *v, const struct attrset *attrs)
1062 {
1063   attrset_destroy (&v->attributes);
1064   attrset_clone (&v->attributes, attrs);
1065 }
1066
1067 /* Returns true if V has any custom attributes, false if it has none. */
1068 bool
1069 var_has_attributes (const struct variable *v)
1070 {
1071   return attrset_count (&v->attributes) > 0;
1072 }
1073 \f
1074 /* Returns V's vardict structure. */
1075 const struct vardict_info *
1076 var_get_vardict (const struct variable *v)
1077 {
1078   assert (var_has_vardict (v));
1079   return &v->vardict;
1080 }
1081
1082 /* Sets V's vardict data to VARDICT. */
1083 void
1084 var_set_vardict (struct variable *v, const struct vardict_info *vardict)
1085 {
1086   assert (vardict->dict_index >= 0);
1087   assert (vardict->case_index >= 0);
1088   v->vardict = *vardict;
1089 }
1090
1091 /* Returns true if V has vardict data. */
1092 bool
1093 var_has_vardict (const struct variable *v)
1094 {
1095   return v->vardict.dict_index != -1;
1096 }
1097
1098 /* Clears V's vardict data. */
1099 void
1100 var_clear_vardict (struct variable *v)
1101 {
1102   v->vardict.dict_index = v->vardict.case_index = -1;
1103 }