#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_VALUE,              ///< parameter value
    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
 * @param err returned error info
 */
typedef err_t (*str_format_cb) (const char *name, const char **value, ssize_t *value_len, void *arg, error_t *err);

/**
 * 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