src/data/value-labels.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
  22 #include "value-labels.h"
  23
  24 #include <stdlib.h>
  25
  26 #include <data/data-out.h>
  27 #include <data/variable.h>
  28 #include <libpspp/alloc.h>
  29 #include <libpspp/compiler.h>
  30 #include <libpspp/hash.h>
  31 #include <libpspp/message.h>
  32 #include <libpspp/str.h>
  33
  34 static hsh_compare_func compare_int_val_lab;
  35 static hsh_hash_func hash_int_val_lab;
  36 static hsh_free_func free_int_val_lab;
  37
  38 struct atom;
  39 static struct atom *atom_create (const char *string);
  40 static void atom_destroy (struct atom *);
  41 static char *atom_to_string (const struct atom *);
  42
  43 /* A set of value labels. */
  44 struct val_labs
  45   {
  46     int width;                  /* 0=numeric, otherwise string width. */
  47     struct hsh_table *labels;   /* Hash table of `struct int_val_lab's. */
  48   };
  49
  50 /* Creates and returns a new, empty set of value labels with the
  51    given WIDTH.  To actually add any value labels, WIDTH must be
  52    a numeric or short string width. */
  53 struct val_labs *
  54 val_labs_create (int width)
  55 {
  56   struct val_labs *vls;
  57
  58   assert (width >= 0);
  59
  60   vls = xmalloc (sizeof *vls);
  61   vls->width = width;
  62   vls->labels = NULL;
  63   return vls;
  64 }
  65
  66 /* Creates and returns a new set of value labels identical to
  67    VLS. */
  68 struct val_labs *
  69 val_labs_copy (const struct val_labs *vls)
  70 {
  71   struct val_labs *copy;
  72   struct val_labs_iterator *i;
  73   struct val_lab *vl;
  74
  75   assert (vls != NULL);
  76
  77   copy = val_labs_create (vls->width);
  78   for (vl = val_labs_first (vls, &i); vl != NULL;
  79        vl = val_labs_next (vls, &i))
  80     val_labs_add (copy, vl->value, vl->label);
  81   return copy;
  82 }
  83
  84 /* Determines whether VLS's width can be changed to NEW_WIDTH.
  85    Numeric widths cannot be changed at all.
  86    Strings can be widened.  They can be shortened only if the
  87    characters that will be truncated are spaces. */
  88 bool
  89 val_labs_can_set_width (const struct val_labs *vls, int new_width)
  90 {
  91   assert ((vls->width == 0) == (new_width == 0));
  92
  93   if (vls->width == 0)
  94     return new_width == 0;
  95   else if (new_width < vls->width)
  96     {
  97       struct val_labs_iterator *i;
  98       struct val_lab *lab;
  99
 100       for (lab = val_labs_first (vls, &i); lab != NULL;
 101            lab = val_labs_next (vls, &i))
 102         {
 103           int j;
 104
 105           /* We can shorten the value labels only if all the
 106              truncated characters are blanks. */
 107           for (j = vls->width; j < new_width; j++)
 108             if (lab->value.s[j] != ' ')
 109               {
 110                 val_labs_done (&i);
 111                 return false;
 112               }
 113         }
 114       return true;
 115     }
 116   else
 117     return true;
 118 }
 119
 120 /* Changes the width of VLS to NEW_WIDTH.  If VLS is numeric,
 121    NEW_WIDTH must be 0, otherwise it must be within the range
 122    1...MAX_SHORT_STRING inclusive. */
 123 void
 124 val_labs_set_width (struct val_labs *vls, int new_width)
 125 {
 126   assert (val_labs_can_set_width (vls, new_width));
 127
 128   vls->width = new_width;
 129   if (new_width > MAX_SHORT_STRING)
 130     val_labs_clear (vls);
 131 }
 132
 133 /* Destroys VLS. */
 134 void
 135 val_labs_destroy (struct val_labs *vls)
 136 {
 137   if (vls != NULL)
 138     {
 139       hsh_destroy (vls->labels);
 140       free (vls);
 141     }
 142 }
 143
 144 /* Removes all the value labels from VLS. */
 145 void
 146 val_labs_clear (struct val_labs *vls)
 147 {
 148   assert (vls != NULL);
 149
 150   hsh_destroy (vls->labels);
 151   vls->labels = NULL;
 152 }
 153
 154 /* Returns the number of value labels in VLS. */
 155 size_t
 156 val_labs_count (const struct val_labs *vls)
 157 {
 158   assert (vls != NULL);
 159
 160   if (vls->labels == NULL)
 161     return 0;
 162   else
 163     return hsh_count (vls->labels);
 164 }
 165 \f
 166 /* One value label in internal format. */
 167 struct int_val_lab
 168   {
 169     union value value;          /* The value being labeled. */
 170     struct atom *label;         /* A ref-counted string. */
 171   };
 172
 173 /* Creates and returns an int_val_lab based on VALUE and
 174    LABEL. */
 175 static struct int_val_lab *
 176 create_int_val_lab (struct val_labs *vls, union value value, const char *label)
 177 {
 178   struct int_val_lab *ivl;
 179
 180   assert (label != NULL);
 181   assert (vls->width <= MAX_SHORT_STRING);
 182
 183   ivl = xmalloc (sizeof *ivl);
 184   ivl->value = value;
 185   if (vls->width > 0)
 186     memset (ivl->value.s + vls->width, ' ', MAX_SHORT_STRING - vls->width);
 187   ivl->label = atom_create (label);
 188
 189   return ivl;
 190 }
 191
 192 /* If VLS does not already contain a value label for VALUE, adds
 193    LABEL for it and returns true.  Otherwise, returns false.
 194    Behavior is undefined if VLS's width is greater than
 195    MAX_SHORT_STRING. */
 196 bool
 197 val_labs_add (struct val_labs *vls, union value value, const char *label)
 198 {
 199   struct int_val_lab *ivl;
 200   void **vlpp;
 201
 202   assert (vls != NULL);
 203   assert (vls->width <= MAX_SHORT_STRING);
 204   assert (label != NULL);
 205
 206   if (vls->labels == NULL)
 207     vls->labels = hsh_create (8, compare_int_val_lab, hash_int_val_lab,
 208                               free_int_val_lab, vls);
 209
 210   ivl = create_int_val_lab (vls, value, label);
 211   vlpp = hsh_probe (vls->labels, ivl);
 212   if (*vlpp == NULL)
 213     {
 214       *vlpp = ivl;
 215       return true;
 216     }
 217   free_int_val_lab (ivl, vls);
 218   return false;
 219 }
 220
 221 /* Sets LABEL as the value label for VALUE in VLS.  Returns false
 222    if there wasn't already a value label for VALUE, or true if
 223    there was.  Behavior is undefined if VLS's width is greater
 224    than MAX_SHORT_STRING. */
 225 bool
 226 val_labs_replace (struct val_labs *vls, union value value, const char *label)
 227 {
 228   struct int_val_lab *ivl;
 229
 230   assert (vls != NULL);
 231   assert (vls->width <= MAX_SHORT_STRING);
 232   assert (label != NULL);
 233
 234   if (vls->labels == NULL)
 235     {
 236       val_labs_add (vls, value, label);
 237       return false;
 238     }
 239
 240   ivl = hsh_replace (vls->labels, create_int_val_lab (vls, value, label));
 241   if (ivl == NULL)
 242     return false;
 243   else
 244     {
 245       free_int_val_lab (ivl, vls);
 246       return true;
 247     }
 248 }
 249
 250 /* Removes any value label for VALUE within VLS.  Returns true
 251    if a value label was removed. Behavior is undefined if VLS's
 252    width is greater than MAX_SHORT_STRING. */
 253 bool
 254 val_labs_remove (struct val_labs *vls, union value value)
 255 {
 256   assert (vls != NULL);
 257   assert (vls->width <= MAX_SHORT_STRING);
 258
 259   if (vls->labels != NULL)
 260     {
 261       struct int_val_lab *ivl = create_int_val_lab (vls, value, "");
 262       int deleted = hsh_delete (vls->labels, ivl);
 263       free (ivl);
 264       return deleted;
 265     }
 266   else
 267     return false;
 268 }
 269
 270 /* Searches VLS for a value label for VALUE.  If successful,
 271    returns the label; otherwise, returns a null pointer.  If
 272    VLS's width is greater than MAX_SHORT_STRING, always returns a
 273    null pointer. */
 274 char *
 275 val_labs_find (const struct val_labs *vls, union value value)
 276 {
 277   assert (vls != NULL);
 278
 279   if (vls->width > MAX_SHORT_STRING)
 280     return NULL;
 281
 282   if (vls->labels != NULL)
 283     {
 284       struct int_val_lab ivl, *vlp;
 285
 286       ivl.value = value;
 287       vlp = hsh_find (vls->labels, &ivl);
 288       if (vlp != NULL)
 289         return atom_to_string (vlp->label);
 290     }
 291   return NULL;
 292 }
 293 \f
 294 /* A value labels iterator. */
 295 struct val_labs_iterator
 296   {
 297     void **labels;              /* The labels, in order. */
 298     void **lp;                  /* Current label. */
 299     struct val_lab vl;          /* Structure presented to caller. */
 300   };
 301
 302 /* Sets up *IP for iterating through the value labels in VLS in
 303    no particular order.  Returns the first value label or a null
 304    pointer if VLS is empty.  If the return value is non-null,
 305    then val_labs_next() may be used to continue iterating or
 306    val_labs_done() to free up the iterator.  Otherwise, neither
 307    function may be called for *IP. */
 308 struct val_lab *
 309 val_labs_first (const struct val_labs *vls, struct val_labs_iterator **ip)
 310 {
 311   struct val_labs_iterator *i;
 312
 313   assert (vls != NULL);
 314   assert (ip != NULL);
 315
 316   if (vls->labels == NULL || vls->width > MAX_SHORT_STRING)
 317     return NULL;
 318
 319   i = *ip = xmalloc (sizeof *i);
 320   i->labels = hsh_data_copy (vls->labels);
 321   i->lp = i->labels;
 322   return val_labs_next (vls, ip);
 323 }
 324
 325 /* Sets up *IP for iterating through the value labels in VLS in
 326    sorted order of values.  Returns the first value label or a
 327    null pointer if VLS is empty.  If the return value is
 328    non-null, then val_labs_next() may be used to continue
 329    iterating or val_labs_done() to free up the iterator.
 330    Otherwise, neither function may be called for *IP. */
 331 struct val_lab *
 332 val_labs_first_sorted (const struct val_labs *vls,
 333                        struct val_labs_iterator **ip)
 334 {
 335   struct val_labs_iterator *i;
 336
 337   assert (vls != NULL);
 338   assert (ip != NULL);
 339
 340   if (vls->labels == NULL || vls->width > MAX_SHORT_STRING)
 341     return NULL;
 342
 343   i = *ip = xmalloc (sizeof *i);
 344   i->lp = i->labels = hsh_sort_copy (vls->labels);
 345   return val_labs_next (vls, ip);
 346 }
 347
 348 /* Returns the next value label in an iteration begun by
 349    val_labs_first() or val_labs_first_sorted().  If the return
 350    value is non-null, then val_labs_next() may be used to
 351    continue iterating or val_labs_done() to free up the iterator.
 352    Otherwise, neither function may be called for *IP. */
 353 struct val_lab *
 354 val_labs_next (const struct val_labs *vls, struct val_labs_iterator **ip)
 355 {
 356   struct val_labs_iterator *i;
 357   struct int_val_lab *ivl;
 358
 359   assert (vls != NULL);
 360   assert (vls->width <= MAX_SHORT_STRING);
 361   assert (ip != NULL);
 362   assert (*ip != NULL);
 363
 364   i = *ip;
 365   ivl = *i->lp++;
 366   if (ivl != NULL)
 367     {
 368       i->vl.value = ivl->value;
 369       i->vl.label = atom_to_string (ivl->label);
 370       return &i->vl;
 371     }
 372   else
 373     {
 374       free (i->labels);
 375       free (i);
 376       *ip = NULL;
 377       return NULL;
 378     }
 379 }
 380
 381 /* Discards the state for an incomplete iteration begun by
 382    val_labs_first() or val_labs_first_sorted(). */
 383 void
 384 val_labs_done (struct val_labs_iterator **ip)
 385 {
 386   struct val_labs_iterator *i;
 387
 388   assert (ip != NULL);
 389   assert (*ip != NULL);
 390
 391   i = *ip;
 392   free (i->labels);
 393   free (i);
 394   *ip = NULL;
 395 }
 396 \f
 397 /* Compares two value labels and returns a strcmp()-type result. */
 398 int
 399 compare_int_val_lab (const void *a_, const void *b_, const void *vls_)
 400 {
 401   const struct int_val_lab *a = a_;
 402   const struct int_val_lab *b = b_;
 403   const struct val_labs *vls = vls_;
 404
 405   if (vls->width == 0)
 406     return a->value.f < b->value.f ? -1 : a->value.f > b->value.f;
 407   else
 408     return memcmp (a->value.s, b->value.s, vls->width);
 409 }
 410
 411 /* Hash a value label. */
 412 unsigned
 413 hash_int_val_lab (const void *vl_, const void *vls_)
 414 {
 415   const struct int_val_lab *vl = vl_;
 416   const struct val_labs *vls = vls_;
 417
 418   if (vls->width == 0)
 419     return hsh_hash_double (vl->value.f);
 420   else
 421     return hsh_hash_bytes (vl->value.s, sizeof vl->value.s);
 422 }
 423
 424 /* Free a value label. */
 425 void
 426 free_int_val_lab (void *vl_, const void *vls_ UNUSED)
 427 {
 428   struct int_val_lab *vl = vl_;
 429
 430   atom_destroy (vl->label);
 431   free (vl);
 432 }
 433 \f
 434 /* Atoms. */
 435
 436 /* An atom. */
 437 struct atom
 438   {
 439     char *string;               /* String value. */
 440     unsigned ref_count;         /* Number of references. */
 441   };
 442
 443 static hsh_compare_func compare_atoms;
 444 static hsh_hash_func hash_atom;
 445 static hsh_free_func free_atom;
 446
 447 /* Hash table of atoms. */
 448 static struct hsh_table *atoms;
 449
 450 /* Creates and returns an atom for STRING. */
 451 static struct atom *
 452 atom_create (const char *string)
 453 {
 454   struct atom a;
 455   void **app;
 456
 457   assert (string != NULL);
 458
 459   if (atoms == NULL)
 460     atoms = hsh_create (8, compare_atoms, hash_atom, free_atom, NULL);
 461
 462   a.string = (char *) string;
 463   app = hsh_probe (atoms, &a);
 464   if (*app != NULL)
 465     {
 466       struct atom *ap = *app;
 467       ap->ref_count++;
 468       return ap;
 469     }
 470   else
 471     {
 472       struct atom *ap = xmalloc (sizeof *ap);
 473       ap->string = xstrdup (string);
 474       ap->ref_count = 1;
 475       *app = ap;
 476       return ap;
 477     }
 478 }
 479
 480 /* Destroys ATOM. */
 481 static void
 482 atom_destroy (struct atom *atom)
 483 {
 484   if (atom != NULL)
 485     {
 486       assert (atom->ref_count > 0);
 487       atom->ref_count--;
 488       if (atom->ref_count == 0)
 489         hsh_force_delete (atoms, atom);
 490     }
 491 }
 492
 493 /* Returns the string associated with ATOM. */
 494 static  char *
 495 atom_to_string (const struct atom *atom)
 496 {
 497   assert (atom != NULL);
 498
 499   return atom->string;
 500 }
 501
 502 /* A hsh_compare_func that compares A and B. */
 503 static int
 504 compare_atoms (const void *a_, const void *b_, const void *aux UNUSED)
 505 {
 506   const struct atom *a = a_;
 507   const struct atom *b = b_;
 508
 509   return strcmp (a->string, b->string);
 510 }
 511
 512 /* A hsh_hash_func that hashes ATOM. */
 513 static unsigned
 514 hash_atom (const void *atom_, const void *aux UNUSED)
 515 {
 516   const struct atom *atom = atom_;
 517
 518   return hsh_hash_string (atom->string);
 519 }
 520
 521 /* A hsh_free_func that destroys ATOM. */
 522 static void
 523 free_atom (void *atom_, const void *aux UNUSED)
 524 {
 525   struct atom *atom = atom_;
 526
 527   free (atom->string);
 528   free (atom);
 529 }
 530
 531
 532 /* Get a string representing the value.
 533    That is, if it has a label, then return that label,
 534    otherwise, if the value is alpha, then return the string for it,
 535    else format it and return the formatted string
 536 */
 537 const char *
 538 value_to_string (const union value *val, const struct variable *var)
 539 {
 540   char *s;
 541
 542   assert (val != NULL);
 543   assert (var != NULL);
 544
 545   s = val_labs_find (var->val_labs, *val);
 546   if (s == NULL)
 547     {
 548       static char buf[MAX_STRING + 1];
 549       data_out (val, &var->print, buf);
 550       buf[var->print.w] = '\0';
 551       s = buf;
 552     }
 553
 554   return s;
 555 }