From 4a415ed56dcfcc8b5642e5d3c31a7efada96712b Mon Sep 17 00:00:00 2001 From: Tyge Løvset Date: Thu, 3 Dec 2020 12:03:22 +0100 Subject: Simplified API for cstr --- docs/cstr_api.md | 104 ++++++++++++++++++++++--------------------------------- 1 file changed, 41 insertions(+), 63 deletions(-) diff --git a/docs/cstr_api.md b/docs/cstr_api.md index 3860ced2..6815abfe 100644 --- a/docs/cstr_api.md +++ b/docs/cstr_api.md @@ -26,7 +26,6 @@ All cstr definitions and prototypes may be included in your C source file by inc ``` ## Methods -### Construction and destruction ```c (1) cstr_t cstr_init(void); (2) cstr_t cstr_with_capacity(size_t cap); @@ -37,23 +36,19 @@ All cstr definitions and prototypes may be included in your C source file by inc (7) cstr_t cstr_clone(cstr_t s); (8) void cstr_del(cstr_t *self); ``` -(1) Create an empty cstr_t, (2) with capacity `cap`. (3) Create a cstr_t by repeating the `fill` character `len` times. -(4) Construct a cstr_t from `str`, and (5) limit the length by `len` and `strlen(str)`. -(6) Construct a string from a formatting string `fmt` with arguments, using `printf()` formatting. +(1) Create an empty string, (2) with capacity. (3) Create a string by repeating `fill` character `len` times. +(4) Construct a string from `str`, and (5) limit the length by `len` and `strlen(str)`. +(6) Construct a string from the format specified by `fmt` and arguments, using `printf()` formatting. (7) Construct a new string by cloning another string. (8) Free the allocated memory used by string. - -### Get string properties ```c -(1) size_t cstr_size(cstr_t s); -(2) size_t cstr_length(cstr_t s); -(3) size_t cstr_capacity(cstr_t s); -(4) bool cstr_empty(cstr_t s); + size_t cstr_size(cstr_t s); + size_t cstr_length(cstr_t s); + size_t cstr_capacity(cstr_t s); + bool cstr_empty(cstr_t s); (5) char* cstr_front(cstr_t* self); (6) char* cstr_back(cstr_t* self); ``` -These returns properties of a string. `cstr_front()` and `cstr_back()` returns reference, ie. pointer to the character. - -### String resource management and ownership +These returns properties of a string. (5-6) returns reference, ie. pointer to the char. ```c (1) size_t cstr_reserve(cstr_t* self, size_t capacity); (2) void cstr_resize(cstr_t* self, size_t len, char fill); @@ -63,11 +58,9 @@ These returns properties of a string. `cstr_front()` and `cstr_back()` returns r (6) cstr_t* cstr_take(cstr_t* self, cstr_t s); (7) cstr_t cstr_move(cstr_t* self); ``` -(4) Assign `str` to `*self`, (5) assign substring `str` limited by `len` and `strlen(str)`. -(6) Take the constructed or moved string `s`, i.e., no allocation takes place. -(7) Explicitly move `*self` to the caller of the method; `*self` becomes an empty string after move. - -### Append, insert replace, and erase strings or substrings +(1-3) Reserve, resize, clear string. (4) Assign `str` to string, (5) assign substring `str` limited by +`len` and `strlen(str)`. (6) Take the constructed or moved string `s`, i.e., no allocation takes place. +(7) Explicitly move string to the caller of the method; string becomes empty after move. ```c (1) cstr_t* cstr_append(cstr_t* self, const char* str); (2) cstr_t* cstr_append_n(cstr_t* self, const char* str, size_t len); @@ -79,64 +72,49 @@ These returns properties of a string. `cstr_front()` and `cstr_back()` returns r (8) void cstr_replace(cstr_t* self, size_t pos, size_t len, const char* str); (9) void cstr_replace_n(cstr_t* self, size_t pos, size_t len, const char* str, size_t n); ``` -(1) Append `str` to `*self`. (2) Append substring `str` limited by `len`. (3), Append character `ch`. +(1) Append `str` to stirng. (2) Append substring `str` limited by `len`. (3), Append character `ch`. (4) Erase last character. (5) Insert string at a positions, (6) string limited by n characters. (7) Erase n characters at position pos. (8) Replace len characters at position pos with str, (9) replacement str limited by n characters. - - -### String comparisons and search, case sensitive and insensitive ```c -(1) int cstr_compare(const cstr_t *s1, const cstr_t *s2); -(2) bool cstr_equals(cstr_t s, const char* str); -(3) bool cstr_equals_s(cstr_t s, cstr_t s2); -(4) bool cstr_iequals(cstr_t s, const char* str); -(5) size_t cstr_find(cstr_t s, const char* substr); -(6) size_t cstr_find_n(cstr_t s, const char* substr, size_t pos, size_t nlen); -(7) size_t cstr_ifind_n(cstr_t s, const char* substr, size_t pos, size_t nlen); -(8) bool cstr_contains(cstr_t s, const char* substr); -(9) bool cstr_icontains(cstr_t s, const char* substr); -(10) bool cstr_begins_with(cstr_t s, const char* substr); -(11) bool cstr_ibegins_with(cstr_t s, const char* substr); -(12) bool cstr_ends_with(cstr_t s, const char* substr); -(13) bool cstr_iends_with(cstr_t s, const char* substr); + int cstr_compare(const cstr_t *s1, const cstr_t *s2); + bool cstr_equals(cstr_t s, const char* str); + bool cstr_equals_s(cstr_t s, cstr_t s2); + bool cstr_iequals(cstr_t s, const char* str); + size_t cstr_find(cstr_t s, const char* substr); + size_t cstr_find_n(cstr_t s, const char* substr, size_t pos, size_t nlen); + size_t cstr_ifind_n(cstr_t s, const char* substr, size_t pos, size_t nlen); + bool cstr_contains(cstr_t s, const char* substr); + bool cstr_icontains(cstr_t s, const char* substr); + bool cstr_begins_with(cstr_t s, const char* substr); + bool cstr_ibegins_with(cstr_t s, const char* substr); + bool cstr_ends_with(cstr_t s, const char* substr); + bool cstr_iends_with(cstr_t s, const char* substr); ``` -These are mostly self-explainatory. Methods prefixed by i does case-insensitive search. - -### Iterator methods +Methods prefixed by i does case-insensitive search. ```c -(1) cstr_iter_t cstr_begin(cstr_t* self); -(2) cstr_iter_t cstr_end(cstr_t* self); -(3) void cstr_next(cstr_iter_t* it); -(4) char* cstr_itval(cstr_iter_t it); + cstr_iter_t cstr_begin(cstr_t* self); + cstr_iter_t cstr_end(cstr_t* self); + void cstr_next(cstr_iter_t* it); + char* cstr_itval(cstr_iter_t it); ``` -The general macro `c_foreach` uses these method for iterating, e.g. `c_foreach (i, cstr, mystr) printf("%c", *i.val);`. -This is equivalent to `for (size_t i=0; i