#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_BEGIN = _ERR_STR,
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
};
/**
* 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);
#endif