comparison: docs/Writerside/topics/string.h.md
docs/Writerside/topics/string.h.md
- changeset 1673
- 0c338b80e7dd
- parent 1672
- 94360453bce4
equal
deleted
inserted
replaced
| 1672:94360453bce4 | 1673:0c338b80e7dd |
|---|---|
| 12 The following listing shows basic string functions. | 12 The following listing shows basic string functions. |
| 13 | 13 |
| 14 > To simplify documentation, we introduce the pseudo-type `AnyStr` with the meaning that | 14 > To simplify documentation, we introduce the pseudo-type `AnyStr` with the meaning that |
| 15 > any UCX string and any C string are supported. | 15 > any UCX string and any C string are supported. |
| 16 > The implementation is actually hidden behind a macro which uses `cx_strcast()` to guarantee compatibility. | 16 > The implementation is actually hidden behind a macro which uses `cx_strcast()` to guarantee compatibility. |
| 17 > Similarly we introduce `UcxStr` with the meaning that it is either a `cxstring` or a `cxmutstr`, | |
| 18 > created by `cx_strcast_m()`. | |
| 17 {style="note"} | 19 {style="note"} |
| 18 | 20 |
| 19 ```C | 21 ```C |
| 20 #include <cx/string.h> | 22 #include <cx/string.h> |
| 21 | 23 |
| 47 void cx_strfree(cxmutstr *str); | 49 void cx_strfree(cxmutstr *str); |
| 48 | 50 |
| 49 void cx_strfree_a(const CxAllocator *alloc, cxmutstr *str); | 51 void cx_strfree_a(const CxAllocator *alloc, cxmutstr *str); |
| 50 | 52 |
| 51 | 53 |
| 52 #define CX_NULLSTR cx_mutstr(NULL) | 54 #define CX_NULLSTR cx_mutstr(NULL) |
| 53 #define CX_SFMT(s) (int) (s).length, (s).ptr | 55 #define CX_SFMT(s) (int) (s).length, (s).ptr |
| 54 #define CX_PRIstr ".*s" | 56 #define CX_PRIstr ".*s" |
| 55 #define cx_strcast(s) // converts any string to cxstring | 57 #define cx_strcast(s) // converts any string to cxstring |
| 58 #define cx_strcast_m(s) // converts any string to a UcxStr | |
| 56 ``` | 59 ``` |
| 57 | 60 |
| 58 The functions `cx_str()` and `cx_mutstr()` create a UCX string from a `const char*` or a `char*` | 61 The functions `cx_str()` and `cx_mutstr()` create a UCX string from a `const char*` or a `char*` |
| 59 and compute the length with a call to stdlib `strlen()` (except for `NULL` in which case the length is set to zero). | 62 and compute the length with a call to stdlib `strlen()` (except for `NULL` in which case the length is set to zero). |
| 60 In case you already know the length, or the string is not zero-terminated, you can use `cx_strn()` or `cx_mutstrn()`. | 63 In case you already know the length, or the string is not zero-terminated, you can use `cx_strn()` or `cx_mutstrn()`. |
| 73 It is also safe to call the functions with a `NULL`-pointer, just like any other `free()`-like function. | 76 It is also safe to call the functions with a `NULL`-pointer, just like any other `free()`-like function. |
| 74 | 77 |
| 75 When you want to use a UCX string in a `printf`-like function, you can use the macro `CX_PRIstr` for the format specifier, | 78 When you want to use a UCX string in a `printf`-like function, you can use the macro `CX_PRIstr` for the format specifier, |
| 76 and the `CX_SFMT(s)` macro to expand the arguments. | 79 and the `CX_SFMT(s)` macro to expand the arguments. |
| 77 | 80 |
| 81 The macros `cx_strcast()` and `cx_strcast_m()` take any supported string (`AnyStr`) and convert it either to a `cxstring` or a `cxmutstr`. | |
| 82 While `cx_strcast()` _always_ converts to a `cxstring`, `cx_strcast_m()` decides depending on the constness of the string to return either a `cxstring` or a `cxmutstr`. | |
| 83 You should rarely need those macros in your code, as most UCX functions are already implemented behind macros that do the conversions for you. | |
| 84 | |
| 78 > When you want to convert a string _literal_ into a UCX string, you can also use the `cx_str()` function. | 85 > When you want to convert a string _literal_ into a UCX string, you can also use the `cx_str()` function. |
| 79 > With optimizations turned on, this function gets inlined and optimizes the call to `strlen()` out, giving | 86 > With optimizations turned on, this function gets inlined and optimizes the call to `strlen()` out, giving |
| 80 > you a `cxstring` structure at zero cost with the length calculated at compile-time. | 87 > you a `cxstring` structure at zero cost with the length calculated at compile-time. |
| 81 | 88 |
| 82 ## Comparison | 89 ## Comparison |
| 152 ## Find Characters and Substrings | 159 ## Find Characters and Substrings |
| 153 | 160 |
| 154 ```C | 161 ```C |
| 155 #include <cx/string.h> | 162 #include <cx/string.h> |
| 156 | 163 |
| 157 char cx_strat(cxstring str, off_t index); | 164 char cx_strat(AnyStr str, off_t index); |
| 158 | 165 |
| 159 cxstring cx_strchr(cxstring string, int chr); | 166 UcxStr cx_strchr(AnyStr string, int chr); |
| 160 | 167 |
| 161 cxstring cx_strrchr(cxstring string, int chr); | 168 UcxStr cx_strrchr(AnyStr string, int chr); |
| 162 | 169 |
| 163 cxstring cx_strstr(cxstring string, AnyStr search); | 170 UcxStr cx_strstr(AnyStr string, AnyStr search); |
| 164 | 171 |
| 165 cxstring cx_strsubs(cxstring string, size_t start); | 172 UcxStr cx_strsubs(AnyStr string, size_t start); |
| 166 | 173 |
| 167 cxstring cx_strsubsl(cxstring string, size_t start, size_t length); | 174 UcxStr cx_strsubsl(AnyStr string, size_t start, size_t length); |
| 168 | 175 |
| 169 cxstring cx_strtrim(cxstring string); | 176 UcxStr cx_strtrim(AnyStr string); |
| 170 | |
| 171 cxmutstr cx_strchr_m(cxmutstr string, int chr); | |
| 172 | |
| 173 cxmutstr cx_strrchr_m(cxmutstr string, int chr); | |
| 174 | |
| 175 cxmutstr cx_strstr_m(cxmutstr string, AnyStr search); | |
| 176 | |
| 177 cxmutstr cx_strsubs_m(cxmutstr string, size_t start); | |
| 178 | |
| 179 cxmutstr cx_strsubsl_m(cxmutstr string, size_t start, size_t length); | |
| 180 | |
| 181 cxmutstr cx_strtrim_m(cxmutstr string); | |
| 182 ``` | 177 ``` |
| 183 | 178 |
| 184 The function `cx_strat()` returns the character at the specified `index`. | 179 The function `cx_strat()` returns the character at the specified `index`. |
| 185 When the `index` is negative, the characters are counted from the end of the string. | 180 When the `index` is negative, the characters are counted from the end of the string. |
| 186 When the `index` is out of bounds, the zero-character is returned. | 181 When the `index` is out of bounds, the zero-character is returned. |
