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