list.c

   1 const char list_rcs[] = "$Id: list.c,v 1.11 2001/10/23 21:21:03 jongfoster Exp $";
   2 /*********************************************************************
   3  *
   4  * File        :  $Source: /cvsroot/ijbswa/current/list.c,v $
   5  *
   6  * Purpose     :  Declares functions to handle lists.
   7  *                Functions declared include:
   8  *                   `destroy_list', `enlist' and `list_to_text'
   9  *
  10  * Copyright   :  Written by and Copyright (C) 2001 the SourceForge
  11  *                IJBSWA team.  http://ijbswa.sourceforge.net
  12  *
  13  *                Based on the Internet Junkbuster originally written
  14  *                by and Copyright (C) 1997 Anonymous Coders and
  15  *                Junkbusters Corporation.  http://www.junkbusters.com
  16  *
  17  *                This program is free software; you can redistribute it
  18  *                and/or modify it under the terms of the GNU General
  19  *                Public License as published by the Free Software
  20  *                Foundation; either version 2 of the License, or (at
  21  *                your option) any later version.
  22  *
  23  *                This program is distributed in the hope that it will
  24  *                be useful, but WITHOUT ANY WARRANTY; without even the
  25  *                implied warranty of MERCHANTABILITY or FITNESS FOR A
  26  *                PARTICULAR PURPOSE.  See the GNU General Public
  27  *                License for more details.
  28  *
  29  *                The GNU General Public License should be included with
  30  *                this file.  If not, you can view it at
  31  *                http://www.gnu.org/copyleft/gpl.html
  32  *                or write to the Free Software Foundation, Inc., 59
  33  *                Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  34  *
  35  * Revisions   :
  36  *    $Log: list.c,v $
  37  *    Revision 1.11  2001/10/23 21:21:03  jongfoster
  38  *    New error handling - error codes are now jb_errs, not ints.
  39  *    Changed the way map() handles out-of-memory, to dramatically
  40  *    reduce the amount of error-checking clutter needed.
  41  *
  42  *    Revision 1.10  2001/09/16 17:30:24  jongfoster
  43  *    Fixing a compiler warning.
  44  *
  45  *    Revision 1.9  2001/09/16 13:20:29  jongfoster
  46  *    Rewrite of list library.  Now has seperate header and list_entry
  47  *    structures.  Also added a large sprinking of assert()s to the list
  48  *    code.
  49  *
  50  *    Revision 1.8  2001/08/07 14:00:20  oes
  51  *    Fixed comment
  52  *
  53  *    Revision 1.7  2001/08/05 16:06:20  jongfoster
  54  *    Modifiying "struct map" so that there are now separate header and
  55  *    "map_entry" structures.  This means that functions which modify a
  56  *    map no longer need to return a pointer to the modified map.
  57  *    Also, it no longer reverses the order of the entries (which may be
  58  *    important with some advanced template substitutions).
  59  *
  60  *    Revision 1.6  2001/07/31 14:44:51  oes
  61  *    list_to_text() now appends empty line at end
  62  *
  63  *    Revision 1.5  2001/06/29 21:45:41  oes
  64  *    Indentation, CRLF->LF, Tab-> Space
  65  *
  66  *    Revision 1.4  2001/06/29 13:30:22  oes
  67  *    - Added Convenience function enlist_unique_header(),
  68  *      which takes the Header name and value as separate
  69  *      arguments and thus saves the pain of sprintf()ing
  70  *      and determining the Header name length to enlist_unique
  71  *    - Improved comments
  72  *    - Removed logentry from cancelled commit
  73  *
  74  *    Revision 1.3  2001/06/03 19:12:24  oes
  75  *    functions for new struct map, extended enlist_unique
  76  *
  77  *    Revision 1.2  2001/06/01 18:49:17  jongfoster
  78  *    Replaced "list_share" with "list" - the tiny memory gain was not
  79  *    worth the extra complexity.
  80  *
  81  *    Revision 1.1  2001/05/31 21:11:53  jongfoster
  82  *    - Moved linked list support to new "list.c" file.
  83  *      Structure definitions are still in project.h,
  84  *      function prototypes are now in "list.h".
  85  *    - Added support for "struct list_share", which is identical
  86  *      to "struct list" except it saves memory by not duplicating
  87  *      the strings.  Obviously, this only works if there is some
  88  *      other way of managing the memory used by the strings.
  89  *      (These list_share lists are used for lists which last
  90  *      for only 1 request, and where all the list entries are
  91  *      just coming directly from entries in the actionsfile.)
  92  *      Note that you still need to destroy list_share lists
  93  *      properly to free the nodes - it's only the strings
  94  *      which are shared.
  95  *
  96  *
  97  *********************************************************************/
  98 \f
  99
 100 #include "config.h"
 101
 102 #ifndef _WIN32
 103 /* FIXME: The following headers are not needed for Win32.  Are they
 104  * needed on other platforms?
 105  */
 106 #include <stdio.h>
 107 #include <sys/types.h>
 108 #include <stdlib.h>
 109 #include <ctype.h>
 110 #endif
 111 #include <string.h>
 112
 113 #if !defined(_WIN32) && !defined(__OS2__)
 114 #include <unistd.h>
 115 #endif
 116
 117 #include <assert.h>
 118
 119 #include "project.h"
 120 #include "list.h"
 121 #include "miscutil.h"
 122
 123 const char list_h_rcs[] = LIST_H_VERSION;
 124
 125
 126 static int list_is_valid (const struct list *the_list);
 127
 128
 129 /*********************************************************************
 130  *
 131  * Function    :  list_init
 132  *
 133  * Description :  Create a new, empty list in user-allocated memory.
 134  *                Caller should allocate a "struct list" variable,
 135  *                then pass it to this function.
 136  *                (Implementation note:  Rather than calling this
 137  *                function, you can also just memset the memory to
 138  *                zero, e.g. if you have a larger structure you
 139  *                want to initialize quickly.  However, that isn't
 140  *                really good design.)
 141  *
 142  * Parameters  :
 143  *          1  :  the_list = pointer to list
 144  *
 145  * Returns     :  N/A
 146  *
 147  *********************************************************************/
 148 void init_list(struct list *the_list)
 149 {
 150    memset(the_list, '\0', sizeof(*the_list));
 151 }
 152
 153
 154 /*********************************************************************
 155  *
 156  * Function    :  destroy_list
 157  *
 158  * Description :  Destroy a string list (opposite of list_init).
 159  *                On return, the memory used by the list entries has
 160  *                been freed, but not the memory used by the_list
 161  *                itself.  You should not re-use the_list without
 162  *                calling list_init().
 163  *
 164  *                (Implementation note:  You *can* reuse the_list
 165  *                without calling list_init(), but please don't.
 166  *                If you want to remove all entries from a list
 167  *                and still have a usable list, then use
 168  *                list_remove_all().)
 169  *
 170  * Parameters  :
 171  *          1  :  the_list = pointer to list
 172  *
 173  * Returns     :  N/A
 174  *
 175  *********************************************************************/
 176 void destroy_list (struct list *the_list)
 177 {
 178    struct list_entry *cur_entry, *next_entry;
 179
 180    assert(the_list);
 181
 182    for (cur_entry = the_list->first; cur_entry ; cur_entry = next_entry)
 183    {
 184       next_entry = cur_entry->next;
 185       freez(cur_entry->str);
 186       free(cur_entry);
 187    }
 188
 189    the_list->first = NULL;
 190    the_list->last = NULL;
 191 }
 192
 193
 194 /*********************************************************************
 195  *
 196  * Function    :  list_is_valid
 197  *
 198  * Description :  Check that a string list is valid.  The intended
 199  *                usage is "assert(list_is_valid(the_list))".
 200  *                Currently this checks that "the_list->last"
 201  *                is correct, and that the list dosn't contain
 202  *                circular references.  It is likely to crash if
 203  *                it's passed complete garbage.
 204  *
 205  * Parameters  :
 206  *          1  :  the_list = pointer to list.  Must be non-null.
 207  *
 208  * Returns     :  1 if list is valid, 0 otherwise.
 209  *
 210  *********************************************************************/
 211 static int list_is_valid (const struct list *the_list)
 212 {
 213    /*
 214     * If you don't want this check, just change the line below
 215     * from "#if 1" to "#if 0".
 216     */
 217 #if 1
 218    const struct list_entry *cur_entry;
 219    const struct list_entry *last_entry = NULL;
 220    int length = 0;
 221
 222    assert(the_list);
 223
 224    for (cur_entry = the_list->first; cur_entry ; cur_entry = cur_entry->next)
 225    {
 226       last_entry = cur_entry;
 227
 228       if (cur_entry->str)
 229       {
 230          /*
 231           * Just check that this string can be accessed - i.e. it's a valid
 232           * pointer.
 233           */
 234          strlen(cur_entry->str);
 235       }
 236
 237       /*
 238        * Check for looping back to first
 239        */
 240       if ((length != 0) && (cur_entry == the_list->first))
 241       {
 242          return 0;
 243       }
 244
 245       /*
 246        * Arbitrarily limit length to prevent infinite loops.
 247        */
 248       if (++length > 1000)
 249       {
 250          return 0;
 251       }
 252
 253       /*
 254        * Check this isn't marked as the last entry, unless of course it's
 255        * *really* the last entry.
 256        */
 257       if ((the_list->last == cur_entry) && (cur_entry->next != NULL))
 258       {
 259          /* This is the last entry, but there's data after it !!?? */
 260          return 0;
 261       }
 262    }
 263
 264    return (the_list->last == last_entry);
 265 #else
 266    return 1;
 267 #endif
 268 }
 269
 270 /*********************************************************************
 271  *
 272  * Function    :  enlist
 273  *
 274  * Description :  Append a string into a specified string list.
 275  *
 276  * Parameters  :
 277  *          1  :  the_list = pointer to list
 278  *          2  :  str = string to add to the list (maybe NULL)
 279  *
 280  * Returns     :  JB_ERR_OK on success
 281  *                JB_ERR_MEMORY on out-of-memory error.
 282  *                On error, the_list will be unchanged.
 283  *
 284  *********************************************************************/
 285 jb_err enlist(struct list *the_list, const char *str)
 286 {
 287    struct list_entry *cur;
 288
 289    assert(the_list);
 290    assert(list_is_valid(the_list));
 291
 292    if (NULL == (cur = (struct list_entry *)zalloc(sizeof(*cur))))
 293    {
 294       return JB_ERR_MEMORY;
 295    }
 296
 297    if (str)
 298    {
 299       if (NULL == (cur->str = strdup(str)))
 300       {
 301          free(cur);
 302          return JB_ERR_MEMORY;
 303       }
 304    }
 305    /* else { cur->str = NULL; }  - implied by zalloc */
 306
 307    /* cur->next = NULL;  - implied by zalloc */
 308
 309    if (the_list->last)
 310    {
 311       the_list->last->next = cur;
 312       the_list->last = cur;
 313    }
 314    else
 315    {
 316       the_list->first = cur;
 317       the_list->last = cur;
 318    }
 319
 320    assert(list_is_valid(the_list));
 321    return JB_ERR_OK;
 322 }
 323
 324
 325 /*********************************************************************
 326  *
 327  * Function    :  enlist_first
 328  *
 329  * Description :  Append a string as first element into a specified
 330  *                string list.
 331  *
 332  * Parameters  :
 333  *          1  :  the_list = pointer to list
 334  *          2  :  str = string to add to the list (maybe NULL)
 335  *
 336  * Returns     :  JB_ERR_OK on success
 337  *                JB_ERR_MEMORY on out-of-memory error.
 338  *                On error, the_list will be unchanged.
 339  *
 340  *********************************************************************/
 341 jb_err enlist_first(struct list *the_list, const char *str)
 342 {
 343    struct list_entry *cur;
 344
 345    assert(the_list);
 346    assert(list_is_valid(the_list));
 347
 348    if (NULL == (cur = (struct list_entry *)zalloc(sizeof(*cur))))
 349    {
 350       return JB_ERR_MEMORY;
 351    }
 352
 353    if (str)
 354    {
 355       if (NULL == (cur->str = strdup(str)))
 356       {
 357          free(cur);
 358          return JB_ERR_MEMORY;
 359       }
 360    }
 361    /* else { cur->str = NULL; }  - implied by zalloc */
 362
 363    cur->next = the_list->first;
 364
 365    the_list->first = cur;
 366    if (the_list->last == NULL)
 367    {
 368       the_list->last = cur;
 369    }
 370
 371    assert(list_is_valid(the_list));
 372    return JB_ERR_OK;
 373 }
 374
 375
 376 /*********************************************************************
 377  *
 378  * Function    :  enlist_unique
 379  *
 380  * Description :  Append a string into a specified string list,
 381  *                if & only if it's not there already.
 382  *                If the num_significant_chars argument is nonzero,
 383  *                only compare up to the nth character.
 384  *
 385  * Parameters  :
 386  *          1  :  the_list = pointer to list
 387  *          2  :  str = string to add to the list
 388  *          3  :  num_significant_chars = number of chars to use
 389  *                for uniqueness test, or 0 to require an exact match.
 390  *
 391  * Returns     :  JB_ERR_OK on success
 392  *                JB_ERR_MEMORY on out-of-memory error.
 393  *                On error, the_list will be unchanged.
 394  *                "Success" does not indicate whether or not the
 395  *                item was already in the list.
 396  *
 397  *********************************************************************/
 398 jb_err enlist_unique(struct list *the_list, const char *str,
 399                      int num_significant_chars)
 400 {
 401    struct list_entry *cur_entry;
 402
 403    assert(the_list);
 404    assert(list_is_valid(the_list));
 405    assert(str);
 406    assert(num_significant_chars >= 0);
 407    assert((size_t)num_significant_chars <= strlen(str));
 408
 409    if (num_significant_chars > 0)
 410    {
 411       for (cur_entry = the_list->first; cur_entry != NULL; cur_entry = cur_entry->next)
 412       {
 413          if ( (cur_entry->str != NULL)
 414            && (0 == strncmp(str, cur_entry->str, num_significant_chars)))
 415          {
 416             /* Already there */
 417             return JB_ERR_OK;
 418          }
 419       }
 420    }
 421    else
 422    {
 423       /* Test whole string */
 424       for (cur_entry = the_list->first; cur_entry != NULL; cur_entry = cur_entry->next)
 425       {
 426          if ( (cur_entry->str != NULL) && (0 == strcmp(str, cur_entry->str)))
 427          {
 428             /* Already there */
 429             return JB_ERR_OK;
 430          }
 431       }
 432    }
 433
 434    return enlist(the_list, str);
 435 }
 436
 437
 438 /*********************************************************************
 439  *
 440  * Function    :  enlist_unique_header
 441  *
 442  * Description :  Make a HTTP header from the two strings name and value,
 443  *                and append the result into a specified string list,
 444  *                if & only if there isn't already a header with that name.
 445  *
 446  * Parameters  :
 447  *          1  :  the_list = pointer to list
 448  *          2  :  name = HTTP header name (e.g. "Content-type")
 449  *          3  :  value = HTTP header value (e.g. "text/html")
 450  *
 451  * Returns     :  JB_ERR_OK on success
 452  *                JB_ERR_MEMORY on out-of-memory error.
 453  *                On error, the_list will be unchanged.
 454  *                "Success" does not indicate whether or not the
 455  *                header was already in the list.
 456  *
 457  *********************************************************************/
 458 jb_err enlist_unique_header(struct list *the_list, const char *name,
 459                             const char *value)
 460 {
 461    int length;
 462    jb_err result;
 463    char *str;
 464
 465    assert(the_list);
 466    assert(list_is_valid(the_list));
 467    assert(name);
 468    assert(value);
 469
 470    length = strlen(name) + 2;
 471    if (NULL == (str = (char *)malloc(length + strlen(value) + 1)))
 472    {
 473       return JB_ERR_MEMORY;
 474    }
 475    strcpy(str, name);
 476    str[length - 2] = ':';
 477    str[length - 1] = ' ';
 478    strcpy(str + length, value);
 479
 480    result = enlist_unique(the_list, str, length);
 481
 482    free(str);
 483
 484    assert(list_is_valid(the_list));
 485
 486    return result;
 487 }
 488
 489
 490 /*********************************************************************
 491  *
 492  * Function    :  list_remove_all
 493  *
 494  * Description :  Remove all entries from a list.  On return, the_list
 495  *                is a valid, empty list.  Note that this is similar
 496  *                to destroy_list(), but the difference is that this
 497  *                function guarantees that the list structure is still
 498  *                valid after the call.
 499  *
 500  * Parameters  :
 501  *          1  :  the_list = pointer to list
 502  *
 503  * Returns     :  N/A
 504  *
 505  *********************************************************************/
 506 void list_remove_all(struct list *the_list)
 507 {
 508    struct list_entry *cur_entry;
 509    struct list_entry *next_entry;
 510
 511    assert(the_list);
 512    assert(list_is_valid(the_list));
 513
 514    for (cur_entry = the_list->first; cur_entry ; cur_entry = next_entry)
 515    {
 516       next_entry = cur_entry->next;
 517       freez(cur_entry->str);
 518       free(cur_entry);
 519    }
 520
 521    the_list->first = the_list->last = NULL;
 522
 523    assert(list_is_valid(the_list));
 524 }
 525
 526
 527 /*********************************************************************
 528  *
 529  * Function    :  list_to_text
 530  *
 531  * Description :  "Flatten" a string list into 1 long \r\n delimited string,
 532  *                adding an empty line at the end.  NULL entries are ignored.
 533  *                This function does not change the_list.
 534  *
 535  * Parameters  :
 536  *          1  :  the_list = pointer to list
 537  *
 538  * Returns     :  NULL on malloc error, else new long string.
 539  *                Caller must free() it.
 540  *
 541  *********************************************************************/
 542 char *list_to_text(const struct list *the_list)
 543 {
 544    struct list_entry *cur_entry;
 545    char *ret = NULL;
 546    char *s;
 547    int size = 2;
 548
 549    assert(the_list);
 550    assert(list_is_valid(the_list));
 551
 552    for (cur_entry = the_list->first; cur_entry ; cur_entry = cur_entry->next)
 553    {
 554       if (cur_entry->str)
 555       {
 556          size += strlen(cur_entry->str) + 2;
 557       }
 558    }
 559
 560    if ((ret = (char *)malloc(size + 1)) == NULL)
 561    {
 562       return NULL;
 563    }
 564
 565    ret[size] = '\0';
 566
 567    s = ret;
 568
 569    for (cur_entry = the_list->first; cur_entry ; cur_entry = cur_entry->next)
 570    {
 571       if (cur_entry->str)
 572       {
 573          strcpy(s, cur_entry->str);
 574          s += strlen(s);
 575          *s++ = '\r'; *s++ = '\n';
 576       }
 577    }
 578    *s++ = '\r'; *s++ = '\n';
 579
 580    return ret;
 581 }
 582
 583
 584 /*********************************************************************
 585  *
 586  * Function    :  list_remove_item
 587  *
 588  * Description :  Remove a string from a specified string list.
 589  *
 590  * Parameters  :
 591  *          1  :  the_list = pointer to list
 592  *          2  :  str = string to remove from the list - non-NULL
 593  *
 594  * Returns     :  Number of times it was removed.
 595  *
 596  *********************************************************************/
 597 int list_remove_item(struct list *the_list, const char *str)
 598 {
 599    struct list_entry *prev = NULL;
 600    struct list_entry *cur;
 601    struct list_entry *next;
 602    int count = 0;
 603
 604    assert(the_list);
 605    assert(list_is_valid(the_list));
 606    assert(str);
 607
 608    cur = the_list->first;
 609
 610    while (cur != NULL)
 611    {
 612       next = cur->next;
 613
 614       if ((cur->str != NULL) && (0 == strcmp(str, cur->str)))
 615       {
 616          count++;
 617
 618          if (prev != NULL)
 619          {
 620             prev->next = next;
 621          }
 622          else
 623          {
 624             the_list->first = next;
 625          }
 626          free((char *)cur->str);
 627          free(cur);
 628       }
 629       else
 630       {
 631          prev = cur;
 632       }
 633       cur = next;
 634    }
 635
 636    the_list->last = prev;
 637
 638    assert(list_is_valid(the_list));
 639
 640    return count;
 641 }
 642
 643
 644 /*********************************************************************
 645  *
 646  * Function    :  list_remove_list
 647  *
 648  * Description :  Remove all strings in one list from another list.
 649  *                This is currently a brute-force algorithm
 650  *                (it compares every pair of strings).
 651  *
 652  * Parameters  :
 653  *          1  :  dest = list to change
 654  *          2  :  src = list of strings to remove
 655  *
 656  * Returns     :  Total number of strings removed.
 657  *
 658  *********************************************************************/
 659 int list_remove_list(struct list *dest, const struct list *src)
 660 {
 661    struct list_entry *cur;
 662    int count = 0;
 663
 664    assert(src);
 665    assert(dest);
 666    assert(list_is_valid(src));
 667    assert(list_is_valid(dest));
 668
 669    for (cur = src->first; cur != NULL; cur = cur->next)
 670    {
 671       if (cur->str != NULL)
 672       {
 673          count += list_remove_item(dest, cur->str);
 674       }
 675    }
 676
 677    assert(list_is_valid(src));
 678    assert(list_is_valid(dest));
 679
 680    return count;
 681 }
 682
 683
 684 /*********************************************************************
 685  *
 686  * Function    :  list_duplicate
 687  *
 688  * Description :  Copy a string list
 689  *
 690  * Parameters  :
 691  *          1  :  dest = Destination list.  Must be a valid list.
 692  *                       All existing entries will be removed.
 693  *          1  :  src = pointer to source list for copy.
 694  *
 695  * Returns     :  JB_ERR_OK on success
 696  *                JB_ERR_MEMORY on out-of-memory error.
 697  *                On error, dest will be empty.
 698  *
 699  *********************************************************************/
 700 jb_err list_duplicate(struct list *dest, const struct list *src)
 701 {
 702    struct list_entry * cur_src;
 703    struct list_entry * cur_dest;
 704
 705    assert(src);
 706    assert(dest);
 707    assert(list_is_valid(src));
 708    assert(list_is_valid(dest));
 709
 710    list_remove_all(dest);
 711
 712    /* Need to process first entry specially so we can set dest->first */
 713    cur_src = src->first;
 714    if (cur_src)
 715    {
 716       cur_dest = dest->first = (struct list_entry *)zalloc(sizeof(*cur_dest));
 717       if (cur_dest == NULL)
 718       {
 719          destroy_list(dest);
 720
 721          assert(list_is_valid(src));
 722          assert(list_is_valid(dest));
 723
 724          return JB_ERR_MEMORY;
 725       }
 726
 727       if (cur_src->str)
 728       {
 729          cur_dest->str = strdup(cur_src->str);
 730          if (cur_dest->str == NULL)
 731          {
 732             destroy_list(dest);
 733
 734             assert(list_is_valid(src));
 735             assert(list_is_valid(dest));
 736
 737             return JB_ERR_MEMORY;
 738          }
 739       }
 740       /* else { cur_dest->str = NULL; }  - implied by zalloc */
 741
 742       /* Now process the rest */
 743       for (cur_src = cur_src->next; cur_src; cur_src = cur_src->next)
 744       {
 745          cur_dest = cur_dest->next = (struct list_entry *)zalloc(sizeof(*cur_dest));
 746          if (cur_dest == NULL)
 747          {
 748             destroy_list(dest);
 749
 750             assert(list_is_valid(src));
 751             assert(list_is_valid(dest));
 752
 753             return JB_ERR_MEMORY;
 754          }
 755          if (cur_src->str)
 756          {
 757             cur_dest->str = strdup(cur_src->str);
 758             if (cur_dest->str == NULL)
 759             {
 760                destroy_list(dest);
 761
 762                assert(list_is_valid(src));
 763                assert(list_is_valid(dest));
 764
 765                return JB_ERR_MEMORY;
 766             }
 767          }
 768          /* else { cur_dest->str = NULL; }  - implied by zalloc */
 769       }
 770
 771       dest->last = cur_dest;
 772    }
 773
 774    assert(list_is_valid(src));
 775    assert(list_is_valid(dest));
 776
 777    return JB_ERR_OK;
 778 }
 779
 780
 781 /*********************************************************************
 782  *
 783  * Function    :  list_append_list_unique
 784  *
 785  * Description :  Append a string list to another list.
 786  *                Duplicate items are not added.
 787  *
 788  * Parameters  :
 789  *          1  :  dest = pointer to destination list for merge.
 790  *          2  :  src = pointer to source for merge.
 791  *
 792  * Returns     :  JB_ERR_OK on success
 793  *                JB_ERR_MEMORY on out-of-memory error.
 794  *                On error, some (but not all) of src might have
 795  *                been copied into dest.
 796  *
 797  *********************************************************************/
 798 jb_err list_append_list_unique(struct list *dest, const struct list *src)
 799 {
 800    struct list_entry * cur;
 801
 802    assert(src);
 803    assert(dest);
 804    assert(list_is_valid(src));
 805    assert(list_is_valid(dest));
 806
 807    for (cur = src->first; cur; cur = cur->next)
 808    {
 809       if (cur->str)
 810       {
 811          if (enlist_unique(dest, cur->str, 0))
 812          {
 813             assert(list_is_valid(src));
 814             assert(list_is_valid(dest));
 815
 816             return JB_ERR_MEMORY;
 817          }
 818       }
 819    }
 820
 821    assert(list_is_valid(src));
 822    assert(list_is_valid(dest));
 823
 824    return JB_ERR_OK;
 825 }
 826
 827
 828 /*********************************************************************
 829  *
 830  * Function    :  list_is_empty
 831  *
 832  * Description :  Test whether a list is empty.  Does not change the list.
 833  *
 834  * Parameters  :
 835  *          1  :  the_list = pointer to list to test.
 836  *
 837  * Returns     :  Nonzero iff the list contains no entries.
 838  *
 839  *********************************************************************/
 840 int list_is_empty(const struct list *the_list)
 841 {
 842    assert(the_list);
 843    assert(list_is_valid(the_list));
 844
 845    return (the_list->first == NULL);
 846 }
 847
 848
 849 /*********************************************************************
 850  *
 851  * Function    :  new_map
 852  *
 853  * Description :  Create a new, empty map.
 854  *
 855  * Parameters  :  N/A
 856  *
 857  * Returns     :  A new, empty map, or NULL if out of memory.
 858  *
 859  *********************************************************************/
 860 struct map *new_map(void)
 861 {
 862    return (struct map *) zalloc(sizeof(struct map));
 863 }
 864
 865
 866 /*********************************************************************
 867  *
 868  * Function    :  free_map
 869  *
 870  * Description :  Free the memory occupied by a map and its
 871  *                depandant strings
 872  *
 873  * Parameters  :
 874  *          1  :  the_map = map to be freed.  May be NULL.
 875  *
 876  * Returns     :  N/A
 877  *
 878  *********************************************************************/
 879 void free_map(struct map *the_map)
 880 {
 881    struct map_entry *cur_entry;
 882    struct map_entry *next_entry;
 883
 884    if (the_map == NULL)
 885    {
 886       return;
 887    }
 888
 889    for (cur_entry = the_map->first; cur_entry != NULL; cur_entry = next_entry)
 890    {
 891       freez(cur_entry->name);
 892       freez(cur_entry->value);
 893
 894       next_entry = cur_entry->next;
 895       free(cur_entry);
 896    }
 897
 898    the_map->first = the_map->last = NULL;
 899
 900    free(the_map);
 901 }
 902
 903
 904 /*********************************************************************
 905  *
 906  * Function    :  map
 907  *
 908  * Description :  Add a mapping from given name to given value to a
 909  *                given map.
 910  *
 911  *                Note: Since all strings will be free()d in free_map()
 912  *                      later, set the copy flags for constants or
 913  *                      strings that will be independantly free()d.
 914  *
 915  *                Note2: This function allows NULL parameters - it
 916  *                       returns JB_ERR_MEMORY in that case.
 917  *
 918  *                Note3: If this function returns JB_ERR_MEMORY,
 919  *                       it will free(name) unless you specify
 920  *                       name_needs_copying, and similarly it will
 921  *                       free(value) unless you specify
 922  *                       value_needs_copying.
 923  *
 924  *                Due to Note2 and Note3 above, the following code
 925  *                is legal, and will never crash or leak memory even
 926  *                if the system runs out of memory:
 927  *
 928  *                    err = map(mymap, "xyz", 1, html_encode(somestring), 0);
 929  *
 930  *                err will be set to JB_ERR_MEMORY if either call runs
 931  *                out-of-memory.  Without these features, you would
 932  *                need to check the return value of html_encode in the
 933  *                above example for NULL, which (at least) doubles the
 934  *                amount of error-checking code needed.
 935  *
 936  * Parameters  :
 937  *          1  :  the_map = map to add to
 938  *          2  :  name = name to add
 939  *          3  :  name_needs_copying = flag set if a copy of name should be used
 940  *          4  :  value = value to add
 941  *          5  :  value_needs_copying = flag set if a copy of value should be used
 942  *
 943  * Returns     :  JB_ERR_OK on success
 944  *                JB_ERR_MEMORY on out-of-memory error.
 945  *
 946  *********************************************************************/
 947 jb_err map(struct map *the_map,
 948            const char *name, int name_needs_copying,
 949            const char *value, int value_needs_copying)
 950 {
 951    struct map_entry *new_entry;
 952
 953    assert(the_map);
 954
 955    if ( (NULL == value)
 956      || (NULL == name)
 957      || (NULL == (new_entry = zalloc(sizeof(*new_entry)))) )
 958    {
 959       if ((name != NULL) && (!name_needs_copying))
 960       {
 961           free((char *)name);
 962       }
 963       if ((value != NULL) && (!value_needs_copying))
 964       {
 965           free((char *)value);
 966       }
 967       return JB_ERR_MEMORY;
 968    }
 969
 970    if (name_needs_copying)
 971    {
 972       if (NULL == (name = strdup(name)))
 973       {
 974          free(new_entry);
 975          if (!value_needs_copying)
 976          {
 977              free((char *)value);
 978          }
 979          return JB_ERR_MEMORY;
 980       }
 981    }
 982
 983    if (value_needs_copying)
 984    {
 985       if (NULL == (value = strdup(value)))
 986       {
 987          free((char *)name);
 988          free(new_entry);
 989          return JB_ERR_MEMORY;
 990       }
 991    }
 992
 993    new_entry->name = name;
 994    new_entry->value = value;
 995    /* new_entry->next = NULL;  - implied by zalloc */
 996
 997    if (the_map->last)
 998    {
 999       the_map->last->next = new_entry;
1000       the_map->last = new_entry;
1001    }
1002    else
1003    {
1004       the_map->first = new_entry;
1005       the_map->last = new_entry;
1006    }
1007
1008    return JB_ERR_OK;
1009 }
1010
1011
1012 /*********************************************************************
1013  *
1014  * Function    :  lookup
1015  *
1016  * Description :  Look up an item with a given name in a map, and
1017  *                return its value
1018  *
1019  * Parameters  :
1020  *          1  :  the_map = map to look in
1021  *          2  :  name = name parameter to look for
1022  *
1023  * Returns     :  the value if found, else the empty string.
1024  *                Return value is alloced as part of the map, so
1025  *                it is freed when the map is destroyed.  Caller
1026  *                must not free or modify it.
1027  *
1028  *********************************************************************/
1029 const char *lookup(const struct map *the_map, const char *name)
1030 {
1031    const struct map_entry *cur_entry;
1032
1033    assert(the_map);
1034    assert(name);
1035
1036    for (cur_entry = the_map->first; cur_entry != NULL; cur_entry = cur_entry->next)
1037    {
1038       if (!strcmp(name, cur_entry->name))
1039       {
1040          return cur_entry->value;
1041       }
1042    }
1043    return "";
1044 }
1045
1046
1047 /*
1048   Local Variables:
1049   tab-width: 3
1050   end:
1051 */