list.c

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