src/data/variable.c

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