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