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
|
# STC [csview](../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);
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));` |
## Container adaptors
```
using_cvec_sv()
using_cdeq_sv()
using_clist_sv()
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);
// cvec<cstr> with csview as convertion type
using_cvec_sv();
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);
// cvec of cstr elements, using csview as "emplace" type
c_var (cvec_sv, vec, { // defines vec with 3 cstr elements.
c_lit("Element 1"), // will be converted to cstr.
c_lit("Element 2"),
c_lit("Element 3")
});
c_defer (cvec_sv_del(&vec)) // defer destruction to end of block.
{
// push constructed cstr directly
cvec_sv_push_back(&vec, cstr_lit("Second last element"));
// emplace constructs cstr from a csview
cvec_sv_emplace_back(&vec, c_lit("Last element"));
c_foreach (i, cvec_sv, vec)
printf("%s\n", i.ref->str);
}
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("gone mad"), 300);
// 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
Great
Fantastic
Sensational
Second last element
Last element
world: 200
```
### Example 2: string view tokensizer
Splits strings into tokens. **No** memory allocations, *strlen()*, or string zero-termination dependency.
```c
#include <stc/csview.h>
void splitstring(csview str, csview sep)
{
csview token = csview_first_token(str, sep);
for (;;) {
printf("token: \"%.*s\"\n", csview_ARG(token));
if (csview_end(&token).ref == csview_end(&str).ref) break;
token = csview_next_token(str, sep, token);
}
puts("--");
}
int main()
{
splitstring(c_lit("//This is//double slash//separated//string"), c_lit("//"));
splitstring(c_lit("This has no matching separator"), c_lit("xx"));
splitstring(c_lit("Split,this,string,now,ok,"), c_lit(","));
}
```
|
