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

2 files changed, 64 insertions, 64 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:
diff --git a/docs/csview_api.md b/docs/csview_api.md
index 49f7cb70..e6a89d5e 100644
--- a/docs/csview_api.md
+++ b/docs/csview_api.md
@@ -27,22 +27,21 @@ All csview definitions and prototypes are available by including a single header
 
 ```c
 csview          c_sv(const char literal_only[]);                    // alias for csview_new
+csview          c_sv(const char* str, size_t n);                    // overloaded csview constructor.
 csview          csview_new(const char literal_only[]);              // construct from literal, no strlen()
 csview          csview_from(const char* str);                       // construct from const char*
-csview          csview_from_s(const cstr* s);                       // construct from cstr
-csview          csview_from_n(const char* str, size_t n);           // construct 
 void            csview_clear(csview* self);
 
 size_t          csview_size(csview sv);
 bool            csview_empty(csview sv);
 
 bool            csview_equals(csview sv, csview sv2);
-size_t          csview_find(csview sv, csview needle);
-bool            csview_contains(csview sv, csview needle);
+size_t          csview_find(csview sv, csview search);
+bool            csview_contains(csview sv, csview search);
 bool            csview_starts_with(csview sv, csview sub);
 bool            csview_ends_with(csview sv, csview sub);
 
-// requires i_implement defined before one include of csview.h
+// requires i_implement defined before inclusion of csview.h
 csview          csview_substr_ex(csview sv, intptr_t pos, size_t n);   // negative pos count from end
 csview          csview_slice_ex(csview sv, intptr_t p1, intptr_t p2);  // negative p1, p2 count from end
 csview          csview_token(csview sv, csview sep, size_t* start);    // see split example below.
@@ -50,8 +49,9 @@ csview          csview_token(csview sv, csview sep, size_t* start);    // see sp
 
 #### UTF8 methods
 ```c
-size_t          csview_u8size(csview sv);
-csview          csview_substr_u8(csview sv, size_t u8pos, size_t u8len);
+size_t          csview_u8_size(csview sv);
+csview          csview_u8_substr(csview sv, size_t u8pos, size_t u8len);
+csview          csview_u8_slice(csview sv, size_t u8p1, size_t u8p2);
 
 csview_iter     csview_begin(const csview* self);
 csview_iter     csview_end(const csview* self);
@@ -60,14 +60,14 @@ void            csview_next(csview_iter* it);                          // utf8 c
 // requires linking with src/utf8code.c:
 bool            csview_valid_utf8(csview sv);
 
-// from utf8.h/utf8code.c:
+// from utf8.h, linking src/utf8code.c:
 bool            utf8_valid(const char* s);
 bool            utf8_valid_n(const char* s, size_t nbytes);
 size_t          utf8_size(const char *s);
 size_t          utf8_size_n(const char *s, size_t nbytes);          // number of UTF8 codepoints within n bytes
 const char*     utf8_at(const char *s, size_t index);               // from UTF8 index to char* position
 size_t          utf8_pos(const char* s, size_t index);              // from UTF8 index to byte index position
-unsigned        utf8_chr_size(const char* s);                       // 0-4 (0 if s[0] is illegal utf8)
+unsigned        utf8_chr_size(const char* s);                       // 0-4 (0 if s[0] means illegal utf8)
 uint32_t        utf8_decode(utf8_decode_t *d, uint8_t byte);        // decode next byte to utf8, return state.
 unsigned        utf8_encode(char *out, uint32_t codepoint);         // encode unicode cp into out buffer
 uint32_t        utf8_peek(const char* s, int pos);                  // codepoint value at utf8 pos (may be negative)
@@ -75,22 +75,13 @@ uint32_t        utf8_peek(const char* s, int pos);                  // codepoint
 
 #### Extended cstr methods
 ```c
-cstr            cstr_from_sv(csview sv);                            // construct cstr from csview
-csview          cstr_sv(const cstr* self);                          // convert to csview from const cstr*
-
-csview          cstr_substr(const cstr* s, intptr_t pos, size_t n); // negative pos count from end
-csview          cstr_slice(const cstr* s, intptr_t p, intptr_t q);  // negative p or q count from end
-
-csview          cstr_assign_sv(cstr* self, csview sv);              // return csview of assigned cstr
-void            cstr_append_sv(cstr* self, csview sv);
-void            cstr_insert_sv(cstr* self, size_t pos, csview sv);
-void            cstr_replace_sv(cstr* self, size_t pos, size_t len, csview sv);
-
-bool            cstr_equals_sv(cstr s, csview sv);
-size_t          cstr_find_sv(cstr s, csview needle);
-bool            cstr_contains_sv(cstr s, csview needle);
-bool            cstr_starts_with_sv(cstr s, csview sub);
-bool            cstr_ends_with_sv(cstr s, csview sub);
+csview          cstr_substr(const cstr* self, size_t pos, size_t n);
+csview          cstr_substr_ex(const cstr* s, intptr_t pos, size_t n); // negative pos count from end
+csview          cstr_u8_substr(const cstr* self, size_t u8pos, size_t u8len);
+
+csview          cstr_slice(const cstr* self, size_t p1, size_t p2);
+csview          cstr_slice_ex(const cstr* s, intptr_t p, intptr_t q);  // negative p or q count from end
+csview          cstr_u8_slice(const cstr* self, size_t u8p1, size_t u8p2);
 ```
 
 #### Helper methods
@@ -115,8 +106,8 @@ uint64_t        csview_hash(const csview* x);
 |:---------------|:---------------------|:---------------------------------------------|
 | `csview_null`  | same as `c_sv("")`   | `sview = csview_null;`                       |
 | `csview_npos`  | same as `cstr_npos`  |                                              |
-| `c_PRIsv`      | printf format        |                                              |
-| `c_ARGsv(sv)`  | printf argument      | `printf("sv: %" c_PRIsv "\n", c_ARGsv(sv));` |
+| `c_PRIsv`      | `".*s"`              | `printf("sv: %" c_PRIsv "\n", c_ARGsv(sv));` |
+| `c_ARGsv(sv)`  | printf argument      | `printf("sv: %.*s\n", c_ARGsv(sv));`         |
 
 ## Example
 ```c
@@ -157,18 +148,18 @@ int main()
 {
     c_auto (cstr, s1) {
         s1 = cstr_new("hell😀 w😀rld");
-        cstr_replace_sv(&s1, utf8_substr(cstr_str(&s1), 7, 1), c_sv("x"));
+        cstr_u8_replace_at(&s1, 7, 1, c_sv("ø"));
         printf("%s\n", cstr_str(&s1));
 
         c_foreach (i, cstr, s1)
-            printf("%" c_PRIsv ",", c_ARGsv(i.chr));
+            printf("%.*s,", c_ARGsv(i.chr));
     }
 }
 ```
 Output:
 ```
-hell😀 wxrld
-h,e,l,l,😀, ,w,x,r,l,d,
+hell😀 wørld
+h,e,l,l,😀, ,w,ø,r,l,d,
 ```
 
 ### Example 3: csview tokenizer (string split)