---

list.h File Reference

Declares functions to handle lists. More...

Go to the source code of this file.

Defines
#define	LIST_H_VERSION   "$Id: list.h,v 2.0 2002/06/04 14:34:21 jongfoster Exp $"
Functions
void	init_list (struct list *the_list)
void	destroy_list (struct list *the_list)
jb_err	enlist (struct list *the_list, const char *str)
jb_err	enlist_unique (struct list *the_list, const char *str, size_t num_significant_chars)
jb_err	enlist_unique_header (struct list *the_list, const char *name, const char *value)
jb_err	enlist_first (struct list *the_list, const char *str)
jb_err	list_append_list_unique (struct list *dest, const struct list *src)
jb_err	list_duplicate (struct list *dest, const struct list *src)
int	list_remove_item (struct list *the_list, const char *str)
int	list_remove_list (struct list *dest, const struct list *src)
void	list_remove_all (struct list *the_list)
int	list_is_empty (const struct list *the_list)
char *	list_to_text (const struct list *the_list)
map *	new_map (void)
void	free_map (struct map *the_map)
int	map (struct map *the_map, const char *name, int name_needs_copying, const char *value, int value_needs_copying)
const char *	lookup (const struct map *the_map, const char *name)
Variables
const char	list_rcs []
const char	list_h_rcs []

---

Detailed Description

Declares functions to handle lists.

Functions declared include: `destroy_list', `enlist' and `list_to_text'

Log:

list.h,v

Revision 2.0 2002/06/04 14:34:21 jongfoster Moving source files to src/

Revision 1.12 2002/03/26 22:29:55 swa we have a new homepage!

Revision 1.11 2002/03/24 13:25:43 swa name change related issues

Revision 1.10 2002/03/07 03:46:17 oes Fixed compiler warnings

Revision 1.9 2001/10/23 21:21:03 jongfoster New error handling - error codes are now jb_errs, not ints. Changed the way map() handles out-of-memory, to dramatically reduce the amount of error-checking clutter needed.

Revision 1.8 2001/09/16 17:30:24 jongfoster Fixing a compiler warning.

Revision 1.7 2001/09/16 13:20:29 jongfoster Rewrite of list library. Now has seperate header and list_entry structures. Also added a large sprinking of assert()s to the list code.

Revision 1.6 2001/08/05 16:06:20 jongfoster Modifiying "struct map" so that there are now separate header and "map_entry" structures. This means that functions which modify a map no longer need to return a pointer to the modified map. Also, it no longer reverses the order of the entries (which may be important with some advanced template substitutions).

Revision 1.5 2001/07/29 18:43:08 jongfoster Changing ifdef _FILENAME_H to FILENAME_H_INCLUDED, to conform to ANSI C rules.

Revision 1.4 2001/06/29 13:30:37 oes

• Introduced enlist_unique_header()
• Removed logentry from cancelled commit

Revision 1.3 2001/06/03 11:03:48 oes introduced functions for new list type "map": map(), lookup(), free_map(), and extended enlist_unique

Revision 1.2 2001/06/01 18:49:17 jongfoster Replaced "list_share" with "list" - the tiny memory gain was not worth the extra complexity.

Revision 1.1 2001/05/31 21:11:53 jongfoster

• Moved linked list support to new "list.c" file. Structure definitions are still in project.h, function prototypes are now in "list.h".
• Added support for "struct list_share", which is identical to "struct list" except it saves memory by not duplicating the strings. Obviously, this only works if there is some other way of managing the memory used by the strings. (These list_share lists are used for lists which last for only 1 request, and where all the list entries are just coming directly from entries in the actionsfile.) Note that you still need to destroy list_share lists properly to free the nodes - it's only the strings which are shared.

---

Function Documentation

void destroy_list (  struct list *    the_list )

Destroy a string list (opposite of list_init). On return, the memory used by the list entries has been freed, but not the memory used by the_list itself. You should not re-use the_list without calling list_init(). (Implementation note: You *can* reuse the_list without calling list_init(), but please don't. If you want to remove all entries from a list and still have a usable list, then use list_remove_all().) Parameters: the_list  pointer to list Returns: N/A

jb_err enlist (  struct list *    the_list, const char *    str )

Append a string into a specified string list. Parameters: the_list  pointer to list str  string to add to the list (maybe NULL) Returns: JB_ERR_OK on success JB_ERR_MEMORY on out-of-memory error. On error, the_list will be unchanged.

jb_err enlist_first (  struct list *    the_list, const char *    str )

Append a string as first element into a specified string list. Parameters: the_list  pointer to list str  string to add to the list (maybe NULL) Returns: JB_ERR_OK on success JB_ERR_MEMORY on out-of-memory error. On error, the_list will be unchanged.

jb_err enlist_unique (  struct list *    the_list, const char *    str, size_t    num_significant_chars )

Append a string into a specified string list, if & only if it's not there already. If the num_significant_chars argument is nonzero, only compare up to the nth character. Parameters: the_list  pointer to list str  string to add to the list num_significant_chars  number of chars to use for uniqueness test, or 0 to require an exact match. Returns: JB_ERR_OK on success JB_ERR_MEMORY on out-of-memory error. On error, the_list will be unchanged. "Success" does not indicate whether or not the item was already in the list.

jb_err enlist_unique_header (  struct list *    the_list, const char *    name, const char *    value )

Make a HTTP header from the two strings name and value, and append the result into a specified string list, if & only if there isn't already a header with that name. Parameters: the_list  pointer to list name  HTTP header name (e.g. "Content-type") value  HTTP header value (e.g. "text/html") Returns: JB_ERR_OK on success JB_ERR_MEMORY on out-of-memory error. On error, the_list will be unchanged. "Success" does not indicate whether or not the header was already in the list.

void free_map (  struct map *    the_map )

Free the memory occupied by a map and its depandant strings. Parameters: the_map  map to be freed. May be NULL. Returns: N/A

void init_list (  struct list *    the_list )

Create a new, empty list in user-allocated memory. Caller should allocate a "struct list" variable, then pass it to this function. (Implementation note: Rather than calling this function, you can also just memset the memory to zero, e.g. if you have a larger structure you want to initialize quickly. However, that isn't really good design.) Parameters: the_list  pointer to list Returns: N/A

jb_err list_append_list_unique (  struct list *    dest, const struct list *    src )

Append a string list to another list. Duplicate items are not added. Parameters: dest  pointer to destination list for merge. src  pointer to source for merge. Returns: JB_ERR_OK on success JB_ERR_MEMORY on out-of-memory error. On error, some (but not all) of src might have been copied into dest.

jb_err list_duplicate (  struct list *    dest, const struct list *    src )

Copy a string list. Parameters: dest  Destination list. Must be a valid list. All existing entries will be removed. src  pointer to source list for copy. Returns: JB_ERR_OK on success JB_ERR_MEMORY on out-of-memory error. On error, dest will be empty.

int list_is_empty (  const struct list *    the_list )

Test whether a list is empty. Does not change the list. Parameters: the_list  pointer to list to test. Returns: Nonzero iff the list contains no entries.

void list_remove_all (  struct list *    the_list )

Remove all entries from a list. On return, the_list is a valid, empty list. Note that this is similar to destroy_list(), but the difference is that this function guarantees that the list structure is still valid after the call. Parameters: the_list  pointer to list Returns: N/A

int list_remove_item (  struct list *    the_list, const char *    str )

Remove a string from a specified string list. Parameters: the_list  pointer to list str  string to remove from the list - non-NULL Returns: Number of times it was removed.

int list_remove_list (  struct list *    dest, const struct list *    src )

Remove all strings in one list from another list. This is currently a brute-force algorithm (it compares every pair of strings). Parameters: dest  list to change src  list of strings to remove Returns: Total number of strings removed.

char* list_to_text (  const struct list *    the_list )

"Flatten" a string list into 1 long \r delimited string, adding an empty line at the end. NULL entries are ignored. This function does not change the_list. Parameters: the_list  pointer to list Returns: NULL on malloc error, else new long string. Caller must free() it.

const char* lookup (  const struct map *    the_map, const char *    name )

Look up an item with a given name in a map, and return its value. Parameters: the_map  map to look in name  name parameter to look for Returns: the value if found, else the empty string. Return value is alloced as part of the map, so it is freed when the map is destroyed. Caller must not free or modify it.

int map (  struct map *    the_map, const char *    name, int    name_needs_copying, const char *    value, int    value_needs_copying )

Add a mapping from given name to given value to a given map. Note Since all strings will be free()d in free_map() later, set the copy flags for constants or strings that will be independantly free()d. Note2 This function allows NULL parameters - it returns JB_ERR_MEMORY in that case. Note3 If this function returns JB_ERR_MEMORY, it will free(name) unless you specify name_needs_copying, and similarly it will free(value) unless you specify value_needs_copying. Due to Note2 and Note3 above, the following code is legal, and will never crash or leak memory even if the system runs out of memory: err = map(mymap, "xyz", 1, html_encode(somestring), 0); err will be set to JB_ERR_MEMORY if either call runs out-of-memory. Without these features, you would need to check the return value of html_encode in the above example for NULL, which (at least) doubles the amount of error-checking code needed. Parameters: the_map  map to add to name  name to add name_needs_copying  flag set if a copy of name should be used value  value to add value_needs_copying  flag set if a copy of value should be used Returns: JB_ERR_OK on success JB_ERR_MEMORY on out-of-memory error.

struct map* new_map (  void    )

Create a new, empty map. Parameters : N/A Returns: A new, empty map, or NULL if out of memory.

---

Variable Documentation

const char list_h_rcs[]

Version information about list.h.

const char list_rcs[]

Version information about list.c.

---