#ifndef base_str_h
#define base_str_h

#include "vec.h"

#include <string.h>

/**
 * @file str.h
 * @addtogroup base-str
 * @{
 * @brief Safe/small/fast strings.
 */

static const size_t YSTR_SMALL_THRESHOLD = sizeof(yvec_t) - 2;

/// ystr_t is a dynamically allocated, growable, NULL-terminated string.
typedef struct {
    /// The string value.
    union {
        /// A string in an array, also NULL-terminated for easy conversion to C
        /// strings.
        yvec_t big;
        /// The last two bytes will be zero if this is an inline
        /// string; otherwise they will be 1, because the size
        /// field of the yvec_t will be 1.
        ///
        /// This field is NULL-terminated.
        char small[sizeof(yvec_t) - 2];
    } inner;
} ystr_t;

/**
 * @brief Create a new string and return it. It must be freed with
 * `ystr_destroy()` after use.
 */
ystr_t ystr_new(const char *src);

/**
 * @brief Initialize a `ystr_t` with `src`, which can be `NULL`. The string
 * contents are copied, and `src` ownership stays with the caller.
 */
void ystr_init(ystr_t *s, const char *src);

/**
 * @brief Initialize a `ystr_t` with a string `src` that is then owned by the
 * `ystr_t` instance, i.e. no copy is done. It is generally invalid to use `src`
 * afterwards. Do not use before having called `ystr_init()`.
 *
 * This is both useful when you have a string you don't need anymore and want to
 * save a copy, or when you have a fixed buffer that you want to have a "view"
 * into. In the second case, you should not call ystr_destroy().
 */
void ystr_set_owned(ystr_t *s, char *src);

/**
 * @brief Set value of `s` to `src`. If `src` is `NULL`, the string will be
 * empty. Do not use before having called `ystr_init()`.
 */
void ystr_set(ystr_t *s, const char *src);

/**
 * @brief Set the value of `s` to the first `srclen` elements of `src`. Do not
 * use before having called `ystr_init()`.
 */
void ystr_set_n(ystr_t *s, const char *src, size_t srclen);

/**
 * @brief Deallocate a string. It is invalid to use the string afterwards.
 */
void ystr_destroy(ystr_t *s);

/**
 * @brief Obtain length of `s`.
 */
size_t ystr_len(ystr_t *s);

/**
 * @brief Get character at `index`.
 */
char *ystr_at(ystr_t *s, size_t index);

/**
 * @brief Compare to `ystr_t` values. If `s1` is lexically lesser than `s2`, -1
 * is returned, if greater, 1 is returned, if equal, 0 is returned.
 */
int ystr_cmp(ystr_t *s1, ystr_t *s2);

/**
 * @brief Like `ystr_cmp`, but with a C string.
 */
int ystr_cmp_str(ystr_t *s1, const char *s2);

/**
 * @brief Obtain a C string (NULL-terminated) from a `ystr_t`.
 */
const char *ystr_str(ystr_t *s);

/**
 * @brief Split a string at `limit` and store all parts into `dst`, which is a
 * `yvec_t` of `ystr_t`.
 */
void ystr_split(ystr_t *s, char limit, yvec_t *dst);

/**
 * @brief Append string `s2` to first string `s1`. `s2` is unchanged and can be
 * used afterwards.
 */
void ystr_append(ystr_t *s1, ystr_t *s2);

/**
 * @brief Resize a string to a length of `new` characters. If `new`
 * is smaller than the current capacity, the length is truncated to `new`, but
 * capacity is not changed.
 */
void ystr_resize(ystr_t *s, size_t new);

/**
 * @brief Create a copy of `src` in `dst`, potentially freeing dst before
 * copying.
 */
void ystr_copy(ystr_t *src, ystr_t *dst);

/**
 * @brief Return a cloned copy of `src`.
 */
ystr_t ystr_clone(ystr_t *src);

/**
 * @brief Append a C string to string, with possible formatting directives like
 * printf.
 */
void ystr_build(ystr_t *s, const char *fmt, ...);

/**
 * @}
 */

#endif