+/*********************************************************************
+ *
+ * Function : map
+ *
+ * Description : 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 independently 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 :
+ * 1 : the_map = map to add to
+ * 2 : name = name to add
+ * 3 : name_needs_copying = flag set if a copy of name should be used
+ * 4 : value = value to add
+ * 5 : 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.
+ *
+ *********************************************************************/
+jb_err map(struct map *the_map,
+ const char *name, int name_needs_copying,
+ const char *value, int value_needs_copying)
+{
+ struct map_entry *new_entry;
+
+ assert(the_map);
+
+ if ( (NULL == value)
+ || (NULL == name)
+ || (NULL == (new_entry = zalloc(sizeof(*new_entry)))))
+ {
+ if ((name != NULL) && (!name_needs_copying))
+ {
+ free((char *)name);
+ }
+ if ((value != NULL) && (!value_needs_copying))
+ {
+ free((char *)value);
+ }
+ return JB_ERR_MEMORY;
+ }
+
+ if (name_needs_copying)
+ {
+ if (NULL == (name = strdup(name)))
+ {
+ free(new_entry);
+ if (!value_needs_copying)
+ {
+ free((char *)value);
+ }
+ return JB_ERR_MEMORY;
+ }
+ }
+
+ if (value_needs_copying)
+ {
+ if (NULL == (value = strdup(value)))
+ {
+ free((char *)name);
+ free(new_entry);
+ return JB_ERR_MEMORY;
+ }
+ }
+
+ new_entry->name = name;
+ new_entry->value = value;
+ /* new_entry->next = NULL; - implied by zalloc */
+
+ if (the_map->last)
+ {
+ the_map->last->next = new_entry;
+ the_map->last = new_entry;
+ }
+ else
+ {
+ the_map->first = new_entry;
+ the_map->last = new_entry;
+ }
+
+ return JB_ERR_OK;
+}
+
+
+/*********************************************************************
+ *
+ * Function : unmap
+ *
+ * Description : Remove all map_entry structs with a given name from
+ * a given map.
+ *
+ * Parameters :
+ * 1 : the_map = map to look in
+ * 2 : name = name to unmap
+ *
+ * Returns : JB_ERR_OK
+ *
+ *********************************************************************/
+jb_err unmap(struct map *the_map, const char *name)
+{
+ struct map_entry *cur_entry, *last_entry;
+
+ assert(the_map);
+ assert(name);
+
+ last_entry = NULL;
+
+ for (cur_entry = the_map->first; cur_entry != NULL; cur_entry = cur_entry->next)
+ {
+ if (!strcmp(name, cur_entry->name))
+ {
+ /*
+ * Update the incoming pointer
+ */
+ if (cur_entry == the_map->first)
+ {
+ the_map->first = cur_entry->next;
+ }
+ else
+ {
+ last_entry->next = cur_entry->next;
+ }
+
+ /*
+ * Update the map's last pointer
+ */
+ if (cur_entry == the_map->last)
+ {
+ the_map->last = last_entry;
+ }
+
+ /*
+ * Free the map_entry
+ */
+ freez(cur_entry->name);
+ freez(cur_entry->value);
+ freez(cur_entry);
+ if (last_entry == NULL)
+ {
+ /* The map only had a single entry which has just been removed. */
+ break;
+ }
+ cur_entry = last_entry;
+ }
+ else
+ {
+ last_entry = cur_entry;
+ }
+ }
+ return JB_ERR_OK;
+}
+
+
+/*********************************************************************
+ *
+ * Function : lookup
+ *
+ * Description : Look up an item with a given name in a map, and
+ * return its value
+ *
+ * Parameters :
+ * 1 : the_map = map to look in
+ * 2 : name = name parameter to look for
+ *
+ * Returns : the value if found, else the empty string.
+ * Return value is allocated as part of the map, so
+ * it is freed when the map is destroyed. Caller
+ * must not free or modify it.
+ *
+ *********************************************************************/
+const char *lookup(const struct map *the_map, const char *name)
+{
+ const struct map_entry *cur_entry;
+
+ assert(the_map);
+ assert(name);
+
+ for (cur_entry = the_map->first; cur_entry != NULL; cur_entry = cur_entry->next)
+ {
+ if (!strcmp(name, cur_entry->name))
+ {
+ return cur_entry->value;
+ }
+ }
+ return "";
+}
+
+