--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/src/lib/str.h	Wed May 27 23:07:00 2009 +0300
@@ -0,0 +1,126 @@
+#ifndef STR_H
+#define STR_H
+
+/**
+ * @file
+ *
+ * Miscellaneous string utility functions
+ */
+#include <sys/types.h>
+#include <stdarg.h>
+#include "error.h"
+
+/**
+ * Error codes
+ */
+enum str_error_code {
+    ERR_STR_NONE,
+    ERR_STR_FMT_TAG,                ///< invalid parameter tag syntax
+    ERR_STR_FMT_NAME_LEN,           ///< invalid parameter name length
+    ERR_STR_FMT_NAME,               ///< invalid/unknown parameter name
+    ERR_STR_FMT_FLAGS_LEN,          ///< invalid paramter flags length
+    ERR_STR_FMT_FLAG,               ///< invalid paramter flag
+    ERR_STR_FMT_BUF_LEN,            ///< output buffer ran out
+};
+
+/**
+ * Error list
+ */
+const struct error_list str_errors;
+
+/**
+ * Writes the given string into the given buffer, reading at most len bytes (or up to NUL if -1), and writing at most
+ * buf_size bytes, including the terminating NUL.
+ *
+ * Returns the number of input bytes that would have been written, not including the terminating NUL.
+ */
+size_t str_append_num (char *buf, size_t buf_size, const char *str, ssize_t len);
+
+/**
+ * Like str_append_num with len = -1.
+ *
+ * @see str_append_num()
+ */
+size_t str_append (char *buf, size_t buf_size, const char *str);
+
+/**
+ * Like str_append, but only a single char.
+ *
+ * @see str_append()
+ */
+size_t str_append_char (char *buf, size_t buf_size, char c);
+
+/**
+ * Like str_append, but using formatted input instead.
+ *
+ * @see str_append()
+ */
+size_t str_append_fmt (char *buf, size_t buf_size, const char *fmt, ...);
+
+/**
+ * Like str_append_fmt, but using a vargs list instead.
+ *
+ * @see str_append_fmt()
+ */
+size_t str_append_fmt_va (char *buf, size_t buf_size, const char *fmt, va_list vargs);
+
+/**
+ * Use str_append* to write out the quoted char value to the given buffer.
+ */
+size_t str_quote_char (char *buf, size_t buf_size, char c);
+
+/**
+ * Update data_size to add len (if given), then update buf_size to remove to min(buf_size, len), and return len.
+ *
+ * Intended to be used like:
+ * \code
+ *  buf += str_advance(&data_size, &buf_size, str_append_fmt(buf, buf_size, "...", ...));
+ * \endcode
+ */
+size_t str_advance (size_t *data_size, size_t *buf_size, size_t len);
+
+/**
+ * Copy the given \a str into \buf, surrounding it with quotes and escaping any data inside.
+ *
+ * At most \a str_len bytes of input will be read, unless given as -1, whereupon str will be read up to the first \0 byte.
+ *
+ * At most \a buf_size bytes of output will be written, if the output string was truncated, it will end in '...', and a
+ * value larger than \a buf_size will be returned.
+ *
+ * As a special case, if \a str is NULL, only the string "NULL" will be output.
+ *
+ * @param buf the buffer to write the output to
+ * @param buf_size the size of the given output buffer
+ * @param str the input string
+ * @param str_len number of bytes of input to process, or -1 to use strlen()
+ * @return the total number of bytes that would have been written out, may be more than buf_size
+ */
+size_t str_quote (char *buf, size_t buf_size, const char *str, ssize_t str_len);
+
+/**
+ * Callback function used by str_format to look up a value for a parameter.
+ *
+ * @param name the name of the paramter in the format string
+ * @param value returned pointer to param value
+ * @param value_len returned param value length, or -1 for strlen
+ * @param arg the context arg given to str_format
+ * @return the parameter value, or NULL to error out
+ */
+typedef err_t (*str_format_cb) (const char *name, const char **value, ssize_t *value_len, void *arg);
+
+/**
+ * Maximum length of a parameter name
+ */
+#define STR_FORMAT_PARAM_MAX 32
+
+/**
+ * Maximum length of a parameter flags section
+ */
+#define STR_FORMAT_FLAGS_MAX 8
+
+/**
+ * Format an output string based on the given template, filling in parameter values using a callback function.
+ */
+err_t str_format (char *buf, size_t buf_size, const char *format, str_format_cb func, void *arg, error_t *err);
+
+#endif