src/data/variable.c

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