Add guf_str hash functions

src/guf_str.h

@@ -66,40 +66,57 @@ typedef struct guf_str {
     #define GUF_STR_UNINITIALISED_CPP guf_str{.allocator = NULL, .data.shrt.size = 0, .data.shrt.c_str[0] = '\0'}
 #endif
 
-// guf_str_view:
+// 1.) guf_str_view:
-GUF_STR_KWRDS bool guf_str_view_is_valid(guf_str_view sv);
+
+// Return a new guf_str_view corresponding to the substring in range [pos, pos + count) of str
 GUF_STR_KWRDS guf_str_view guf_str_view_substr(guf_str_view str, ptrdiff_t pos, ptrdiff_t count);
 
-GUF_STR_KWRDS guf_hash_size_t guf_str_view_hash(const guf_str_view *sv);
+// Equality- and comparison-operators
-GUF_STR_KWRDS uint64_t guf_str_view_hash64(const guf_str_view *sv);
-GUF_STR_KWRDS uint32_t guf_str_view_hash32(const guf_str_view *sv);
-
 GUF_STR_KWRDS bool guf_str_view_equal(const guf_str_view* a, const guf_str_view* b);
 GUF_STR_KWRDS bool guf_str_view_equal_val_arg(guf_str_view a_val, guf_str_view b_val);
 GUF_STR_KWRDS int guf_str_view_cmp(const void *str_view_a, const void *str_view_b);  // For qsort etc.
 
-GUF_STR_KWRDS guf_str_view guf_str_view_trim_right_ascii(guf_str_view sv);
+// Hash functions.
-GUF_STR_KWRDS guf_str_view guf_str_view_trim_left_ascii(guf_str_view sv);
+GUF_STR_KWRDS guf_hash_size_t guf_str_view_hash(const guf_str_view *sv);
+GUF_STR_KWRDS uint64_t guf_str_view_hash64(const guf_str_view *sv);
+GUF_STR_KWRDS uint32_t guf_str_view_hash32(const guf_str_view *sv);
 
+// Return a new guf_str_view corresponding to the substring with leading/trailing ascii-whitespace chars removed from the left/right
+GUF_STR_KWRDS guf_str_view guf_str_view_trim_left_ascii(guf_str_view sv);
+GUF_STR_KWRDS guf_str_view guf_str_view_trim_right_ascii(guf_str_view sv);
+
+// Return true if sv does not violate any of its invariants (.len must be >= 0, .str must not be NULL unless len is 0)
+GUF_STR_KWRDS bool guf_str_view_is_valid(guf_str_view sv);
+
+// Return the guf_str_view corresponding to the next token (delimiters (each can be more than once character) given by delims, preserved_delims are delimiters which are returned as tokens when encountered)
 GUF_STR_KWRDS guf_str_view guf_str_next_tok(guf_str_view *input, const guf_str_view *delims, ptrdiff_t num_delims, const guf_str_view *preserved_delims, ptrdiff_t num_preserved_delims);
 
-// guf_str:
+
+// 2.) guf_str:
+
+// Initialise the guf_str pointed to by str -> return the initalised str on success (or NULL on error)
 GUF_STR_KWRDS guf_str *guf_str_try_init(guf_str *str, guf_str_view str_view, guf_allocator *alloc, guf_err *err);
 GUF_STR_KWRDS guf_str *guf_str_init(guf_str *str, guf_str_view str_view, guf_allocator *alloc);
 GUF_STR_KWRDS guf_str *guf_str_init_empty(guf_str *str, guf_allocator *alloc);
-
 GUF_STR_KWRDS guf_str *guf_str_try_init_from_cstr(guf_str *str, const char* c_str, guf_allocator *alloc, guf_err *err);
 GUF_STR_KWRDS guf_str *guf_str_init_from_cstr(guf_str *str, const char* c_str, guf_allocator *alloc);
 
+// Return an initialised guf_str (or GUF_STR_UNINITIALISED on error)
 GUF_STR_KWRDS guf_str guf_str_try_new(guf_str_view str_view, guf_allocator *alloc, guf_err *err);
 GUF_STR_KWRDS guf_str guf_str_new(guf_str_view str_view, guf_allocator *alloc);
 
+// Destructor, copy-constructor and move-constructor; equality- and comparison-operator (NOTE: ctx is ignored, just pass NULL)
 GUF_STR_KWRDS void guf_str_free(guf_str *str, void *ctx);
 GUF_STR_KWRDS guf_str *guf_str_copy(guf_str *dst, const guf_str *src, void *ctx);
 GUF_STR_KWRDS guf_str *guf_str_move(guf_str *dst, guf_str *src, void *ctx);
 GUF_STR_KWRDS bool guf_str_equal(const guf_str *a, const guf_str *b);
 GUF_STR_KWRDS int guf_str_cmp(const guf_str *a, const guf_str *b);
 
+// Hash-functions.
+GUF_STR_KWRDS guf_hash_size_t guf_str_hash(const guf_str *str);
+GUF_STR_KWRDS uint64_t guf_str_hash64(const guf_str *str);
+GUF_STR_KWRDS uint32_t guf_str_hash32(const guf_str *str);
+
 // Reserve at least min_capacity characters (excluding the null-terminator) (try to double the current capacity first; if that's not at least min_capacity, set the new capacity to min_capacity instead).
 GUF_STR_KWRDS guf_str *guf_str_try_reserve(guf_str *str, ptrdiff_t min_capacity, guf_err *err); 
 GUF_STR_KWRDS guf_str *guf_str_reserve(guf_str *str, ptrdiff_t min_capacity); 
@@ -165,12 +182,15 @@ GUF_STR_KWRDS ptrdiff_t guf_str_capacity(const guf_str *str);
 GUF_STR_KWRDS bool guf_str_is_short(const guf_str *str);
 // Return true if the string is in readonly ("view") mode, i.e. can't be modified, copied etc. which is useful for guf_dict so we don't have to use guf_str_view but can use guf_str (by passing a read-only guf_str) for the lookup functions.
 GUF_STR_KWRDS bool guf_str_is_readonly(const guf_str *str);
-// Return true if the string's data does not violate its invariants (useful for debugging, should never be false after initialising if there are not bugs in guf_str). 
-GUF_STR_KWRDS bool guf_str_is_valid(const guf_str *str);
 
+// Return an guf_str which is in explicitly uninitialised state. 
 GUF_STR_KWRDS guf_str guf_str_new_uninitialised(void);
+// Return true if str is explicitly uninitialised.
 GUF_STR_KWRDS bool guf_str_is_uninit(const guf_str *str);
 
+// Return true if the string's data does not violate its invariants (useful for debugging the library, should never be false after initialising a guf_str). 
+GUF_STR_KWRDS bool guf_str_is_valid(const guf_str *str);
+
 #endif
 
 // #define GUF_STR_IMPL_STATIC /* debug */
@@ -1128,6 +1148,24 @@ GUF_STR_KWRDS char guf_str_pop_back(guf_str *str)
     return guf_str_try_pop_back(str, NULL);
 }
 
+GUF_STR_KWRDS guf_hash_size_t guf_str_hash(const guf_str *str)
+{
+    GUF_ASSERT(guf_str_is_valid(str));
+    return guf_str_view_hash(&(guf_str_view){.str = guf_str_const_cstr(str), .len = guf_str_len(str)});
+}
+
+GUF_STR_KWRDS uint64_t guf_str_hash64(const guf_str *str)
+{
+    GUF_ASSERT(guf_str_is_valid(str));
+    return guf_str_view_hash64(&(guf_str_view){.str = guf_str_const_cstr(str), .len = guf_str_len(str)});
+}
+
+GUF_STR_KWRDS uint32_t guf_str_hash32(const guf_str *str)
+{
+    GUF_ASSERT(guf_str_is_valid(str));
+    return guf_str_view_hash32(&(guf_str_view){.str = guf_str_const_cstr(str), .len = guf_str_len(str)});
+}
+
 
 // guf_str_view: