feat(lsm): write str tests; start trie tests

lsm/include/lsm/str.h

@@ -1,6 +1,8 @@
 #ifndef LSM_STR
 #define LSM_STR
 
+#include <stdbool.h>
+
 #include "lsm.h"
 
 /**
@@ -10,22 +12,6 @@
  */
 typedef struct lsm_str lsm_str;
 
-/**
- * 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);
-
-/**
- * Update an existing lsm_str so it now represents the new provided string. The
- * string pointer of the original object is free'd if needed.
- *
- * @param str lsm_str object to modify
- * @param s string to convert into lsm string; ownership is taken over
- */
-void lsm_str_init_prealloc(lsm_str *str, char *s);
-
 /**
  * Allocate and initialize a new lsm_str object
  *
@@ -35,17 +21,45 @@ void lsm_str_init_prealloc(lsm_str *str, char *s);
 lsm_error lsm_str_init(lsm_str **ptr, char *s);
 
 /**
- * Same as lsm_str_init, except it copies the original string instead of taking
- * over ownership, leaving the original string untouched.
+ * 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, 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. 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 convert into lsm string; ownership is taken over
+ */
+lsm_error lsm_str_overwrite_copy(lsm_str *str, char *s);
+
 /**
  * Deallocate the existing internal string if needed and replace the lsm_str
- * with a string of length 0, wiping its contents.
+ * 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
  */
@@ -85,7 +99,8 @@ char lsm_str_char(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.
+ * 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.
@@ -109,7 +124,16 @@ uint64_t lsm_str_cmp(lsm_str *s1, uint64_t s1_offset, lsm_str *s2,
                      uint64_t s2_offset);
 
 /**
- * Truncate a string in-place.
+ * 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(lsm_str *s1, 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