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