lander/lsm/include/lsm/str.h

#ifndef LSM_STR
#define LSM_STR

#include <stdbool.h>

#include "lsm.h"

/**
 * Represents a string (or really any kind of data) with a known length. Data
 * with length 8 or less is stored inside the pointer, and does not allocate
 * additional memory.
 */
typedef struct lsm_str lsm_str;

/**
 * Allocate and initialize a new lsm_str object
 *
 * @param ptr pointer to store newly allocated pointer
 * @param s string to convert into lsm string; ownership is taken over
 */
lsm_error lsm_str_init(lsm_str **ptr, char *s);

/**
 * Allocate a new string struct of length 0.
 *
 * @param ptr pointer to store newly allocated pointer in
 */
lsm_error lsm_str_init_zero(lsm_str **ptr);

/**
 * Allocate and initialize a new lsm_str object, but copy the original string
 * instead of taking over ownership, leaving the original string untouched.
 *
 * @param ptr pointer to store newly allocated pointer
 * @param s string to copy into lsm string
 */
lsm_error lsm_str_init_copy(lsm_str **ptr, const char *s);

/**
 * Same as `lsm_str_init_copy`, except that it takes an additional argument
 * specifying the length of the string to copy over. This can be used to more
 * easily "cut" parts of a C-style string out into an LSM string.
 *
 * @param ptr pointer to store newly allocated pointer
 * @param s string to copy into lsm string
 * @param len length of string to copy
 */
lsm_error lsm_str_init_copy_n(lsm_str **ptr, const char *s, uint64_t len);

/**
 * Overwrite an existing lsm_str so it now represents the new provided string.
 * The string pointer of the original object is free'd if needed. Ownership of
 * the pointer is taken over.
 *
 * @param str lsm_str object to modify
 * @param s string to convert into lsm string; ownership is taken over
 */
void lsm_str_overwrite(lsm_str *str, char *s);

/**
 * Overwrite an existing lsm_str so it now represents the new provided string.
 * The string pointer of the original object is free'd if needed. The provided
 * string is copied, leaving the original untouched.
 *
 * @param str lsm_str object to modify
 * @param s string to copy into lsm string
 */
lsm_error lsm_str_overwrite_copy(lsm_str *str, const char *s);

/**
 * Same as `lsm_str_overwrite_copy`, except the length is explicitely specified,
 * allowing you to easily "cut" parts of a C string out into an LSM string.
 *
 * @param str lsm_str object to modify
 * @param s string to copy into lsm string
 * @param len length of the string to copy
 */
lsm_error lsm_str_overwrite_copy_n(lsm_str *str, const char *s, uint64_t len);

/**
 * Deallocate the existing internal string if needed and replace the lsm_str
 * with a string of length 0, wiping its contents. This function can be used as
 * a substitute for lsm_str_free for stack-allocated structs.
 *
 * @param str string to wipe
 */
void lsm_str_zero(lsm_str *str);

/**
 * Deallocate the string and its internal char buffer if needed. Only call this
 * on heap-allocated strings.
 *
 * @param str string to dealloate
 */
void lsm_str_free(lsm_str *str);

/**
 * Return the length of the string.
 *
 * @param str string to return length for.
 */
uint64_t lsm_str_len(const lsm_str *str);

/**
 * Return a pointer to the string's underlying char array. Note that this array
 * will *not* neccessarily be null-terminatd.
 *
 * @param str string to return pointer for
 */
const char *lsm_str_ptr(const lsm_str *str);

/**
 * Returns the character at the specified position.
 *
 * @index index of character to return
 */
char lsm_str_char(const lsm_str *str, uint64_t index);

/**
 * Take a substring and copy it to a provided string object.
 *
 * @param out string to store new substring in. The contents of this string will
 * be replaced. This string is assumed to be unitialized, so zero this string
 * manually if you're overwriting an existing string.
 * @param str string to take substring from
 * @param start inclusive start index for the substring. If this is greater than
 * or equal to the string's length, out will be a zero-length string.
 * @param end exclusive end index for the substring
 */
lsm_error lsm_str_substr(lsm_str *out, const lsm_str *str, uint64_t start,
                         uint64_t end);

/**
 * Return the first index where s1 and s2 differ, starting at their respective
 * offsets. If both strings are equal (or one is a prefix of the other), the
 * result will be the length of the shortest string. The returned value is
 * relative to the given offets.
 *
 * @param s1 string to compare
 * @param s1_offset offset inside s1 to start comparing from
 * @param s2 string to compare s1 to
 * @param s2_offset offset inside s2 to start comparing from
 */
uint64_t lsm_str_cmp(const lsm_str *s1, uint64_t s1_offset, const lsm_str *s2,
                     uint64_t s2_offset);

/**
 * Checks whether the two strings are identical.
 *
 * @param s1 first string to compare
 * @param s2 second string to compare
 * @return true if their values are equal, false otherwise
 */
bool lsm_str_eq(const lsm_str *s1, const lsm_str *s2);

/**
 * Truncate an already initialized string in-place.
 *
 * @param s string to truncate
 * @param new_len new length of the string. If new_len is >= the original
 * length, this function does nothing.
 */
lsm_error lsm_str_truncate(lsm_str *s, uint64_t new_len);

/**
 * Split s at the specified index, saving the second half the string in s2.
 *
 * @param s string to split
 * @param s2 string to store second part of s
 * @param index position to split string. If index is the length of s or
 * greater, s2 will simply be an empty string.
 */
lsm_error lsm_str_split(lsm_str *s, lsm_str *s2, uint64_t index);

/**
 * Append s2 to s. s2 is left untouched.
 *
 * @param s string to append s2 to
 * @param s2 string to append to s
 */
lsm_error lsm_str_append(lsm_str *s, const lsm_str *s2);

/**
 * Same as `lsm_str_append`, but it takes a C-style string instead.
 *
 * @param s string to append c_str to
 * @param c_str char buffer to append
 * @param len length of c_str
 */
lsm_error lsm_str_append_c(lsm_str *s, const char *c_str, uint64_t len);

#endif