VERSION 3.8 BETA: Some changes in cstr / csview APIs: replace* / find*, *_u8(). . See README.md

1 files changed, 42 insertions, 33 deletions

diff --git a/docs/cstr_api.md b/docs/cstr_api.md
index 7afdcf77..a05dc1ae 100644
--- a/docs/cstr_api.md
+++ b/docs/cstr_api.md
@@ -3,16 +3,16 @@
 
 A **cstr** object represent sequences of characters. It supports an interface similar to that of a standard container of bytes, but adding features specifically designed to operate with strings of single-byte characters, terminated by the null character.
 
-**cstr** has basic support for *UTF8* encoded strings, and has a set of compact and efficient functions for handling case-foldings and comparisons of UTF strings. The **cstr** type uses short strings optimization (sso), which eliminates heap memory allocation for strings shorter than 24 bytes (sizeof(cstr) is also 24).
+**cstr** has basic support for *UTF8* encoded strings, and has a set of compact and efficient functions for handling case-foldings and comparisons of UTF strings.
 
-See the c++ class [std::basic_string](https://en.cppreference.com/w/cpp/string/basic_string) for a functional description.
+**cstr** uses short strings optimization (sso), which eliminates heap memory allocation for string capacity less than 24 bytes. `sizeof(cstr)` is also 24. In comparison, c++ `sizeof(std::string)` is typically 32, but sso capacity is only 15 bytes.
 
 ## Header file
 
 All cstr definitions and prototypes are available by including a single header file.
 
 ```c
-#define i_implement // optional: define in one source file only for shared symbols linking!
+#define i_implement   // define this to implement many functions as shared symbols!
 #include <stc/cstr.h>
 ```
 
@@ -21,61 +21,70 @@ All cstr definitions and prototypes are available by including a single header f
 cstr         cstr_init(void);                                         // constructor; same as cstr_null.
 cstr         cstr_new(const char literal_only[]);                     // cstr from literal; no strlen() call.
 cstr         cstr_from(const char* str);                              // constructor using strlen()
-cstr         cstr_from_n(const char* str, size_t len);                // constructor with specified length
+cstr         cstr_from_n(const char* str, size_t n);                  // constructor with n first bytes of str
+cstr         cstr_from_sv(csview sv);                                 // construct cstr from csview
 cstr         cstr_with_capacity(size_t cap);
 cstr         cstr_with_size(size_t len, char fill);                   // repeat fill len times
 cstr         cstr_from_fmt(const char* fmt, ...);                     // printf() formatting
 cstr         cstr_clone(cstr s);
 
-cstr*        cstr_take(cstr* self, cstr s);                           // take the constructed or moved string
-cstr         cstr_move(cstr* self);                                   // move string to caller, leave empty string
+cstr*        cstr_take(cstr* self, cstr s);                           // take ownership of s, i.e. don't drop s.
+cstr         cstr_move(cstr* self);                                   // move string to caller, leave self empty
 void         cstr_drop(cstr *self);                                   // destructor
 
-const char*  cstr_str(const cstr* self);                              // access to const char*
-char*        cstr_data(cstr* self);                                   // access to char*
-csview       cstr_sv(const cstr* self);                               // access to string view
-cstr_buf     cstr_buffer(cstr* self);                                 // access to mutable buffer (with capacity)
+const char*  cstr_str(const cstr* self);                              // cast to const char*
+char*        cstr_data(cstr* self);                                   // cast to mutable char*
+csview       cstr_sv(const cstr* self);                               // cast to string view
+cstr_buf     cstr_buffer(cstr* self);                                 // cast to mutable buffer (with capacity)
 
 size_t       cstr_size(cstr s);
 size_t       cstr_capacity(cstr s);
 bool         cstr_empty(cstr s);
 
-size_t       cstr_reserve(cstr* self, size_t capacity);
+char*        cstr_reserve(cstr* self, size_t capacity);               // return pointer to buffer
 void         cstr_resize(cstr* self, size_t len, char fill);
 void         cstr_shrink_to_fit(cstr* self);
 char*        cstr_append_uninit(cstr* self, size_t len);              // return ptr to uninit data
 void         cstr_clear(cstr* self);
 
 char*        cstr_assign(cstr* self, const char* str);
-char*        cstr_assign_s(cstr* self, cstr s);
-char*        cstr_assign_n(cstr* self, const char* str, size_t len);  // assign n first chars of str
-int          cstr_printf(cstr* self, const char* fmt, ...);           // printf() formatting
+char*        cstr_assign_n(cstr* self, const char* str, size_t n);    // assign n first bytes of str
+char*        cstr_assign_sv(cstr* self, csview sv)
+char*        cstr_copy(cstr* self, cstr s);                           // copy-assign a cstr
+int          cstr_printf(cstr* self, const char* fmt, ...);           // source and target must not overlap.
 
-char*        cstr_append(cstr* self, const char* app);
-char*        cstr_append_s(cstr* self, cstr app);
-char*        cstr_append_n(cstr* self, const char* app, size_t len);
+char*        cstr_append(cstr* self, const char* str);
+char*        cstr_append_n(cstr* self, const char* str, size_t n);    // append n first bytes of str
+char*        cstr_append_sv(cstr* self, csview str);
+char*        cstr_append_s(cstr* self, cstr str);
+char*        cstr_append_uninit(cstr *self, size_t len);              // append len uninitialized bytes
 
 void         cstr_insert(cstr* self, size_t pos, const char* ins);
+void         cstr_insert_sv(cstr* self, size_t pos, csview ins);
 void         cstr_insert_s(cstr* self, size_t pos, cstr ins);
-void         cstr_insert_n(cstr* self, size_t pos, const char* ins, size_t len);
 
 void         cstr_erase(cstr* self, size_t pos);
-void         cstr_erase_n(cstr* self, size_t pos, size_t len);
+void         cstr_erase_n(cstr* self, size_t pos, size_t n);         // erase n bytes from pos
 
-size_t       cstr_replace(cstr* self, const char* search, const char* repl);
-size_t       cstr_replace_from(cstr* self, size_t pos, const char* search, const char* repl);
-void         cstr_replace_at(cstr* self, size_t pos, size_t len, const char* repl);
-void         cstr_replace_s(cstr* self, size_t pos, size_t len, cstr repl);
-void         cstr_replace_with_n(cstr* self, size_t pos, size_t len, const char* repl, size_t rlen);
-void         cstr_replace_all(cstr* self, const char* search, const char* repl);
+void         cstr_replace(cstr* self, const char* search, const char* repl, unsigned count); // count==0: replace all.
+cstr         cstr_replace_sv(csview in, csview search, csview repl, unsigned count);
+void         cstr_replace_at(cstr* self, size_t pos, size_t len, const char* repl);          // replace at a position
+void         cstr_replace_at_sv(cstr* self, size_t pos, size_t len, const csview repl);
+void         cstr_replace_at_s(cstr* self, size_t pos, size_t len, cstr repl);
 
 bool         cstr_equals(cstr s, const char* str);
 bool         cstr_equals_s(cstr s, cstr s2);
 size_t       cstr_find(cstr s, const char* search);
-size_t       cstr_find_from(cstr s, size_t pos, const char* search);
+size_t       cstr_find_at(cstr s, size_t pos, const char* search);                           // search from pos
 bool         cstr_contains(cstr s, const char* search);
+
 bool         cstr_starts_with(cstr s, const char* str);
+bool         cstr_starts_with_sv(cstr s, csview sv);
+bool         cstr_starts_with_s(cstr s, cstr s);
+
 bool         cstr_ends_with(cstr s, const char* str);
+bool         cstr_ends_with_sv(cstr s, csview sv);
+bool         cstr_ends_with_s(cstr s, cstr s);
 
 bool         cstr_getline(cstr *self, FILE *stream);                  // cstr_getdelim(self, '\n', stream)
 bool         cstr_getdelim(cstr *self, int delim, FILE *stream);      // does not append delim to result
@@ -83,11 +92,12 @@ bool         cstr_getdelim(cstr *self, int delim, FILE *stream);      // does no
 
 #### UTF8 methods
 ```c
-size_t       cstr_u8size(cstr s);                                     // number of utf8 codepoints
-size_t       cstr_u8size_n(cstr s, size_t nbytes);                    // utf8 size within n bytes  
-size_t       cstr_pos_u8(cstr s, size_t u8idx);                       // byte pos offset at utf8 index
-const char*  cstr_at_u8(const cstr* self, size_t u8idx);              // char* position at utf8 index
-csview       cstr_chr_u8(const cstr* self, size_t u8idx);             // utf8 character at utf8 pos as csview
+size_t       cstr_u8_size(cstr s);                                    // number of utf8 codepoints
+size_t       cstr_u8_size_n(cstr s, size_t nbytes);                   // utf8 size within n bytes  
+size_t       cstr_u8_to_pos(cstr s, size_t u8idx);                    // byte pos offset at utf8 codepoint index
+const char*  cstr_u8_at(const cstr* self, size_t u8idx);              // char* position at utf8 codepoint index
+csview       cstr_u8_chr(const cstr* self, size_t u8idx);             // get utf8 character as a csview
+void         cstr_u8_replace_at(cstr* self, size_t u8pos, size_t u8len, csview repl); // replace at utf8 indices
 
 // iterate utf8 codepoints
 cstr_iter    cstr_begin(const cstr* self);
@@ -150,8 +160,7 @@ int main() {
     cstr_erase_n(&s1, 7, 5); // -nine
     printf("%s\n", cstr_str(&s1));
 
-    //cstr_replace_at(&s1, cstr_find(s1, "seven"), 5, "four");
-    cstr_replace(&s1, "seven", "four");
+    cstr_replace(&s1, "seven", "four", 1);
     printf("%s\n", cstr_str(&s1));
 
     // reassign: