Finished last commit (cleanup, fixes).

1 files changed, 43 insertions, 40 deletions

diff --git a/docs/csubstr_api.md b/docs/csubstr_api.md
index 925c69db..6cf76cf7 100644
--- a/docs/csubstr_api.md
+++ b/docs/csubstr_api.md
@@ -1,15 +1,16 @@
 # STC [csubstr](../include/stc/csubstr.h): String View
 ![String](pics/string.jpg)
 
-The type **csubstr** is a string view and can refer to a constant contiguous sequence of char-elements with the first
-element of the sequence at position zero. The implementation holds two members: a pointer to constant char and a size.
+The type **csubstr** is a non-null terminated string view and can refer to a constant contiguous sequence of
+char-elements with the first element of the sequence at position zero. The implementation holds two members:
+a pointer to constant char and a size.
 
-**csubstr** is non-null terminated, and therefore not a replacent for `const char*` - see [csview](csview_api.md) for
-that. **csubstr** never allocates memory, and therefore need not be destructed.
-Its lifetime is limited by the source string storage. It keeps the length of the string, and does not need to call
-*strlen()* to acquire the length.
+Because **csubstr** is non-null terminated, it is not a replacent for `const char*` - see [csview](csview_api.md)
+for that. **csubstr** never allocates memory, and therefore need not be destructed. Its lifetime is limited by
+the source string storage. It keeps the length of the string, and does not need to call *strlen()* to acquire
+the length.
 
-Note: a **csubstr** may ***not be null-terminated***, and must therefore be printed this way:
+Note: a **csubstr** must be printed the following way:
 ```c
 printf("%.*s", c_SS(sstr))
 ```
@@ -29,47 +30,49 @@ All csubstr definitions and prototypes are available by including a single heade
 ## Methods
 
 ```c
-csubstr         c_ss(const char literal_only[]);                        // construct from literal, no strlen()
-csubstr         c_ss(const char* str, intptr_t n);                      // construct from str and length n
+csubstr         c_ss(const char literal_only[]);                         // construct from literal, no strlen()
+csubstr         c_ss(const char* str, intptr_t n);                       // construct from str and length n
 csubstr         csubstr_from(const char* str);                           // construct from const char*
 csubstr         csubstr_from_n(const char* str, intptr_t n);             // alias for c_ss(str, n)
 
-intptr_t        csubstr_size(csubstr sv);
-bool            csubstr_empty(csubstr sv);
+intptr_t        csubstr_size(csubstr ss);
+bool            csubstr_empty(csubstr ss);
 void            csubstr_clear(csubstr* self);
 
-bool            csubstr_equals(csubstr sv, csubstr sv2);
-intptr_t        csubstr_find(csubstr sv, const char* str);
-intptr_t        csubstr_find_ss(csubstr sv, csubstr find);
-bool            csubstr_contains(csubstr sv, const char* str);
-bool            csubstr_starts_with(csubstr sv, const char* str);
-bool            csubstr_ends_with(csubstr sv, const char* str);
+bool            csubstr_equals(csubstr ss, const char* str);
+intptr_t        csubstr_equals_ss(csubstr ss, csubstr find);
+intptr_t        csubstr_find(csubstr ss, const char* str);
+intptr_t        csubstr_find_ss(csubstr ss, csubstr find);
+bool            csubstr_contains(csubstr ss, const char* str);
+bool            csubstr_starts_with(csubstr ss, const char* str);
+bool            csubstr_ends_with(csubstr ss, const char* str);
+csubstr         csubstr_substr(csubstr ss, intptr_t pos, intptr_t n);
+csubstr         csubstr_slice(csubstr ss, intptr_t pos1, intptr_t pos2);
 
-csubstr         csubstr_substr_ex(csubstr sv, intptr_t pos, intptr_t n);  // negative pos count from end
-csubstr         csubstr_slice_ex(csubstr sv, intptr_t p1, intptr_t p2);   // negative p1, p2 count from end
-csubstr         csubstr_token(csubstr sv, const char* sep, intptr_t* start); // *start > sv.size after last token
+csubstr         csubstr_substr_ex(csubstr ss, intptr_t pos, intptr_t n);     // negative pos count from end
+csubstr         csubstr_slice_ex(csubstr ss, intptr_t pos1, intptr_t pos2);  // negative pos1, pos2 count from end
+csubstr         csubstr_token(csubstr ss, const char* sep, intptr_t* start); // *start > ss.size after last token
 ```
 
 #### UTF8 methods
 ```c
-intptr_t        csubstr_u8_size(csubstr sv);
-csubstr         csubstr_u8_substr(csubstr sv, intptr_t bytepos, intptr_t u8len);
-bool            csubstr_valid_utf8(csubstr sv);                           // requires linking with src/utf8code.c
-
+intptr_t        csubstr_u8_size(csubstr ss);
+csubstr         csubstr_u8_substr(csubstr ss, intptr_t bytepos, intptr_t u8len);
+bool            csubstr_valid_utf8(csubstr ss);                              // requires linking with src/utf8code.c
+ 
 csubstr_iter    csubstr_begin(const csubstr* self);
 csubstr_iter    csubstr_end(const csubstr* self);
-void            csubstr_next(csubstr_iter* it);                           // utf8 codepoint step, not byte!
+void            csubstr_next(csubstr_iter* it);                              // utf8 codepoint step, not byte!
 csubstr_iter    csubstr_advance(csubstr_iter it, intptr_t n);
 ```
 
-#### Extended cstr methods
+#### cstr methods returning csubstr
 ```c
+csubstr         cstr_slice(const cstr* self, intptr_t pos1, intptr_t pos2);
+csubstr         cstr_slice_ex(const cstr* self, intptr_t pos1, intptr_t pos2); // see csubstr_slice_ex()
 csubstr         cstr_substr(const cstr* self, intptr_t pos, intptr_t n);
-csubstr         cstr_substr_ex(const cstr* s, intptr_t pos, intptr_t n); // negative pos count from end
+csubstr         cstr_substr_ex(const cstr* self, intptr_t pos, intptr_t n);    // see csubstr_substr_ex()
 csubstr         cstr_u8_substr(const cstr* self, intptr_t bytepos, intptr_t u8len);
-
-csubstr         cstr_slice(const cstr* self, intptr_t p1, intptr_t p2);
-csubstr         cstr_slice_ex(const cstr* s, intptr_t p, intptr_t q);    // negative p or q count from end
 ```
 #### Iterate tokens with *c_fortoken*, *c_fortoken_ss*
 
@@ -99,7 +102,7 @@ uint64_t        csubstr_hash(const csubstr* x);
 
 | Name           | Value                | Usage                                        |
 |:---------------|:---------------------|:---------------------------------------------|
-| `c_SS(sv)`     | printf argument      | `printf("sv: %.*s\n", c_SS(sv));`            |
+| `c_SS(ss)`     | printf argument      | `printf("ss: %.*s\n", c_SS(ss));`            |
 
 ## Example
 ```c
@@ -109,18 +112,18 @@ uint64_t        csubstr_hash(const csubstr* x);
 
 int main(void)
 {
-    cstr str1 = cstr_lit("We think in generalities, but we live in details.");
-                                                            // (quoting Alfred N. Whitehead)
+    cstr str1 = cstr_from("We think in generalities, but we live in details.");
+                                                        // (quoting Alfred N. Whitehead)
 
-    csubstr sv1 = cstr_substr_ex(&str1, 3, 5);               // "think"
-    intptr_t pos = cstr_find(&str1, "live");                // position of "live" in str1
-    csubstr sv2 = cstr_substr_ex(&str1, pos, 4);             // get "live"
-    csubstr sv3 = cstr_slice_ex(&str1, -8, -1);              // get "details"
+    csubstr ss1 = cstr_substr_ex(&str1, 3, 5);          // "think"
+    intptr_t pos = cstr_find(&str1, "live");            // position of "live" in str1
+    csubstr ss2 = cstr_substr_ex(&str1, pos, 4);        // get "live"
+    csubstr ss3 = cstr_slice_ex(&str1, -8, -1);         // get "details"
     printf("%.*s %.*s %.*s\n",
-        c_SS(sv1), c_SS(sv2), c_SS(sv3));
+        c_SS(ss1), c_SS(ss2), c_SS(ss3));
     cstr s1 = cstr_lit("Apples are red");
-    cstr s2 = cstr_from_ss(cstr_substr_ex(&s1, -3, 3));     // "red"
-    cstr s3 = cstr_from_ss(cstr_substr_ex(&s1, 0, 6));      // "Apples"
+    cstr s2 = cstr_from_ss(cstr_substr_ex(&s1, -3, 3)); // "red"
+    cstr s3 = cstr_from_ss(cstr_substr_ex(&s1, 0, 6));  // "Apples"
     printf("%s %s\n", cstr_str(&s2), cstr_str(&s3));
 
     c_drop(cstr, &str1, &s1, &s2, &s3);