+/*********************************************************************
+ *
+ * Function : string_join
+ *
+ * Description : Join two strings together. Frees BOTH the original
+ * strings. If either or both input strings are NULL,
+ * fails as if it had run out of memory.
+ *
+ * For comparison, string_append requires that the
+ * second string is non-NULL, and doesn't free it.
+ *
+ * Rationale: Too often, we want to do
+ * string_append(s, html_encode(s2)). That assert()s
+ * if s2 is NULL or if html_encode() runs out of memory.
+ * It also leaks memory. Proper checking is cumbersome.
+ * The solution: string_join(s, html_encode(s2)) is safe,
+ * and will free the memory allocated by html_encode().
+ *
+ * Parameters :
+ * 1 : target_string = Pointer to old text that is to be
+ * extended. *target_string will be free()d by this
+ * routine. target_string must be non-NULL.
+ * 2 : text_to_append = Text to be appended to old.
+ *
+ * Returns : JB_ERR_OK on success, and sets *target_string
+ * to newly malloc'ed appended string. Caller
+ * must free(*target_string).
+ * JB_ERR_MEMORY on out-of-memory, or if
+ * *target_string or text_to_append is NULL. (In
+ * this case, frees *target_string and text_to_append,
+ * sets *target_string to NULL).
+ *
+ *********************************************************************/
+jb_err string_join(char **target_string, char *text_to_append)
+{
+ jb_err err;
+
+ assert(target_string);
+
+ if (text_to_append == NULL)
+ {
+ freez(*target_string);
+ return JB_ERR_MEMORY;
+ }
+
+ err = string_append(target_string, text_to_append);
+
+ free(text_to_append);
+
+ return err;
+}
+
+