1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
|
# STC [csview](../include/stc/csview.h): Null-terminated UTF8 String View
The type **csview** is a ***null-terminated*** string view and refers 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. See [csubstr](csubstr_api.md) for a ***non null-terminated***
string view/span type.
Because **csview** is null-terminated, it can be an efficient replacent for `const char*`. It 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, i.e. no need to call *strlen()* for various operations.
## Header file
All csview definitions and prototypes are available by including a single header file.
```c
#define i_implement
#include <stc/cstr.h>
#include <stc/csview.h> // after cstr.h: include extra cstr-csview functions
```
## Methods
```c
csview c_sv(const char literal_only[]); // construct from literal, no strlen()
csview csview_from(const char* str); // construct from const char*
intptr_t csview_size(csview sv);
bool csview_empty(csview sv); // check if size == 0
void csview_clear(csview* self);
csubstr csview_ss(csview sv); // convert to csubstr type
bool csview_equals(csview sv, const char* str);
intptr_t csview_find(csview sv, const char* str);
bool csview_contains(csview sv, const char* str);
bool csview_starts_with(csview sv, const char* str);
bool csview_ends_with(csview sv, const char* str);
```
#### UTF8 methods
```c
intptr_t csview_u8_size(csview sv);
bool csview_valid_utf8(csview sv); // depends on src/utf8code.c
csview_iter csview_begin(const csview* self);
csview_iter csview_end(const csview* self);
void csview_next(csview_iter* it); // utf8 codepoint step, not byte!
csview_iter csview_advance(csview_iter it, intptr_t n);
// from utf8.h
intptr_t utf8_size(const char *s);
intptr_t utf8_size_n(const char *s, intptr_t nbytes); // number of UTF8 codepoints within n bytes
const char* utf8_at(const char *s, intptr_t index); // from UTF8 index to char* position
intptr_t utf8_pos(const char* s, intptr_t index); // from UTF8 index to byte index position
unsigned utf8_chr_size(const char* s); // UTF8 character size: 1-4
// implemented in src/utf8code.c:
bool utf8_valid(const char* s);
bool utf8_valid_n(const char* s, intptr_t nbytes);
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); // codepoint value of character at s
uint32_t utf8_peek_off(const char* s, int offset); // codepoint value at utf8 pos (may be negative)
```
#### Helper methods
```c
int csview_cmp(const csview* x, const csview* y);
int csview_icmp(const csview* x, const csview* y); // depends on src/utf8code.c:
bool csview_eq(const csview* x, const csview* y);
uint64_t csview_hash(const csview* x);
```
## Types
| Type name | Type definition | Used to represent... |
|:----------------|:-------------------------------------------|:-------------------------|
| `csview` | `struct { const char *str; intptr_t size; }` | The string view type |
| `csview_value` | `char` | The string element type |
| `csview_iter` | `struct { csview_value *ref; }` | UTF8 iterator |
## Example: UTF8 iteration and case conversion
```c
#define i_import
#include <stc/cstr.h>
#include <stc/csview.h>
int main(void)
{
cstr str = cstr_from("Liberté, égalité, fraternité.");
csview sv = cstr_sv(&str);
c_foreach (i, csview, sv)
printf("%.*s ", c_SS(i.u8.chr));
puts("");
cstr_uppercase(&str);
printf("%s\n", cstr_str(&str));
cstr_drop(&str);
}
```
Output:
```
L i b e r t é , é g a l i t é , f r a t e r n i t é .
LIBERTÉ, ÉGALITÉ, FRATERNITÉ.
```
### Example 2: UTF8 replace
```c
#define i_import // include dependent utf8 definitions.
#include <stc/cstr.h>
int main(void)
{
cstr s1 = cstr_lit("hell😀 w😀rld");
cstr_u8_replace_at(&s1, cstr_find(&s1, "😀rld"), 1, c_sv("ø"));
printf("%s\n", cstr_str(&s1));
c_foreach (i, cstr, s1)
printf("%.*s,", c_SS(i.u8.chr)); // u8.chr is a csubstr
cstr_drop(&s1);
}
```
Output:
```
hell😀 wørld
h,e,l,l,😀, ,w,ø,r,l,d,
```
|
