+ * 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.
+ *