1ustr(3) Ustr String Library ustr(3)
2
6 ustr - ustr string library functions
7
9 #include "ustr.h"
10 struct Ustr *USTR(void *);
13 struct Ustrp *USTRP(void *);
14 struct Ustr *USTR1(symbol, const char[]);
15 struct Ustr *USTR2(symbol, symbol, const char[]);
16 struct Ustr *USTR4(symbol, symbol, symbol, symbol, const char[]);
17 struct Ustr *USTR1_CHK(symbol, const char[]);
18 struct Ustr *USTR2_CHK(symbol, symbol, const char[]);
19 struct Ustr *USTR4_CHK(symbol, symbol, symbol, symbol, const char[]);
20 struct Ustr *USTRP1(symbol, const char[]);
21 struct Ustr *USTRP2(symbol, symbol, const char[]);
22 struct Ustrp *USTRP4(symbol, symbol, symbol, symbol, const char[]);
23 struct Ustr *USTRP1_CHK(symbol, const char[]);
24 struct Ustr *USTRP2_CHK(symbol, symbol, const char[]);
25 struct Ustrp *USTRP4_CHK(symbol, symbol, symbol, symbol, const char[]);
26 size_t USTR_SIZE_FIXED(size_t);
28 struct Ustr *ustr_init_fixed(void *, size_t, int, size_t);
29 struct Ustr *USTR_SC_INIT_AUTO(char[], int, size_t);
30 struct Ustr *USTR_SC_INIT_AUTO_OSTR(char[], int, size_t);
31 int ustr_assert_valid(Ustr *);
33 int ustr_assert_valid_subustr(Ustr *, size_t, size_t);
34 int USTR_CNTL_MALLOC_CHECK_BEG(int);
35 int USTR_CNTL_MALLOC_CHECK_LVL(void);
36 int USTR_CNTL_MALLOC_CHECK_MEM(void *);
37 int USTR_CNTL_MALLOC_CHECK_MEM_SZ(void *, size_t);
38 int USTR_CNTL_MALLOC_CHECK_MEM_MINSZ(void *, size_t);
39 int USTR_CNTL_MALLOC_CHECK_MEM_USTR(Ustr *);
40 int USTR_CNTL_MALLOC_CHECK_MEM_USTRP(Ustrp *);
41 int USTR_CNTL_MALLOC_CHECK_END(void);
42 int USTR_CNTL_MALLOC_CHECK_ADD(int);
43 int USTR_CNTL_MALLOC_CHECK_DEL(int);
44 size_t ustr_init_size(size_t, size_t, int, size_t);
46 struct Ustr *ustr_init_alloc(void *, size_t, size_t, size_t, int, int,
47 size_t);
48 struct Ustr *ustr_dupx_empty(size_t, size_t, int, int);
49 struct Ustr *ustr_dup_empty(void);
50 struct Ustr *ustr_dupx_undef(size_t, size_t, int, int, size_t);
51 struct Ustr *ustr_dup_undef(size_t);
52 struct Ustr *ustr_dup(const struct Ustr *);
53 struct Ustr *ustr_dupx(size_t, size_t, int, int, const struct Ustr *);
54 struct Ustr *ustr_sc_dup(struct Ustr **);
55 struct Ustr *ustr_sc_dupx(size_t, size_t, int, int, struct Ustr **);
56 struct Ustr *ustr_dup_buf(const void *, size_t);
57 struct Ustr *ustr_dupx_buf(size_t, size_t, int, int, const void *, size_t);
58 struct Ustr *ustr_dup_cstr(const char *);
59 struct Ustr *ustr_dupx_cstr(size_t, size_t, int, int, const char *);
60 struct Ustr *USTR_DUP_OSTR(const char []);
61 struct Ustr *USTR_DUP_OBJ(...);
62 struct Ustr *ustr_dup_subustr(const struct Ustr *, size_t, size_t);
63 struct Ustr *ustr_dupx_subustr(size_t, size_t, int, int, const struct Ustr
64 *, size_t, size_t);
65 struct Ustr *ustr_dup_rep_chr(char, size_t);
66 struct Ustr *ustr_dupx_rep_chr(size_t, size_t, int, int, char, size_t);
67 struct Ustr *ustr_sc_vjoin(const struct Ustr *, const struct Ustr *, const
68 struct Ustr *, va_list);
69 struct Ustr *ustr_sc_join(const struct Ustr *, const struct Ustr *, const
70 struct Ustr *, ...);
71 struct Ustr *ustr_sc_vjoinx(size_t, size_t, int, int, const struct Ustr *,
72 const struct Ustr *, const struct Ustr *,
73 va_list);
74 struct Ustr *ustr_sc_joinx(size_t, size_t, int, int, const struct Ustr *,
75 const struct Ustr *, const struct Ustr *, ...);
76 struct Ustr *ustr_sc_vconcat(const struct Ustr *, va_list);
77 struct Ustr *ustr_sc_concat(const struct Ustr *, ...);
78 struct Ustr *ustr_sc_vconcatx(size_t, size_t, int, int, const struct Ustr *,
79 va_list);
80 struct Ustr *ustr_sc_concatx(size_t, size_t, int, int, const struct Ustr *,
81 ...);
82 void ustr_free(struct Ustr *);
84 void ustrp_free(struct Ustr_pool *, struct Ustrp *);
85 void ustr_sc_free(struct Ustr **);
86 void ustr_sc_free2(struct Ustr **, struct Ustr *);
87 void ustr_sc_free_shared(struct Ustr **);
88 int ustr_del(struct Ustr **, size_t);
89 int ustr_del_subustr(struct Ustr **, size_t, size_t);
90 void ustr_sc_del(struct Ustr **);
91 int ustr_add_undef(struct Ustr **, size_t);
93 int ustr_add_buf(struct Ustr **, const void *, size_t);
94 int ustr_add_cstr(struct Ustr **, const char *);
95 int USTR_ADD_OSTR(struct Ustr **, const char []);
96 int USTR_ADD_OBJ(struct Ustr **, ...);
97 int ustr_add(struct Ustr **, const struct Ustr *);
98 int ustr_add_subustr(struct Ustr **, const struct Ustr *, size_t, size_t);
99 int ustr_add_rep_chr(struct Ustr **, char, size_t);
100 int ustr_set_undef(struct Ustr **, size_t);
102 int ustr_set_empty(struct Ustr **);
103 int ustr_set_buf(struct Ustr **, const void *, size_t);
104 int ustr_set_cstr(struct Ustr **, const char *);
105 int USTR_SET_OSTR(struct Ustr **, const char []);
106 int USTR_SET_OBJ(struct Ustr **, ...);
107 int ustr_set(struct Ustr **, const struct Ustr *);
108 int ustr_set_subustr(struct Ustr **, const struct Ustr *, size_t, size_t);
109 int ustr_set_rep_chr(struct Ustr **, char, size_t);
110 int ustr_ins_undef(struct Ustr **, size_t, size_t);
112 int ustr_ins_buf(struct Ustr **, size_t, const void *, size_t);
113 int ustr_ins_cstr(struct Ustr **, size_t, const char *);
114 int USTR_INS_OSTR(struct Ustr **, size_t, const char []);
115 int USTR_INS_OBJ(struct Ustr **, size_t, ...);
116 int ustr_ins(struct Ustr **, size_t, const struct Ustr *);
117 int ustr_ins_subustr(struct Ustr **, size_t, const struct Ustr *, size_t,
118 size_t);
119 int ustr_ins_rep_chr(struct Ustr **, size_t, char, size_t);
120 int ustr_add_vfmt_lim(struct Ustr **, size_t, const char *, va_list);
122 int ustr_add_vfmt(struct Ustr **, const char *, va_list);
123 int ustr_add_fmt_lim(struct Ustr **, size_t, const char *, ...);
124 int ustr_add_fmt(struct Ustr **, const char *, ...);
125 struct Ustr *ustr_dup_vfmt_lim(size_t, const char *, va_list);
126 struct Ustr *ustr_dup_vfmt(size_t, const char *, va_list);
127 struct Ustr *ustr_dup_fmt_lim(size_t, const char *, ...);
128 struct Ustr *ustr_dup_fmt(const char *, ...);
129 struct Ustr *ustr_dupx_fmt_lim(size_t, size_t, int, int, size_t, const char
130 *, ...);
131 struct Ustr *ustr_dupx_fmt(size_t, size_t, int, int, const char *, ...);
132 int ustr_set_vfmt_lim(struct Ustr **, size_t, const char *, va_list);
133 int ustr_set_vfmt(struct Ustr **, const char *, va_list);
134 int ustr_set_fmt_lim(struct Ustr **, size_t, const char *, ...);
135 int ustr_set_fmt(struct Ustr **, const char *, ...);
136 int ustr_ins_vfmt_lim(struct Ustr **, size_t, size_t, const char *,
137 va_list);
138 int ustr_ins_vfmt(struct Ustr **, size_t, const char *, va_list);
139 int ustr_ins_fmt_lim(struct Ustr **, size_t, size_t, const char *, ...);
140 int ustr_ins_fmt(struct Ustr **, size_t, const char *, ...);
141 int ustr_sub_vfmt_lim(struct Ustr **, size_t, size_t, const char *,
142 va_list);
143 int ustr_sub_vfmt(struct Ustr **, size_t, const char *, va_list);
144 int ustr_sub_fmt_lim(struct Ustr **, size_t, size_t, const char *, ...);
145 int ustr_sub_fmt(struct Ustr **, size_t, const char *, ...);
146 int ustr_sc_sub_vfmt_lim(struct Ustr **, size_t, size_t, size_t, const char
147 *, va_list);
148 int ustr_sc_sub_vfmt(struct Ustr **, size_t, size_t, const char *,
149 va_list);
150 int ustr_sc_sub_fmt_lim(struct Ustr **, size_t, size_t, size_t, const char
151 *, ...);
152 int ustr_sc_sub_fmt(struct Ustr **, size_t, size_t, const char *, ...);
153 size_t ustr_len(const struct Ustr *);
155 const char *ustr_cstr(const struct Ustr *);
156 char *ustr_wstr(struct Ustr *);
157 int ustr_alloc(const struct Ustr *);
158 int ustr_exact(const struct Ustr *);
159 int ustr_sized(const struct Ustr *);
160 int ustr_ro(const struct Ustr *);
161 int ustr_fixed(const struct Ustr *);
162 int ustr_enomem(const struct Ustr *);
163 int ustr_shared(const struct Ustr *);
164 int ustr_limited(const struct Ustr *);
165 int ustr_owner(const struct Ustr *);
166 size_t ustr_size(const struct Ustr *);
167 size_t ustr_size_alloc(const struct Ustr *);
168 size_t ustr_size_overhead(const struct Ustr *);
169 void ustr_conf(const struct Ustr *, size_t *, size_t *, int *, size_t *,
170 size_t *);
171 int ustr_setf_enomem_err(struct Ustr *);
173 int ustr_setf_enomem_clr(struct Ustr *);
174 int ustr_setf_share(struct Ustr *);
175 int ustr_setf_owner(struct Ustr *);
176 int ustr_cmp_buf(const struct Ustr *, const void *, size_t);
178 int ustr_cmp(const struct Ustr *, const struct Ustr *);
179 int ustr_cmp_subustr(const struct Ustr *, const struct Ustr *, size_t,
180 size_t);
181 int ustr_cmp_cstr(const struct Ustr *, const char *);
182 int ustr_cmp_fast_buf(const struct Ustr *, const void *, size_t);
183 int ustr_cmp_fast(const struct Ustr *, const struct Ustr *);
184 int ustr_cmp_fast_subustr(const struct Ustr *, const struct Ustr *, size_t,
185 size_t);
186 int ustr_cmp_fast_cstr(const struct Ustr *, const char *);
187 int ustr_cmp_case_buf(const struct Ustr *, const void *, size_t);
188 int ustr_cmp_case(const struct Ustr *, const struct Ustr *);
189 int ustr_cmp_case_subustr(const struct Ustr *, const struct Ustr *, size_t,
190 size_t);
191 int ustr_cmp_case_cstr(const struct Ustr *, const char *);
192 int ustr_cmp_eq(const struct Ustr *, const struct Ustr *);
193 int ustr_cmp_buf_eq(const struct Ustr *, const void *, size_t);
194 int ustr_cmp_subustr_eq(const struct Ustr *, const struct Ustr *, size_t,
195 size_t);
196 int ustr_cmp_cstr_eq(const struct Ustr *, const char *);
197 int ustr_cmp_case_eq(const struct Ustr *, const struct Ustr *);
198 int ustr_cmp_case_buf_eq(const struct Ustr *, const void *, size_t);
199 int ustr_cmp_case_subustr_eq(const struct Ustr *, const struct Ustr *,
200 size_t, size_t);
201 int ustr_cmp_case_cstr_eq(const struct Ustr *, const char *);
202 int ustr_cmp_prefix_eq(const struct Ustr *, const struct Ustr *);
203 int ustr_cmp_prefix_buf_eq(const struct Ustr *, const void *, size_t);
204 int ustr_cmp_prefix_cstr_eq(const struct Ustr *, const char *);
205 int ustr_cmp_prefix_subustr_eq(const struct Ustr *, const struct Ustr *,
206 size_t, size_t);
207 int ustr_cmp_case_prefix_eq(const struct Ustr *, const struct Ustr *);
208 int ustr_cmp_case_prefix_buf_eq(const struct Ustr *, const void *, size_t);
209 int ustr_cmp_case_prefix_cstr_eq(const struct Ustr *, const char *);
210 int ustr_cmp_case_prefix_subustr_eq(const struct Ustr *, const struct Ustr
211 *, size_t, size_t);
212 int ustr_cmp_suffix_eq(const struct Ustr *, const struct Ustr *);
213 int ustr_cmp_suffix_buf_eq(const struct Ustr *, const void *, size_t);
214 int ustr_cmp_suffix_cstr_eq(const struct Ustr *, const char *);
215 int ustr_cmp_suffix_subustr_eq(const struct Ustr *, const struct Ustr *,
216 size_t, size_t);
217 int ustr_cmp_case_suffix_eq(const struct Ustr *, const struct Ustr *);
218 int ustr_cmp_case_suffix_buf_eq(const struct Ustr *, const void *, size_t);
219 int ustr_cmp_case_suffix_cstr_eq(const struct Ustr *, const char *);
220 int ustr_cmp_case_suffix_subustr_eq(const struct Ustr *, const struct Ustr
221 *, size_t, size_t);
222 size_t ustr_srch_chr_fwd(const struct Ustr *, size_t, char);
224 size_t ustr_srch_chr_rev(const struct Ustr *, size_t, char);
225 size_t ustr_srch_buf_fwd(const struct Ustr *, size_t, const void *,
226 size_t);
227 size_t ustr_srch_buf_rev(const struct Ustr *, size_t, const void *,
228 size_t);
229 size_t ustr_srch_fwd(const struct Ustr *, size_t, const struct Ustr *);
230 size_t ustr_srch_rev(const struct Ustr *, size_t, const struct Ustr *);
231 size_t ustr_srch_cstr_fwd(const struct Ustr *, size_t, const char *);
232 size_t ustr_srch_cstr_rev(const struct Ustr *, size_t, const char *);
233 size_t ustr_srch_subustr_fwd(const struct Ustr *, size_t, const struct Ustr
234 *, size_t, size_t);
235 size_t ustr_srch_subustr_rev(const struct Ustr *, size_t, const struct
236 Ustr *, size_t, size_t);
237 size_t ustr_srch_case_chr_fwd(const struct Ustr *, size_t, char);
238 size_t ustr_srch_case_chr_rev(const struct Ustr *, size_t, char);
239 size_t ustr_srch_case_buf_fwd(const struct Ustr *, size_t, const void *,
240 size_t);
241 size_t ustr_srch_case_buf_rev(const struct Ustr *, size_t, const void *,
242 size_t);
243 size_t ustr_srch_case_fwd(const struct Ustr *, size_t, const struct Ustr
244 *);
245 size_t ustr_srch_case_rev(const struct Ustr *, size_t, const struct Ustr
246 *);
247 size_t ustr_srch_case_cstr_fwd(const struct Ustr *, size_t, const char *);
248 size_t ustr_srch_case_cstr_rev(const struct Ustr *, size_t, const char *);
249 size_t ustr_srch_case_subustr_fwd(const struct Ustr *, size_t, const struct
250 Ustr *, size_t, size_t);
251 size_t ustr_srch_case_subustr_rev(const struct Ustr *, size_t, const
252 struct Ustr *, size_t, size_t);
253 size_t ustr_spn_chr_fwd(const struct Ustr *, size_t, char);
255 size_t ustr_spn_chr_rev(const struct Ustr *, size_t, char);
256 size_t ustr_spn_chrs_fwd(const struct Ustr *, size_t, const char *,
257 size_t);
258 size_t ustr_spn_chrs_rev(const struct Ustr *, size_t, const char *,
259 size_t);
260 size_t ustr_spn_fwd(const struct Ustr *, size_t, const struct Ustr *);
261 size_t ustr_spn_rev(const struct Ustr *, size_t, const struct Ustr *);
262 size_t ustr_spn_cstr_fwd(const struct Ustr *, size_t, const char *);
263 size_t ustr_spn_cstr_rev(const struct Ustr *, size_t, const char *);
264 size_t ustr_cspn_chr_fwd(const struct Ustr *, size_t, char);
265 size_t ustr_cspn_chr_rev(const struct Ustr *, size_t, char);
266 size_t ustr_cspn_chrs_fwd(const struct Ustr *, size_t, const char *,
267 size_t);
268 size_t ustr_cspn_chrs_rev(const struct Ustr *, size_t, const char *,
269 size_t);
270 size_t ustr_cspn_fwd(const struct Ustr *, size_t, const struct Ustr *);
271 size_t ustr_cspn_rev(const struct Ustr *, size_t, const struct Ustr *);
272 size_t ustr_cspn_cstr_fwd(const struct Ustr *, size_t, const char *);
273 size_t ustr_cspn_cstr_rev(const struct Ustr *, size_t, const char *);
274 size_t ustr_utf8_spn_chrs_fwd(const struct Ustr *, size_t, const char *,
275 size_t);
276 size_t ustr_utf8_spn_chrs_rev(const struct Ustr *, size_t, const char *,
277 size_t);
278 size_t ustr_utf8_spn_fwd(const struct Ustr *, size_t, const struct Ustr *);
279 size_t ustr_utf8_spn_rev(const struct Ustr *, size_t, const struct Ustr *);
280 size_t ustr_utf8_spn_cstr_fwd(const struct Ustr *, size_t, const char *);
281 size_t ustr_utf8_spn_cstr_rev(const struct Ustr *, size_t, const char *);
282 size_t ustr_utf8_cspn_chrs_fwd(const struct Ustr *, size_t, const char *,
283 size_t);
284 size_t ustr_utf8_cspn_chrs_rev(const struct Ustr *, size_t, const char *,
285 size_t);
286 size_t ustr_utf8_cspn_fwd(const struct Ustr *, size_t, const struct Ustr
287 *);
288 size_t ustr_utf8_cspn_rev(const struct Ustr *, size_t, const struct Ustr
289 *);
290 size_t ustr_utf8_cspn_cstr_fwd(const struct Ustr *, size_t, const char *);
291 size_t ustr_utf8_cspn_cstr_rev(const struct Ustr *, size_t, const char *);
292 int ustr_io_get(struct Ustr **, FILE *, size_t, size_t *);
294 int ustr_io_getfile(struct Ustr **, FILE *);
295 int ustr_io_getfilename(struct Ustr **, const char *);
296 int ustr_io_getdelim(struct Ustr **, FILE *, char);
297 int ustr_io_getline(struct Ustr **, FILE *);
298 int ustr_io_put(struct Ustr **, FILE *, size_t);
299 int ustr_io_putline(struct Ustr **, FILE *, size_t);
300 int ustr_io_putfile(struct Ustr **, FILE *);
301 int ustr_io_putfileline(struct Ustr **, FILE *);
302 int ustr_io_putfilename(struct Ustr **, const char *, const char *);
303 int ustr_sub_undef(struct Ustr **, size_t, size_t);
305 int ustr_sub_buf(struct Ustr **, size_t, const void *, size_t);
306 int ustr_sub_cstr(struct Ustr **, size_t, const char *);
307 int USTR_SUB_OSTR(struct Ustr **, size_t, const char []);
308 int USTR_SUB_OBJ(struct Ustr **, size_t, ...);
309 int ustr_sub(struct Ustr **, size_t, const struct Ustr *);
310 int ustr_sub_subustr(struct Ustr **, size_t, const struct Ustr *, size_t,
311 size_t);
312 int ustr_sc_sub_undef(struct Ustr **, size_t, size_t, size_t);
313 int ustr_sc_sub_buf(struct Ustr **, size_t , size_t , const void *, size_t
314 );
315 int ustr_sc_sub_cstr(struct Ustr **, size_t, size_t, const char *);
316 int ustr_sc_sub(struct Ustr **, size_t, size_t, const struct Ustr *);
317 int ustr_sc_sub_subustr(struct Ustr **, size_t, size_t, const struct Ustr
318 *, size_t, size_t);
319 int USTR_SC_SUB_OSTR(struct Ustr **, size_t, size_t, const char []);
320 int USTR_SC_SUB_OBJ(struct Ustr **, size_t, size_t, ...);
321 size_t ustr_replace_buf(struct Ustr **, const void *, size_t, const void *,
322 size_t, size_t);
323 size_t ustr_replace_cstr(struct Ustr **, const char *, const char *,
324 size_t);
325 int ustr_replace(struct Ustr **, const struct Ustr *, const struct Ustr *,
326 size_t);
327 size_t ustr_replace_rep_chr(struct Ustr **ps1, char, size_t, char, size_t
328 nlen, size_t lim);
329 struct Ustr *ustr_split_buf(const struct Ustr *, size_t *, const void *,
331 size_t, struct Ustr *, unsigned int);
332 struct Ustr *ustr_split(const struct Ustr *, size_t *, const struct Ustr *,
333 struct Ustr *, unsigned int);
334 struct Ustr *ustr_split_cstr(const struct Ustr *, size_t *, const char *,
335 struct Ustr *, unsigned int);
336 struct Ustr *ustr_split_spn_chrs(const struct Ustr *, size_t *, const char
337 *, size_t, struct Ustr *, unsigned int);
338 struct Ustr *ustr_split_spn_cstr(const struct Ustr *, size_t *, const char
339 *, struct Ustr *, unsigned int);
340 struct Ustr *ustr_split_spn(const struct Ustr *, size_t *, const struct Ustr
341 *, struct Ustr *, unsigned int);
342 int ustr_utf8_valid(const struct Ustr *);
344 size_t ustr_utf8_len(const struct Ustr *);
345 ssize_t ustr_utf8_width(const struct Ustr *);
346 size_t ustr_utf8_chars2bytes(const struct Ustr *, size_t, size_t, size_t
347 *);
348 size_t ustr_utf8_bytes2chars(const struct Ustr *, size_t, size_t, size_t
349 *);
350 int ustr_sc_utf8_reverse(struct Ustr **);
351 uintmax_t ustr_parse_uintmaxx(const struct Ustr *, size_t, unsigned int,
353 uintmax_t, uintmax_t, const char *, size_t *,
354 unsigned int *);
355 uintmax_t ustr_parse_uintmax(const struct Ustr *, size_t, unsigned int,
356 size_t *, unsigned int *);
357 intmax_t ustr_parse_intmax(const struct Ustr *, size_t, unsigned int,
358 size_t *, unsigned int *);
359 unsigned long ustr_parse_ulongx(const struct Ustr *, size_t, unsigned
360 int, unsigned long, unsigned long, const
361 char *, size_t *, unsigned int *);
362 unsigned long ustr_parse_ulong(const struct Ustr *, size_t, unsigned int,
363 size_t *, unsigned int *);
364 long ustr_parse_long(const struct Ustr *, size_t, unsigned int, size_t *,
365 unsigned int *);
366 unsigned int ustr_parse_uint(const struct Ustr *, size_t, unsigned int,
367 size_t *, unsigned int *);
368 int ustr_parse_int(const struct Ustr *, size_t, unsigned int, size_t *,
369 unsigned int *);
370 unsigned short ustr_parse_ushort(const struct Ustr *, size_t, unsigned int,
371 size_t *, unsigned int *);
372 short ustr_parse_short(const struct Ustr *, size_t, unsigned int, size_t *,
373 unsigned int *);
374 int ustr_sc_ensure_owner(struct Ustr **);
376 char *ustr_sc_wstr(struct Ustr **);
377 char *ustr_sc_export_subustr(const struct Ustr *, size_t, size_t, void
378 *(*)(size_t));
379 char *ustr_sc_export(const struct Ustr *, void *(*)(size_t));
380 char *ustrp_sc_export_subustrp(struct Ustr_pool *, const struct Ustr *,
381 size_t, size_t, void *(*)(size_t));
382 char *ustrp_sc_export(struct Ustr_pool *, const struct Ustr *, void
383 *(*)(size_t));
384 int ustr_sc_reverse(struct Ustr **);
385 int ustr_sc_tolower(struct Ustr **);
386 int ustr_sc_toupper(struct Ustr **);
387 int ustr_sc_ltrim_chrs(struct Ustr **, const char *, size_t);
388 int ustr_sc_ltrim(struct Ustr **, const struct Ustr *);
389 int ustr_sc_ltrim_cstr(struct Ustr **, const char *);
390 int ustr_sc_rtrim_chrs(struct Ustr **, const char *, size_t);
391 int ustr_sc_rtrim(struct Ustr **, const struct Ustr *);
392 int ustr_sc_rtrim_cstr(struct Ustr **, const char *);
393 int ustr_sc_trim_chrs(struct Ustr **, const char *, size_t);
394 int ustr_sc_trim(struct Ustr **, const struct Ustr *);
395 int ustr_sc_trim_cstr(struct Ustr **, const char *);
396 int ustr_add_b_uint16(struct Ustr **, uint_least16_t);
398 int ustr_add_b_uint32(struct Ustr **, uint_least32_t);
399 int ustr_add_b_uint64(struct Ustr **, uint_least64_t);
400 uint_least16_t ustr_parse_b_uint16(const struct Ustr *, size_t);
402 uint_least32_t ustr_parse_b_uint32(const struct Ustr *, size_t);
403 uint_least64_t ustr_parse_b_uint64(const struct Ustr *, size_t);
404 int ustr_realloc(struct Ustr **, size_t);
406 int ustr_cntl_opt(int, ...);
407 struct Ustr_pool *ustr_pool_ll_make(void);
409 struct Ustr_pool *ustr_pool_make_subpool(struct Ustr_pool *);
410 void ustr_pool_free(struct Ustr_pool *);
411 void ustr_pool_clear(struct Ustr_pool *);
412
415 A very simple overview is that you can use ustr_dup_cstr() to convert
416 a C-style to a Ustr, and ustr_cstr() to convert it back. You can also
417 use USTR1() to create constant/read-only strings, and
418 USTR_SC_INIT_AUTO() to create strings that use stack space upto a cer‐
419 tain amount.
420 Use is somewhat unique in that, by default, it has an average overhead
421 of only 55% overhead over strdup(), for strings in the range of 0 to 20
422 bytes. Or, to put it another way it only uses 8 bytes to store a 2 byte
423 string where strdup() uses 3.
424
426 Function: USTR()
427 Returns: Ustr string
428 Type: struct Ustr *
429 Parameter[1]: Pointer to Ustr data
431 Type[1]: void *
432 Explanation:
434 This macro function is normally used with the empty string "".
436 Note:
438 There is basically just a simple cast behind the macro.
440 Function: USTRP()
442 Returns: Ustrp string
443 Type: struct Ustrp *
444 Parameter[1]: Pointer to Ustrp data
446 Type[1]: void *
447 Explanation:
449 This macro function is normally used with the empty string "".
451 Note:
453 There is basically just a simple cast behind the macro.
455 Function: USTR1()
457 Returns: Ustr string
458 Type: struct Ustr *
459 Parameter[1]: Encoded number of the length of Ustr string
461 Type[1]: symbol
462 Parameter[2]: Data for Ustr string
464 Type[2]: const char[]
465 Explanation:
467 This macro function simplifies the creation of read-only Ustr
469 string's. And is normally used like...
470 USTR1(\x4, "abcd")
472 ...it is worth pointing out that running with debugging turned on
474 (USTR_CONF_USE_ASSERT) will complain if the length isn't encoded cor‐
475 rectly, as in...
476 USTR1(\x3, "abcd")
478 ...here ustr_assert_valid() will fail, which is called before most
480 functions do
481 anything in debugging mode. Note also that extra debugging
482 (USTR_CONF_USE_EOS_MARK) will still catch cases like...
483 USTR1(\x3, "abc\0d")
485 ...at least using debugging is esp. important if you are putting UTF-8
487 characters into the strings.
488 Note:
490 Having ustr_ro() return true means that the Ustr cannot be written to
492 without be reallocated into allocation space ... not that ustr_add()
493 etc. will fail.
494 There is now USTR1_CHK() which performs a compile time check so you
495 can never have an invalid ustr.
496 Function: USTR2()
498 Returns: Ustr string
499 Type: struct Ustr *
500 Parameter[1]: Encoded 2nd byte of number of the length of Ustr string
502 Type[1]: symbol
503 Parameter[2]: Encoded 1st byte of number of the length of Ustr string
505 Type[2]: symbol
506 Parameter[3]: Data for Ustr string
508 Type[3]: const char[]
509 Explanation:
511 This function works in the same way as USTR1() but takes two length
513 bytes, so the read-only string can be upto 65,535 (2**16 - 1) bytes in
514 length.
515 Function: USTR4()
517 Returns: Ustr string
518 Type: struct Ustr *
519 Parameter[1]: Encoded 4th byte of number of the length of Ustr string
521 Type[1]: symbol
522 Parameter[2]: Encoded 3rd byte of number of the length of Ustr string
524 Type[2]: symbol
525 Parameter[3]: Encoded 2nd byte of number of the length of Ustr string
527 Type[3]: symbol
528 Parameter[4]: Encoded 1st byte of number of the length of Ustr string
530 Type[4]: symbol
531 Parameter[5]: Data for Ustr string
533 Type[5]: const char[]
534 Explanation:
536 This function works in the same way as USTR1() but takes four length
538 bytes, so the read-only string can be upto 2**32 - 1 bytes in length.
539 Function: USTR1_CHK()
541 Returns: Ustr string
542 Type: struct Ustr *
543 Parameter[1]: Encoded number of the length of Ustr string
545 Type[1]: symbol
546 Parameter[2]: Data for Ustr string
548 Type[2]: const char[]
549 Explanation:
551 This function works in the same way as USTR1() but it does a check
553 against the length of (Parameter[2]) using sizeof() - 1.
554 Note:
556 If the check fails the returned Ustr * will be "", so you can check
558 ustr_len() to see if you screwed something up.
559 Function: USTR2_CHK()
561 Returns: Ustr string
562 Type: struct Ustr *
563 Parameter[1]: Encoded 2nd byte of number of the length of Ustr string
565 Type[1]: symbol
566 Parameter[2]: Encoded 1st byte of number of the length of Ustr string
568 Type[2]: symbol
569 Parameter[3]: Data for Ustr string
571 Type[3]: const char[]
572 Explanation:
574 This function works in the same way as USTR2() but it does a check
576 against the length of (Parameter[2]) using sizeof() - 1.
577 Note:
579 If the check fails the returned Ustr * will be "".
581 Function: USTR4_CHK()
583 Returns: Ustr string
584 Type: struct Ustr *
585 Parameter[1]: Encoded 4th byte of number of the length of Ustr string
587 Type[1]: symbol
588 Parameter[2]: Encoded 3rd byte of number of the length of Ustr string
590 Type[2]: symbol
591 Parameter[3]: Encoded 2nd byte of number of the length of Ustr string
593 Type[3]: symbol
594 Parameter[4]: Encoded 1st byte of number of the length of Ustr string
596 Type[4]: symbol
597 Parameter[5]: Data for Ustr string
599 Type[5]: const char[]
600 Explanation:
602 This function works in the same way as USTR4() but it does a check
604 against the length of (Parameter[2]) using sizeof() - 1.
605 Note:
607 If the check fails the returned Ustr * will be "".
609 Function: USTRP1()
611 Returns: Ustr string
612 Type: struct Ustr *
613 Parameter[1]: Encoded number of the length of Ustr string
615 Type[1]: symbol
616 Parameter[2]: Data for Ustr string
618 Type[2]: const char[]
619 Explanation:
621 This function works like USTR1(), but returns a Ustrp instead.
623 Function: USTRP2()
625 Returns: Ustr string
626 Type: struct Ustr *
627 Parameter[1]: Encoded 2nd byte of number of the length of Ustr string
629 Type[1]: symbol
630 Parameter[2]: Encoded 1st byte of number of the length of Ustr string
632 Type[2]: symbol
633 Parameter[3]: Data for Ustr string
635 Type[3]: const char[]
636 Explanation:
638 This function works like USTR4(), but returns a Ustrp instead.
640 Function: USTRP4()
642 Returns: Ustrp string
643 Type: struct Ustrp *
644 Parameter[1]: Encoded 4th byte of number of the length of Ustrp string
646 Type[1]: symbol
647 Parameter[2]: Encoded 3rd byte of number of the length of Ustrp string
649 Type[2]: symbol
650 Parameter[3]: Encoded 2nd byte of number of the length of Ustrp string
652 Type[3]: symbol
653 Parameter[4]: Encoded 1st byte of number of the length of Ustrp string
655 Type[4]: symbol
656 Parameter[5]: Data for Ustr string
658 Type[5]: const char[]
659 Explanation:
661 This function works like USTR2(), but returns a Ustrp instead.
663 Function: USTRP1_CHK()
665 Returns: Ustr string
666 Type: struct Ustr *
667 Parameter[1]: Encoded number of the length of Ustr string
669 Type[1]: symbol
670 Parameter[2]: Data for Ustr string
672 Type[2]: const char[]
673 Explanation:
675 This function works like USTR1_CHK(), but returns a Ustrp instead.
677 Function: USTRP2_CHK()
679 Returns: Ustr string
680 Type: struct Ustr *
681 Parameter[1]: Encoded 2nd byte of number of the length of Ustr string
683 Type[1]: symbol
684 Parameter[2]: Encoded 1st byte of number of the length of Ustr string
686 Type[2]: symbol
687 Parameter[3]: Data for Ustr string
689 Type[3]: const char[]
690 Explanation:
692 This function works like USTR4_CHK(), but returns a Ustrp instead.
694 Function: USTRP4_CHK()
696 Returns: Ustrp string
697 Type: struct Ustrp *
698 Parameter[1]: Encoded 4th byte of number of the length of Ustrp string
700 Type[1]: symbol
701 Parameter[2]: Encoded 3rd byte of number of the length of Ustrp string
703 Type[2]: symbol
704 Parameter[3]: Encoded 2nd byte of number of the length of Ustrp string
706 Type[3]: symbol
707 Parameter[4]: Encoded 1st byte of number of the length of Ustrp string
709 Type[4]: symbol
710 Parameter[5]: Data for Ustr string
712 Type[5]: const char[]
713 Explanation:
715 This function works like USTR2_CHK(), but returns a Ustrp instead.
717
720 Function: USTR_SIZE_FIXED()
721 Returns: Size of area of memory
722 Type: size_t
723 Parameter[1]: Size of area of memory
725 Type[1]: size_t
726 Explanation:
728 This macro function is replaced by a static conversion from the max
730 length desired (Parameter[1]) to the storage size needed. In other
731 words it works out what ustr_size_overhead() will be, and adds that
732 value.
733 Note:
735 This is useful is you want a small fixed size allocation, as you can
737 declare it like so:
738 char buf[USTR_SIZE_FIXED(4)];
740 ...to give you exactly 4 bytes as a maximum, this is esp. useful if
741 you want
742 a limited (ustr_limited() == USTR_TRUE) Ustr string.
743 Function: ustr_init_fixed()
745 Returns: Ustr string
746 Type: struct Ustr *
747 Parameter[1]: Pointer to area of memory to use as a Ustr string
749 Type[1]: void *
750 Parameter[2]: Size of area of memory
752 Type[2]: size_t
753 Parameter[3]: Whether the fixed size Ustr should be limited
755 Type[3]: int
756 Parameter[4]: The initial length of the Ustr
758 Type[4]: size_t
759 Explanation:
761 This creates a new Ustr string, which is "fixed". This means the Ustr
763 storage is managed outside of the ustr_* API, it is often used for
764 stack allocated strings.
765 As you add data to the Ustr past the size allowed via. the fixed
766 storge the Ustr will automatically be converted into an allocated Ustr.
767 So if this is possible you should always call ustr_free(), as this does
768 nothing if given a fixed size Ustr.
769 Note:
771 For simplicity you probably want to use USTR_SC_INIT_AUTO() or
773 USTR_SC_INIT_AUTO() when possible.
774 Function: USTR_SC_INIT_AUTO()
776 Returns: Ustr string
777 Type: struct Ustr *
778 Parameter[1]: Area of memory to use as a Ustr string
780 Type[1]: char[]
781 Parameter[2]: Whether the fixed size Ustr should be limited
783 Type[2]: int
784 Parameter[3]: The initial length of the Ustr
786 Type[3]: size_t
787 Explanation:
789 This calls ustr_init_fixed() with sizeof() the area of memory (Param‐
791 eter[1]) as the second argument.
792 Note:
794 This does mean that the first argument must be the correct size, as
796 far as sizeof() is concerned, as in...
797 char buf_sz[1024];
799 Ustr *s1 = USTR_SC_INIT_AUTO(buf_sz, USTR_FALSE, 0);
800 ...so passing pointers to memory from malloc() will probably just
802 return NULL.
803 Function: USTR_SC_INIT_AUTO_OSTR()
806 Returns: Ustr string
807 Type: struct Ustr *
808 Parameter[1]: Area of memory to use as a Ustr string
810 Type[1]: char[]
811 Parameter[2]: Whether the fixed size Ustr should be limited
813 Type[2]: int
814 Parameter[3]: The initial string in the buffer, as a constant string
816 Type[3]: size_t
817 Explanation:
819 This calls ustr_init_fixed() with sizeof() the area of memory (Param‐
821 eter[1]) as the second argument, given as an "object string".
822 Note:
824 This does mean that the first argument must be the correct size, as
826 far as sizeof() is concerned, as in...
827 char buf_sz[1024] = USTR_BEG_FIXED2 "abcd";
829 Ustr *s1 = USTR_SC_INIT_AUTO_OSTR(buf_sz, USTR_FALSE, "abcd");
830 ...so passing pointers to memory from malloc() will probably just
832 return NULL.
833
837 Function: ustr_assert_valid()
838 Returns: Success or failure
839 Type: int
840 Parameter[1]: Pointer to a Ustr string
842 Type[1]: Ustr *
843 Explanation:
845 This function asserts a few internal consistency checks, and can help
847 point out when a Ustr is invalid.
848 Note:
850 This calls ustr_assert_ret() so that when USTR_DEBUG if off the
852 checks are still performed and the result is returned.
853 Function: ustr_assert_valid_subustr()
855 Returns: Success or failure
856 Type: int
857 Parameter[1]: Pointer to a Ustr string
859 Type[1]: Ustr *
860 Parameter[2]: Position in the Ustr
862 Type[2]: size_t
863 Parameter[3]: Length to delete from the Ustr
865 Type[3]: size_t
866 Explanation:
868 This function calls ustr_assert_valid() and also checks that the
870 position and length are within the Ustr. If they aren't valid it
871 returns 0, if they are valid it returns ustr_len().
872 Function: USTR_CNTL_MALLOC_CHECK_BEG()
874 Returns: Success or failure
875 Type: int
876 Parameter[1]: Condition for begin malloc checking or not
878 Type[1]: int
879 Explanation:
882 This function begins malloc checking, meaning all ustr allocations
884 will go through the malloc check routines, but it fails if the condi‐
885 tion check (Parameter[1]) fails.
886 Note:
888 Turning malloc checking on after one or more allocations has happened
890 will lead to false failures unless you really known what you are doing.
891 You can automatically turn malloc checking on by giving the
892 USTR_CNTL_MC environment variable the value of "1", "yes" or "on".
893 Function: USTR_CNTL_MALLOC_CHECK_LVL()
895 Returns: Level of current malloc check
896 Type: int
897 Parameter[1]: Nothing
899 Type[1]: void
900 Explanation:
902 This function returns the current "level" of the malloc check, with 0
904 indicating that malloc check isn't enabled.
905 The level goes up by one whenever USTR_CNTL_MALLOC_CHECK_BEG() or
906 USTR_CNTL_MALLOC_CHECK_ADD() returns success, and goes down by one
907 whenever USTR_CNTL_MALLOC_CHECK_DEL() or USTR_CNTL_MALLOC_CHECK_END()
908 returns success.
909 Function: USTR_CNTL_MALLOC_CHECK_MEM()
911 Returns: Success or failure
912 Type: int
913 Parameter[1]: Pointer returned from malloc check
915 Type[1]: void *
916 Explanation:
918 This function asserts that the pointer (Parameter[1]) was allocated
920 from malloc checking.
921 Note:
923 Unless you are doing something special, or using a builtin Ustr_pool
925 it is very likely you want to just call USTR_CNTL_MAL‐
926 LOC_CHECK_MEM_USTR().
927 Function: USTR_CNTL_MALLOC_CHECK_MEM_SZ()
929 Returns: Success or failure
930 Type: int
931 Parameter[1]: Pointer returned from malloc check
933 Type[1]: void *
934 Parameter[2]: Length of allocated memory
936 Type[2]: size_t
937 Explanation:
939 This function asserts that the pointer (Parameter[1]) was allocated
941 from malloc checking, and has the specified size (Parameter[2]).
942 Note:
944 Unless you are doing something special, or using a builtin Ustr_pool
946 it is very likely you want to just call USTR_CNTL_MAL‐
947 LOC_CHECK_MEM_USTR().
948 Function: USTR_CNTL_MALLOC_CHECK_MEM_MINSZ()
950 Returns: Success or failure
951 Type: int
952 Parameter[1]: Pointer returned from malloc check
954 Type[1]: void *
955 Parameter[2]: Length of allocated memory
957 Type[2]: size_t
958 Explanation:
960 This function asserts that the pointer (Parameter[1]) was allocated
962 from malloc checking, and has at least the specified size (Parame‐
963 ter[2]).
964 Note:
966 Unless you are doing something special, or using a builtin Ustr_pool
968 it is very likely you want to just call USTR_CNTL_MAL‐
969 LOC_CHECK_MEM_USTR().
970 Function: USTR_CNTL_MALLOC_CHECK_MEM_USTR()
972 Returns: Success or failure
973 Type: int
974 Parameter[1]: Pointer to a Ustr string
976 Type[1]: Ustr *
977 Explanation:
979 This function asserts that the pointer (Parameter[1]) is a Ustr allo‐
981 cated from malloc checking, if the Ustr is allocated (if not it returns
982 TRUE).
983 Note:
985 Because of the layering between the Ustr code and the pool code, if
987 you allocate an implicity sized Ustrp from a pool and then delete some
988 data from it (which fails) the Ustr layer will think it has an implicit
989 less than the actual size so this function will fail. This is what
990 USTR_CNTL_MALLOC_CHECK_MEM_USTRP() is for.
991 Function: USTR_CNTL_MALLOC_CHECK_MEM_USTRP()
993 Returns: Success or failure
994 Type: int
995 Parameter[1]: Pointer to a Ustrp string
997 Type[1]: Ustrp *
998 Explanation:
1000 This function asserts that the pointer (Parameter[1]) is a Ustr allo‐
1002 cated from a builtin pool using malloc checking, if the Ustr is allo‐
1003 cated (if not it returns TRUE).
1004 Function: USTR_CNTL_MALLOC_CHECK_END()
1006 Returns: Success or failure
1007 Type: int
1008 Parameter[1]: Nothing
1010 Type[1]: void
1011 Explanation:
1013 This macro will cleanup any memory used by malloc check, and assert
1015 that no memory is left allocated.
1016 Note:
1018 If any memory is left allocated, each one found is output to stderr
1020 with the file/line/function of the level it was allocated from.
1021 Function: USTR_CNTL_MALLOC_CHECK_ADD()
1023 Returns: Success or failure
1024 Type: int
1025 Parameter[1]: Condition to begin malloc checking or not
1027 Type[1]: int
1028 Explanation:
1030 This function works like USTR_CNTL_MALLOC_CHECK_END() but it fails if
1032 the condition check (Parameter[1]) fails, or if USTR_CNTL_MAL‐
1033 LOC_CHECK_LVL() is zero.
1034 Function: USTR_CNTL_MALLOC_CHECK_DEL()
1036 Returns: Success or failure
1037 Type: int
1038 Parameter[1]: Condition to end malloc checking or not
1040 Type[1]: int
1041 Explanation:
1043 This function works like USTR_CNTL_MALLOC_CHECK_END() but it fails if
1045 the condition check (Parameter[1]) fails, or if USTR_CNTL_MAL‐
1046 LOC_CHECK_LVL() is one.
1047 Note:
1049 The condition (Parameter[1]) to this macro should almost certainly be
1051 the return value from USTR_CNTL_MALLOC_CHECK_ADD().
1052
1055 Function: ustr_init_size()
1056 Returns: Size that needs to be allocated
1057 Type: size_t
1058 Parameter[1]: Size of allocated storage
1060 Type[1]: size_t
1061 Parameter[2]: Number of bytes to use for reference count
1063 Type[2]: size_t
1064 Parameter[3]: Exact memory allocations
1066 Type[3]: int
1067 Parameter[4]: Length of data in the Ustr
1069 Type[4]: size_t
1070 Explanation:
1072 This function finds out the exact size of memory needed to store the
1074 specified Ustr of the given configuration.
1075 Function: ustr_init_alloc()
1077 Returns: Ustr string
1078 Type: struct Ustr *
1079 Parameter[1]: Pointer to area of memory to use as a Ustr string
1081 Type[1]: void *
1082 Parameter[2]: Size of area of memory
1084 Type[2]: size_t
1085 Parameter[3]: Whether Ustr should store the size
1087 Type[3]: size_t
1088 Parameter[4]: Number of bytes to use for references
1090 Type[4]: size_t
1091 Parameter[5]: Whether the Ustr should use exact allocations
1093 Type[5]: int
1094 Parameter[6]: Whether the Ustr should have the "enomem" flag set
1096 Type[6]: int
1097 Parameter[7]: The initial length of the Ustr
1099 Type[7]: size_t
1100 Explanation:
1102 This creates a new Ustr string, you should have allocated the data
1104 via. USTR_CONF_MALLOC() or bad things will happen if the Ustr string
1105 is ever free'd or reallocated.
1106 Function: ustr_dupx_empty()
1108 Returns: Ustr string
1109 Type: struct Ustr *
1110 Parameter[1]: Size of allocated storage
1112 Type[1]: size_t
1113 Parameter[2]: Number of bytes to use for reference count
1115 Type[2]: size_t
1116 Parameter[3]: Exact memory allocation flag
1118 Type[3]: int
1119 Parameter[4]: ENOMEM, memory error flag
1121 Type[4]: int
1122 Explanation:
1124 This function creates an empty Ustr, owned by you, that is allocated
1126 from system memory, or it returns NULL.
1127 The size is the desired allocation size for the entire Ustr, includ‐
1128 ing overhead for metadata. This value will be rounded up, if it's too
1129 small, so passing 1 as the size means you want a stored size but to
1130 allocate the smallest amount of memory possible.
1131 The exact memory allocation flag says if the Ustr should round allo‐
1132 cations up to the nearest half power of two or should be no more than
1133 needed.
1134 The ENOMEM memory error flag sets the iniital state of the user visi‐
1135 ble flag for memory allocation errors. Eg. ustr_enomem(),
1136 ustr_setf_enomem_clr() and ustr_setf_enomem_err()
1137 Note:
1139 The reference byte count can only be one of the following values: 0,
1141 1, 2 or 4, or 8 (on environments with a 64bit size_t).
1142 It can be useful to ensure that the Ustr is in system memory, so that
1143 you can add things to it and check for errors with ustr_enomem().
1144 If you chose to store the allocated size in the Ustr then the number
1145 of bytes allocated for the reference count will be a minimum of 2.
1146 Function: ustr_dup_empty()
1148 Returns: Ustr string
1149 Type: struct Ustr *
1150 Parameter[1]: Nothing
1152 Type[1]: void
1153 Explanation:
1155 This function is the same as calling ustr_dupx_empty() with the cur‐
1157 rent set of default options.
1158 Function: ustr_dupx_undef()
1160 Returns: Ustr string
1161 Type: struct Ustr *
1162 Parameter[1]: Size of allocated storage
1164 Type[1]: size_t
1165 Parameter[2]: Number of bytes to use for reference count
1167 Type[2]: size_t
1168 Parameter[3]: Exact memory allocations
1170 Type[3]: int
1171 Parameter[4]: ENOMEM, memory error flag
1173 Type[4]: int
1174 Parameter[5]: Length of new undefined data
1176 Type[5]: size_t
1177 Explanation:
1179 This function works like you called ustr_dupx_empty() and then
1181 ustr_add_undef().
1182 Function: ustr_dup_undef()
1184 Returns: Pointer to a Ustr string
1185 Type: struct Ustr *
1186 Parameter[1]: Length of new undefined data
1188 Type[1]: size_t
1189 Explanation:
1191 This function is the same as calling ustr_dupx_undef() with the cur‐
1193 rent set of default options.
1194 Function: ustr_dup()
1196 Returns: A pointer to a Ustr string
1197 Type: struct Ustr *
1198 Parameter[1]: Pointer to a constant Ustr string
1200 Type[1]: const struct Ustr *
1201 Explanation:
1203 This function tries to increase the reference count on the passed
1205 Ustr string, and if that succeeds returns that as an argument. If that
1206 fails it tries creates a new Ustr string that looks identical to the
1207 old Ustr string, apart from the reference count.
1208 Note:
1210 Because the new Ustr string is configured identically to the old Ustr
1212 string this means the result can be very different to what you get if
1213 you call ustr_dup_buf() with ustr_cstr() and ustr_len() from the origi‐
1214 nal string where the configuration would be whatever the default is.
1215 Esp. worth of note is that if you ustr_dup() a Ustr string with an
1216 explicit size of 900 but a length of 1, and the reference count is full
1217 the returned Ustr string will have a size of 900 bytes and so will have
1218 allocated a little over that. ustr_dup_buf(), even with a sized config‐
1219 uration would only allocate about 12 bytes and have a size a little
1220 less than that.
1221 Function: ustr_dupx()
1223 Returns: Pointer to a Ustr string
1224 Type: struct Ustr *
1225 Parameter[1]: Size of allocated storage
1227 Type[1]: size_t
1228 Parameter[2]: Number of bytes to use for reference count
1230 Type[2]: size_t
1231 Parameter[3]: Exact memory allocations
1233 Type[3]: int
1234 Parameter[4]: ENOMEM, memory error flag
1236 Type[4]: int
1237 Parameter[5]: Pointer to a constant Ustr string
1239 Type[5]: const struct Ustr *
1240 Explanation:
1242 This function tries to add a reference if the value of the size, ref‐
1244 erence bytes, exact memory allocations and ENOMEM are the same as those
1245 in the passed Ustr string (Parameter[5]). If the comparison fails or
1246 the addition of a reference fails it works like ustr_dupx_buf() using
1247 ustr_cstr() and ustr_len().
1248 Function: ustr_sc_dup()
1250 Returns: A pointer to a Ustr string
1251 Type: struct Ustr *
1252 Parameter[1]: A pointer to a pointer to a Ustr string
1254 Type[1]: struct Ustr **
1255 Explanation:
1257 This function works like calling ustr_dup(), but if the reference
1259 count is maxed out then and so a new Ustr string has been allocated
1260 then that is stored in the passed argument (Parameter[1]) and the "old"
1261 Ustr string is returned.
1262 Note:
1264 The reason to use this is that if you have a "main" Ustr string
1266 pointer that a lot of things are getting references too then when the
1267 reference count maxes out you'll degrade into worst case behaviour
1268 which acts as though there are no reference counts. This function stops
1269 that problem.
1270 As an example, if you have a 1 byte reference count and have 255 * 2
1271 references then using ustr_dup() will create 256 Ustr strings using
1272 this function will create 4 Ustr strings.
1273 Function: ustr_sc_dupx()
1275 Returns: Pointer to a Ustr string
1276 Type: struct Ustr *
1277 Parameter[1]: Size of allocated storage
1279 Type[1]: size_t
1280 Parameter[2]: Number of bytes to use for reference count
1282 Type[2]: size_t
1283 Parameter[3]: Exact memory allocations
1285 Type[3]: int
1286 Parameter[4]: ENOMEM, memory error flag
1288 Type[4]: int
1289 Parameter[5]: A pointer to a pointer to a Ustr string
1291 Type[5]: struct Ustr **
1292 Explanation:
1294 This function works like calling ustr_dupx(), but if the reference
1296 count is maxed out then and so a new Ustr string is allocated then that
1297 is stored in the passed argument (Parameter[1]) and the "old" Ustr
1298 string is returned.
1299 If the configurations of the new Ustr string and the old Ustr string
1300 are not the same, this function works identically to ustr_dupx().
1301 Note:
1303 The reason to use this is that if you have a "main" Ustr string
1305 pointer that a lot of things are getting references too then when the
1306 reference count maxes out you'll degrade into worst case behaviour
1307 which acts as though there are no reference counts. This function stops
1308 that problem.
1309 As an example, if you have a 1 byte reference count and have 255 * 2
1310 references then using ustr_dupx() will create 256 Ustr strings using
1311 this function will create 4 Ustr strings.
1312 Function: ustr_dup_buf()
1314 Returns: A pointer to a Ustr string
1315 Type: struct Ustr *
1316 Parameter[1]: Pointer to data
1318 Type[1]: const void *
1319 Parameter[2]: Length of data
1321 Type[2]: size_t
1322 Explanation:
1324 This function works as if you had called ustr_dup_undef() and then
1326 copied the data into the new undefined space.
1327 Function: ustr_dupx_buf()
1329 Returns: Pointer to a Ustr string
1330 Type: struct Ustr *
1331 Parameter[1]: Size of allocated storage
1333 Type[1]: size_t
1334 Parameter[2]: Number of bytes to use for reference count
1336 Type[2]: size_t
1337 Parameter[3]: Exact memory allocations
1339 Type[3]: int
1340 Parameter[4]: ENOMEM, memory error flag
1342 Type[4]: int
1343 Parameter[5]: Pointer to data
1345 Type[5]: const void *
1346 Parameter[6]: Length of data
1348 Type[6]: size_t
1349 Explanation:
1351 This function works as if you had called ustr_dupx_undef() and then
1353 copied the data into the new undefined space.
1354 Function: ustr_dup_cstr()
1356 Returns: A pointer to a Ustr string
1357 Type: struct Ustr *
1358 Parameter[1]: Pointer to constant C-style string
1360 Type[1]: const char *
1361 Explanation:
1363 This function works as if you had called ustr_dup_buf() and passed
1365 strlen() as the length.
1366 Function: ustr_dupx_cstr()
1368 Returns: Pointer to a Ustr string
1369 Type: struct Ustr *
1370 Parameter[1]: Size of allocated storage
1372 Type[1]: size_t
1373 Parameter[2]: Number of bytes to use for reference count
1375 Type[2]: size_t
1376 Parameter[3]: Exact memory allocations
1378 Type[3]: int
1379 Parameter[4]: ENOMEM, memory error flag
1381 Type[4]: int
1382 Parameter[5]: Pointer to constant C-style string
1384 Type[5]: const char *
1385 Explanation:
1387 This function works as if you had called ustr_dupx_buf() and passed
1389 strlen() as the length.
1390 Function: USTR_DUP_OSTR()
1392 Returns: A pointer to a Ustr string
1393 Type: struct Ustr *
1394 Parameter[1]: A constant C-style string
1396 Type[1]: const char []
1397 Explanation:
1399 This function works as if you had called ustr_dup_buf() and passed
1401 sizeof() - 1 as the length.
1402 Function: USTR_DUP_OBJ()
1404 Returns: A pointer to a Ustr string
1405 Type: struct Ustr *
1406 Parameter[1]: A symbol
1408 Type[1]: ...
1409 Explanation:
1411 This function works as if you had called ustr_dup_buf() and passed
1413 sizeof() as the length.
1414 Note:
1416 In most cases you'll want to use USTR_DUP_OSTR().
1418 Function: ustr_dup_subustr()
1420 Returns: A pointer to a Ustr string
1421 Type: struct Ustr *
1422 Parameter[1]: A pointer to a constant Ustr string
1424 Type[1]: const struct Ustr *
1425 Parameter[2]: Position in the Ustr
1427 Type[2]: size_t
1428 Parameter[3]: Length to add from the Ustr
1430 Type[3]: size_t
1431 Explanation:
1433 This function mostly works as if you had called ustr_dup_buf() with
1435 the ustr_cstr() + position - 1 and length values of the Ustr string to
1436 be added.
1437 Note:
1439 If the position is 1 and the length is the length of the Ustr string
1441 then it just calls ustr_dup().
1442 Function: ustr_dupx_subustr()
1444 Returns: Pointer to a Ustr string
1445 Type: struct Ustr *
1446 Parameter[1]: Size of allocated storage
1448 Type[1]: size_t
1449 Parameter[2]: Number of bytes to use for reference count
1451 Type[2]: size_t
1452 Parameter[3]: Exact memory allocations
1454 Type[3]: int
1455 Parameter[4]: ENOMEM, memory error flag
1457 Type[4]: int
1458 Parameter[5]: A pointer to a constant Ustr string
1460 Type[5]: const struct Ustr *
1461 Parameter[6]: Position in the Ustr
1463 Type[6]: size_t
1464 Parameter[7]: Length to add from the Ustr
1466 Type[7]: size_t
1467 Explanation:
1469 This function mostly works as if you had called ustr_dupx_buf() with
1471 the ustr_cstr() + position - 1 and length values of the Ustr string to
1472 be added.
1473 Note:
1475 If the position is 1 and the length is the length of the Ustr string
1477 then it just calls ustr_dupx().
1478 Function: ustr_dup_rep_chr()
1480 Returns: A pointer to a Ustr string
1481 Type: struct Ustr *
1482 Parameter[1]: Byte value of data
1484 Type[1]: char
1485 Parameter[2]: Length of bytes as data
1487 Type[2]: size_t
1488 Explanation:
1490 This function works as if you had called ustr_dup_undef() and then
1492 copied the byte value to each position.
1493 Function: ustr_dupx_rep_chr()
1495 Returns: Pointer to a Ustr string
1496 Type: struct Ustr *
1497 Parameter[1]: Size of allocated storage
1499 Type[1]: size_t
1500 Parameter[2]: Number of bytes to use for reference count
1502 Type[2]: size_t
1503 Parameter[3]: Exact memory allocations
1505 Type[3]: int
1506 Parameter[4]: ENOMEM, memory error flag
1508 Type[4]: int
1509 Parameter[5]: Byte value of data
1511 Type[5]: char
1512 Parameter[6]: Length of bytes as data
1514 Type[6]: size_t
1515 Explanation:
1517 This function works as if you had called ustr_dupx_undef() and then
1519 copied the byte value to each position.
1520 Function: ustr_sc_vjoin()
1522 Returns: Pointer to a Ustr string
1523 Type: struct Ustr *
1524 Parameter[1]: Separator to go between Ustr strings
1526 Type[1]: const struct Ustr *
1527 Parameter[2]: A pointer to the first constant Ustr string
1529 Type[2]: const struct Ustr *
1530 Parameter[3]: A pointer to the second constant Ustr string
1532 Type[3]: const struct Ustr *
1533 Parameter[4]: Variable argument list variable, from va_start()
1535 Type[4]: va_list
1536 Explanation:
1538 This function works as if you called ustr_dup() on the first Ustr
1540 string (Parameter[2]), and then ustr_add() on the separator (Parame‐
1541 ter[1]) followed by ustr_add() on the second Ustr string (Parame‐
1542 ter[3]). This process then repeats for all the Ustr strings in the
1543 variable argument list (Parameter[4]) until a USTR_NULL is reached.
1544 Note:
1546 This function doesn't guarantee to just take a reference to one of
1548 the passed Ustr strings, even if that is what would happen if you
1549 called the above manually.
1550 Function: ustr_sc_join()
1552 Returns: Pointer to a Ustr string
1553 Type: struct Ustr *
1554 Parameter[1]: Separator to go between Ustr strings
1556 Type[1]: const struct Ustr *
1557 Parameter[2]: A pointer to the first constant Ustr string
1559 Type[2]: const struct Ustr *
1560 Parameter[3]: A pointer to the second constant Ustr string
1562 Type[3]: const struct Ustr *
1563 Parameter[4]: Zero or more pointers to constant Ustr strings and then
1565 USTR_NULL
1566 Type[4]: ...
1567 Explanation:
1569 This function calls va_start() to get a variable argument list and
1571 then calls ustr_sc_vjoin().
1572 Note:
1574 This function doesn't guarantee to just take a reference to one of
1576 the passed Ustr strings, even if that is what would happen if you
1577 called the above manually.
1578 Function: ustr_sc_vjoinx()
1580 Returns: Pointer to a Ustr string
1581 Type: struct Ustr *
1582 Parameter[1]: Size of allocated storage
1584 Type[1]: size_t
1585 Parameter[2]: Number of bytes to use for reference count
1587 Type[2]: size_t
1588 Parameter[3]: Exact memory allocations
1590 Type[3]: int
1591 Parameter[4]: ENOMEM, memory error flag
1593 Type[4]: int
1594 Parameter[5]: Separator to go between Ustr strings
1596 Type[5]: const struct Ustr *
1597 Parameter[6]: A pointer to the first constant Ustr string
1599 Type[6]: const struct Ustr *
1600 Parameter[7]: A pointer to the second constant Ustr string
1602 Type[7]: const struct Ustr *
1603 Parameter[8]: Variable argument list variable, from va_start()
1605 Type[8]: va_list
1606 Explanation:
1608 This function works as if you called ustr_dupx() on the first Ustr
1610 string (Parameter[2]), and then ustr_add() on the separator (Parame‐
1611 ter[1]) followed by ustr_add() on the second Ustr string (Parame‐
1612 ter[3]). This process then repeats for all the Ustr strings in the
1613 variable argument list (Parameter[4]) until a USTR_NULL is reached.
1614 Note:
1616 This function doesn't guarantee to just take a reference to one of
1618 the passed Ustr strings, even if that is what would happen if you
1619 called the above manually.
1620 Function: ustr_sc_joinx()
1622 Returns: Pointer to a Ustr string
1623 Type: struct Ustr *
1624 Parameter[1]: Size of allocated storage
1626 Type[1]: size_t
1627 Parameter[2]: Number of bytes to use for reference count
1629 Type[2]: size_t
1630 Parameter[3]: Exact memory allocations
1632 Type[3]: int
1633 Parameter[4]: ENOMEM, memory error flag
1635 Type[4]: int
1636 Parameter[5]: Separator to go between Ustr strings
1638 Type[5]: const struct Ustr *
1639 Parameter[6]: A pointer to the first constant Ustr string
1641 Type[6]: const struct Ustr *
1642 Parameter[7]: A pointer to the second constant Ustr string
1644 Type[7]: const struct Ustr *
1645 Parameter[8]: Zero or more pointers to constant Ustr strings and then
1647 USTR_NULL
1648 Type[8]: ...
1649 Explanation:
1651 This function calls va_start() to get a variable argument list and
1653 then calls ustr_sc_vjoinx().
1654 Function: ustr_sc_vconcat()
1656 Returns: Pointer to a Ustr string
1657 Type: struct Ustr *
1658 Parameter[1]: A pointer to the first constant Ustr string
1660 Type[1]: const struct Ustr *
1661 Parameter[2]: Variable argument list variable, from va_start()
1663 Type[2]: va_list
1664 Explanation:
1666 This function works as if you called ustr_dup() on the first Ustr
1668 string (Parameter[1]), and then ustr_add() on the second Ustr string
1669 (Parameter[3]). This process then repeats for all the Ustr strings in
1670 the variable argument list (Parameter[4]) until a USTR_NULL is reached.
1671 Note:
1673 This function doesn't guarantee to just take a reference to one of
1675 the passed Ustr strings, even if that is what would happen if you
1676 called the above manually.
1677 Function: ustr_sc_concat()
1679 Returns: Pointer to a Ustr string
1680 Type: struct Ustr *
1681 Parameter[1]: A pointer to the first constant Ustr string
1683 Type[1]: const struct Ustr *
1684 Parameter[2]: Zero or more pointers to constant Ustr strings and then
1686 USTR_NULL
1687 Type[2]: ...
1688 Explanation:
1690 This function calls va_start() to get a variable argument list and
1692 then calls ustr_sc_vconcat().
1693 Function: ustr_sc_vconcatx()
1695 Returns: Pointer to a Ustr string
1696 Type: struct Ustr *
1697 Parameter[1]: Size of allocated storage
1699 Type[1]: size_t
1700 Parameter[2]: Number of bytes to use for reference count
1702 Type[2]: size_t
1703 Parameter[3]: Exact memory allocations
1705 Type[3]: int
1706 Parameter[4]: ENOMEM, memory error flag
1708 Type[4]: int
1709 Parameter[5]: A pointer to the first constant Ustr string
1711 Type[5]: const struct Ustr *
1712 Parameter[6]: Variable argument list variable, from va_start()
1714 Type[6]: va_list
1715 Explanation:
1717 This function works as if you called ustr_dupx() on the first Ustr
1719 string (Parameter[1]), and then ustr_add() on the second Ustr string
1720 (Parameter[3]). This process then repeats for all the Ustr strings in
1721 the variable argument list (Parameter[4]) until a USTR_NULL is reached.
1722 Note:
1724 This function doesn't guarantee to just take a reference to one of
1726 the passed Ustr strings, even if that is what would happen if you
1727 called the above manually.
1728 Function: ustr_sc_concatx()
1730 Returns: Pointer to a Ustr string
1731 Type: struct Ustr *
1732 Parameter[1]: Size of allocated storage
1734 Type[1]: size_t
1735 Parameter[2]: Number of bytes to use for reference count
1737 Type[2]: size_t
1738 Parameter[3]: Exact memory allocations
1740 Type[3]: int
1741 Parameter[4]: ENOMEM, memory error flag
1743 Type[4]: int
1744 Parameter[5]: A pointer to the first constant Ustr string
1746 Type[5]: const struct Ustr *
1747 Parameter[6]: Zero or more pointers to constant Ustr strings and then
1749 USTR_NULL
1750 Type[6]: ...
1751 Explanation:
1753 This function calls va_start() to get a variable argument list and
1755 then calls ustr_sc_vconcatx().
1756
1759 Function: ustr_free()
1760 Returns: Nothing
1761 Type: void
1762 Parameter[1]: Pointer to a Ustr
1764 Type[1]: struct Ustr *
1765 Explanation:
1767 This function decrements the reference count on a Ustr, if there is
1769 one, and free's it if it is allocated and the reference count becomes
1770 zero.
1771 Note:
1773 This function does nothing if passed USTR_NULL.
1775 Function: ustrp_free()
1777 Returns: Nothing
1778 Type: void
1779 Parameter[1]: Pointer to a Ustr pool object
1781 Type[1]: struct Ustr_pool *
1782 Parameter[2]: Pointer to a Ustrp (pool allocated Ustr)
1784 Type[2]: struct Ustrp *
1785 Explanation:
1787 This function works like ustr_free() but calls the pool_free member
1789 function of the Ustr_pool (Parameter[1]) instead of the ustr system
1790 free.
1791 Function: ustr_sc_free()
1793 Returns: Nothing
1794 Type: void
1795 Parameter[1]: A pointer to a pointer to a Ustr string
1797 Type[1]: struct Ustr **
1798 Explanation:
1800 This function calls ustr_free() and then sets the pointer (Parame‐
1802 ter[1]) to USTR_NULL, which is a noop when passed to ustr_free(). This
1803 can be used to help prevent "double free" errors.
1804 Note:
1806 While the point to the pointer must be non-NULL, this function also
1808 accepts a NULL ustr and does nothing. So you can pass the same pointer
1809 to this function multiple times and only the first one will do any‐
1810 thing.
1811 Function: ustr_sc_free2()
1813 Returns: Nothing
1814 Type: void
1815 Parameter[1]: A pointer to a pointer to a Ustr string
1817 Type[1]: struct Ustr **
1818 Parameter[2]: Pointer to a Ustr string
1820 Type[2]: struct Ustr *
1821 Explanation:
1823 This function works like ustr_sc_free() but instead of setting the
1825 pointer (Parameter[1]) to USTR_NULL it sets it to the Ustr string
1826 (Parameter[2]).
1827 Note:
1829 While the point to the pointer must be non-NULL, this function also
1831 accepts a NULL ustr to be free'd and does nothing. So you can pass the
1832 same pointer to ustr_sc_free() and then this function safely.
1833 The passed value (Parameter[2]) shouldn't be USTR_NULL, and in debug‐
1834 ging mode the function will assert() that it isn't.
1835 Function: ustr_sc_free_shared()
1837 Returns: Nothing
1838 Type: void
1839 Parameter[1]: A pointer to a pointer to a Ustr string
1841 Type[1]: struct Ustr **
1842 Explanation:
1844 This function is a simple way to "free" a Ustr string that has been
1846 shared (ustr_shared() returns USTR_TRUE), normally ustr_free() is
1847 ignored on a shared Ustr string. It just calls ustr_setf_owner() and
1848 then ustr_sc_free().
1849 Function: ustr_del()
1851 Returns: Success or failure
1852 Type: int
1853 Parameter[1]: Pointer to a pointer to a Ustr string
1855 Type[1]: struct Ustr **
1856 Parameter[2]: Length to delete from the Ustr
1858 Type[2]: size_t
1859 Explanation:
1861 This function deletes data from the end of Ustr, possibly re-sizing
1863 the Ustr at the same time.
1864 Note:
1866 The Ustr is never re-sized when the size is stored explicitly, so the
1868 pointer never changes.
1869 Function: ustr_del_subustr()
1871 Returns: Success or failure
1872 Type: int
1873 Parameter[1]: Pointer to a pointer to a Ustr string
1875 Type[1]: struct Ustr **
1876 Parameter[2]: Position in the Ustr
1878 Type[2]: size_t
1879 Parameter[3]: Length to delete from the Ustr
1881 Type[3]: size_t
1882 Explanation:
1884 This function works like ustr_del() but can delete an arbitrary sec‐
1886 tion of the Ustr.
1887 Function: ustr_sc_del()
1889 Returns: Nothing
1890 Type: void
1891 Parameter[1]: A pointer to a pointer to a Ustr string
1893 Type[1]: struct Ustr **
1894 Explanation:
1896 This function is like calling ustr_del() with ustr_len() as the
1898 length, however if that fails it does a ustr_free() and then sets the
1899 pointer to USTR("").
1900 Note:
1902 While the benifit is that you don't have to check for memory failure
1904 errors, if there is a memory failure and you have a non-default config‐
1905 uration the configuration will revert back to the default.
1906
1909 Function: ustr_add_undef()
1910 Returns: Success or failure
1911 Type: int
1912 Parameter[1]: A pointer to a pointer to a Ustr string
1914 Type[1]: struct Ustr **
1915 Parameter[2]: Length of new undefined data
1917 Type[2]: size_t
1918 Explanation:
1920 The Ustr string is expanded (possibly reallocated) so that it can
1922 contain length (Parameter[2]) extra data, if the length is not zero the
1923 Ustr will be writable. Or it'll return USTR_FALSE (zero) on failure.
1924 Function: ustr_add_buf()
1926 Returns: Success or failure
1927 Type: int
1928 Parameter[1]: Pointer to a pointer to a Ustr string
1930 Type[1]: struct Ustr **
1931 Parameter[2]: Pointer to data
1933 Type[2]: const void *
1934 Parameter[3]: Length of data
1936 Type[3]: size_t
1937 Explanation:
1939 This function works as if you had called ustr_add_undef() and then
1941 copied the data into the new undefined space.
1942 Function: ustr_add_cstr()
1944 Returns: Success or failure
1945 Type: int
1946 Parameter[1]: Pointer to a pointer to a Ustr string
1948 Type[1]: struct Ustr **
1949 Parameter[2]: Pointer to constant C-style string
1951 Type[2]: const char *
1952 Explanation:
1954 This function works as if you had called ustr_add_buf() and passed
1956 strlen() as the length.
1957 Function: USTR_ADD_OSTR()
1959 Returns: Success or failure
1960 Type: int
1961 Parameter[1]: Pointer to a pointer to a Ustr string
1963 Type[1]: struct Ustr **
1964 Parameter[2]: A constant C-style string
1966 Type[2]: const char []
1967 Explanation:
1969 This function works as if you had called ustr_add_buf() and passed
1971 sizeof() - 1 as the length.
1972 Function: USTR_ADD_OBJ()
1974 Returns: Success or failure
1975 Type: int
1976 Parameter[1]: Pointer to a pointer to a Ustr string
1978 Type[1]: struct Ustr **
1979 Parameter[2]: A symbol
1981 Type[2]: ...
1982 Explanation:
1984 This function works as if you had called ustr_add_buf() and passed
1986 sizeof() as the length.
1987 Note:
1989 In most cases you'll want to use USTR_ADD_OSTR().
1991 Function: ustr_add()
1993 Returns: Success or failure
1994 Type: int
1995 Parameter[1]: Pointer to a pointer to a Ustr string
1997 Type[1]: struct Ustr **
1998 Parameter[2]: A pointer to a constant Ustr string
2000 Type[2]: const struct Ustr *
2001 Explanation:
2003 This function mostly works as if you had called ustr_add_buf() with
2005 the ustr_cstr() and ustr_len() values of the Ustr string to be added.
2006 Note:
2008 If the Ustr string is zero length and isn't writable this function
2010 may just add a reference, this is fine for Ustr strings that are "con‐
2011 stant" because if the Ustr is read-only then the memory will not be
2012 written to.
2013 Function: ustr_add_subustr()
2015 Returns: Success or failure
2016 Type: int
2017 Parameter[1]: Pointer to a pointer to a Ustr string
2019 Type[1]: struct Ustr **
2020 Parameter[2]: A pointer to a constant Ustr string
2022 Type[2]: const struct Ustr *
2023 Parameter[3]: Position in the Ustr
2025 Type[3]: size_t
2026 Parameter[4]: Length to add from the Ustr
2028 Type[4]: size_t
2029 Explanation:
2031 This function mostly works as if you had called ustr_add_buf() with
2033 the ustr_cstr() + position - 1 and length values of the Ustr string to
2034 be added. The exception being if you add a ustr to itself, while only
2035 having a single reference count, the simple method would access a
2036 free'd ustr, but this function just works.
2037 Note:
2039 If the position is 1 and the length is the length of the Ustr string
2041 then it just calls ustr_add().
2042 Function: ustr_add_rep_chr()
2044 Returns: Success or failure
2045 Type: int
2046 Parameter[1]: Pointer to a pointer to a Ustr string
2048 Type[1]: struct Ustr **
2049 Parameter[2]: Byte value of data
2051 Type[2]: char
2052 Parameter[3]: Length of bytes as data
2054 Type[3]: size_t
2055 Explanation:
2057 This function works as if you had called ustr_add_undef() and then
2059 copied the byte value to each position.
2060
2063 Function: ustr_set_undef()
2064 Returns: Success or failure
2065 Type: int
2066 Parameter[1]: Pointer to a pointer to a Ustr string
2068 Type[1]: struct Ustr **
2069 Parameter[2]: size_t
2071 Type[2]: size_t
2072 Explanation:
2074 This function works as if you had called ustr_del() for the entire
2076 string and the ustr_add_undef().
2077 Function: ustr_set_empty()
2079 Returns: Success or failure
2080 Type: int
2081 Parameter[1]: Pointer to a pointer to a Ustr string
2083 Type[1]: struct Ustr **
2084 Explanation:
2086 This function works as if you had called ustr_del() for the entire
2088 string, however the string will be allocated if this completes.
2089 Function: ustr_set_buf()
2091 Returns: Success or failure
2092 Type: int
2093 Parameter[1]: Pointer to a pointer to a Ustr string
2095 Type[1]: struct Ustr **
2096 Parameter[2]: Buffer containting data
2098 Type[2]: const void *
2099 Parameter[3]: Length of Buffer
2101 Type[3]: size_t
2102 Explanation:
2104 This function works as if you had called ustr_del() for the entire
2106 string and the ustr_add_buf().
2107 Function: ustr_set_cstr()
2109 Returns: Success or failure
2110 Type: int
2111 Parameter[1]: Pointer to a pointer to a Ustr string
2113 Type[1]: struct Ustr **
2114 Parameter[2]: A pointer to a constant C-style string
2116 Type[2]: const char *
2117 Explanation:
2119 This function works as if you had called ustr_del() for the entire
2121 string and then ustr_add_cstr().
2122 Function: USTR_SET_OSTR()
2124 Returns: Success or failure
2125 Type: int
2126 Parameter[1]: Pointer to a pointer to a Ustr string
2128 Type[1]: struct Ustr **
2129 Parameter[2]: A constant C-style string
2131 Type[2]: const char []
2132 Explanation:
2134 This function works as if you had called ustr_del() for the entire
2136 string and then USTR_ADD_OSTR().
2137 Function: USTR_SET_OBJ()
2139 Returns: Success or failure
2140 Type: int
2141 Parameter[1]: Pointer to a pointer to a Ustr string
2143 Type[1]: struct Ustr **
2144 Parameter[2]: A symbol
2146 Type[2]: ...
2147 Explanation:
2149 This function works as if you had called ustr_del() for the entire
2151 string and then USTR_ADD_OBJ().
2152 Note:
2154 In most cases you'll want to use USTR_SET_OSTR().
2156 Function: ustr_set()
2158 Returns: Success or failure
2159 Type: int
2160 Parameter[1]: Pointer to a pointer to a Ustr string
2162 Type[1]: struct Ustr **
2163 Parameter[2]: A pointer to a constant Ustr string
2165 Type[2]: const struct Ustr *
2166 Explanation:
2168 This function works as if you had called ustr_del() for the entire
2170 string and the ustr_add().
2171 Function: ustr_set_subustr()
2173 Returns: Success or failure
2174 Type: int
2175 Parameter[1]: Pointer to a pointer to a Ustr string
2177 Type[1]: struct Ustr **
2178 Parameter[2]: A pointer to a constant Ustr string
2180 Type[2]: const struct Ustr *
2181 Parameter[3]: Position in the Ustr
2183 Type[3]: size_t
2184 Parameter[4]: Length to set from the Ustr
2186 Type[4]: size_t
2187 Explanation:
2189 This function works as if you had called ustr_del() for the entire
2191 string and the ustr_add_subustr(). The exception being if you set a
2192 ustr to itself, while only having a single reference count, the simple
2193 method would access a free'd ustr data, but this function just works.
2194 Function: ustr_set_rep_chr()
2196 Returns: Success or failure
2197 Type: int
2198 Parameter[1]: Pointer to a pointer to a Ustr string
2200 Type[1]: struct Ustr **
2201 Parameter[2]: Byte value of data
2203 Type[2]: char
2204 Parameter[3]: Length of bytes as data
2206 Type[3]: size_t
2207 Explanation:
2209 This function works as if you had called ustr_del() for the entire
2211 string and the ustr_add_rep_chr().
2212
2215 Function: ustr_ins_undef()
2216 Returns: Success or failure
2217 Type: int
2218 Parameter[1]: A pointer to a pointer to a Ustr string
2220 Type[1]: struct Ustr **
2221 Parameter[2]: Position after which the data should be added
2223 Type[2]: size_t
2224 Parameter[3]: Length of new undefined data
2226 Type[3]: size_t
2227 Explanation:
2229 The Ustr string is expanded (possibly reallocated) so that it can
2231 contain length (Parameter[2]) extra data, from after the required posi‐
2232 tion. If the length is not zero the Ustr will be writable. Or it'll
2233 return USTR_FALSE (zero) on failure. The data in the Ustr is moved as
2234 needed to put the new data at position (Parameter[2]) + 1.
2235 Function: ustr_ins_buf()
2237 Returns: Success or failure
2238 Type: int
2239 Parameter[1]: Pointer to a pointer to a Ustr string
2241 Type[1]: struct Ustr **
2242 Parameter[2]: Position after which the data should be added
2244 Type[2]: size_t
2245 Parameter[3]: Pointer to data
2247 Type[3]: const void *
2248 Parameter[4]: Length of data
2250 Type[4]: size_t
2251 Explanation:
2253 This function works as if you had called ustr_ins_undef() and then
2255 copied the data into the new undefined space.
2256 Function: ustr_ins_cstr()
2258 Returns: Success or failure
2259 Type: int
2260 Parameter[1]: Pointer to a pointer to a Ustr string
2262 Type[1]: struct Ustr **
2263 Parameter[2]: Position after which the data should be added
2265 Type[2]: size_t
2266 Parameter[3]: Pointer to constant C-style string
2268 Type[3]: const char *
2269 Explanation:
2271 This function works as if you had called ustr_ins_buf() and passed
2273 strlen() as the length.
2274 Function: USTR_INS_OSTR()
2276 Returns: Success or failure
2277 Type: int
2278 Parameter[1]: Pointer to a pointer to a Ustr string
2280 Type[1]: struct Ustr **
2281 Parameter[2]: Position after which the data should be added
2283 Type[2]: size_t
2284 Parameter[3]: A constant C-style string
2286 Type[3]: const char []
2287 Explanation:
2289 This function works as if you had called ustr_ins_buf() and passed
2291 sizeof() - 1 as the length.
2292 Function: USTR_INS_OBJ()
2294 Returns: Success or failure
2295 Type: int
2296 Parameter[1]: Pointer to a pointer to a Ustr string
2298 Type[1]: struct Ustr **
2299 Parameter[2]: Position after which the data should be added
2301 Type[2]: size_t
2302 Parameter[3]: A symbol
2304 Type[3]: ...
2305 Explanation:
2307 This function works as if you had called ustr_ins_buf() and passed
2309 sizeof() as the length.
2310 Note:
2312 In most cases you'll want to use USTR_INS_OSTR().
2314 Function: ustr_ins()
2316 Returns: Success or failure
2317 Type: int
2318 Parameter[1]: Pointer to a pointer to a Ustr string
2320 Type[1]: struct Ustr **
2321 Parameter[2]: Position after which the data should be added
2323 Type[2]: size_t
2324 Parameter[3]: A pointer to a constant Ustr string
2326 Type[3]: const struct Ustr *
2327 Explanation:
2329 This function works as if you had called ustr_ins_buf() with the
2331 ustr_cstr() and ustr_len() values of the Ustr string to be added.
2332 Function: ustr_ins_subustr()
2334 Returns: Success or failure
2335 Type: int
2336 Parameter[1]: Pointer to a pointer to a Ustr string
2338 Type[1]: struct Ustr **
2339 Parameter[2]: Position after which the data should be added
2341 Type[2]: size_t
2342 Parameter[2]: A pointer to a constant Ustr string
2344 Type[2]: const struct Ustr *
2345 Parameter[3]: Position in the Ustr
2347 Type[3]: size_t
2348 Parameter[4]: Length to ins from the Ustr
2350 Type[4]: size_t
2351 Explanation:
2353 This function mostly as if you had called ustr_ins_buf() with the
2355 ustr_cstr() + position - 1 and length values of the Ustr string to be
2356 insed. The exception being if you insert a ustr to itself, while only
2357 having a single reference count, the simple method would access a
2358 free'd ustr data, but this function just works.
2359 Function: ustr_ins_rep_chr()
2361 Returns: Success or failure
2362 Type: int
2363 Parameter[1]: Pointer to a pointer to a Ustr string
2365 Type[1]: struct Ustr **
2366 Parameter[2]: Position after which the data should be added
2368 Type[2]: size_t
2369 Parameter[2]: Byte value of data
2371 Type[2]: char
2372 Parameter[3]: Length of bytes as data
2374 Type[3]: size_t
2375 Explanation:
2377 This function works as if you had called ustr_ins_undef() and then
2379 copied the byte value to each position.
2380
2383 Function: ustr_add_vfmt_lim()
2384 Returns: Success or failure
2385 Type: int
2386 Parameter[1]: A pointer to a pointer to a Ustr string
2388 Type[1]: struct Ustr **
2389 Parameter[2]: Limit of data to add
2391 Type[2]: size_t
2392 Parameter[3]: A pointer to a constant C-style string
2394 Type[3]: const char *
2395 Parameter[4]: Variable argument list variable, from va_start()
2397 Type[4]: va_list
2398 Explanation:
2400 This function works like calling the system vsnprintf() with the
2402 limit (Parameter[2]) as the limit to vsnprintf() and then calling
2403 ustr_add_buf().
2404 Function: ustr_add_vfmt()
2406 Returns: Success or failure
2407 Type: int
2408 Parameter[1]: A pointer to a pointer to a Ustr string
2410 Type[1]: struct Ustr **
2411 Parameter[2]: A pointer to a constant C-style string
2413 Type[2]: const char *
2414 Parameter[3]: Variable argument list variable, from va_start()
2416 Type[3]: va_list
2417 Explanation:
2419 This function works like calling the system vsnprintf() and then
2421 calling ustr_add_buf().
2422 Function: ustr_add_fmt_lim()
2424 Returns: Success or failure
2425 Type: int
2426 Parameter[1]: A pointer to a pointer to a Ustr string
2428 Type[1]: struct Ustr **
2429 Parameter[2]: Limit of data to add
2431 Type[2]: size_t
2432 Parameter[3]: A pointer to a constant C-style string
2434 Type[3]: const char *
2435 Parameter[4]: Options depending on value of Parameter[3]
2437 Type[4]: ...
2438 Explanation:
2440 This function works like calling the system snprintf() with the limit
2442 (Parameter[2]) as the limit to snprintf() and then calling
2443 ustr_add_buf().
2444 Function: ustr_add_fmt()
2446 Returns: Success or failure
2447 Type: int
2448 Parameter[1]: A pointer to a pointer to a Ustr string
2450 Type[1]: struct Ustr **
2451 Parameter[2]: A pointer to a constant C-style string
2453 Type[2]: const char *
2454 Parameter[3]: Options depending on value of Parameter[2]
2456 Type[3]: ...
2457 Explanation:
2459 This function works like calling the system snprintf() and then call‐
2461 ing ustr_add_buf().
2462 Function: ustr_dup_vfmt_lim()
2464 Returns: Pointer to a Ustr string
2465 Type: struct Ustr *
2466 Parameter[1]: Limit of data to dup
2468 Type[1]: size_t
2469 Parameter[2]: Pointer to a constant Ustr string
2471 Type[2]: const char *
2472 Parameter[3]: Variable argument list variable, from va_start()
2474 Type[3]: va_list
2475 Explanation:
2477 This function works like calling the system vsnprintf() with the
2479 limit (Parameter[2]) as the limit to vsnprintf() and then calling
2480 ustr_dup_buf().
2481 Function: ustr_dup_vfmt()
2483 Returns: Pointer to a Ustr string
2484 Type: struct Ustr *
2485 Parameter[1]: Limit of data to dup
2487 Type[1]: size_t
2488 Parameter[2]: Pointer to a constant Ustr string
2490 Type[2]: const char *
2491 Parameter[3]: Variable argument list variable, from va_start()
2493 Type[3]: va_list
2494 Explanation:
2496 This function works like calling the system vsnprintf() and then
2498 calling ustr_dup_buf().
2499 Function: ustr_dup_fmt_lim()
2501 Returns: Pointer to a Ustr string
2502 Type: struct Ustr *
2503 Parameter[1]: Limit of data to dup
2505 Type[1]: size_t
2506 Parameter[2]: Pointer to a constant Ustr string
2508 Type[2]: const char *
2509 Parameter[3]: Options depending on value of Parameter[2]
2511 Type[3]: ...
2512 Explanation:
2514 This function works like calling the system snprintf() with the limit
2516 (Parameter[2]) as the limit to snprintf() and then calling
2517 ustr_dup_buf().
2518 Function: ustr_dup_fmt()
2520 Returns: Pointer to a Ustr string
2521 Type: struct Ustr *
2522 Parameter[1]: Pointer to a constant Ustr string
2524 Type[1]: const char *
2525 Parameter[2]: Options depending on value of Parameter[1]
2527 Type[2]: ...
2528 Explanation:
2530 This function works like calling the system snprintf() and then call‐
2532 ing ustr_dup_buf().
2533 Function: ustr_dupx_fmt_lim()
2535 Returns: Pointer to a Ustr string
2536 Type: struct Ustr *
2537 Parameter[1]: Size of allocated storage
2539 Type[1]: size_t
2540 Parameter[2]: Number of bytes to use for reference count
2542 Type[2]: size_t
2543 Parameter[3]: Exact memory allocations
2545 Type[3]: int
2546 Parameter[4]: ENOMEM, memory error flag
2548 Type[4]: int
2549 Parameter[5]: Limit of data to dup
2551 Type[5]: size_t
2552 Parameter[6]: Pointer to a constant Ustr string
2554 Type[6]: const char *
2555 Parameter[7]: Options depending on value of Parameter[6]
2557 Type[7]: ...
2558 Explanation:
2560 This function works like calling the system snprintf() with the limit
2562 (Parameter[2]) as the limit to snprintf() and then calling
2563 ustr_dupx_buf().
2564 Function: ustr_dupx_fmt()
2566 Returns: Pointer to a Ustr string
2567 Type: struct Ustr *
2568 Parameter[1]: Size of allocated storage
2570 Type[1]: size_t
2571 Parameter[2]: Number of bytes to use for reference count
2573 Type[2]: size_t
2574 Parameter[3]: Exact memory allocations
2576 Type[3]: int
2577 Parameter[4]: ENOMEM, memory error flag
2579 Type[4]: int
2580 Parameter[5]: Pointer to a constant Ustr string
2582 Type[5]: const char *
2583 Parameter[6]: Options depending on value of Parameter[5]
2585 Type[6]: ...
2586 Explanation:
2588 This function works like calling the system snprintf() and then call‐
2590 ing ustr_dup_bufx().
2591 Function: ustr_set_vfmt_lim()
2593 Returns: Success or failure
2594 Type: int
2595 Parameter[1]: A pointer to a pointer to a Ustr string
2597 Type[1]: struct Ustr **
2598 Parameter[2]: Limit of data to set
2600 Type[2]: size_t
2601 Parameter[3]: A pointer to a constant C-style string
2603 Type[3]: const char *
2604 Parameter[4]: Variable argument list variable, from va_start()
2606 Type[4]: va_list
2607 Explanation:
2609 This function works like calling ustr_del() for all the data and then
2611 ustr_add_vfmt_lim().
2612 Function: ustr_set_vfmt()
2614 Returns: Success or failure
2615 Type: int
2616 Parameter[1]: A pointer to a pointer to a Ustr string
2618 Type[1]: struct Ustr **
2619 Parameter[2]: A pointer to a constant C-style string
2621 Type[2]: const char *
2622 Parameter[3]: Variable argument list variable, from va_start()
2624 Type[3]: va_list
2625 Explanation:
2627 This function works like calling ustr_del() for all the data and then
2629 ustr_add_vfmt().
2630 Function: ustr_set_fmt_lim()
2632 Returns: Success or failure
2633 Type: int
2634 Parameter[1]: A pointer to a pointer to a Ustr string
2636 Type[1]: struct Ustr **
2637 Parameter[2]: Limit of data to set
2639 Type[2]: size_t
2640 Parameter[3]: A pointer to a constant C-style string
2642 Type[3]: const char *
2643 Parameter[4]: Options depending on value of Parameter[3]
2645 Type[4]: ...
2646 Explanation:
2648 This function works like calling ustr_del() for all the data and then
2650 ustr_add_fmt_lim().
2651 Function: ustr_set_fmt()
2653 Returns: Success or failure
2654 Type: int
2655 Parameter[1]: A pointer to a pointer to a Ustr string
2657 Type[1]: struct Ustr **
2658 Parameter[2]: A pointer to a constant C-style string
2660 Type[2]: const char *
2661 Parameter[3]: Options depending on value of Parameter[2]
2663 Type[3]: ...
2664 Explanation:
2666 This function works like calling ustr_del() for all the data and then
2668 ustr_add_fmt().
2669 Function: ustr_ins_vfmt_lim()
2671 Returns: Success or failure
2672 Type: int
2673 Parameter[1]: A pointer to a pointer to a Ustr string
2675 Type[1]: struct Ustr **
2676 Parameter[2]: Position after which the data should be added
2678 Type[2]: size_t
2679 Parameter[3]: Limit of data to insert
2681 Type[3]: size_t
2682 Parameter[4]: A pointer to a constant C-style string
2684 Type[4]: const char *
2685 Parameter[5]: Variable argument list variable, from va_start()
2687 Type[5]: va_list
2688 Explanation:
2690 This function works like calling the system vsnprintf() with the
2692 limit (Parameter[3]) as the limit to vsnprintf() and then calling
2693 ustr_ins_buf().
2694 Function: ustr_ins_vfmt()
2696 Returns: Success or failure
2697 Type: int
2698 Parameter[1]: A pointer to a pointer to a Ustr string
2700 Type[1]: struct Ustr **
2701 Parameter[2]: Position after which the data should be added
2703 Type[2]: size_t
2704 Parameter[3]: A pointer to a constant C-style string
2706 Type[3]: const char *
2707 Parameter[4]: Variable argument list variable, from va_start()
2709 Type[4]: va_list
2710 Explanation:
2712 This function works like calling the system vsnprintf() and then
2714 calling ustr_ins_buf().
2715 Function: ustr_ins_fmt_lim()
2717 Returns: Success or failure
2718 Type: int
2719 Parameter[1]: A pointer to a pointer to a Ustr string
2721 Type[1]: struct Ustr **
2722 Parameter[2]: Position after which the data should be added
2724 Type[2]: size_t
2725 Parameter[3]: Limit of data to insert
2727 Type[3]: size_t
2728 Parameter[4]: A pointer to a constant C-style string
2730 Type[4]: const char *
2731 Parameter[5]: Options depending on value of Parameter[4]
2733 Type[5]: ...
2734 Explanation:
2736 This function works like calling the system snprintf() with the limit
2738 (Parameter[3]) as the limit to snprintf() and then calling
2739 ustr_ins_buf().
2740 Function: ustr_ins_fmt()
2742 Returns: Success or failure
2743 Type: int
2744 Parameter[1]: A pointer to a pointer to a Ustr string
2746 Type[1]: struct Ustr **
2747 Parameter[2]: Position after which the data should be added
2749 Type[2]: size_t
2750 Parameter[3]: A pointer to a constant C-style string
2752 Type[3]: const char *
2753 Parameter[4]: Options depending on value of Parameter[3]
2755 Type[4]: ...
2756 Explanation:
2758 This function works like calling the system snprintf() and then call‐
2760 ing ustr_ins_buf().
2761 Function: ustr_sub_vfmt_lim()
2763 Returns: Success or failure
2764 Type: int
2765 Parameter[1]: A pointer to a pointer to a Ustr string
2767 Type[1]: struct Ustr **
2768 Parameter[2]: Position where to start substitution
2770 Type[2]: size_t
2771 Parameter[3]: Limit of data to substitute
2773 Type[3]: size_t
2774 Parameter[4]: A pointer to a constant C-style string
2776 Type[4]: const char *
2777 Parameter[5]: Variable argument list variable, from va_start()
2779 Type[5]: va_list
2780 Explanation:
2782 This function works like calling the system vsnprintf() with the
2784 limit (Parameter[3]) as the limit to vsnprintf() and then calling
2785 ustr_sub_buf().
2786 Function: ustr_sub_vfmt()
2788 Returns: Success or failure
2789 Type: int
2790 Parameter[1]: A pointer to a pointer to a Ustr string
2792 Type[1]: struct Ustr **
2793 Parameter[2]: Position where to start substitution
2795 Type[2]: size_t
2796 Parameter[3]: A pointer to a constant C-style string
2798 Type[3]: const char *
2799 Parameter[4]: Variable argument list variable, from va_start()
2801 Type[4]: va_list
2802 Explanation:
2804 This function works like calling the system vsnprintf() and then
2806 calling ustr_sub_buf().
2807 Function: ustr_sub_fmt_lim()
2809 Returns: Success or failure
2810 Type: int
2811 Parameter[1]: A pointer to a pointer to a Ustr string
2813 Type[1]: struct Ustr **
2814 Parameter[2]: Position where to start substitution
2816 Type[2]: size_t
2817 Parameter[3]: Limit of data to substitute
2819 Type[3]: size_t
2820 Parameter[4]: A pointer to a constant C-style string
2822 Type[4]: const char *
2823 Parameter[5]: Options depending on value of Parameter[4]
2825 Type[5]: ...
2826 Explanation:
2828 This function works like calling the system snprintf() with the limit
2830 (Parameter[3]) as the limit to snprintf() and then calling
2831 ustr_sub_buf().
2832 Function: ustr_sub_fmt()
2834 Returns: Success or failure
2835 Type: int
2836 Parameter[1]: A pointer to a pointer to a Ustr string
2838 Type[1]: struct Ustr **
2839 Parameter[2]: Position where to start substitution
2841 Type[2]: size_t
2842 Parameter[3]: A pointer to a constant C-style string
2844 Type[3]: const char *
2845 Parameter[4]: Options depending on value of Parameter[3]
2847 Type[4]: ...
2848 Explanation:
2850 This function works like calling the system snprintf() and then call‐
2852 ing ustr_sub_buf().
2853 Function: ustr_sc_sub_vfmt_lim()
2855 Returns: Success or failure
2856 Type: int
2857 Parameter[1]: A pointer to a pointer to a Ustr string
2859 Type[1]: struct Ustr **
2860 Parameter[2]: Position where to start substitution
2862 Type[2]: size_t
2863 Parameter[3]: Length of substitution
2865 Type[3]: size_t
2866 Parameter[4]: Limit of data to substitute
2868 Type[4]: size_t
2869 Parameter[5]: A pointer to a constant C-style string
2871 Type[5]: const char *
2872 Parameter[6]: Variable argument list variable, from va_start()
2874 Type[6]: va_list
2875 Explanation:
2877 This function works like calling the system vsnprintf() with the
2879 limit (Parameter[4]) as the limit to vsnprintf() and then calling
2880 ustr_sc_sub_buf().
2881 Function: ustr_sc_sub_vfmt()
2883 Returns: Success or failure
2884 Type: int
2885 Parameter[1]: A pointer to a pointer to a Ustr string
2887 Type[1]: struct Ustr **
2888 Parameter[2]: Position where to start substitution
2890 Type[2]: size_t
2891 Parameter[3]: Length of substitution
2893 Type[3]: size_t
2894 Parameter[4]: A pointer to a constant C-style string
2896 Type[4]: const char *
2897 Parameter[5]: Variable argument list variable, from va_start()
2899 Type[5]: va_list
2900 Explanation:
2902 This function works like calling the system vsnprintf() and then
2904 calling ustr_sc_sub_buf().
2905 Function: ustr_sc_sub_fmt_lim()
2907 Returns: Success or failure
2908 Type: int
2909 Parameter[1]: A pointer to a pointer to a Ustr string
2911 Type[1]: struct Ustr **
2912 Parameter[2]: Position where to start substitution
2914 Type[2]: size_t
2915 Parameter[3]: Length of substitution
2917 Type[3]: size_t
2918 Parameter[4]: Limit of data to substitute
2920 Type[4]: size_t
2921 Parameter[5]: A pointer to a constant C-style string
2923 Type[5]: const char *
2924 Parameter[6]: Options depending on value of Parameter[5]
2926 Type[6]: ...
2927 Explanation:
2929 This function works like calling the system snprintf() with the limit
2931 (Parameter[3]) as the limit to snprintf() and then calling
2932 ustr_sc_sub_buf().
2933 Function: ustr_sc_sub_fmt()
2935 Returns: Success or failure
2936 Type: int
2937 Parameter[1]: A pointer to a pointer to a Ustr string
2939 Type[1]: struct Ustr **
2940 Parameter[2]: Position where to start substitution
2942 Type[2]: size_t
2943 Parameter[3]: Length of substitution
2945 Type[3]: size_t
2946 Parameter[4]: A pointer to a constant C-style string
2948 Type[4]: const char *
2949 Parameter[5]: Options depending on value of Parameter[5]
2951 Type[5]: ...
2952 Explanation:
2954 This function works like calling the system snprintf() and then call‐
2956 ing ustr_sc_sub_buf().
2957
2960 Function: ustr_len()
2961 Returns: The length of the Ustr
2962 Type: size_t
2963 Parameter[1]: A pointer to a constant Ustr string
2965 Type[1]: const struct Ustr *
2966 Explanation:
2968 This function returns the length of the data within the Ustr, much
2970 like strlen() but without getting the value wrong in the case of extra
2971 NIL bytes.
2972 Function: ustr_cstr()
2974 Returns: Read-only pointer to the start of data in the Ustr
2975 Type: const char *
2976 Parameter[1]: A pointer to a constant Ustr string
2978 Type[1]: const struct Ustr *
2979 Explanation:
2981 This function returns a read-only pointer to the start of the data of
2983 the Ustr string. Due to there always being a terminating NIL byte in a
2984 Ustr, this is also a valid C-style string.
2985 Function: ustr_wstr()
2987 Returns: Writable pointer to the start of data in the Ustr, or NULL
2988 Type: char *
2989 Parameter[1]: A pointer to a constant Ustr string
2991 Type[1]: struct Ustr *
2992 Explanation:
2994 This function returns a writable pointer to the start of the data of
2996 the Ustr string. Due to there always being a terminating NIL byte in a
2997 Ustr, this is also a valid C-style string.
2998 If the ustr is read-only (ustr_ro() == USTR_TRUE) then this function
2999 will return NULL.
3000 Note:
3002 Unless the string is owned (ustr_owner() == USTR_TRUE) it can be a
3004 very bad idea to use this to change data, as then all references will
3005 be updated. See ustr_sc_wstr().
3006 Function: ustr_alloc()
3008 Returns: A boolean flag of either USTR_TRUE or USTR_FALSE
3009 Type: int
3010 Parameter[1]: A pointer to a constant Ustr string
3012 Type[1]: const struct Ustr *
3013 Explanation:
3015 This function says if the Ustr is currently in allocated storage.
3017 Function: ustr_exact()
3019 Returns: A boolean flag of either USTR_TRUE or USTR_FALSE
3020 Type: int
3021 Parameter[1]: A pointer to a constant Ustr string
3023 Type[1]: const struct Ustr *
3024 Explanation:
3026 This function says if the Ustr is doing exact allocations, so as the
3028 Ustr grows it will only have storage allocated exactly as required and
3029 not in half powers of two.
3030 Note:
3032 This will always be USTR_FALSE for read-only Ustr strings (ustr_ro()
3034 == USTR_TRUE), even though the default may be to used exact sized allo‐
3035 cations when adding data to them etc.
3036 Function: ustr_sized()
3038 Returns: A boolean flag of either USTR_TRUE or USTR_FALSE
3039 Type: int
3040 Parameter[1]: A pointer to a constant Ustr string
3042 Type[1]: const struct Ustr *
3043 Explanation:
3045 This function says if the Ustr stores an explicit allocation size, if
3047 not the size is implied as the next highest half power of two.
3048 Function: ustr_ro()
3050 Returns: A boolean flag of either USTR_TRUE or USTR_FALSE
3051 Type: int
3052 Parameter[1]: A pointer to a constant Ustr string
3054 Type[1]: const struct Ustr *
3055 Explanation:
3057 This function says if the Ustr is current in read-only storage.
3059 Read-only storage is not writable but can be referenced via.
3060 ustr_dup() an infinite amount of times.
3061 Function: ustr_fixed()
3063 Returns: A boolean flag of either USTR_TRUE or USTR_FALSE
3064 Type: int
3065 Parameter[1]: A pointer to a constant Ustr string
3067 Type[1]: const struct Ustr *
3068 Explanation:
3070 This function says if the Ustr is current in fixed size storage.
3072 Fixed size storage is writable but cannot be referenced.
3073 Note:
3075 Fixed size storage always explicitly stores the size of the storage.
3077 Function: ustr_enomem()
3079 Returns: A boolean flag of either USTR_TRUE or USTR_FALSE
3080 Type: int
3081 Parameter[1]: A pointer to a constant Ustr string
3083 Type[1]: const struct Ustr *
3084 Explanation:
3086 This function just returns the value of the user settable flag in the
3088 Ustr. It can be set via. ustr_setf_enomem_err() and cleared by
3089 ustr_setf_enomem_clr().
3090 This function is automatically set to on whever a memory allocation
3091 failure happens for a Ustr.
3092 Note:
3094 If a Ustr is referenced multiple times, ustr_setf_enomem_err() will
3096 fail.
3097 This always fails for Ustr's in read-only storage.
3098 Function: ustr_shared()
3100 Returns: A boolean flag of either USTR_TRUE or USTR_FALSE
3101 Type: int
3102 Parameter[1]: A pointer to a constant Ustr string
3104 Type[1]: const struct Ustr *
3105 Explanation:
3107 This function says if the Ustr is in the "shared" mode. It can be set
3109 via. ustr_setf_shared() and cleared by ustr_setf_owner() on allocated
3110 Ustr's.
3111 Shared mode means that a Ustr can be referenced and unreferenced an
3112 infinite number of times.
3113 Note:
3115 This always succeeds for Ustr's in read-only storage.
3117 This always fails for Ustr's in fixed size storage.
3118 Function: ustr_limited()
3120 Returns: A boolean flag of either USTR_TRUE or USTR_FALSE
3121 Type: int
3122 Parameter[1]: A pointer to a constant Ustr string
3124 Type[1]: const struct Ustr *
3125 Explanation:
3127 This function says if the Ustr is currently in fixed size storage and
3129 cannot move to allocated storage.
3130 Note:
3132 This always fails for Ustr's in allocated storage.
3134 This always fails for Ustr's in read-only storage.
3135 Function: ustr_owner()
3137 Returns: A boolean flag of either USTR_TRUE or USTR_FALSE
3138 Type: int
3139 Parameter[1]: A pointer to a constant Ustr string
3141 Type[1]: const struct Ustr *
3142 Explanation:
3144 This function says if there is only a single reference to the Ustr
3146 string.
3147 Note:
3149 This always fails for Ustr's in read-only storage.
3151 This always succeeds for Ustr's in fixed size storage.
3152 Function: ustr_size()
3154 Returns: size_t
3155 Type: size_t
3156 Parameter[1]: A pointer to a constant Ustr string
3158 Type[1]: const struct Ustr *
3159 Explanation:
3161 This function calculates the maximum amount of data that could be
3163 stored (Ie. the max ustr_len()) without having to re-size the Ustr
3164 string.
3165 Function: ustr_size_alloc()
3167 Returns: size_t
3168 Type: size_t
3169 Parameter[1]: A pointer to a constant Ustr string
3171 Type[1]: const struct Ustr *
3172 Explanation:
3174 This function returns the size of the storage for the Ustr.
3176 Function: ustr_size_overhead()
3178 Returns: size_t
3179 Type: size_t
3180 Parameter[1]: A pointer to a constant Ustr string
3182 Type[1]: const struct Ustr *
3183 Explanation:
3185 This function returns the difference between the size of the storage
3187 and the maximum amount of data that could be stored without having to
3188 re-size the Ustr string.
3189 Function: ustr_conf()
3191 Returns: Nothing
3192 Type: void
3193 Parameter[1]: A pointer to a constant Ustr string
3195 Type[1]: const struct Ustr *
3196 Parameter[2]: Return size allocated number
3198 Type[2]: size_t *
3199 Parameter[3]: Return number of bytes used in the reference count
3201 Type[3]: size_t *
3202 Parameter[4]: Return exact allocations flag
3204 Type[4]: int *
3205 Parameter[5]: Return number of bytes used in the length
3207 Type[5]: size_t *
3208 Parameter[5]: Return number of references to this Ustr
3210 Type[5]: size_t *
3211 Explanation:
3213 This function gives the configuration of the current Ustr needed to
3215 duplicate it via. the ustr_dupx_*() functions. It also gives the number
3216 of bytes used for the length and the number of references, which are
3217 mainly informational.
3218 Note:
3220 This function differs from calling the ustr_exact() etc. functions in
3222 that it returns the global options if this Ustr isn't allocated, thus
3223 telling you what the configuration would be if the Ustr was turned into
3224 an allocated Ustr by adding data etc.
3225 Zero references for an allocated Ustr with a non-zero number of bytes
3226 for a reference count means it's in "shared" mode).
3227
3230 Function: ustr_setf_enomem_err()
3231 Returns: Success or failure
3232 Type: int
3233 Parameter[1]: A pointer to a Ustr string
3235 Type[1]: struct Ustr *
3236 Explanation:
3238 This function sets the enomem flag, which can be observed via. the
3240 ustr_enomem() function.
3241 The implication of setting this flag is that a memory error has
3242 occured in a previous function call on this Ustr.
3243 Note:
3245 This function fails if ustr_owner() fails for the Ustr.
3247 Function: ustr_setf_enomem_clr()
3249 Returns: Success or failure
3250 Type: int
3251 Parameter[1]: A pointer to a Ustr string
3253 Type[1]: struct Ustr *
3254 Explanation:
3256 This function clears the enomem flag, which can be observed via. the
3258 ustr_enomem() function.
3259 The implication of this flag being set is that a memory error has
3260 occured in a previous function call on this Ustr, so on clearing the
3261 flag you should know you have brought the Ustr back to a known state.
3262 Note:
3264 This function fails if ustr_owner() fails for the Ustr.
3266 Function: ustr_setf_share()
3268 Returns: Success or failure
3269 Type: int
3270 Parameter[1]: A pointer to a Ustr string
3272 Type[1]: struct Ustr *
3273 Explanation:
3275 This function sets the shared mode, which can be observed via. the
3277 ustr_shared() function.
3278 This is used on a Ustr so that it can have more references than it is
3279 able to hold in it's reference count. After this call the Ustr can be
3280 referenced and unreferenced an infinite number of times.
3281 Note:
3283 After this call the Ustr will never be deleted until
3285 ustr_setf_owner() is called.
3286 This function fails if ustr_alloc() fails for the Ustr.
3287 Function: ustr_setf_owner()
3289 Returns: Success or failure
3290 Type: int
3291 Parameter[1]: A pointer to a Ustr string
3293 Type[1]: struct Ustr *
3294 Explanation:
3296 This function removes the shared mode, which can be observed via. the
3298 ustr_shared() function.
3299 This is used so that a Ustr in shared mode can be free'd.
3300 Note:
3302 This function fails if ustr_alloc() fails for the Ustr.
3304
3307 Function: ustr_cmp_buf()
3308 Returns: Less then zero, zero or greater than zero depending on compar‐
3309 ison
3310 Type: int
3311 Parameter[1]: A pointer to a constant Ustr string
3313 Type[1]: const struct Ustr *
3314 Parameter[2]: A pointer to constant bytes, to compare
3316 Type[2]: const void *
3317 Parameter[3]: Length of comparison bytes
3319 Type[3]: size_t
3320 Explanation:
3322 This function works like memcmp() on the Ustr and the passed data.
3324 Function: ustr_cmp()
3326 Returns: Less then zero, zero or greater than zero depending on compar‐
3327 ison
3328 Type: int
3329 Parameter[1]: A pointer to a constant Ustr string
3331 Type[1]: const struct Ustr *
3332 Parameter[2]: A pointer to a constant Ustr string
3334 Type[2]: const struct Ustr *
3335 Explanation:
3337 This function works like ustr_cmp_buf() but with the data from
3339 ustr_cstr() and the length from ustr_len().
3340 Function: ustr_cmp_subustr()
3342 Returns: Less then zero, zero or greater than zero depending on compar‐
3343 ison
3344 Type: int
3345 Parameter[1]: A pointer to a constant Ustr string
3347 Type[1]: const struct Ustr *
3348 Parameter[2]: A pointer to a constant Ustr string
3350 Type[2]: const struct Ustr *
3351 Parameter[3]: Position in the Ustr
3353 Type[3]: size_t
3354 Parameter[4]: Length to compare from the Ustr
3356 Type[4]: size_t
3357 Explanation:
3359 This function works like ustr_cmp() but with a limit on the data and
3361 length.
3362 Function: ustr_cmp_cstr()
3364 Returns: Less then zero, zero or greater than zero depending on compar‐
3365 ison
3366 Type: int
3367 Parameter[1]: A pointer to a constant Ustr string
3369 Type[1]: const struct Ustr *
3370 Parameter[2]: A pointer to a constant C-style string
3372 Type[2]: const char *
3373 Explanation:
3375 This function works like ustr_cmp_buf() but with a length from
3377 strlen().
3378 Function: ustr_cmp_fast_buf()
3380 Returns: Less then zero, zero or greater than zero depending on compar‐
3381 ison
3382 Type: int
3383 Parameter[1]: A pointer to a constant Ustr string
3385 Type[1]: const struct Ustr *
3386 Parameter[2]: A pointer to constant bytes, to compare
3388 Type[2]: const void *
3389 Parameter[3]: Length of comparison bytes
3391 Type[3]: size_t
3392 Explanation:
3394 This function works like ustr_cmp_buf() but the order of comparison
3396 is optimized for speed, but is much less friendly to humans.
3397 Function: ustr_cmp_fast()
3399 Returns: Less then zero, zero or greater than zero depending on compar‐
3400 ison
3401 Type: int
3402 Parameter[1]: A pointer to a constant Ustr string
3404 Type[1]: const struct Ustr *
3405 Parameter[2]: A pointer to a constant Ustr string
3407 Type[2]: const struct Ustr *
3408 Explanation:
3410 This function works like ustr_cmp_fast_buf() but with the data from
3412 ustr_cstr() and the length from ustr_len().
3413 Function: ustr_cmp_fast_subustr()
3415 Returns: Less then zero, zero or greater than zero depending on compar‐
3416 ison
3417 Type: int
3418 Parameter[1]: A pointer to a constant Ustr string
3420 Type[1]: const struct Ustr *
3421 Parameter[2]: A pointer to a constant Ustr string
3423 Type[2]: const struct Ustr *
3424 Parameter[3]: Position in the Ustr
3426 Type[3]: size_t
3427 Parameter[4]: Length to compare from the Ustr
3429 Type[4]: size_t
3430 Explanation:
3432 This function works like ustr_cmp_fast() but with a limit on the data
3434 and length.
3435 Function: ustr_cmp_fast_cstr()
3437 Returns: Less then zero, zero or greater than zero depending on compar‐
3438 ison
3439 Type: int
3440 Parameter[1]: A pointer to a constant Ustr string
3442 Type[1]: const struct Ustr *
3443 Parameter[2]: A pointer to a constant C-style string
3445 Type[2]: const char *
3446 Explanation:
3448 This function works like ustr_cmp_fast_buf() but with a length from
3450 strlen().
3451 Function: ustr_cmp_case_buf()
3453 Returns: Less then zero, zero or greater than zero depending on compar‐
3454 ison
3455 Type: int
3456 Parameter[1]: A pointer to a constant Ustr string
3458 Type[1]: const struct Ustr *
3459 Parameter[2]: A pointer to constant bytes, to compare
3461 Type[2]: const void *
3462 Parameter[3]: Length of comparison bytes
3464 Type[3]: size_t
3465 Explanation:
3467 This function works like ustr_cmp_buf() but the order of comparison
3469 ignores ASCII case.
3470 Function: ustr_cmp_case()
3472 Returns: Less then zero, zero or greater than zero depending on compar‐
3473 ison
3474 Type: int
3475 Parameter[1]: A pointer to a constant Ustr string
3477 Type[1]: const struct Ustr *
3478 Parameter[2]: A pointer to a constant Ustr string
3480 Type[2]: const struct Ustr *
3481 Explanation:
3483 This function works like ustr_cmp_case_buf() but with the data from
3485 ustr_cstr() and the length from ustr_len().
3486 Function: ustr_cmp_case_subustr()
3488 Returns: Less then zero, zero or greater than zero depending on compar‐
3489 ison
3490 Type: int
3491 Parameter[1]: A pointer to a constant Ustr string
3493 Type[1]: const struct Ustr *
3494 Parameter[2]: A pointer to a constant Ustr string
3496 Type[2]: const struct Ustr *
3497 Parameter[3]: Position in the Ustr
3499 Type[3]: size_t
3500 Parameter[4]: Length to compare from the Ustr
3502 Type[4]: size_t
3503 Explanation:
3505 This function works like ustr_cmp_case() but with a limit on the data
3507 and length.
3508 Function: ustr_cmp_case_cstr()
3510 Returns: Less then zero, zero or greater than zero depending on compar‐
3511 ison
3512 Type: int
3513 Parameter[1]: A pointer to a constant Ustr string
3515 Type[1]: const struct Ustr *
3516 Parameter[2]: A pointer to a constant C-style string
3518 Type[2]: const char *
3519 Explanation:
3521 This function works like ustr_cmp_case_buf() but with a length from
3523 strlen().
3524 Function: ustr_cmp_eq()
3526 Returns: Success or failure
3527 Type: int
3528 Parameter[1]: A pointer to a constant Ustr string
3530 Type[1]: const struct Ustr *
3531 Parameter[2]: A pointer to a constant Ustr string
3533 Type[2]: const struct Ustr *
3534 Explanation:
3536 This function works like comparing ustr_cmp() against 0.
3538 Function: ustr_cmp_buf_eq()
3540 Returns: Success or failure
3541 Type: int
3542 Parameter[1]: A pointer to a constant Ustr string
3544 Type[1]: const struct Ustr *
3545 Parameter[2]: A pointer to constant bytes, to compare
3547 Type[2]: const void *
3548 Parameter[3]: Length of comparison bytes
3550 Type[3]: size_t
3551 Explanation:
3553 This function works like comparing ustr_cmp_buf() against 0.
3555 Function: ustr_cmp_subustr_eq()
3557 Returns: Success or failure
3558 Type: int
3559 Parameter[1]: A pointer to a constant Ustr string
3561 Type[1]: const struct Ustr *
3562 Parameter[2]: A pointer to a constant Ustr string
3564 Type[2]: const struct Ustr *
3565 Parameter[3]: Position in the Ustr
3567 Type[3]: size_t
3568 Parameter[4]: Length to compare from the Ustr
3570 Type[4]: size_t
3571 Explanation:
3573 This function works like comparing ustr_cmp_subustr() against 0.
3575 Function: ustr_cmp_cstr_eq()
3577 Returns: Success or failure
3578 Type: int
3579 Parameter[1]: A pointer to a constant Ustr string
3581 Type[1]: const struct Ustr *
3582 Parameter[2]: A pointer to a constant C-style string
3584 Type[2]: const char *
3585 Explanation:
3587 This function works like comparing ustr_cmp_cstr() against 0.
3589 Function: ustr_cmp_case_eq()
3591 Returns: Success or failure
3592 Type: int
3593 Parameter[1]: A pointer to a constant Ustr string
3595 Type[1]: const struct Ustr *
3596 Parameter[2]: A pointer to a constant Ustr string
3598 Type[2]: const struct Ustr *
3599 Explanation:
3601 This function works like comparing ustr_cmp_case() against 0.
3603 Function: ustr_cmp_case_buf_eq()
3605 Returns: Success or failure
3606 Type: int
3607 Parameter[1]: A pointer to a constant Ustr string
3609 Type[1]: const struct Ustr *
3610 Parameter[2]: A pointer to constant bytes, to compare
3612 Type[2]: const void *
3613 Parameter[3]: Length of comparison bytes
3615 Type[3]: size_t
3616 Explanation:
3618 This function works like comparing ustr_cmp_case_buf() against 0.
3620 Function: ustr_cmp_case_subustr_eq()
3622 Returns: Success or failure
3623 Type: int
3624 Parameter[1]: A pointer to a constant Ustr string
3626 Type[1]: const struct Ustr *
3627 Parameter[2]: A pointer to a constant Ustr string
3629 Type[2]: const struct Ustr *
3630 Parameter[3]: Position in the Ustr
3632 Type[3]: size_t
3633 Parameter[4]: Length to compare from the Ustr
3635 Type[4]: size_t
3636 Explanation:
3638 This function works like comparing ustr_cmp_case_subustr() against 0.
3640 Function: ustr_cmp_case_cstr_eq()
3642 Returns: Success or failure
3643 Type: int
3644 Parameter[1]: A pointer to a constant Ustr string
3646 Type[1]: const struct Ustr *
3647 Parameter[2]: A pointer to a constant C-style string
3649 Type[2]: const char *
3650 Explanation:
3652 This function works like comparing ustr_cmp_case_cstr() against 0.
3654 Function: ustr_cmp_prefix_eq()
3656 Returns: Success or failure
3657 Type: int
3658 Parameter[1]: A pointer to a constant Ustr string
3660 Type[1]: const struct Ustr *
3661 Parameter[2]: A pointer to a constant Ustr string
3663 Type[2]: const struct Ustr *
3664 Explanation:
3666 This function works like comparing ustr_cmp() against 0, but the com‐
3668 parison is limited to the length of the right hand side.
3669 Function: ustr_cmp_prefix_buf_eq()
3671 Returns: Success or failure
3672 Type: int
3673 Parameter[1]: A pointer to a constant Ustr string
3675 Type[1]: const struct Ustr *
3676 Parameter[2]: A pointer to constant bytes, to compare
3678 Type[2]: const void *
3679 Parameter[3]: Length of comparison bytes
3681 Type[3]: size_t
3682 Explanation:
3684 This function works like comparing ustr_cmp_buf() against 0, but the
3686 comparison is limited to the length of the right hand side (Parame‐
3687 ter[3]).
3688 Function: ustr_cmp_prefix_cstr_eq()
3690 Returns: Success or failure
3691 Type: int
3692 Parameter[1]: A pointer to a constant Ustr string
3694 Type[1]: const struct Ustr *
3695 Parameter[2]: A pointer to a constant C-style string
3697 Type[2]: const char *
3698 Explanation:
3700 This function works like comparing ustr_cmp_cstr() against 0, but the
3702 comparison is limited to the length of the right hand side.
3703 Function: ustr_cmp_prefix_subustr_eq()
3705 Returns: Success or failure
3706 Type: int
3707 Parameter[1]: A pointer to a constant Ustr string
3709 Type[1]: const struct Ustr *
3710 Parameter[2]: A pointer to a constant Ustr string
3712 Type[2]: const struct Ustr *
3713 Parameter[3]: Position in the Ustr
3715 Type[3]: size_t
3716 Parameter[4]: Length to compare from the Ustr
3718 Type[4]: size_t
3719 Explanation:
3721 This function works like comparing ustr_cmp_subustr() against 0, but
3723 the comparison is limited to the given length (Parameter[4]).
3724 Function: ustr_cmp_case_prefix_eq()
3726 Returns: Success or failure
3727 Type: int
3728 Parameter[1]: A pointer to a constant Ustr string
3730 Type[1]: const struct Ustr *
3731 Parameter[2]: A pointer to a constant Ustr string
3733 Type[2]: const struct Ustr *
3734 Explanation:
3736 This function works like comparing ustr_cmp_case() against 0, but the
3738 comparison is limited to the length of the right hand side.
3739 Function: ustr_cmp_case_prefix_buf_eq()
3741 Returns: Success or failure
3742 Type: int
3743 Parameter[1]: A pointer to a constant Ustr string
3745 Type[1]: const struct Ustr *
3746 Parameter[2]: A pointer to constant bytes, to compare
3748 Type[2]: const void *
3749 Parameter[3]: Length of comparison bytes
3751 Type[3]: size_t
3752 Explanation:
3754 This function works like comparing ustr_cmp_case_buf() against 0, but
3756 the comparison is limited to the length of the right hand side (Parame‐
3757 ter[3]).
3758 Function: ustr_cmp_case_prefix_cstr_eq()
3760 Returns: Success or failure
3761 Type: int
3762 Parameter[1]: A pointer to a constant Ustr string
3764 Type[1]: const struct Ustr *
3765 Parameter[2]: A pointer to a constant C-style string
3767 Type[2]: const char *
3768 Explanation:
3770 This function works like comparing ustr_cmp_case_cstr() against 0,
3772 but the comparison is limited to the length of the right hand side.
3773 Function: ustr_cmp_case_prefix_subustr_eq()
3775 Returns: Success or failure
3776 Type: int
3777 Parameter[1]: A pointer to a constant Ustr string
3779 Type[1]: const struct Ustr *
3780 Parameter[2]: A pointer to a constant Ustr string
3782 Type[2]: const struct Ustr *
3783 Parameter[3]: Position in the Ustr
3785 Type[3]: size_t
3786 Parameter[4]: Length to compare from the Ustr
3788 Type[4]: size_t
3789 Explanation:
3791 This function works like comparing ustr_cmp_case_subustr() against 0,
3793 but the comparison is limited to the given length (Parameter[4]).
3794 Function: ustr_cmp_suffix_eq()
3796 Returns: Success or failure
3797 Type: int
3798 Parameter[1]: A pointer to a constant Ustr string
3800 Type[1]: const struct Ustr *
3801 Parameter[2]: A pointer to a constant Ustr string
3803 Type[2]: const struct Ustr *
3804 Explanation:
3806 This function works like ustr_cmp_prefix_eq() but compares the end of
3808 the left hand side.
3809 Function: ustr_cmp_suffix_buf_eq()
3811 Returns: Success or failure
3812 Type: int
3813 Parameter[1]: A pointer to a constant Ustr string
3815 Type[1]: const struct Ustr *
3816 Parameter[2]: A pointer to constant bytes, to compare
3818 Type[2]: const void *
3819 Parameter[3]: Length of comparison bytes
3821 Type[3]: size_t
3822 Explanation:
3824 This function works like ustr_cmp_prefix_buf_eq() but compares the
3826 end of the left hand side.
3827 Function: ustr_cmp_suffix_cstr_eq()
3829 Returns: Success or failure
3830 Type: int
3831 Parameter[1]: A pointer to a constant Ustr string
3833 Type[1]: const struct Ustr *
3834 Parameter[2]: A pointer to a constant C-style string
3836 Type[2]: const char *
3837 Explanation:
3839 This function works like ustr_cmp_prefix_cstr_eq() but compares the
3841 end of the left hand side.
3842 Function: ustr_cmp_suffix_subustr_eq()
3844 Returns: Success or failure
3845 Type: int
3846 Parameter[1]: A pointer to a constant Ustr string
3848 Type[1]: const struct Ustr *
3849 Parameter[2]: A pointer to a constant Ustr string
3851 Type[2]: const struct Ustr *
3852 Parameter[3]: Position in the Ustr
3854 Type[3]: size_t
3855 Parameter[4]: Length to compare from the Ustr
3857 Type[4]: size_t
3858 Explanation:
3860 This function works like comparing ustr_cmp_subustr() against 0, but
3862 compares the end of the left hand side.
3863 Function: ustr_cmp_case_suffix_eq()
3865 Returns: Success or failure
3866 Type: int
3867 Parameter[1]: A pointer to a constant Ustr string
3869 Type[1]: const struct Ustr *
3870 Parameter[2]: A pointer to a constant Ustr string
3872 Type[2]: const struct Ustr *
3873 Explanation:
3875 This function works like ustr_cmp_case_prefix_eq() but compares the
3877 end of the left hand side.
3878 Function: ustr_cmp_case_suffix_buf_eq()
3880 Returns: Success or failure
3881 Type: int
3882 Parameter[1]: A pointer to a constant Ustr string
3884 Type[1]: const struct Ustr *
3885 Parameter[2]: A pointer to constant bytes, to compare
3887 Type[2]: const void *
3888 Parameter[3]: Length of comparison bytes
3890 Type[3]: size_t
3891 Explanation:
3893 This function works like ustr_cmp_case_prefix_buf_eq() but compares
3895 the end of the left hand side.
3896 Function: ustr_cmp_case_suffix_cstr_eq()
3898 Returns: Success or failure
3899 Type: int
3900 Parameter[1]: A pointer to a constant Ustr string
3902 Type[1]: const struct Ustr *
3903 Parameter[2]: A pointer to a constant C-style string
3905 Type[2]: const char *
3906 Explanation:
3908 This function works like ustr_cmp_case_prefix_cstr_eq() but compares
3910 the end of the left hand side.
3911 Function: ustr_cmp_case_suffix_subustr_eq()
3913 Returns: Success or failure
3914 Type: int
3915 Parameter[1]: A pointer to a constant Ustr string
3917 Type[1]: const struct Ustr *
3918 Parameter[2]: A pointer to a constant Ustr string
3920 Type[2]: const struct Ustr *
3921 Parameter[3]: Position in the Ustr
3923 Type[3]: size_t
3924 Parameter[4]: Length to compare from the Ustr
3926 Type[4]: size_t
3927 Explanation:
3929 This function works like comparing ustr_cmp_case_subustr() against 0,
3931 but compares the end of the left hand side.
3932
3935 Function: ustr_srch_chr_fwd()
3936 Returns: Position in the Ustr, or zero if not found
3937 Type: size_t
3938 Parameter[1]: A pointer to a constant Ustr string
3940 Type[1]: const struct Ustr *
3941 Parameter[2]: Offset within string to start searching at
3943 Type[2]: size_t
3944 Parameter[3]: Byte data to search for
3946 Type[3]: char
3947 Explanation:
3949 This function searches for the data (Parameter[3]) in the Ustr, skip‐
3951 ping an offset (Parameter[2]) number of bytes.
3952 Function: ustr_srch_chr_rev()
3954 Returns: Position in the Ustr, or zero if not found
3955 Type: size_t
3956 Parameter[1]: A pointer to a constant Ustr string
3958 Type[1]: const struct Ustr *
3959 Parameter[2]: Offset within string to start searching at
3961 Type[2]: size_t
3962 Parameter[3]: Byte data to search for
3964 Type[3]: char
3965 Explanation:
3967 This function works like ustr_srch_chr_fwd() but it searches from the
3969 end of the string to the beginning.
3970 Note:
3972 The searching starts from the end of the string, and so the offset is
3974 the offset from the end. However the position of a byte is always rela‐
3975 tive to the begining, so to do a loop you need to take the position
3976 from the length.
3977 Function: ustr_srch_buf_fwd()
3979 Returns: Position in the Ustr, or zero if not found
3980 Type: size_t
3981 Parameter[1]: A pointer to a constant Ustr string
3983 Type[1]: const struct Ustr *
3984 Parameter[2]: Offset within string to start searching at
3986 Type[2]: size_t
3987 Parameter[3]: A pointer to data to search for
3989 Type[3]: const void *
3990 Parameter[4]: Length of the data to search for
3992 Type[4]: size_t
3993 Explanation:
3995 This function searches for the data (Parameter[3]) of length (Parame‐
3997 ter[4]) in the Ustr, skipping an offset (Parameter[2]) number of bytes.
3998 Function: ustr_srch_buf_rev()
4000 Returns: Position in the Ustr, or zero if not found
4001 Type: size_t
4002 Parameter[1]: A pointer to a constant Ustr string
4004 Type[1]: const struct Ustr *
4005 Parameter[2]: Offset within string to start searching at
4007 Type[2]: size_t
4008 Parameter[3]: A pointer to data to search for
4010 Type[3]: const void *
4011 Parameter[4]: Length of the data to search for
4013 Type[4]: size_t
4014 Explanation:
4016 This function works like ustr_srch_buf_fwd() but it searches from the
4018 end of the string to the beginning.
4019 Note:
4021 The searching starts from the end of the string, and so the offset is
4023 the offset from the end. However the position of a byte is always rela‐
4024 tive to the begining, so to do a loop you need to take the position
4025 from the length.
4026 Function: ustr_srch_fwd()
4028 Returns: Position in the Ustr, or zero if not found
4029 Type: size_t
4030 Parameter[1]: A pointer to a constant Ustr string
4032 Type[1]: const struct Ustr *
4033 Parameter[2]: Offset within string to start searching at
4035 Type[2]: size_t
4036 Parameter[3]: A pointer to a constant Ustr string, to search for
4038 Type[3]: const struct Ustr *
4039 Explanation:
4041 This function works like ustr_srch_buf_fwd() but it gets the data
4043 pointer by calling ustr_cstr() and the length by calling ustr_len() on
4044 the passed Ustr (Parameter[3]).
4045 Function: ustr_srch_rev()
4047 Returns: Position in the Ustr, or zero if not found
4048 Type: size_t
4049 Parameter[1]: A pointer to a constant Ustr string
4051 Type[1]: const struct Ustr *
4052 Parameter[2]: Offset within string to start searching at
4054 Type[2]: size_t
4055 Parameter[3]: A pointer to a constant Ustr string, to search for
4057 Type[3]: const struct Ustr *
4058 Explanation:
4060 This function works like ustr_srch_fwd() but it searches from the end
4062 of the string to the beginning.
4063 Note:
4065 The searching starts from the end of the string, and so the offset is
4067 the offset from the end. However the position of a byte is always rela‐
4068 tive to the begining, so to do a loop you need to take the position
4069 from the length.
4070 Function: ustr_srch_cstr_fwd()
4072 Returns: Position in the Ustr, or zero if not found
4073 Type: size_t
4074 Parameter[1]: A pointer to a constant Ustr string
4076 Type[1]: const struct Ustr *
4077 Parameter[2]: Offset within string to start searching at
4079 Type[2]: size_t
4080 Parameter[3]: A pointer to C-style string data, to search for
4082 Type[3]: const char *
4083 Explanation:
4085 This function works like ustr_srch_buf_fwd() but it gets the length
4087 by calling strlen() on the passed data (Parameter[3]).
4088 Function: ustr_srch_cstr_rev()
4090 Returns: Position in the Ustr, or zero if not found
4091 Type: size_t
4092 Parameter[1]: A pointer to a constant Ustr string
4094 Type[1]: const struct Ustr *
4095 Parameter[2]: Offset within string to start searching at
4097 Type[2]: size_t
4098 Parameter[3]: A pointer to C-style string data, to search for
4100 Type[3]: const char *
4101 Explanation:
4103 This function works like ustr_srch_cstr_fwd() but it searches from
4105 the end of the string to the beginning.
4106 Note:
4108 The searching starts from the end of the string, and so the offset is
4110 the offset from the end. However the position of a byte is always rela‐
4111 tive to the begining, so to do a loop you need to take the position
4112 from the length.
4113 Function: ustr_srch_subustr_fwd()
4115 Returns: Position in the Ustr, or zero if not found
4116 Type: size_t
4117 Parameter[1]: A pointer to a constant Ustr string
4119 Type[1]: const struct Ustr *
4120 Parameter[2]: Offset within string to start searching at
4122 Type[2]: size_t
4123 Parameter[3]: A pointer to a constant Ustr string
4125 Type[3]: const struct Ustr *
4126 Parameter[4]: Position in the Ustr
4128 Type[4]: size_t
4129 Parameter[5]: Length of data to search, from the Ustr
4131 Type[5]: size_t
4132 Explanation:
4134 This function works like ustr_srch_fwd() but it moves the data to
4136 start at the correct position and limits the length to the value speci‐
4137 fied.
4138 Function: ustr_srch_subustr_rev()
4140 Returns: Position in the Ustr, or zero if not found
4141 Type: size_t
4142 Parameter[1]: A pointer to a constant Ustr string
4144 Type[1]: const struct Ustr *
4145 Parameter[2]: Offset within string to start searching at
4147 Type[2]: size_t
4148 Parameter[3]: A pointer to a constant Ustr string
4150 Type[3]: const struct Ustr *
4151 Parameter[4]: Position in the Ustr
4153 Type[4]: size_t
4154 Parameter[5]: Length of data to search, from the Ustr
4156 Type[5]: size_t
4157 Explanation:
4159 This function works like ustr_srch_rev() but it moves the data to
4161 start at the correct position and limits the length to the value speci‐
4162 fied.
4163 Note:
4165 The searching starts from the end of the string, and so the offset is
4167 the offset from the end. However the position of a byte is always rela‐
4168 tive to the begining, so to do a loop you need to take the position
4169 from the length.
4170 Function: ustr_srch_case_chr_fwd()
4172 Returns: Position in the Ustr, or zero if not found
4173 Type: size_t
4174 Parameter[1]: A pointer to a constant Ustr string
4176 Type[1]: const struct Ustr *
4177 Parameter[2]: Offset within string to start searching at
4179 Type[2]: size_t
4180 Parameter[3]: Byte data to search for
4182 Type[3]: char
4183 Explanation:
4185 This function works like ustr_srch_chr_fwd(), but treats ASCII upper‐
4187 case and lowercase as equivalent.
4188 Function: ustr_srch_case_chr_rev()
4190 Returns: Position in the Ustr, or zero if not found
4191 Type: size_t
4192 Parameter[1]: A pointer to a constant Ustr string
4194 Type[1]: const struct Ustr *
4195 Parameter[2]: Offset within string to start searching at
4197 Type[2]: size_t
4198 Parameter[3]: Byte data to search for
4200 Type[3]: char
4201 Explanation:
4203 This function works like ustr_srch_chr_fwd(), but treats ASCII upper‐
4205 case and lowercase as equivalent.
4206 Function: ustr_srch_case_buf_fwd()
4208 Returns: Position in the Ustr, or zero if not found
4209 Type: size_t
4210 Parameter[1]: A pointer to a constant Ustr string
4212 Type[1]: const struct Ustr *
4213 Parameter[2]: Offset within string to start searching at
4215 Type[2]: size_t
4216 Parameter[3]: A pointer to data to search for
4218 Type[3]: const void *
4219 Parameter[4]: Length of the data to search for
4221 Type[4]: size_t
4222 Explanation:
4224 This function works like ustr_srch_buf_fwd(), but treats ASCII upper‐
4226 case and lowercase as equivalent.
4227 Function: ustr_srch_case_buf_rev()
4229 Returns: Position in the Ustr, or zero if not found
4230 Type: size_t
4231 Parameter[1]: A pointer to a constant Ustr string
4233 Type[1]: const struct Ustr *
4234 Parameter[2]: Offset within string to start searching at
4236 Type[2]: size_t
4237 Parameter[3]: A pointer to data to search for
4239 Type[3]: const void *
4240 Parameter[4]: Length of the data to search for
4242 Type[4]: size_t
4243 Explanation:
4245 This function works like ustr_srch_buf_rev(), but treats ASCII upper‐
4247 case and lowercase as equivalent.
4248 Function: ustr_srch_case_fwd()
4250 Returns: Position in the Ustr, or zero if not found
4251 Type: size_t
4252 Parameter[1]: A pointer to a constant Ustr string
4254 Type[1]: const struct Ustr *
4255 Parameter[2]: Offset within string to start searching at
4257 Type[2]: size_t
4258 Parameter[3]: A pointer to a constant Ustr string, to search for
4260 Type[3]: const struct Ustr *
4261 Explanation:
4263 This function works like ustr_srch_fwd(), but treats ASCII uppercase
4265 and lowercase as equivalent.
4266 Function: ustr_srch_case_rev()
4268 Returns: Position in the Ustr, or zero if not found
4269 Type: size_t
4270 Parameter[1]: A pointer to a constant Ustr string
4272 Type[1]: const struct Ustr *
4273 Parameter[2]: Offset within string to start searching at
4275 Type[2]: size_t
4276 Parameter[3]: A pointer to a constant Ustr string, to search for
4278 Type[3]: const struct Ustr *
4279 Explanation:
4281 This function works like ustr_srch_rev(), but treats ASCII uppercase
4283 and lowercase as equivalent.
4284 Function: ustr_srch_case_cstr_fwd()
4286 Returns: Position in the Ustr, or zero if not found
4287 Type: size_t
4288 Parameter[1]: A pointer to a constant Ustr string
4290 Type[1]: const struct Ustr *
4291 Parameter[2]: Offset within string to start searching at
4293 Type[2]: size_t
4294 Parameter[3]: A pointer to C-style string data, to search for
4296 Type[3]: const char *
4297 Explanation:
4299 This function works like ustr_srch_cstr_fwd(), but treats ASCII
4301 uppercase and lowercase as equivalent.
4302 Function: ustr_srch_case_cstr_rev()
4304 Returns: Position in the Ustr, or zero if not found
4305 Type: size_t
4306 Parameter[1]: A pointer to a constant Ustr string
4308 Type[1]: const struct Ustr *
4309 Parameter[2]: Offset within string to start searching at
4311 Type[2]: size_t
4312 Parameter[3]: A pointer to C-style string data, to search for
4314 Type[3]: const char *
4315 Explanation:
4317 This function works like ustr_srch_cstr_rev(), but treats ASCII
4319 uppercase and lowercase as equivalent.
4320 Function: ustr_srch_case_subustr_fwd()
4322 Returns: Position in the Ustr, or zero if not found
4323 Type: size_t
4324 Parameter[1]: A pointer to a constant Ustr string
4326 Type[1]: const struct Ustr *
4327 Parameter[2]: Offset within string to start searching at
4329 Type[2]: size_t
4330 Parameter[3]: A pointer to a constant Ustr string
4332 Type[3]: const struct Ustr *
4333 Parameter[4]: Position in the Ustr
4335 Type[4]: size_t
4336 Parameter[5]: Length of data to search, from the Ustr
4338 Type[5]: size_t
4339 Explanation:
4341 This function works like ustr_srch_subustr_fwd(), but treats ASCII
4343 uppercase and lowercase as equivalent.
4344 Function: ustr_srch_case_subustr_rev()
4346 Returns: Position in the Ustr, or zero if not found
4347 Type: size_t
4348 Parameter[1]: A pointer to a constant Ustr string
4350 Type[1]: const struct Ustr *
4351 Parameter[2]: Offset within string to start searching at
4353 Type[2]: size_t
4354 Parameter[3]: A pointer to a constant Ustr string
4356 Type[3]: const struct Ustr *
4357 Parameter[4]: Position in the Ustr
4359 Type[4]: size_t
4360 Parameter[5]: Length of data to search, from the Ustr
4362 Type[5]: size_t
4363 Explanation:
4365 This function works like ustr_srch_subustr_rev(), but treats ASCII
4367 uppercase and lowercase as equivalent.
4368
4371 Function: ustr_spn_chr_fwd()
4372 Returns: Number of bytes in the span
4373 Type: size_t
4374 Parameter[1]: A pointer to a constant Ustr string
4376 Type[1]: const struct Ustr *
4377 Parameter[2]: Offset within string, to start spanning from
4379 Type[2]: size_t
4380 Parameter[3]: Byte data
4382 Type[3]: char
4383 Explanation:
4385 This function returns the length of the start of the Ustr (Parame‐
4387 ter[1]) that only contains bytes that are equal to the data (Parame‐
4388 ter[3]), skipping offset (Parameter[2]) bytes.
4389 Function: ustr_spn_chr_rev()
4391 Returns: Number of bytes in the span
4392 Type: size_t
4393 Parameter[1]: A pointer to a constant Ustr string
4395 Type[1]: const struct Ustr *
4396 Parameter[2]: Offset within string, to start spanning from
4398 Type[2]: size_t
4399 Parameter[3]: Byte data
4401 Type[3]: char
4402 Explanation:
4404 This function returns the length of the end of the Ustr (Parame‐
4406 ter[1]) that only contains bytes that are equal to the data (Parame‐
4407 ter[3]), skipping offset (Parameter[2]) bytes.
4408 Function: ustr_spn_chrs_fwd()
4410 Returns: Number of bytes in the span
4411 Type: size_t
4412 Parameter[1]: A pointer to a constant Ustr string
4414 Type[1]: const struct Ustr *
4415 Parameter[2]: Offset within string, to start spanning from
4417 Type[2]: size_t
4418 Parameter[3]: Array of byte data, for spanning
4420 Type[3]: const char *
4421 Parameter[4]: Length of byte data, for spanning
4423 Type[4]: size_t
4424 Explanation:
4426 This function returns the length of the start of the Ustr (Parame‐
4428 ter[1]) that only contains bytes that are equal to any byte in the data
4429 (Parameter[3]), skipping offset (Parameter[2]) bytes.
4430 Function: ustr_spn_chrs_rev()
4432 Returns: Number of bytes in the span
4433 Type: size_t
4434 Parameter[1]: A pointer to a constant Ustr string
4436 Type[1]: const struct Ustr *
4437 Parameter[2]: Offset within string, to start spanning from
4439 Type[2]: size_t
4440 Parameter[3]: Array of byte data
4442 Type[3]: const char *
4443 Parameter[4]: Length of byte data
4445 Type[4]: size_t
4446 Explanation:
4448 This function returns the length of the end of the Ustr (Parame‐
4450 ter[1]) that only contains bytes that are equal to any byte in the data
4451 (Parameter[3]), skipping offset (Parameter[2]) bytes.
4452 Function: ustr_spn_fwd()
4454 Returns: Number of bytes in the span
4455 Type: size_t
4456 Parameter[1]: A pointer to a constant Ustr string
4458 Type[1]: const struct Ustr *
4459 Parameter[2]: Offset within string, to start spanning from
4461 Type[2]: size_t
4462 Parameter[3]: A pointer to a constant Ustr string, containing spanning
4464 bytes
4465 Type[3]: const struct Ustr *
4466 Explanation:
4468 This function works like ustr_spn_buf_fwd() but passing ustr_cstr()
4470 and ustr_len()
4471 Function: ustr_spn_rev()
4473 Returns: Number of bytes in the span
4474 Type: size_t
4475 Parameter[1]: A pointer to a constant Ustr string
4477 Type[1]: const struct Ustr *
4478 Parameter[2]: Offset within string, to start spanning from
4480 Type[2]: size_t
4481 Parameter[3]: A pointer to a constant Ustr string, containing spanning
4483 bytes
4484 Type[3]: const struct Ustr *
4485 Explanation:
4487 This function works like ustr_spn_buf_rev() but passing ustr_cstr()
4489 and ustr_len()
4490 Function: ustr_spn_cstr_fwd()
4492 Returns: Number of bytes in the span
4493 Type: size_t
4494 Parameter[1]: A pointer to a constant Ustr string
4496 Type[1]: const struct Ustr *
4497 Parameter[2]: Offset within string, to start spanning from
4499 Type[2]: size_t
4500 Parameter[3]: A pointer to a constant C-style string, containing span‐
4502 ning bytes
4503 Type[3]: const char *
4504 Explanation:
4506 This function works like ustr_spn_buf_fwd() but passing strlen() for
4508 the length.
4509 Function: ustr_spn_cstr_rev()
4511 Returns: Number of bytes in the span
4512 Type: size_t
4513 Parameter[1]: A pointer to a constant Ustr string
4515 Type[1]: const struct Ustr *
4516 Parameter[2]: Offset within string, to start spanning from
4518 Type[2]: size_t
4519 Parameter[3]: A pointer to a constant C-style string, containing span‐
4521 ning bytes
4522 Type[3]: const char *
4523 Explanation:
4525 This function works like ustr_spn_buf_rev() but passing strlen() for
4527 the length.
4528 Function: ustr_cspn_chr_fwd()
4530 Returns: Number of bytes not in the span
4531 Type: size_t
4532 Parameter[1]: A pointer to a constant Ustr string
4534 Type[1]: const struct Ustr *
4535 Parameter[2]: Offset within string, to start compliment spanning from
4537 Type[2]: size_t
4538 Parameter[3]: Byte data
4540 Type[3]: char
4541 Explanation:
4543 This function returns the length of the start of the Ustr (Parame‐
4545 ter[1]) that only contains bytes that are not equal to the data (Param‐
4546 eter[3]), skipping offset (Parameter[2]) bytes.
4547 Function: ustr_cspn_chr_rev()
4549 Returns: Number of bytes not in the span
4550 Type: size_t
4551 Parameter[1]: A pointer to a constant Ustr string
4553 Type[1]: const struct Ustr *
4554 Parameter[2]: Offset within string, to start compliment spanning from
4556 Type[2]: size_t
4557 Parameter[3]: Byte data
4559 Type[3]: char
4560 Explanation:
4562 This function returns the length of the end of the Ustr (Parame‐
4564 ter[1]) that only contains bytes that are not equal to the data (Param‐
4565 eter[3]), skipping offset (Parameter[2]) bytes.
4566 Function: ustr_cspn_chrs_fwd()
4568 Returns: Number of bytes not in the span
4569 Type: size_t
4570 Parameter[1]: A pointer to a constant Ustr string
4572 Type[1]: const struct Ustr *
4573 Parameter[2]: Offset within string, to start compliment spanning from
4575 Type[2]: size_t
4576 Parameter[3]: Array of byte data
4578 Type[3]: const char *
4579 Parameter[4]: Length of byte data
4581 Type[4]: size_t
4582 Explanation:
4584 This function returns the length of the start of the Ustr (Parame‐
4586 ter[1]) that only contains bytes that are not equal to any byte in the
4587 data (Parameter[3]), skipping offset (Parameter[2]) bytes.
4588 Function: ustr_cspn_chrs_rev()
4590 Returns: Number of bytes not in the span
4591 Type: size_t
4592 Parameter[1]: A pointer to a constant Ustr string
4594 Type[1]: const struct Ustr *
4595 Parameter[2]: Offset within string, to start compliment spanning from
4597 Type[2]: size_t
4598 Parameter[3]: Array of byte data
4600 Type[3]: const char *
4601 Parameter[4]: Length of byte data
4603 Type[4]: size_t
4604 Explanation:
4606 This function returns the length of the end of the Ustr (Parame‐
4608 ter[1]) that only contains bytes that are not equal to any byte in the
4609 data (Parameter[3]), skipping offset (Parameter[2]) bytes.
4610 Function: ustr_cspn_fwd()
4612 Returns: Number of bytes not in the span
4613 Type: size_t
4614 Parameter[1]: A pointer to a constant Ustr string
4616 Type[1]: const struct Ustr *
4617 Parameter[2]: Offset within string, to start compliment spanning from
4619 Type[2]: size_t
4620 Parameter[3]: A pointer to a constant Ustr string, containing spanning
4622 bytes
4623 Type[3]: const struct Ustr *
4624 Explanation:
4626 This function works like ustr_cspn_buf_fwd() but passing ustr_cstr()
4628 and ustr_len()
4629 Function: ustr_cspn_rev()
4631 Returns: Number of bytes not in the span
4632 Type: size_t
4633 Parameter[1]: A pointer to a constant Ustr string
4635 Type[1]: const struct Ustr *
4636 Parameter[2]: Offset within string, to start compliment spanning from
4638 Type[2]: size_t
4639 Parameter[3]: A pointer to a constant Ustr string, containing spanning
4641 bytes
4642 Type[3]: const struct Ustr *
4643 Explanation:
4645 This function works like ustr_cspn_buf_rev() but passing ustr_cstr()
4647 and ustr_len()
4648 Function: ustr_cspn_cstr_fwd()
4650 Returns: Number of bytes not in the span
4651 Type: size_t
4652 Parameter[1]: A pointer to a constant Ustr string
4654 Type[1]: const struct Ustr *
4655 Parameter[2]: Offset within string, to start compliment spanning from
4657 Type[2]: size_t
4658 Parameter[3]: A pointer to a constant C-style string, containing span‐
4660 ning bytes
4661 Type[3]: const char *
4662 Explanation:
4664 This function works like ustr_cspn_buf_fwd() but passing strlen() for
4666 the length.
4667 Function: ustr_cspn_cstr_rev()
4669 Returns: Number of bytes not in the span
4670 Type: size_t
4671 Parameter[1]: A pointer to a constant Ustr string
4673 Type[1]: const struct Ustr *
4674 Parameter[2]: Offset within string, to start spanning from
4676 Type[2]: size_t
4677 Parameter[3]: A pointer to a constant C-style string, containing span‐
4679 ning bytes
4680 Type[3]: const char *
4681 Explanation:
4683 This function works like ustr_cspn_buf_rev() but passing strlen() for
4685 the length.
4686 Function: ustr_utf8_spn_chrs_fwd()
4688 Returns: Number of UTF-8 characters not in the span
4689 Type: size_t
4690 Parameter[1]: A pointer to a constant Ustr UTF-8 string
4692 Type[1]: const struct Ustr *
4693 Parameter[2]: Offset within string, in UTF-8 characters, to start span‐
4695 ning from
4696 Type[2]: size_t
4697 Parameter[3]: A pointer to a constant C-style UTF-8 string
4699 Type[3]: const char *
4700 Parameter[4]: Length of the C-style UTF-8 string
4702 Type[4]: size_t
4703 Explanation:
4705 This function works like ustr_spn_chrs_fwd() but the return value,
4707 offset, and length all use UTF-8 characters and not bytes.
4708 Note:
4710 This is much slower than ustr_spn_chrs_fwd() but given "xy" as a
4712 multi-byte UTF-8 character it understands that the span over "xyxz" is
4713 1 UTF-8 character and not 3 bytes.
4714 Function: ustr_utf8_spn_chrs_rev()
4716 Returns: Number of UTF-8 characters not in the span
4717 Type: size_t
4718 Parameter[1]: A pointer to a constant Ustr UTF-8 string
4720 Type[1]: const struct Ustr *
4721 Parameter[2]: Offset within string, in UTF-8 characters, to start span‐
4723 ning from
4724 Type[2]: size_t
4725 Parameter[3]: A pointer to a constant C-style UTF-8 string
4727 Type[3]: const char *
4728 Parameter[4]:
4730 Type[4]: size_t
4731 Explanation:
4733 This function works like ustr_spn_chrs_rev() but the return value,
4735 offset, and length all use UTF-8 characters and not bytes.
4736 Note:
4738 This is much slower than ustr_spn_chrs_rev() but given "xy" as a
4740 multi-byte UTF-8 character it understands that the span over "xyxz" is
4741 1 UTF-8 character and not 3 bytes.
4742 Function: ustr_utf8_spn_fwd()
4744 Returns: Number of UTF-8 characters not in the span
4745 Type: size_t
4746 Parameter[1]: A pointer to a constant Ustr UTF-8 string
4748 Type[1]: const struct Ustr *
4749 Parameter[2]: Offset within string, in UTF-8 characters, to start span‐
4751 ning from
4752 Type[2]: size_t
4753 Parameter[3]: A pointer to a constant Ustr UTF-8 string
4755 Type[3]: const struct Ustr *
4756 Explanation:
4758 This function works like ustr_spn_fwd() but the return value, offset,
4760 and length all use UTF-8 characters and not bytes.
4761 Note:
4763 This is much slower than ustr_spn_fwd() but given "xy" as a
4765 multi-byte UTF-8 character it understands that the span over "xyxz" is
4766 1 UTF-8 character and not 3 bytes.
4767 Function: ustr_utf8_spn_rev()
4769 Returns: Number of UTF-8 characters not in the span
4770 Type: size_t
4771 Parameter[1]: A pointer to a constant Ustr UTF-8 string
4773 Type[1]: const struct Ustr *
4774 Parameter[2]: Offset within string, in UTF-8 characters, to start span‐
4776 ning from
4777 Type[2]: size_t
4778 Parameter[3]: A pointer to a constant Ustr UTF-8 string
4780 Type[3]: const struct Ustr *
4781 Explanation:
4783 This function works like ustr_spn_rev() but the return value, offset,
4785 and length all use UTF-8 characters and not bytes.
4786 Note:
4788 This is much slower than ustr_spn_rev() but given "xy" as a
4790 multi-byte UTF-8 character it understands that the span over "xyxz" is
4791 1 UTF-8 character and not 3 bytes.
4792 Function: ustr_utf8_spn_cstr_fwd()
4794 Returns: Number of UTF-8 characters not in the span
4795 Type: size_t
4796 Parameter[1]: A pointer to a constant Ustr UTF-8 string
4798 Type[1]: const struct Ustr *
4799 Parameter[2]: Offset within string, in UTF-8 characters, to start span‐
4801 ning from
4802 Type[2]: size_t
4803 Parameter[3]: A pointer to a constant C-style UTF-8 string
4805 Type[3]: const char *
4806 Explanation:
4808 This function works like ustr_spn_cstr_fwd() but the return value,
4810 offset, and length all use UTF-8 characters and not bytes.
4811 Note:
4813 This is much slower than ustr_spn_cstr_fwd() but given "xy" as a
4815 multi-byte UTF-8 character it understands that the span over "xyxz" is
4816 1 UTF-8 character and not 3 bytes.
4817 Function: ustr_utf8_spn_cstr_rev()
4819 Returns: Number of UTF-8 characters not in the span
4820 Type: size_t
4821 Parameter[1]: A pointer to a constant Ustr UTF-8 string
4823 Type[1]: const struct Ustr *
4824 Parameter[2]: Offset within string, in UTF-8 characters, to start span‐
4826 ning from
4827 Type[2]: size_t
4828 Parameter[3]: A pointer to a constant C-style UTF-8 string
4830 Type[3]: const char *
4831 Explanation:
4833 This function works like ustr_spn_cstr_rev() but the return value,
4835 offset, and length all use UTF-8 characters and not bytes.
4836 Note:
4838 This is much slower than ustr_spn_cstr_rev() but given "xy" as a
4840 multi-byte UTF-8 character it understands that the span over "xyxz" is
4841 1 UTF-8 character and not 3 bytes.
4842 Function: ustr_utf8_cspn_chrs_fwd()
4844 Returns: Number of UTF-8 characters not in the span
4845 Type: size_t
4846 Parameter[1]: A pointer to a constant Ustr UTF-8 string
4848 Type[1]: const struct Ustr *
4849 Parameter[2]: Offset within string, in UTF-8 characters, to start com‐
4851 pliment spanning from
4852 Type[2]: size_t
4853 Parameter[3]: A pointer to a constant C-style UTF-8 string
4855 Type[3]: const char *
4856 Parameter[4]: Length of the C-style UTF-8 string
4858 Type[4]: size_t
4859 Explanation:
4861 This function works like ustr_cspn_chrs_fwd() but the return value,
4863 offset, and length all use UTF-8 characters and not bytes.
4864 Note:
4866 This is much slower than ustr_cspn_chrs_fwd() but given "xy" as a
4868 multi-byte UTF-8 character it understands that the compliment span over
4869 "xzxy" is 1 UTF-8 character and not 0 bytes.
4870 Function: ustr_utf8_cspn_chrs_rev()
4872 Returns: Number of UTF-8 characters not in the span
4873 Type: size_t
4874 Parameter[1]: A pointer to a constant Ustr UTF-8 string
4876 Type[1]: const struct Ustr *
4877 Parameter[2]: Offset within string, in UTF-8 characters, to start com‐
4879 pliment spanning from
4880 Type[2]: size_t
4881 Parameter[3]: A pointer to a constant C-style UTF-8 string
4883 Type[3]: const char *
4884 Parameter[4]: Length of the C-style UTF-8 string
4886 Type[4]: size_t
4887 Explanation:
4889 This function works like ustr_cspn_chrs_rev() but the return value,
4891 offset, and length all use UTF-8 characters and not bytes.
4892 Note:
4894 This is much slower than ustr_cspn_chrs_rev() but given "xy" as a
4896 multi-byte UTF-8 character it understands that the compliment span over
4897 "xzxy" is 1 UTF-8 character and not 0 bytes.
4898 Function: ustr_utf8_cspn_fwd()
4900 Returns: Number of UTF-8 characters not in the span
4901 Type: size_t
4902 Parameter[1]: A pointer to a constant Ustr UTF-8 string
4904 Type[1]: const struct Ustr *
4905 Parameter[2]: Offset within string, in UTF-8 characters, to start com‐
4907 pliment spanning from
4908 Type[2]: size_t
4909 Parameter[3]: A pointer to a constant Ustr UTF-8 string, containing
4911 spanning data
4912 Type[3]: const struct Ustr *
4913 Explanation:
4915 This function works like ustr_cspn_fwd() but the return value, off‐
4917 set, and length all use UTF-8 characters and not bytes.
4918 Note:
4920 This is much slower than ustr_cspn_fwd() but given "xy" as a
4922 multi-byte UTF-8 character it understands that the compliment span over
4923 "xzxy" is 1 UTF-8 character and not 0 bytes.
4924 Function: ustr_utf8_cspn_rev()
4926 Returns: Number of UTF-8 characters not in the span
4927 Type: size_t
4928 Parameter[1]: A pointer to a constant Ustr UTF-8 string
4930 Type[1]: const struct Ustr *
4931 Parameter[2]: Offset within string, in UTF-8 characters, to start com‐
4933 pliment spanning from
4934 Type[2]: size_t
4935 Parameter[3]: A pointer to constant Ustr UTF-8 string data, containing
4937 spanning data
4938 Type[3]: const struct Ustr *
4939 Explanation:
4941 This function works like ustr_cspn_rev() but the return value, off‐
4943 set, and length all use UTF-8 characters and not bytes.
4944 Note:
4946 This is much slower than ustr_cspn_rev() but given "xy" as a
4948 multi-byte UTF-8 character it understands that the compliment span over
4949 "xzxy" is 1 UTF-8 character and not 0 bytes.
4950 Function: ustr_utf8_cspn_cstr_fwd()
4952 Returns: Number of UTF-8 characters not in the span
4953 Type: size_t
4954 Parameter[1]: A pointer to a constant Ustr UTF-8 string
4956 Type[1]: const struct Ustr *
4957 Parameter[2]: Offset within string, in UTF-8 characters, to start com‐
4959 pliment spanning from
4960 Type[2]: size_t
4961 Parameter[3]: A pointer to constant C-style UTF-8 string data, contain‐
4963 ing spanning data
4964 Type[3]: const char *
4965 Explanation:
4967 This function works like ustr_cspn_cstr_fwd() but the return value,
4969 offset, and length all use UTF-8 characters and not bytes.
4970 Note:
4972 This is much slower than ustr_cspn_cstr_fwd() but given "xy" as a
4974 multi-byte UTF-8 character it understands that the compliment span over
4975 "xzxy" is 1 UTF-8 character and not 0 bytes.
4976 Function: ustr_utf8_cspn_cstr_rev()
4978 Returns: Number of UTF-8 characters not in the span
4979 Type: size_t
4980 Parameter[1]: A pointer to a constant Ustr UTF-8 string
4982 Type[1]: const struct Ustr *
4983 Parameter[2]: Offset within string, in UTF-8 characters, to start com‐
4985 pliment spanning from
4986 Type[2]: size_t
4987 Parameter[3]: A pointer to C-style UTF-8 string data, containing span‐
4989 ning data
4990 Type[3]: const char *
4991 Explanation:
4993 This function works like ustr_cspn_cstr_rev() but the return value,
4995 offset, and length all use UTF-8 characters and not bytes.
4996 Note:
4998 This is much slower than ustr_spn_cstr_rev() but given "xy" as a
5000 multi-byte UTF-8 character it understands that the compliment span over
5001 "xzxy" is 1 UTF-8 character and not 0 bytes.
5002
5005 Function: ustr_io_get()
5006 Returns: Success or failure
5007 Type: int
5008 Parameter[1]: A pointer to a pointer to a Ustr string
5010 Type[1]: struct Ustr **
5011 Parameter[2]: A pointer to a C file object
5013 Type[2]: FILE *
5014 Parameter[3]: Number of bytes to read
5016 Type[3]: size_t
5017 Parameter[4]: Returned number of bytes read
5019 Type[4]: size_t *
5020 Explanation:
5022 This function tries to read a minimum number of bytes from the file
5024 object, into the Ustr string. The exact number read is returned, unless
5025 (Parameter[4]) is NULL.
5026 Function: ustr_io_getfile()
5028 Returns: Success or failure
5029 Type: int
5030 Parameter[1]: Pointer to a pointer to a Ustr string
5032 Type[1]: struct Ustr **
5033 Parameter[2]: A pointer to a C file object
5035 Type[2]: FILE *
5036 Explanation:
5038 This function calls ustr_io_get() rpeatedly until EOF is encountered.
5040 Note:
5042 The errno value when this function ends could either be from fopen(),
5044 fread(), or if both of the those succeeded from fclose().
5045 Function: ustr_io_getfilename()
5047 Returns: Success or failure
5048 Type: int
5049 Parameter[1]: Pointer to a pointer to a Ustr string
5051 Type[1]: struct Ustr **
5052 Parameter[2]: A C-style string of a filename
5054 Type[2]: const char *
5055 Explanation:
5057 This function opens a specified file, and then calls ustr_io_get‐
5059 file(). Finally closing the FILE * object.
5060 Function: ustr_io_getdelim()
5062 Returns: Success or failure
5063 Type: int
5064 Parameter[1]: Pointer to a pointer to a Ustr string
5066 Type[1]: struct Ustr **
5067 Parameter[2]: A pointer to a C file object
5069 Type[2]: FILE *
5070 Parameter[3]: A delimiter byte to stop reading at
5072 Type[3]: char
5073 Explanation:
5075 This function reads bytes from the file until it hits the delimiter
5077 byte.
5078 Note:
5080 The delimiter is included, use ustr_del() to remove 1 byte from the
5082 end if you don't want it.
5083 This function assumes a delimiter will happen every 80 bytes or so.
5084 Function: ustr_io_getline()
5086 Returns: Success or failure
5087 Type: int
5088 Parameter[1]: Pointer to a pointer to a Ustr string
5090 Type[1]: struct Ustr **
5091 Parameter[2]: A pointer to a C file object
5093 Type[2]: FILE *
5094 Explanation:
5096 This function works like calling ustr_io_getdelim() with '\n' as the
5098 delimiter.
5099 Function: ustr_io_put()
5101 Returns: Success or failure
5102 Type: int
5103 Parameter[1]: Pointer to a pointer to a Ustr string
5105 Type[1]: struct Ustr **
5106 Parameter[2]: A pointer to a C file object
5108 Type[2]: FILE *
5109 Parameter[3]: Number of bytes to write
5111 Type[3]: size_t
5112 Explanation:
5114 This function is the opposite of ustr_io_get(), taking bytes from the
5116 beginning of the Ustr and writting them to the file.
5117 Note:
5119 Deleting bytes from the begining of a Ustr string is the most ineffi‐
5121 cient thing to do, so it is recommended to use ustr_io_putfile().
5122 Function: ustr_io_putline()
5124 Returns: Success or failure
5125 Type: int
5126 Parameter[1]: Pointer to a pointer to a Ustr string
5128 Type[1]: struct Ustr **
5129 Parameter[2]: A pointer to a C file object
5131 Type[2]: FILE *
5132 Parameter[3]: Number of bytes to write
5134 Type[3]: size_t
5135 Explanation:
5137 This function works like calling ustr_io_put(), and then writting a
5139 '\n' to the file.
5140 Note:
5142 This doesn't write a line from the Ustr to the file, if you want that
5144 call ustr_io_put() directly, using the return from ustr_srch_chr_fwd()
5145 (with a '\n') as the number of bytes argument.
5146 Function: ustr_io_putfile()
5148 Returns: Success or failure
5149 Type: int
5150 Parameter[1]: Pointer to a pointer to a Ustr string
5152 Type[1]: struct Ustr **
5153 Parameter[2]: A pointer to a C file object
5155 Type[2]: FILE *
5156 Explanation:
5158 This function works like calling ustr_io_put() with ustr_len() as the
5160 number of bytes.
5161 Function: ustr_io_putfileline()
5163 Returns: Success or failure
5164 Type: int
5165 Parameter[1]: Pointer to a pointer to a Ustr string
5167 Type[1]: struct Ustr **
5168 Parameter[2]: A pointer to a C file object
5170 Type[2]: FILE *
5171 Explanation:
5173 This function works like calling ustr_io_putline() with ustr_len() as
5175 the number of bytes.
5176 Function: ustr_io_putfilename()
5178 Returns: Success or failure
5179 Type: int
5180 Parameter[1]: Pointer to a pointer to a Ustr string
5182 Type[1]: struct Ustr **
5183 Parameter[2]: A C-style string of a filename
5185 Type[2]: const char *
5186 Parameter[3]: A C-style string of a filemode (the second argument to
5188 fopen)
5189 Type[3]: const char *
5190 Explanation:
5192 This function opens a specified file, and then calls ustr_io_put‐
5194 file(). Finally closing the FILE * object.
5195 Note:
5197 The errno value when this function ends could either be from fopen(),
5199 fwrite(), or if both of the those succeeded from fclose().
5200
5203 Function: ustr_sub_undef()
5204 Returns: Success or failure
5205 Type: int
5206 Parameter[1]: Pointer to a pointer to a Ustr
5208 Type[1]: struct Ustr **
5209 Parameter[2]: Position where to start substitution
5211 Type[2]: size_t
5212 Parameter[3]: Length of undefined data
5214 Type[3]: size_t
5215 Explanation:
5217 The Ustr string is expanded as required (possibly reallocated) so
5219 that it can contain length (Parameter[2]) data, from the required posi‐
5220 tion. If the length is not zero the Ustr will be writable. Or it'll
5221 return USTR_FALSE (zero) on failure.
5222 Note:
5224 You can think of the operation as two seperate tasks, one which makes
5226 the current data in the Ustr undefined and the second which adds unde‐
5227 fined data to the ustr to accomodate the desired length.
5228 Function: ustr_sub_buf()
5230 Returns: Success or failure
5231 Type: int
5232 Parameter[1]: Pointer to a pointer to a Ustr
5234 Type[1]: struct Ustr **
5235 Parameter[2]: Position where to start substitution
5237 Type[2]: size_t
5238 Parameter[3]: Buffer containing substitution string
5240 Type[3]: const void *
5241 Parameter[4]: Length of buffer
5243 Type[4]: size_t
5244 Explanation:
5246 This function works as if you had called ustr_sub_undef() and then
5248 copied the data into the new undefined space.
5249 Function: ustr_sub_cstr()
5251 Returns: success or failure
5252 Type: int
5253 Parameter[1]: Pointer to a pointer to a Ustr
5255 Type[1]: struct Ustr **
5256 Parameter[2]: Position where to start substitution
5258 Type[2]: size_t
5259 Parameter[3]: A pointer to a constant C-style string, which is the sub‐
5261 stitution
5262 Type[3]: const char *
5263 Explanation:
5265 This function works like ustr_sub_buf() but the length is worked out
5267 automatically by strlen().
5268 Function: USTR_SUB_OSTR()
5270 Returns: Success or failure
5271 Type: int
5272 Parameter[1]: Pointer to a pointer to a Ustr string
5274 Type[1]: struct Ustr **
5275 Parameter[2]: Position where to start substitution
5277 Type[2]: size_t
5278 Parameter[3]: A constant C-style string
5280 Type[3]: const char []
5281 Explanation:
5283 This function works as if you had called ustr_sub_buf() and passed
5285 sizeof() - 1 as the length.
5286 Function: USTR_SUB_OBJ()
5288 Returns: Success or failure
5289 Type: int
5290 Parameter[1]: Pointer to a pointer to a Ustr string
5292 Type[1]: struct Ustr **
5293 Parameter[2]: Position where to start substitution
5295 Type[2]: size_t
5296 Parameter[3]: A symbol
5298 Type[3]: ...
5299 Explanation:
5301 This function works as if you had called ustr_sub_buf() and passed
5303 sizeof() as the length.
5304 Note:
5306 In most cases you'll want to use USTR_SUB_OSTR().
5308 Function: ustr_sub()
5310 Returns: Success or failure
5311 Type: int
5312 Parameter[1]: Pointer to a pointer to a Ustr string
5314 Type[1]: struct Ustr **
5315 Parameter[2]: Position where to start substitution
5317 Type[2]: size_t
5318 Parameter[3]: A pointer to a constant Ustr string
5320 Type[3]: const struct Ustr *
5321 Explanation:
5323 This function works as if you had called ustr_sub_buf() with the
5325 ustr_cstr() and ustr_len() values of the Ustr string to be added. The
5326 exception being if you substitute a ustr into itself, while only having
5327 a single reference count, the simple method could access a free'd ustr
5328 data, but this function just works.
5329 Function: ustr_sub_subustr()
5331 Returns: Success or failure
5332 Type: int
5333 Parameter[1]: Pointer to a pointer to a Ustr string
5335 Type[1]: struct Ustr **
5336 Parameter[2]: Position where to start substitution
5338 Type[2]: size_t
5339 Parameter[3]: A pointer to a constant Ustr string
5341 Type[3]: const struct Ustr *
5342 Parameter[4]: Position in the Ustr
5344 Type[4]: size_t
5345 Parameter[5]: Length to substitute from the Ustr
5347 Type[5]: size_t
5348 Explanation:
5350 This function mostly as if you had called ustr_sub_buf() with the
5352 ustr_cstr() + position - 1 and length values of the Ustr string to be
5353 insed. The exception being if you insert a ustr to itself, while only
5354 having a single reference count, the simple method would access a
5355 free'd ustr data, but this function just works.
5356 Function: ustr_sc_sub_undef()
5358 Returns: Success or failure
5359 Type: int
5360 Parameter[1]: Pointer to a pointer to a Ustr
5362 Type[1]: struct Ustr **
5363 Parameter[2]: Position where to start substitution
5365 Type[2]: size_t
5366 Parameter[3]: Length of substitution
5368 Type[3]: size_t
5369 Parameter[4]: Length of undefined data
5371 Type[4]: size_t
5372 Explanation:
5374 This function works as if you had done ustr_del_subustr() followed by
5376 ustr_ins_undef(), however it is significantly more efficient.
5377 Function: ustr_sc_sub_buf()
5379 Returns: Success or failure
5380 Type: int
5381 Parameter[1]: Pointer to a pointer to a Ustr
5383 Type[1]: struct Ustr **
5384 Parameter[2]: Position where to start substitution
5386 Type[2]: size_t
5387 Parameter[3]: Length of substitution
5389 Type[3]: size_t
5390 Parameter[4]: Buffer containting substitute data
5392 Type[4]: const void *
5393 Parameter[5]: Length of Buffer
5395 Type[5]: size_t
5396 Explanation:
5398 This function will substitute a specific number of characters in a
5400 Ustr with the data from a buffer, this function does the job of one or
5401 more of ustr_add_buf(), ustr_sub_buf() and ustr_del().
5402 Function: ustr_sc_sub_cstr()
5404 Returns: Success or failure
5405 Type: int
5406 Parameter[1]: Pointer to a pointer to a Ustr
5408 Type[1]: struct Ustr **
5409 Parameter[2]: Position where to start replacement
5411 Type[2]: size_t
5412 Parameter[3]: Length of substitution
5414 Type[3]: size_t
5415 Parameter[4]: A pointer to a constant C-style string, containing span‐
5417 ning bytes
5418 Type[4]: const char *
5419 Explanation:
5421 This function works like ustr_sc_sub_buf() but the length is worked
5423 out automatically by strlen().
5424 Function: ustr_sc_sub()
5426 Returns: success or failure
5427 Type: int
5428 Parameter[1]: Pointer to a pointer to a Ustr
5430 Type[1]: struct Ustr **
5431 Parameter[2]: Position where to start substitution
5433 Type[2]: size_t
5434 Parameter[3]: Length of substitution
5436 Type[3]: size_t
5437 Parameter[4]: Pointer to a Ustr containing the substitute string
5439 Type[4]: const struct Ustr *
5440 Explanation:
5442 This function works as if you had called ustr_sc_sub_buf() with the
5444 ustr_cstr() and ustr_len() values of the Ustr string to be added. The
5445 exception being if you substitute a ustr into itself, while only having
5446 a single reference count, the simple method could access a free'd ustr
5447 data, but this function just works.
5448 Function: ustr_sc_sub_subustr()
5450 Returns: Success or failure
5451 Type: int
5452 Parameter[1]: Pointer to a pointer to a Ustr
5454 Type[1]: struct Ustr **
5455 Parameter[2]: Position where to start substitution
5457 Type[2]: size_t
5458 Parameter[3]: Length of substitution
5460 Type[3]: size_t
5461 Parameter[4]: A pointer to a constant Ustr string
5463 Type[4]: const struct Ustr *
5464 Parameter[5]: Position in the Ustr
5466 Type[5]: size_t
5467 Parameter[6]: Length to substitute from the Ustr
5469 Type[6]: size_t
5470 Explanation:
5472 This function mostly as if you had called ustr_sc_sub_buf() with the
5474 ustr_cstr() + position - 1 and length values of the Ustr string to be
5475 insed. The exception being if you insert a ustr to itself, while only
5476 having a single reference count, the simple method would access a
5477 free'd ustr data, but this function just works.
5478 Function: USTR_SC_SUB_OSTR()
5480 Returns: Success or failure
5481 Type: int
5482 Parameter[1]: Pointer to a pointer to a Ustr string
5484 Type[1]: struct Ustr **
5485 Parameter[2]: Position where to start substitution
5487 Type[2]: size_t
5488 Parameter[3]: Length of substitution
5490 Type[3]: size_t
5491 Parameter[4]: A constant C-style string
5493 Type[4]: const char []
5494 Explanation:
5496 This function works as if you had called ustr_sc_sub_buf() and passed
5498 sizeof() - 1 as the length.
5499 Function: USTR_SC_SUB_OBJ()
5501 Returns: Success or failure
5502 Type: int
5503 Parameter[1]: Pointer to a pointer to a Ustr string
5505 Type[1]: struct Ustr **
5506 Parameter[2]: Position where to start substitution
5508 Type[2]: size_t
5509 Parameter[3]: Length of substitution
5511 Type[3]: size_t
5512 Parameter[4]: A symbol
5514 Type[4]: ...
5515 Explanation:
5517 This function works as if you had called ustr_sc_sub_buf() and passed
5519 sizeof() as the length.
5520 Note:
5522 In most cases you'll want to use USTR_SUB_OSTR().
5524 Function: ustr_replace_buf()
5526 Returns: Number of tokens replaced
5527 Type: size_t
5528 Parameter[1]: Pointer to a pointer to a Ustr (haystack)
5530 Type[1]: struct Ustr **
5531 Parameter[2]: Buffer containting search data
5533 Type[2]: const void *
5534 Parameter[3]: Length of search buffer
5536 Type[3]: size_t
5537 Parameter[4]: Buffer containting replacement data
5539 Type[4]: const void *
5540 Parameter[5]: Length of replacement buffer
5542 Type[5]: size_t
5543 Parameter[6]: Maximum number of matches to replace (0 for unlimited)
5545 Type[6]: size_t
5546 Explanation:
5548 This function scans the "haystack" (Parameter[1]) for "needle"
5550 (Parameter[2]) and replaces max_replacements (Parameter[6]) matches
5551 with the "replacement" (Parameter[4]).
5552 Note:
5554 If max_replacements (Parameter[6]) is 0, this function will replace
5556 ALL occurrences.
5557 Function: ustr_replace_cstr()
5559 Returns: Number of tokens replaced
5560 Type: size_t
5561 Parameter[1]: Pointer to a pointer to a Ustr (haystack)
5563 Type[1]: struct Ustr **
5564 Parameter[2]: A pointer to a constant C-style string, containing search
5566 bytes
5567 Type[2]: const char *
5568 Parameter[3]: A pointer to a constant C-style string, containing
5570 replacement bytes
5571 Type[3]: const char *
5572 Parameter[4]: Maximum number of matches to replace (0 for unlimited)
5574 Type[4]: size_t
5575 Explanation:
5577 This function works like ustr_replace_buf() but gets the lengths for
5579 the buffer automatically from strlen().
5580 Function: ustr_replace()
5582 Returns: Number of tokens replaced
5583 Type: int
5584 Parameter[1]: Pointer to a pointer to a Ustr (haystack)
5586 Type[1]: struct Ustr **
5587 Parameter[2]: Ustr to search for (needle)
5589 Type[2]: const struct Ustr *
5590 Parameter[3]: Ustr to replace needle with
5592 Type[3]: const struct Ustr *
5593 Parameter[4]: Maximum number of matches to replace (0 for unlimited)
5595 Type[4]: size_t
5596 Explanation:
5598 This function works like ustr_replace_buf() but gets the lengths from
5600 the ustr automatically.
5601 Function: ustr_replace_rep_chr()
5603 Returns: number of replacements made
5604 Type: size_t
5605 Parameter[1]: pointer to a pointer to a Ustr to be modified
5607 Type[1]: struct Ustr **ps1
5608 Parameter[2]: character to replace
5610 Type[2]: char
5611 Parameter[3]: number of characters to replace
5613 Type[3]: size_t
5614 Parameter[4]: character to replace with
5616 Type[4]: char
5617 Parameter[5]: number of characters to replace with
5619 Type[5]: size_t nlen
5620 Parameter[6]: maximum number of replacements to make (use 0 for unlim‐
5622 ited)
5623 Type[6]: size_t lim
5624 Explanation:
5626 This function replaces a repeating sequence of characters with
5628 another repeating sequence of characters.
5629 For example...
5630 Ustr *data = ustr_dup_cstr("xxxBxxCxDxxx");
5632 ustr_replace_rep_chr(&data,'x',2,'y',1, 0)
5633 ...would change data to be "yxByCxDyx".
5635 Note:
5639 Changing the same letter the same number of times is considered a
5641 No-op since it is a vast performance improvement this way. So passing
5642 in (&data,'y',2,'y',2 ,0) will have a return value of 0 and the string
5643 will be unchanged.
5644
5647 Function: ustr_split_buf()
5648 Returns: pointer to a Ustr representing the next token
5649 Type: struct Ustr *
5650 Parameter[1]: Pointer to a constant Ustr to be split
5652 Type[1]: const struct Ustr *
5653 Parameter[2]: Pointer to an offset
5655 Type[2]: size_t *
5656 Parameter[3]: Buffer to use as split search pattern
5658 Type[3]: const void *
5659 Parameter[4]: Length of buffer
5661 Type[4]: size_t
5662 Parameter[5]: Pointer to a Ustr to be used as the return value
5664 Type[5]: struct Ustr *
5665 Parameter[6]: Flags with the prefix USTR_FLAG_SPLIT_
5667 Type[6]: unsigned int
5668 Explanation:
5670 This function works in a manner similar to strtok(). Each time the
5672 function is called, the string inside of the buffer (Parameter[3]) is
5673 used as a search pattern at which to split. If the pattern is not
5674 found, the entire string will be returned. A USTR_NULL return value
5675 indicates there are no more tokens remaining.
5676 Parameter[5] is a a pointer to a Ustr where the return value will be
5677 placed. Passing a USTR_NULL to this parameter will cause the string to
5678 be allocated and MUST be freed manually. If, however, you pass in a
5679 non-null Ustr to this parameter, each call to ustr_split_buf() will
5680 free what is in this pointer and place the new token there (when
5681 USTR_NULL is returned, nothing needs to be free'd). For example,
5682 given...
5683 Ustr *data = ...;
5685 Ustr *tok = USTR_NULL;
5686 const char *sep = ",";
5687 size_t off = 0;
5688 unsigned int flags = USTR_FLAGS_SPLIT_DEF;
5689 ...there are two options...
5691 while ((tok = ustr_split_buf(data, &off, sep, strlen(sep), tok,
5693 flags)))
5694 {
5695 /* Do something with tok -- but next iteration of the loop will
5696 free
5697 * and overwrite tok, so you must ustr_dup() if you want to keep it
5698 */
5699 }
5700 /* tok is now NULL again after the loop */
5701 ...or...
5703 while ((tok = ustr_split_buf(data, &off, sep, strlen(sep), USTR_NULL,
5705 flags)))
5706 {
5707 /* Do something with tok, and it will NOT be freed in the next
5708 iteration of
5709 * the loop */
5710 ustr_free(tok); /* have to free to avoid mem leaks */
5711 }
5712 ...the former of which being the safer option.
5714 Note:
5717 There are several flags that will alter the behaviour of this func‐
5719 tion, all of which have a common with the default being
5720 USTR_FLAG_SPLIT_DEF.
5721 If you are calling this function directly, it is very likely that
5722 you'd want to use ustr_split_cstr() instead.
5723 Function: ustr_split()
5725 Returns: Pointer to a Ustr representing the next token
5726 Type: struct Ustr *
5727 Parameter[1]: Pointer to a constant Ustr to be split
5729 Type[1]: const struct Ustr *
5730 Parameter[2]: Pointer to an offset variable
5732 Type[2]: size_t *
5733 Parameter[3]: Pointer to a constant Ustr to use as the split search
5735 pattern
5736 Type[3]: const struct Ustr *
5737 Parameter[4]: Pointer to a Ustr where the return value will be placed
5739 Type[4]: struct Ustr *
5740 Parameter[5]: Flags
5742 Type[5]: unsigned int
5743 Explanation:
5745 Works like ustr_split_buf() but takes a Ustr as the split search
5747 pattern
5748 instead.
5749 Function: ustr_split_cstr()
5751 Returns: Pointer to a Ustr representing the next token
5752 Type: struct Ustr *
5753 Parameter[1]: Pointer to a constant Ustr to be split
5755 Type[1]: const struct Ustr *
5756 Parameter[2]: Pointer to an offset variable
5758 Type[2]: size_t *
5759 Parameter[3]: C string to use as split search pattern
5761 Type[3]: const char *
5762 Parameter[4]: Pointer to a Ustr where the return value will be placed
5764 Type[4]: struct Ustr *
5765 Parameter[5]: Flags
5767 Type[5]: unsigned int
5768 Explanation:
5770 Works like ustr_split_buf() but takes a C string as the split search
5772 pattern, and so gets the length via. strlen().
5773 Function: ustr_split_spn_chrs()
5775 Returns: Pointer to a Ustr representing the next token
5776 Type: struct Ustr *
5777 Parameter[1]: Pointer to a Ustr to be split
5779 Type[1]: const struct Ustr *
5780 Parameter[2]: Pointer to an offset variable
5782 Type[2]: size_t *
5783 Parameter[3]: String representing a set of bytes to use as split chars
5785 Type[3]: const char *
5786 Parameter[4]: Length of the string of set of bytes
5788 Type[4]: size_t
5789 Parameter[5]: Pointer to a Ustr where the return value will be placed
5791 Type[5]: struct Ustr *
5792 Parameter[6]: flags
5794 Type[6]: unsigned int
5795 Explanation:
5797 Works like ustr_split_buf() but uses the individual ASCII bytes in
5799 the separator string (Parameter[3]) as search patterns. It will split
5800 if ANY of these individual characters are matched (much like strtok()).
5801 For example: if splitting "this, is,a test" with the separator string
5802 ", " the tokens returned would be {"this" "is" "a" "test"};
5803 Note:
5805 If you are calling this function directly, it is very likely that
5807 you'd want to use ustr_split_spn_cstr() instead.
5808 Function: ustr_split_spn_cstr()
5810 Returns: Pointer to a Ustr representing the next token
5811 Type: struct Ustr *
5812 Parameter[1]: Pointer to a Ustr to be split
5814 Type[1]: const struct Ustr *
5815 Parameter[2]: Pointer to an offset variable
5817 Type[2]: size_t *
5818 Parameter[3]: String representing a set of bytes to use as split chars
5820 Type[3]: const char *
5821 Parameter[4]: Pointer to a Ustr where the return value will be placed
5823 Type[4]: struct Ustr *
5824 Parameter[5]: flags
5826 Type[5]: unsigned int
5827 Explanation:
5829 Works like ustr_split_spn_chrs() but gets the length automatically
5831 via. strlen().
5832 Function: ustr_split_spn()
5834 Returns: Pointer to a Ustr representing the next token
5835 Type: struct Ustr *
5836 Parameter[1]: Pointer to a constant Ustr to be split
5838 Type[1]: const struct Ustr *
5839 Parameter[2]: Pointer to an offset variable
5841 Type[2]: size_t *
5842 Parameter[3]: Pointer to a constant Ustr to use as the split search
5844 pattern
5845 Type[3]: const struct Ustr *
5846 Parameter[4]: Pointer to a Ustr where the return value will be placed
5848 Type[4]: struct Ustr *
5849 Parameter[5]: Flags
5851 Type[5]: unsigned int
5852 Explanation:
5854 Works like ustr_split_spn_chrs() but takes a Ustr as the split chars
5856 instead.
5857
5860 Function: ustr_utf8_valid()
5861 Returns: A boolean flag of either USTR_TRUE or USTR_FALSE
5862 Type: int
5863 Parameter[1]: A pointer to a constant Ustr string
5865 Type[1]: const struct Ustr *
5866 Explanation:
5868 This function tries it's best to find out if the string is a valid
5870 utf-8 string.
5871 Function: ustr_utf8_len()
5873 Returns: The number of the utf-8 characters in the Ustr
5874 Type: size_t
5875 Parameter[1]: A pointer to a constant Ustr string
5877 Type[1]: const struct Ustr *
5878 Explanation:
5880 This function counts the number of utf-8 characters inn the Ustr.
5882 Note:
5884 This function gives undefined answers on strings that aren't utf-8
5886 valid.
5887 Function: ustr_utf8_width()
5889 Returns: ssize_t
5890 Type: ssize_t
5891 Parameter[1]: A pointer to a constant Ustr string
5893 Type[1]: const struct Ustr *
5894 Explanation:
5896 This function returns the visible width of the string, assuming it is
5898 a valid utf-8 string. This is like converting to wide characters and
5899 using wcwidth().
5900 Function: ustr_utf8_chars2bytes()
5902 Returns: Length of span in bytes
5903 Type: size_t
5904 Parameter[1]: A pointer to a constant Ustr string
5906 Type[1]: const struct Ustr *
5907 Parameter[2]: Position of a span in utf-8 characters
5909 Type[2]: size_t
5910 Parameter[3]: Length of a span in utf-8 characters
5912 Type[3]: size_t
5913 Parameter[4]: Returns the position of the span in bytes
5915 Type[4]: size_t *
5916 Explanation:
5918 This function converts a span, in utf-8 characters, to the same span
5920 in bytes.
5921 Function: ustr_utf8_bytes2chars()
5923 Returns: Returns the position of a span in utf-8 characters
5924 Type: size_t
5925 Parameter[1]: A pointer to a constant Ustr string
5927 Type[1]: const struct Ustr *
5928 Parameter[2]: Position of a span in bytes
5930 Type[2]: size_t
5931 Parameter[3]: Length of a span in bytes
5933 Type[3]: size_t
5934 Parameter[4]: Returns length of a span in utf-8 characters
5936 Type[4]: size_t *
5937 Explanation:
5939 This function converts a span, in bytes, to the same span in utf-8
5941 characters.
5942 Note:
5944 Because a byte span can start or end within a utf-8 character, con‐
5946 verting the return values back into bytes via. ustr_utf8_chars2bytes()
5947 may make the span be slightly bigger (position slightly earlier, and
5948 the length slightly longer).
5949 Function: ustr_sc_utf8_reverse()
5951 Returns: Success or failure
5952 Type: int
5953 Parameter[1]: A pointer to a pointer to a Ustr string
5955 Type[1]: struct Ustr **
5956 Explanation:
5958 This function reverses the utf-8 characters in the Ustr string,
5960 assuming it is a valid utf-8 string, so the last one becomes the first
5961 and the second to last becomes the second etc.
5962
5965 Function: ustr_parse_uintmaxx()
5966 Returns: Parsed number, or zero on error
5967 Type: uintmax_t
5968 Parameter[1]: A pointer to a constant Ustr string
5970 Type[1]: const struct Ustr *
5971 Parameter[2]: Offset within string to start parsing at
5973 Type[2]: size_t
5974 Parameter[3]: Base (2-36) and flags, starting with USTR_FLAG_PARSE_NUM_
5976 Type[3]: unsigned int
5977 Parameter[4]: Absolute minimum value
5979 Type[4]: uintmax_t
5980 Parameter[5]: Absolute maximum value
5982 Type[5]: uintmax_t
5983 Parameter[6]: Thousands separator
5985 Type[6]: const char *
5986 Parameter[7]: Return length of parsed number
5988 Type[7]: size_t *
5989 Parameter[8]: Return error code, starting with USTR_TYPE_PARSE_NUM_ERR_
5991 Type[8]: unsigned int *
5992 Explanation:
5994 This function parses an ASCII representation of a number from a Ustr
5996 (Parameter[1]) starting at the offset (Parameter[2]).
5997 Note:
5999 If stdint.h isn't available this function won't be available.
6001 Function: ustr_parse_uintmax()
6003 Returns: Parsed number, or zero on error
6004 Type: uintmax_t
6005 Parameter[1]: A pointer to a constant Ustr string
6007 Type[1]: const struct Ustr *
6008 Parameter[2]: Offset within string to start parsing at
6010 Type[2]: size_t
6011 Parameter[3]: Base (2-36) and flags, starting with USTR_FLAG_PARSE_NUM_
6013 Type[3]: unsigned int
6014 Parameter[4]: Return length of parsed number
6016 Type[4]: size_t *
6017 Parameter[5]: Return error code, starting with USTR_TYPE_PARSE_NUM_ERR_
6019 Type[5]: unsigned int *
6020 Explanation:
6022 This function works like ustr_parse_uintmaxx() with the minimum and
6024 maximum values taken as 0 and UINTMAX_MAX, and the thousands separator
6025 as "_".
6026 Note:
6028 If stdint.h isn't available this function won't be available.
6030 Function: ustr_parse_intmax()
6032 Returns: Parsed number, or zero on error
6033 Type: intmax_t
6034 Parameter[1]: A pointer to a constant Ustr string
6036 Type[1]: const struct Ustr *
6037 Parameter[2]: Offset within string to start parsing at
6039 Type[2]: size_t
6040 Parameter[3]: Base (2-36) and flags, starting with USTR_FLAG_PARSE_NUM_
6042 Type[3]: unsigned int
6043 Parameter[4]: Return length of parsed number
6045 Type[4]: size_t *
6046 Parameter[5]: Return error code, starting with USTR_TYPE_PARSE_NUM_ERR_
6048 Type[5]: unsigned int *
6049 Explanation:
6051 This function works like ustr_parse_uintmaxx() with the minimum and
6053 maximum values taken as -INTMAX_MIN and INTMAX_MAX, and the thousands
6054 separator as "_".
6055 Note:
6057 If stdint.h isn't available this function won't be available.
6059 Function: ustr_parse_ulongx()
6061 Returns: Parsed number, or zero on error
6062 Type: unsigned long
6063 Parameter[1]: A pointer to a constant Ustr string
6065 Type[1]: const struct Ustr *
6066 Parameter[2]: Offset within string to start parsing at
6068 Type[2]: size_t
6069 Parameter[3]: Base (2-36) and flags, starting with USTR_FLAG_PARSE_NUM_
6071 Type[3]: unsigned int
6072 Parameter[4]: Absolute minimum value
6074 Type[4]: unsigned long
6075 Parameter[5]: Absolute maximum value
6077 Type[5]: unsigned long
6078 Parameter[6]: Thousands separator
6080 Type[6]: const char *
6081 Parameter[7]: Return length of parsed number
6083 Type[7]: size_t *
6084 Parameter[8]: Return error code, starting with USTR_TYPE_PARSE_NUM_ERR_
6086 Type[8]: unsigned int *
6087 Explanation:
6089 This function works like ustr_parse_uintmaxx() but returns an
6091 unsigned long, it is always available even when stdint.h isn't.
6092 Function: ustr_parse_ulong()
6094 Returns: Parsed number, or zero on error
6095 Type: unsigned long
6096 Parameter[1]: A pointer to a constant Ustr string
6098 Type[1]: const struct Ustr *
6099 Parameter[2]: Offset within string to start parsing at
6101 Type[2]: size_t
6102 Parameter[3]: Base (2-36) and flags, starting with USTR_FLAG_PARSE_NUM_
6104 Type[3]: unsigned int
6105 Parameter[4]: Return length of parsed number
6107 Type[4]: size_t *
6108 Parameter[5]: Return error code, starting with USTR_TYPE_PARSE_NUM_ERR_
6110 Type[5]: unsigned int *
6111 Explanation:
6113 This function works like ustr_parse_ulongx() with the minimum and
6115 maximum values taken as 0 and ULONG_MAX, and the thousands separator as
6116 "_".
6117 Function: ustr_parse_long()
6119 Returns: Parsed number, or zero on error
6120 Type: long
6121 Parameter[1]: A pointer to a constant Ustr string
6123 Type[1]: const struct Ustr *
6124 Parameter[2]: Offset within string to start parsing at
6126 Type[2]: size_t
6127 Parameter[3]: Base (2-36) and flags, starting with USTR_FLAG_PARSE_NUM_
6129 Type[3]: unsigned int
6130 Parameter[4]: Return length of parsed number
6132 Type[4]: size_t *
6133 Parameter[5]: Return error code, starting with USTR_TYPE_PARSE_NUM_ERR_
6135 Type[5]: unsigned int *
6136 Explanation:
6138 This function works like ustr_parse_ulongx() with the minimum and
6140 maximum values taken as -LONG_MIN and LONG_MAX, and the thousands sepa‐
6141 rator as "_".
6142 Function: ustr_parse_uint()
6144 Returns: Parsed number, or zero on error
6145 Type: unsigned int
6146 Parameter[1]: A pointer to a constant Ustr string
6148 Type[1]: const struct Ustr *
6149 Parameter[2]: Offset within string to start parsing at
6151 Type[2]: size_t
6152 Parameter[3]: Base (2-36) and flags, starting with USTR_FLAG_PARSE_NUM_
6154 Type[3]: unsigned int
6155 Parameter[4]: Return length of parsed number
6157 Type[4]: size_t *
6158 Parameter[5]: Return error code, starting with USTR_TYPE_PARSE_NUM_ERR_
6160 Type[5]: unsigned int *
6161 Explanation:
6163 This function works like ustr_parse_ulongx() with the minimum and
6165 maximum values taken as 0 and UINT_MAX, and the thousands separator as
6166 "_".
6167 Function: ustr_parse_int()
6169 Returns: Parsed number, or zero on error
6170 Type: int
6171 Parameter[1]: A pointer to a constant Ustr string
6173 Type[1]: const struct Ustr *
6174 Parameter[2]: Offset within string to start parsing at
6176 Type[2]: size_t
6177 Parameter[3]: Base (2-36) and flags, starting with USTR_FLAG_PARSE_NUM_
6179 Type[3]: unsigned int
6180 Parameter[4]: Return length of parsed number
6182 Type[4]: size_t *
6183 Parameter[5]: Return error code, starting with USTR_TYPE_PARSE_NUM_ERR_
6185 Type[5]: unsigned int *
6186 Explanation:
6188 This function works like ustr_parse_ulongx() with the minimum and
6190 maximum values taken as -INT_MIN and INT_MAX, and the thousands separa‐
6191 tor as "_".
6192 Function: ustr_parse_ushort()
6194 Returns: Parsed number, or zero on error
6195 Type: unsigned short
6196 Parameter[1]: A pointer to a constant Ustr string
6198 Type[1]: const struct Ustr *
6199 Parameter[2]: Offset within string to start parsing at
6201 Type[2]: size_t
6202 Parameter[3]: Base (2-36) and flags, starting with USTR_FLAG_PARSE_NUM_
6204 Type[3]: unsigned int
6205 Parameter[4]: Return length of parsed number
6207 Type[4]: size_t *
6208 Parameter[5]: Return error code, starting with USTR_TYPE_PARSE_NUM_ERR_
6210 Type[5]: unsigned int *
6211 Explanation:
6213 This function works like ustr_parse_ulongx() with the minimum and
6215 maximum values taken as 0 and USHRT_MAX, and the thousands separator as
6216 "_".
6217 Function: ustr_parse_short()
6219 Returns: Parsed number, or zero on error
6220 Type: short
6221 Parameter[1]: A pointer to a constant Ustr string
6223 Type[1]: const struct Ustr *
6224 Parameter[2]: Offset within string to start parsing at
6226 Type[2]: size_t
6227 Parameter[3]: Base (2-36) and flags, starting with USTR_FLAG_PARSE_NUM_
6229 Type[3]: unsigned int
6230 Parameter[4]: Return length of parsed number
6232 Type[4]: size_t *
6233 Parameter[5]: Return error code, starting with USTR_TYPE_PARSE_NUM_ERR_
6235 Type[5]: unsigned int *
6236 Explanation:
6238 This function works like ustr_parse_ulongx() with the minimum and
6240 maximum values taken as -SHRT_MIN and SHRT_MAX, and the thousands sepa‐
6241 rator as "_".
6242
6245 Function: ustr_sc_ensure_owner()
6246 Returns: Success or failure
6247 Type: int
6248 Parameter[1]: A pointer to a pointer to a Ustr string
6250 Type[1]: struct Ustr **
6251 Explanation:
6253 This function makes sure that the Ustr string is owned when it
6255 returns (Ie. ustr_owner() returns USTR_TRUE), or it fails to allocate.
6256 Function: ustr_sc_wstr()
6258 Returns: Writable pointer to the start of data in the Ustr, or NULL
6259 Type: char *
6260 Parameter[1]: A pointer to a pointer to a Ustr string
6262 Type[1]: struct Ustr **
6263 Explanation:
6265 This function works like calling ustr_sc_ensure_owner(), to make sure
6267 the Ustr string is writable, and if that succeeds it returns
6268 ustr_wstr(). On failure it returns NULL.
6269 Function: ustr_sc_export_subustr()
6271 Returns: A pointer to newly allocated block of memory
6272 Type: char *
6273 Parameter[1]: A pointer to a constant Ustr string
6275 Type[1]: const struct Ustr *
6276 Parameter[2]: Position in the Ustr
6278 Type[2]: size_t
6279 Parameter[3]: Length to export from the Ustr
6281 Type[3]: size_t
6282 Parameter[4]: Allocation function (like malloc)
6284 Type[4]: void *(*)(size_t)
6285 Explanation:
6287 This function allocates a block of memory of size Length (Parame‐
6289 ter[3]) + 1 using the provided allocation function (Parameter[4]) and
6290 copies the data starting from Position (Parameter[2]) within the ustr.
6291 Function: ustr_sc_export()
6293 Returns: A pointer to newly allocated block of memory
6294 Type: char *
6295 Parameter[1]: A pointer to a constant Ustr string
6297 Type[1]: const struct Ustr *
6298 Parameter[2]: Allocation function (like malloc)
6300 Type[2]: void *(*)(size_t)
6301 Explanation:
6303 This function works like calling ustr_sc_export_subustr() with a
6305 position of 1 and a length of ustr_len().
6306 Function: ustrp_sc_export_subustrp()
6308 Returns: A pointer to newly allocated block of memory
6309 Type: char *
6310 Parameter[1]: Pointer to a Ustr pool object
6312 Type[1]: struct Ustr_pool *
6313 Parameter[2]: A pointer to a constant Ustr string
6315 Type[2]: const struct Ustr *
6316 Parameter[3]: Position in the Ustr
6318 Type[3]: size_t
6319 Parameter[4]: Length to export from the Ustr
6321 Type[4]: size_t
6322 Parameter[5]: Allocation function (like malloc), or NULL
6324 Type[5]: void *(*)(size_t)
6325 Explanation:
6327 This function allocates a block of memory of size Length (Parame‐
6329 ter[4]) + 1 using either the provided allocation function (Parame‐
6330 ter[5]), or from the pool object if the allocation function is NUL, and
6331 copies the data starting from Position (Parameter[3]) within the ustr.
6332 Function: ustrp_sc_export()
6334 Returns: A pointer to newly allocated block of memory
6335 Type: char *
6336 Parameter[1]: Pointer to a Ustr pool object
6338 Type[1]: struct Ustr_pool *
6339 Parameter[2]: A pointer to a constant Ustr string
6341 Type[2]: const struct Ustr *
6342 Parameter[3]: Allocation function (like malloc)
6344 Type[3]: void *(*)(size_t)
6345 Explanation:
6347 This function works like calling ustrp_sc_export_subustrp() with a
6349 position of 1 and a length of ustrp_len().
6350 Function: ustr_sc_reverse()
6352 Returns: Success or failure
6353 Type: int
6354 Parameter[1]: A pointer to a pointer to a Ustr string
6356 Type[1]: struct Ustr **
6357 Explanation:
6359 This function reverses all the bytes in the Ustr string, so the last
6361 one becomes the first and the second to last becomes the second etc.
6362 Function: ustr_sc_tolower()
6364 Returns: Success or failure
6365 Type: int
6366 Parameter[1]: A pointer to a pointer to a Ustr string
6368 Type[1]: struct Ustr **
6369 Explanation:
6371 This function changes any ASCII upper case bytes into ASCII lower
6373 case bytes.
6374 Function: ustr_sc_toupper()
6376 Returns: Success or failure
6377 Type: int
6378 Parameter[1]: A pointer to a pointer to a Ustr string
6380 Type[1]: struct Ustr **
6381 Explanation:
6383 This function changes any ASCII lower case bytes into ASCII upper
6385 case bytes.
6386 Function: ustr_sc_ltrim_chrs()
6388 Returns: Success or failure
6389 Type: int
6390 Parameter[1]: A pointer to a pointer to a Ustr string
6392 Type[1]: struct Ustr **
6393 Parameter[2]: Array of bytes, containing trimming data
6395 Type[2]: const char *
6396 Parameter[3]: Length of byte data
6398 Type[3]: size_t
6399 Explanation:
6401 This function deletes the bytes at the begining of the Ustr (Parame‐
6403 ter[1]) that are in the span (Parameter[2]) of the specificed length
6404 (parameter[2]).
6405 Function: ustr_sc_ltrim()
6407 Returns: Success or failure
6408 Type: int
6409 Parameter[1]: A pointer to a pointer to a Ustr string
6411 Type[1]: struct Ustr **
6412 Parameter[2]: A pointer to a constant Ustr string, containing trimming
6414 bytes
6415 Type[2]: const struct Ustr *
6416 Explanation:
6418 This function works as if you had called ustr_sc_ltrim_chrs() and
6420 passed ustr_cstr() and ustr_len() values of the Ustr string (Parame‐
6421 ter[2]).
6422 Function: ustr_sc_ltrim_cstr()
6424 Returns: Success or failure
6425 Type: int
6426 Parameter[1]: A pointer to a pointer to a Ustr string
6428 Type[1]: struct Ustr **
6429 Parameter[2]: A pointer to a constant C-style string, containing trim‐
6431 ming bytes
6432 Type[2]: const char *
6433 Explanation:
6435 This function works as if you had called ustr_sc_ltrim_chrs() and
6437 passed strlen() as the length.
6438 Function: ustr_sc_rtrim_chrs()
6440 Returns: Success or failure
6441 Type: int
6442 Parameter[1]: A pointer to a pointer to a Ustr string
6444 Type[1]: struct Ustr **
6445 Parameter[2]: Array of bytes, containing trimming data
6447 Type[2]: const char *
6448 Parameter[3]: Length of byte data
6450 Type[3]: size_t
6451 Explanation:
6453 This function deletes the bytes at the end of the Ustr (Parameter[1])
6455 that are in the span (Parameter[2]) of the specificed length (parame‐
6456 ter[2]).
6457 Function: ustr_sc_rtrim()
6459 Returns: Success or failure
6460 Type: int
6461 Parameter[1]: A pointer to a pointer to a Ustr string
6463 Type[1]: struct Ustr **
6464 Parameter[2]: A pointer to a constant Ustr string, containing trimming
6466 bytes
6467 Type[2]: const struct Ustr *
6468 Explanation:
6470 This function works as if you had called ustr_sc_rtrim_chrs() and
6472 passed ustr_cstr() and ustr_len() values of the Ustr string (Parame‐
6473 ter[2]).
6474 Function: ustr_sc_rtrim_cstr()
6476 Returns: Success or failure
6477 Type: int
6478 Parameter[1]: A pointer to a pointer to a Ustr string
6480 Type[1]: struct Ustr **
6481 Parameter[2]: A pointer to a constant C-style string, containing trim‐
6483 ming bytes
6484 Type[2]: const char *
6485 Explanation:
6487 This function works as if you had called ustr_sc_rtrim_chrs() and
6489 passed strlen() as the length.
6490 Function: ustr_sc_trim_chrs()
6492 Returns: Success or failure
6493 Type: int
6494 Parameter[1]: A pointer to a pointer to a Ustr string
6496 Type[1]: struct Ustr **
6497 Parameter[2]: Array of bytes, containing trimming data
6499 Type[2]: const char *
6500 Parameter[3]: Length of byte data
6502 Type[3]: size_t
6503 Explanation:
6505 This function deletes the bytes at the begining or end of the Ustr
6507 (Parameter[1]) that are in the span (Parameter[2]) of the specificed
6508 length (parameter[2]).
6509 Note:
6511 Calling this function is much more efficient than calling
6513 ustr_sc_rtrim_chrs() and then ustr_sc_ltrim_chrs(), as both ends are
6514 trimmed in a single pass.
6515 Function: ustr_sc_trim()
6517 Returns: Success or failure
6518 Type: int
6519 Parameter[1]: A pointer to a pointer to a Ustr string
6521 Type[1]: struct Ustr **
6522 Parameter[2]: A pointer to a constant Ustr string, containing trimming
6524 bytes
6525 Type[2]: const struct Ustr *
6526 Explanation:
6528 This function works as if you had called ustr_sc_trim_chrs() and
6530 passed ustr_cstr() and ustr_len() values of the Ustr string (Parame‐
6531 ter[2]).
6532 Function: ustr_sc_trim_cstr()
6534 Returns: Success or failure
6535 Type: int
6536 Parameter[1]: A pointer to a pointer to a Ustr string
6538 Type[1]: struct Ustr **
6539 Parameter[2]: A pointer to a constant C-style string, containing trim‐
6541 ming bytes
6542 Type[2]: const char *
6543 Explanation:
6545 This function works as if you had called ustr_sc_trim_chrs() and
6547 passed strlen() as the length.
6548
6551 Function: ustr_add_b_uint16()
6552 Returns: Success or failure
6553 Type: int
6554 Parameter[1]: Pointer to a pointer to a Ustr string
6556 Type[1]: struct Ustr **
6557 Parameter[2]: Binary value to add to the Ustr
6559 Type[2]: uint_least16_t
6560 Explanation:
6562 This function adds a binary representation of a value (Parameter[2])
6564 to the Ustr (Parameter[1]).
6565 Function: ustr_add_b_uint32()
6567 Returns: Success or failure
6568 Type: int
6569 Parameter[1]: Pointer to a pointer to a Ustr string
6571 Type[1]: struct Ustr **
6572 Parameter[2]: Binary value to add to the Ustr
6574 Type[2]: uint_least32_t
6575 Explanation:
6577 This function adds a binary representation of a value (Parameter[2])
6579 to the Ustr (Parameter[1]).
6580 Function: ustr_add_b_uint64()
6582 Returns: Success or failure
6583 Type: int
6584 Parameter[1]: Pointer to a pointer to a Ustr string
6586 Type[1]: struct Ustr **
6587 Parameter[2]: Binary value to add to the Ustr
6589 Type[2]: uint_least64_t
6590 Explanation:
6592 This function adds a binary representation of a value (Parameter[2])
6594 to the Ustr (Parameter[1]).
6595
6598 Function: ustr_parse_b_uint16()
6599 Returns: uint_least16_t
6600 Type: uint_least16_t
6601 Parameter[1]: A pointer to a constant Ustr string
6603 Type[1]: const struct Ustr *
6604 Parameter[2]: Offset within string to start parsing at
6606 Type[2]: size_t
6607 Explanation:
6609 This function parses a binary representation from a Ustr (Parame‐
6611 ter[1]) starting at the offset (Parameter[2]).
6612 Function: ustr_parse_b_uint32()
6614 Returns: uint_least32_t
6615 Type: uint_least32_t
6616 Parameter[1]: A pointer to a constant Ustr string
6618 Type[1]: const struct Ustr *
6619 Parameter[2]: Offset within string to start parsing at
6621 Type[2]: size_t
6622 Explanation:
6624 This function parses a binary representation from a Ustr (Parame‐
6626 ter[1]) starting at the offset (Parameter[2]).
6627 Function: ustr_parse_b_uint64()
6629 Returns: uint_least64_t
6630 Type: uint_least64_t
6631 Parameter[1]: A pointer to a constant Ustr string
6633 Type[1]: const struct Ustr *
6634 Parameter[2]: Offset within string to start parsing at
6636 Type[2]: size_t
6637 Explanation:
6639 This function parses a binary representation from a Ustr (Parame‐
6641 ter[1]) starting at the offset (Parameter[2]).
6642
6645 Function: ustr_realloc()
6646 Returns: Success or failure
6647 Type: int
6648 Parameter[1]: Pointer to a pointer to a Ustr string
6650 Type[1]: struct Ustr **
6651 Parameter[2]: Size of allocation
6653 Type[2]: size_t
6654 Explanation:
6656 This function is re-sizes the Ustr to the specified size (Parame‐
6658 ter[2]).
6659 This is mostly used to shrink a sized Ustr that is now significantly
6660 smaller than it once was. Although this function can also grow a Ustr.
6661 Note:
6663 To have a size that isn't implied from the length the Ustr must store
6665 a size value as well as a length (ustr_sized() must return USTR_TRUE).
6666 Function: ustr_cntl_opt()
6668 Returns: Success or failure
6669 Type: int
6670 Parameter[1]: Optional value starting with USTR_CNTL_OPT_
6672 Type[1]: int
6673 Parameter[2]: Arugments to option
6675 Type[2]: ...
6676 Explanation:
6678 This function views and/or changes global Ustr options, like whether
6680 ustr's have an implicit or explicit size (USTR_CNTL_OPT_GET_HAS_SIZE).
6681
6684 Function: ustr_pool_ll_make()
6685 Returns: Pointer to a Ustr pool object
6686 Type: struct Ustr_pool *
6687 Parameter[1]: Nothing
6689 Type[1]: void
6690 Explanation:
6692 This allocates a new pool using the "linked list" strategy, each
6694 allocation in the pool is added to a linked list ... and any alloca‐
6695 tions not freed directly are freed by the pool when it is cleared or
6696 freed.
6697 Function: ustr_pool_make_subpool()
6699 Returns: Pointer to a Ustr pool object
6700 Type: struct Ustr_pool *
6701 Parameter[1]: struct Ustr_pool *
6703 Type[1]: struct Ustr_pool *
6704 Explanation:
6706 This allocates a new pool as a child of the passed in pool (Parame‐
6708 ter[1]), The pool can be freed and cleared independantly of the parent
6709 pool however free and clear operations on the parent pool are automati‐
6710 cally applied to all child pools.
6711 Function: ustr_pool_free()
6713 Returns: Nothing
6714 Type: void
6715 Parameter[1]: Pointer to a Ustr pool object
6717 Type[1]: struct Ustr_pool *
6718 Explanation:
6720 This deallocates a pool, and all sub-pools.
6722 Note:
6724 This also operates on all sub-pools.
6726 Function: ustr_pool_clear()
6728 Returns: Nothing
6729 Type: void
6730 Parameter[1]: Pointer to a Ustr pool object
6732 Type[1]: struct Ustr_pool *
6733 Explanation:
6735 This allows all the data in the pool to be reused, it may also free
6737 some/all of the data in the pool, from the pool API.
6738 Note:
6740 This also operates on all sub-pools.
6742
6744 ustr_const(3)
6745Ustr 1.0.4 05-Mar-2008 ustr(3)