* This function splits a single string into multiple strings. The
* original string is untouched: an array is allocated (using talloc)
* pointing to copies of each substring. Multiple delimiters result
- * in empty substrings.
+ * in empty substrings. By definition, no delimiters will appear in
+ * the substrings.
*
* The final char * in the array will be NULL, so you can use this or
* @nump to find the array length.
*/
char **strsplit(const void *ctx, const char *string, const char *delims,
unsigned int *nump);
+
+/**
+ * strjoin - Join an array of substrings into one long string
+ * @ctx: the context to tallocate from (often NULL)
+ * @strings: the NULL-terminated array of strings to join
+ * @delim: the delimiter to insert between the strings
+ *
+ * This function joins an array of strings into a single string. The
+ * return value is allocated using talloc. Each string in @strings is
+ * followed by a copy of @delim.
+ *
+ * Example:
+ * // Append the string "--EOL" to each line.
+ * char *append_to_all_lines(const char *string)
+ * {
+ * char **lines, *ret;
+ * unsigned int i, num, newnum;
+ *
+ * lines = strsplit(NULL, string, "\n", NULL);
+ * ret = strjoin(NULL, lines, "-- EOL\n");
+ * talloc_free(lines);
+ * return ret;
+ * }
+ */
+char *strjoin(const void *ctx, char *strings[], const char *delim);
+
+/**
+ * grab_fd - read all of a file descriptor into memory
+ * @ctx: the context to tallocate from (often NULL)
+ * @fd: the file descriptor to read from
+ * @size: the (optional) size of the file
+ *
+ * This function reads from the given file descriptor until no more
+ * input is available. The content is talloced off @ctx, and the size
+ * of the file places in @size if it's non-NULL. For convenience, the
+ * byte after the end of the content will always be NUL.
+ *
+ * Example:
+ * // Return all of standard input, as lines.
+ * char **read_as_lines(void)
+ * {
+ * char **lines, *all;
+ *
+ * all = grab_fd(NULL, 0, NULL);
+ * if (!all)
+ * return NULL;
+ * lines = strsplit(NULL, all, "\n", NULL);
+ * talloc_free(all);
+ * return lines;
+ * }
+ */
+void *grab_fd(const void *ctx, int fd, size_t *size);
+
+/**
+ * grab_file - read all of a file (or stdin) into memory
+ * @ctx: the context to tallocate from (often NULL)
+ * @filename: the file to read (NULL for stdin)
+ * @size: the (optional) size of the file
+ *
+ * This function reads from the given file until no more input is
+ * available. The content is talloced off @ctx, and the size of the
+ * file places in @size if it's non-NULL. For convenience, the byte
+ * after the end of the content will always be NUL.
+ *
+ * Example:
+ * // Return all of a given file, as lines.
+ * char **read_as_lines(const char *filename)
+ * {
+ * char **lines, *all;
+ *
+ * all = grab_file(NULL, filename, NULL);
+ * if (!all)
+ * return NULL;
+ * lines = strsplit(NULL, all, "\n", NULL);
+ * talloc_free(all);
+ * return lines;
+ * }
+ */
+void *grab_file(const void *ctx, const char *filename, size_t *size);
#endif /* CCAN_STRING_H */