wstr.h

   1 /*
   2  * wstr.h - string_t implementation.
   3  * Author: Saúl Valdelvira (2023)
   4  */
   5 #pragma once
   6 #include <wchar.h>
   7 #ifndef WSTR_H
   8 #define WSTR_H
   9
  10 #include <stddef.h> // size_t, wchar_t
  11
  12 typedef struct wstring wstring_t;
  13
  14 /**
  15  * Builds an empty wstring_t
  16  */
  17 wstring_t* wstr_empty(void);
  18
  19 /**
  20  * Builds a wstring_t with the given initial size
  21  */
  22 wstring_t* wstr_init(unsigned initial_size);
  23
  24 /**
  25  * Builds a wstring_t, from the given source cwstring.
  26  * @param n max length of src
  27  */
  28 wstring_t* wstr_from_cwstr(const wchar_t *src, unsigned n);
  29 wstring_t* wstr_from_cstr(const char *src, unsigned n);
  30
  31 /**
  32  * Reserves space in the wstring_t for n characters
  33  * @note n characters including the ones already in the string_t,
  34  *       it does not reserve space for n more characters.
  35  */
  36 void wstr_reserve(wstring_t *wstr, unsigned n);
  37
  38 /**
  39  * Concatenates the given cwstring at the end of the wstring_t
  40  * @param n max length of cat
  41  */
  42 int wstr_concat_cwstr(wstring_t *wstr, const wchar_t *cat, unsigned n);
  43
  44 /**
  45  * Concatenates the given cstring at the end of the wstring_t
  46  * @param n max length of cat
  47  */
  48 int wstr_concat_cstr(wstring_t *wstr, const char *cat, unsigned n);
  49
  50 /**
  51  * Concatenates a wstring_t at the end of another
  52  * @cat source wstring_t
  53  * @str dest wstring_t
  54  */
  55 int wstr_concat_wstr(wstring_t *wstr, wstring_t *cat);
  56
  57 /**
  58  * Puts a char at the end of the wstring_t
  59  */
  60 int wstr_push_char(wstring_t *wstr, wchar_t c);
  61
  62 /**
  63  * Removes the last character in the wstring_t
  64 */
  65 int wstr_pop(wstring_t *wstr);
  66
  67 /**
  68  * Removes the characater at the given index
  69  */
  70 int wstr_remove_at(wstring_t *str, unsigned index);
  71
  72 /**
  73  * Removes the range [start, end) from the wstring_t
  74 */
  75 int wstr_remove_range(wstring_t *wstr, unsigned start, unsigned end);
  76
  77 /**
  78  * Gets the character at the given index
  79  */
  80 wchar_t wstr_get_at(const wstring_t *wstr, unsigned index);
  81
  82 /**
  83  * Sets the character at the given index
  84  */
  85 int wstr_set_at(wstring_t *wstr, unsigned index, wchar_t c);
  86
  87 /**
  88  * Inserts the given cwstring at the given index.
  89  * @param n, max length of the insert string
  90  */
  91 int wstr_insert_cwstr(wstring_t *wstr, const wchar_t *insert, unsigned n, unsigned index);
  92 int wstr_insert_cstr(wstring_t *wstr, const char *insert, unsigned n, unsigned index);
  93
  94 /**
  95  * Inserts the given wchar at the given index.
  96  * @param n, max length of the insert string
  97  */
  98 int wstr_insert(wstring_t *wstr, wchar_t c, unsigned index);
  99
 100 /**
 101  * Returns a cwtring copy of the given wstring_t.
 102  * @note The cwstring is allocated using malloc
 103  */
 104 wchar_t* wstr_to_cwstr(const wstring_t *wstr);
 105
 106 /**
 107  * Returns a pointer to the internal buffer of the wstring_t.
 108  * A null terminator will be appended.
 109  */
 110 const wchar_t* wstr_get_buffer(wstring_t *wstr);
 111
 112 /**
 113  * Returns a substring of the wstring_t in the range [start, end)
 114  */
 115 wchar_t* wstr_substring(wstring_t *wstr, unsigned start, unsigned end);
 116
 117 /**
 118  * Creates a copy of the given wstring_t
 119  */
 120 wstring_t* wstr_dup(wstring_t *wstr);
 121
 122 int wstr_cmp_cwstr(const wstring_t *wstr, const wchar_t *cwstr);
 123
 124 /**
 125  * Returns the length of the wstring_t
 126  */
 127 size_t wstr_length(const wstring_t *wstr);
 128
 129 /**
 130  * Splits the wstring_t into substrings, using the characters
 131  * in tokens as dividers.
 132  * - If str is NULL, it continues on the string passed on the
 133  *   previous call.
 134  * - The returned cstring is malloc'd, but it's saved as a static variable,
 135  *   and will be freed on the next call, or when the function it's called with
 136  *   both str and tokens as NULL.
 137  * - When it reaches the end of the string, returns the remaining. After that, it
 138  *   returns NULL until a new string is provided.
 139  */
 140 wchar_t* wstr_tok(wstring_t *wstr, wchar_t *tokens);
 141
 142 /**
 143  * Splits the wstring_t into an array of cwstr, using delim
 144  * as a delimiter.
 145  * @param wstr the string to split
 146  * @param delim the delimiter
 147  * @return an array with the string split by delim.
 148  *         The last element is NULL.
 149 */
 150 wchar_t** wstr_split(wstring_t *wstr, wchar_t *delim);
 151
 152 /**
 153  * Finds the first occurence of substr, starting at index [start_at]
 154  * @param substr string to search
 155  * @param start_at index of the wstring_t to start the search
 156  * @return Index of the first occurence of substr, or -1 if there isn't any
 157  */
 158 int wstr_find_substring(wstring_t *wstr, const wchar_t *substr, unsigned start_at);
 159
 160 /**
 161  * Replaces any occurence of substr with replacement
 162  * @param substr string to replace
 163  * @param replacement replacement for substr
 164  * @return the number of matches
 165 */
 166 int wstr_replace(wstring_t *wstr, const wchar_t *substr, const wchar_t *replacement);
 167
 168 /**
 169  * Transforms all the charcters in the wstring_t, one by one,
 170  * using the given function.
 171  */
 172 int wstr_transform(wstring_t *wstr, wchar_t(*func)(wchar_t));
 173
 174 /**
 175  * Shrinks the given string to fit it's content
 176  */
 177 void wstr_shrink(wstring_t *wstr);
 178
 179 /**
 180  * Converts the given wstring_t into a regular wchar_t*
 181  * - The resulting string is properly NULL terminated
 182  * - The original wstring_t is not usable anymore
 183  * */
 184 wchar_t* wstr_into_cwstr(wstring_t *wstr);
 185
 186 /**
 187  * Clones the given wstring_t into a regular wchar_t*
 188  * - The resulting string is properly NULL terminated
 189  * */
 190 wchar_t* wstr_cloned_cwstr(wstring_t *wstr);
 191
 192 /**
 193  * Clears the wstring_t, without shrinking or freeing the buffer.
 194  */
 195 void wstr_clear(wstring_t *wstr);
 196
 197 /**
 198  * Frees all the memory allocated for the string
 199  */
 200 void wstr_free(wstring_t *wstr, ...);
 201
 202 #define wstr_free(...) wstr_free(__VA_ARGS__, NULL)
 203
 204 /**
 205  * Frees multiple wstring_ts at once
 206  * @param n number of wstring_t to free
 207  * @param ... all the wstring_ts to free
 208 */
 209 void wstr_free_all(unsigned int n, ...);
 210
 211 #endif // WSTR_H