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
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
|
# STC [csview](../include/stc/csview.h): String View
The type **csview** 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.
**csview** is 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, and does not call *strlen()*
when passing it around. It is faster when using`csview` as convertion type (raw) than `const char*` in associative
containers with cstr keys. E.g. prefer `using_cmap_svkey()` over `using_cmap_strkey()`.
Note that a **csview** may not be null-terminated, and should therefore be printed the following way:
`printf("%.*s", csview_ARG(sv))`.
See the c++ class [std::basic_string_view](https://en.cppreference.com/w/cpp/string/basic_string_view) for a functional
description.
## Header file
All csview definitions and prototypes are available by including a single header file.
```c
#include <stc/csview.h>
```
## Methods
```c
csview c_lit(const char literal_only[]); // csview from literal, no strlen()
csview c_sv(cstr s); // construct csview from cstr
csview csview_from(const char* str); // construct from (const char*)
csview csview_from_n(const char* str, size_t n); // construct
csview csview_from_s(cstr s); // same as c_sv()
csview csview_lit(const char literal_only[]); // same as c_lit()
size_t csview_size(csview sv);
size_t csview_length(csview sv);
bool csview_empty(csview sv);
void csview_clear(csview* self);
csview csview_trimmed(csview sv, size_t left, size_t right);
csview csview_trimmed_s(cstr s, size_t left, size_t right);
csview csview_first_token(csview sv, csview sep);
csview csview_next_token(csview sv, csview sep, csview token);
bool csview_equals(csview sv, csview sv2);
size_t csview_find(csview sv, csview needle);
bool csview_contains(csview sv, csview needle);
bool csview_begins_with(csview sv, csview sub);
bool csview_ends_with(csview sv, csview sub);
const char* csview_front(const csview* self);
const char* csview_back(const csview* self);
csview_iter_t csview_begin(const csview* self);
csview_iter_t csview_end(const csview* self);
void csview_next(csview_iter_t* it);
```
#### Extended cstr methods
```c
cstr cstr_from_v(csview sv);
csview cstr_to_v(const cstr* self);
cstr* cstr_assign_v(cstr* self, csview sv);
cstr* cstr_append_v(cstr* self, csview sv);
void cstr_insert_v(cstr* self, size_t pos, csview sv);
void cstr_replace_v(cstr* self, size_t pos, size_t len, csview sv);
bool cstr_equals_v(cstr s, csview sv);
size_t cstr_find_v(cstr s, csview needle);
bool cstr_contains_v(cstr s, csview needle);
bool cstr_begins_with_v(cstr s, csview sub);
bool cstr_ends_with_v(cstr s, csview sub);
```
#### Helper methods
```c
int csview_compare_ref(const csview* x, const csview* y);
bool csview_equals_ref(const csview* x, const csview* y);
uint64_t csview_hash_ref(const csview* x, size_t ignored);
```
## Types
| Type name | Type definition | Used to represent... |
|:------------------|:------------------------------------------|:-------------------------|
| `csview` | `struct { const char *str; size_t size }` | The string view type |
| `csview_value_t` | `char` | The string element type |
| `csview_iter_t` | `struct { csview_value_t *ref; }` | csview iterator |
## Constants and macros
| Name | Value | Usage |
|:-----------------|:--------------------|:----------------------------------|
| `csview_null` | same as `c_lit("")` | `sview = csview_null;` |
| `c_lit(literal)` | csview constructor | `sview = c_lit("hello, world");` |
| `csview_ARG(sv)` | printf argument | `printf("%.*s", csview_ARG(sv));` |
## Associative cstr-containers with csview emplace/lookup API
```
using_csmap_svkey(X, Mapped)
using_csmap_svkey(X, Mapped, mappedDel)
using_csmap_svkey(X, Mapped, mappedDel, mappedClone)
using_csmap_svkey(X, Mapped, mappedDel, mappedFromRaw, mappedToRaw, RawMapped)
using_csmap_sv()
using_csset_sv()
using_cmap_svkey(X, Mapped)
using_cmap_svkey(X, Mapped, mappedDel)
using_cmap_svkey(X, Mapped, mappedDel, mappedClone)
using_cmap_svkey(X, Mapped, mappedDel, mappedFromRaw, mappedToRaw, RawMapped)
using_cmap_sv()
using_cset_sv()
```
## Example
```c
#include <stc/csview.h>
#include <stc/cvec.h>
#include <stc/cmap.h>
// cmap<cstr, int> with csview as convertion type
using_cmap_svkey(si, int);
int main()
{
csview text = c_lit("The length of this literal is evaluated at compile time and stored in csview text.");
printf("%s\nLength: %zu\n\n", text.str, text.size);
c_withvar (cmap_si, map) // defines map and defers destruction.
{
cmap_si_emplace(&map, c_lit("hello"), 100);
cmap_si_emplace(&map, c_lit("world"), 200);
cmap_si_emplace(&map, c_lit("hello"), 300); // already in map, ignored
// Efficient lookup: no string allocation or strlen() takes place:
cmap_si_value_t* v = cmap_si_get(&map, c_lit("world"));
printf("\n%s: %d\n", v->first.str, v->second);
}
}
```
Output:
```
A long and winded literal string
Length: 32
world: 200
```
### Example 2: csview tokenizer (string split)
Splits strings into tokens. *print_split()* calls make **no** memory allocations, *strlen()* calls, or depends on
null-terminated strings. *string_split()* function returns a vector of cstr.
```c
#include <stc/csview.h>
#include <stc/cvec.h>
void print_split(csview str, csview sep)
{
csview token = csview_first_token(str, sep);
for (;;) {
// print non-null-terminated csview
printf("\"%.*s\"\n", csview_ARG(token));
if (csview_end(&token).ref == csview_end(&str).ref) break;
token = csview_next_token(str, sep, token);
}
}
using_cvec_str();
cvec_str string_split(csview str, csview sep)
{
cvec_str vec = cvec_str_init();
csview token = csview_first_token(str, sep);
for (;;) {
cvec_str_push_back(&vec, cstr_from_v(token));
if (csview_end(&token).ref == csview_end(&str).ref) break;
token = csview_next_token(str, sep, token);
}
return vec;
}
int main()
{
print_split(c_lit("//This is a//double-slash//separated//string"), c_lit("//"));
puts("");
print_split(c_lit("This has no matching separator"), c_lit("xx"));
puts("");
c_with (cvec_str v = string_split(c_lit("Split,this,,string,now,"), c_lit(",")), cvec_str_del(&v))
c_foreach (i, cvec_str, v)
printf("\"%s\"\n", i.ref->str);
}
```
Output:
```
""
"This is a"
"double-slash"
"separated"
"string"
"This has no matching separator"
"Split"
"this"
""
"string"
"now"
""
```
|
