Simplified API for cstr

1 files 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<cstr_size(mystr); ++i) printf("%c", mystr.str[i])`.
-
-### Other string methods
-
+Iterator methods, typically used via the general macro `c_foreach`.
 ```c
 (1)     bool         cstr_getline(cstr_t *self, FILE *stream);
 (2)     bool         cstr_getdelim(cstr_t *self, int delim, FILE *stream);
 ```
-(1,2) Reads a line of text from stream and stores it in `*self`. Line is separated by delim, which is '\n' in (1).
-
-### Helper methods
-```c
-(1)     const char*  cstr_to_raw(const cstr_t* x);
-(2)     int          cstr_compare_raw(const char** x, const char** y);
-(3)     bool         cstr_equals_raw(const char** x, const char** y);
-(4)     uint32_t     cstr_hash_raw(const char* const* spp, size_t ignored);
-```
-These methods may be used by other container types.
-
-### Non-members
+Reads a line of text from stream and stores it in string. Line is separated by delim, which is '\n' in (1).
 ```c
-(1)     int          c_strncasecmp(const char* s1, const char* s2, size_t n);
-(2)     char*        c_strnfind(const char* str, const char* needle, size_t nmax);
-(3)     char*        c_istrnfind(const char* str, const char* needle, size_t nmax);
-(4)     uint32_t     c_string_hash(const char* str);
+        const char*  cstr_to_raw(const cstr_t* x);
+        int          cstr_compare_raw(const char** x, const char** y);
+        bool         cstr_equals_raw(const char** x, const char** y);
+        uint32_t     cstr_hash_raw(const char* const* spp, size_t ignored);
+        int          c_strncasecmp(const char* s1, const char* s2, size_t n);
+        char*        c_strnfind(const char* str, const char* needle, size_t nmax);
+        char*        c_istrnfind(const char* str, const char* needle, size_t nmax);
+        uint32_t     c_string_hash(const char* str);
 ```
+Helper methods, used by other container types.
 
 ## Example
 ```c