ustr_const(3)

1ustr_const(3)                 Ustr String Library                ustr_const(3)
2
3
4

NAME

6       ustr_const - ustr string library constants
7

SYNOPSIS

9  #include "ustr.h"
10
11
12  USTR_CONF_INCLUDE_CODEONLY_HEADERS
13  USTR_CONF_USE_EOS_MARK
14  USTR_CONF_USE_ASSERT
15  USTR_CONF_COMPILE_USE_ATTRIBUTES
16  USTR_CONF_COMPILE_TYPEDEF
17  USTR_CONF_COMPILE_USE_INLINE
18
19  USTR_BEG_CONST1
20  USTR_BEG_CONST2
21  USTR_BEG_CONST4
22  USTR_BEG_FIXED1
23  USTR_BEG_FIXED2
24  USTR_BEG_FIXED4
25  USTR_BEG_FIXED8
26  USTR_END_ALOCDx
27  USTR_END_CONSTx
28  USTR_END_FIXEDx
29
30  USTR_FLAG_PARSE_NUM_DEF
31  USTR_FLAG_PARSE_NUM_SEP
32  USTR_FLAG_PARSE_NUM_OVERFLOW
33  USTR_FLAG_PARSE_NUM_SPACE
34  USTR_FLAG_PARSE_NUM_NO_BEG_ZERO
35  USTR_FLAG_PARSE_NUM_NO_BEG_PM
36  USTR_FLAG_PARSE_NUM_NO_NEGATIVE
37  USTR_FLAG_PARSE_NUM_EXACT
38  USTR_TYPE_PARSE_NUM_ERR_NONE
39  USTR_TYPE_PARSE_NUM_ERR_ONLY_S
40  USTR_TYPE_PARSE_NUM_ERR_ONLY_SPM
41  USTR_TYPE_PARSE_NUM_ERR_ONLY_SPMX
42  USTR_TYPE_PARSE_NUM_ERR_OOB
43  USTR_TYPE_PARSE_NUM_ERR_OVERFLOW
44  USTR_TYPE_PARSE_NUM_ERR_NEGATIVE
45  USTR_TYPE_PARSE_NUM_ERR_BEG_ZERO
46
47  USTR_FLAG_SPLIT_DEF
48  USTR_FLAG_SPLIT_RET_SEP
49  USTR_FLAG_SPLIT_RET_NON
50  USTR_FLAG_SPLIT_KEEP_CONFIG
51
52  USTR_NULL
53  USTR_POOL_NULL
54  USTR_TRUE
55  USTR_FALSE
56
57  USTR_CNTL_OPT_GET_REF_BYTES
58  USTR_CNTL_OPT_SET_REF_BYTES
59  USTR_CNTL_OPT_GET_HAS_SIZE
60  USTR_CNTL_OPT_SET_HAS_SIZE
61  USTR_CNTL_OPT_GET_EXACT_BYTES
62  USTR_CNTL_OPT_SET_EXACT_BYTES
63  USTR_CNTL_OPT_GET_MEM
64  USTR_CNTL_OPT_SET_MEM
65  USTR_CNTL_OPT_GET_MC_M_SCRUB
66  USTR_CNTL_OPT_SET_MC_M_SCRUB
67  USTR_CNTL_OPT_GET_MC_F_SCRUB
68  USTR_CNTL_OPT_SET_MC_F_SCRUB
69  USTR_CNTL_OPT_GET_MC_R_SCRUB
70  USTR_CNTL_OPT_SET_MC_R_SCRUB
71  USTR_CNTL_OPT_GET_FMT
72  USTR_CNTL_OPT_SET_FMT
73
74  USTR_POOL_LL_CNTL_GET_FREE_CMP
75  USTR_POOL_LL_CNTL_SET_FREE_CMP
76  USTR_POOL_LL_CNTL_GET_REALLOC
77  USTR_POOL_LL_CNTL_SET_REALLOC
78
79

DESCRIPTION

Compile switch constants

82       Constant:  USTR_CONF_INCLUDE_CODEONLY_HEADERS
83
84       Explanation:
85
86         This  switch controls whether all the code will be included as inline
87       functions. Having this be non-zero means that you don't  have  to  link
88       against the library.
89
90       Constant:  USTR_CONF_USE_EOS_MARK
91
92       Explanation:
93
94         This  switch  turns  on End of String markers, so any bounds overflow
95       will be noticed by ustr_assert_valid().
96
97       Note:
98
99         Changing    this    will    not    do    anything    useful    unless
100       USTR_CONF_INCLUDE_CODEONLY_HEADERS is non-zero.
101
102       Constant:  USTR_CONF_USE_ASSERT
103
104       Explanation:
105
106         This  switch  turns  USTR_ASSERT()  calls on, so the code within them
107       will   be   evaluated.   Note   that   there   are   many   calls    to
108       ustr_assert_valid()  within USTR_ASSERT() macros and that call is rela‐
109       tively expensive.
110
111       Note:
112
113         Changing    this    will    not    do    anything    useful    unless
114       USTR_CONF_INCLUDE_CODEONLY_HEADERS is non-zero.
115
116       Constant:  USTR_CONF_COMPILE_USE_ATTRIBUTES
117
118       Explanation:
119
120         This  switch controls whether gcc type __attribute__() statements are
121       used in the public headers headers for the library. If the value  is  1
122       then  if they are supported by the compiler that built the library they
123       will be used, if the value is 0 they won't be used at all.
124
125       Constant:  USTR_CONF_COMPILE_TYPEDEF
126
127       Explanation:
128
129         This switch controls whether typedef will be used for the structs  in
130       the public headers for the library. If the value is 1 then they will be
131       used, if the value is 0 they won't be used at all (and your  code  will
132       have to use struct tags instead -- note all libraries using ustr should
133       compile without this option set).
134       Constant:  USTR_CONF_COMPILE_USE_INLINE
135
136       Explanation:
137
138         This switch controls whether inline functions will be used in  a  few
139       cases where the function bodies are very small.
140
141       Note:
142
143         In  some  cases  this  is  used  so  that  GCC can eliminate calls to
144       strlen(), for the *_cstr() functions.
145
146

Constants to created fixed/read-only Ustr's

148       Constant:  USTR_BEG_CONST1
149
150       Explanation:
151
152         This macro is a constant C-style string of the first byte of  a  con‐
153       stant/read-only Ustr that has a length in the range 0-255.
154
155       Constant:  USTR_BEG_CONST2
156
157       Explanation:
158
159         This  macro  is a constant C-style string of the first byte of a con‐
160       stant/read-only Ustr that has a length in the range 0-65535.
161
162       Constant:  USTR_BEG_CONST4
163
164       Explanation:
165
166         This macro is a constant C-style string of the first byte of  a  con‐
167       stant/read-only Ustr that has a length in the range 0-4294967295.
168
169       Constant:  USTR_BEG_FIXED1
170
171       Explanation:
172
173         This  macro is a constant C-style string of the first byte of a fixed
174       Ustr that has a length in the range 0-255.
175
176       Constant:  USTR_BEG_FIXED2
177
178       Explanation:
179
180         This macro is a constant C-style string of the first byte of a  fixed
181       Ustr that has a length in the range 0-65535.
182
183       Constant:  USTR_BEG_FIXED4
184
185       Explanation:
186
187         This  macro is a constant C-style string of the first byte of a fixed
188       Ustr that has a length in the range 0-4294967295.
189
190       Constant:  USTR_BEG_FIXED8
191
192       Explanation:
193
194         This macro is a constant C-style string of the first byte of a  fixed
195       Ustr that has a length in the range 0-18446744073709551615.
196
197       Note:
198
199         This macro is only available if the Ustr code was compiled in a 64bit
200       environment.
201
202       Constant:  USTR_END_ALOCDx
203
204       Explanation:
205
206         This macro is a constant C-style string of the last bytes of an allo‐
207       cated Ustr.
208
209       Note:
210
211         Unless USTR_CONF_USE_EOS_MARK is non-zero, this is just the NIL byte.
212
213       Constant:  USTR_END_CONSTx
214
215       Explanation:
216
217         This  macro  is a constant C-style string of the last bytes of a con‐
218       stant/read-only Ustr.
219
220       Note:
221
222         Unless USTR_CONF_USE_EOS_MARK is non-zero, this is just the NIL byte.
223
224       Constant:  USTR_END_FIXEDx
225
226       Explanation:
227
228         This macro is a constant C-style string of the last bytes of a  fixed
229       Ustr.
230
231       Note:
232
233         Unless USTR_CONF_USE_EOS_MARK is non-zero, this is just the NIL byte.
234
235

Constants to use with parsing numbers: ustr_parse_uintmaxx, etc.

237       Constant:  USTR_FLAG_PARSE_NUM_DEF
238
239       Explanation:
240
241         Default  flags,  this  is merely 0 but can be used as live documenta‐
242       tion.
243
244       Constant:  USTR_FLAG_PARSE_NUM_SEP
245
246       Explanation:
247
248         This flag allows the parsing (and ignoring) of the seperator  charac‐
249       ter,  at  arbitrary pointers in the number, so "1234" and "1_234" would
250       both parse the same (assuming "_" is the seperator).
251
252       Constant:  USTR_FLAG_PARSE_NUM_OVERFLOW
253
254       Explanation:
255
256         This flag turns on the overflow checking, in other words  without  it
257       USTR_TYPE_PARSE_NUM_ERR_OVERFLOW  will  never  be  returned as an error
258       code.
259
260       Constant:  USTR_FLAG_PARSE_NUM_SPACE
261
262       Explanation:
263
264         This flag allows one or more ' ' (Space) characters before the number
265       or number prefix (Plus Sign, Hyphen).
266
267       Note:
268
269         Other forms of whitespace don't count, this just affects ' '.
270
271       Constant:  USTR_FLAG_PARSE_NUM_NO_BEG_ZERO
272
273       Explanation:
274
275         This  flag  disallows  one or more '0' (Digit Zero) characters before
276       the number.
277
278       Constant:  USTR_FLAG_PARSE_NUM_NO_BEG_PM
279
280       Explanation:
281
282         This flag disallows a plus or a minus character before the number.
283
284       Constant:  USTR_FLAG_PARSE_NUM_NO_NEGATIVE
285
286       Explanation:
287
288         This flag disallows negative values.
289
290       Constant:  USTR_FLAG_PARSE_NUM_EXACT
291
292       Explanation:
293
294         This flag makes the parsing functions return an error if  the  entire
295       string doesn't contain the number being parsed.
296
297       Constant:  USTR_TYPE_PARSE_NUM_ERR_NONE
298
299       Explanation:
300
301         This  error  code  has  the value 0, and means that no error occurred
302       parsing the number.
303
304       Constant:  USTR_TYPE_PARSE_NUM_ERR_ONLY_S
305
306       Explanation:
307
308         This error code means that the Ustr string consisted only of spaces.
309
310       Constant:  USTR_TYPE_PARSE_NUM_ERR_ONLY_SPM
311
312       Explanation:
313
314         This error code means that the Ustr string consisted only spaces, and
315       a plus or minus sign.
316
317       Constant:  USTR_TYPE_PARSE_NUM_ERR_ONLY_SPMX
318
319       Explanation:
320
321         This  error code means that the Ustr string consisted of only spaces,
322       a plus or minus sign and a "0x" base 16 prefix.
323       Constant:  USTR_TYPE_PARSE_NUM_ERR_OOB
324
325       Explanation:
326
327         This error code means that the Ustr string had characters in it  that
328       where out of bounds from the working base.
329
330       Note:
331
332         Without  the USTR_FLAG_PARSE_NUM_EXACT, this error is ignored as soon
333       as any number is parsed.
334         This out of bounds includes the Ustr string "++"  as  well  as  "4A",
335       when parsing in a base less than 11.
336
337       Constant:  USTR_TYPE_PARSE_NUM_ERR_OVERFLOW
338
339       Explanation:
340
341         This  error  code  means  that the number parsed from the Ustr string
342       would overflow the type it is being parsed into, this is only  returned
343       when  the  USTR_FLAG_PARSE_NUM_OVERFLOW  flag  was  passed to the parse
344       function.
345
346       Constant:  USTR_TYPE_PARSE_NUM_ERR_NEGATIVE
347
348       Explanation:
349
350         This error code means that the number parsed  from  the  Vstr  string
351       starts  with  a  '-'  (Hyphen)  character  when it is supposed to be an
352       unsigned number.
353
354       Constant:  USTR_TYPE_PARSE_NUM_ERR_BEG_ZERO
355
356       Explanation:
357
358         This error code means that the number parsed  from  the  Vstr  string
359       starts    with    a    '0'    (Digit    Zero)   character,   when   the
360       USTR_FLAG_PARSE_NUM_NO_BEG_ZERO flag was passed to the parse function.
361
362

Constants to pass to ustr_split*

364       Constant:  USTR_FLAG_SPLIT_DEF
365
366       Explanation:
367
368         Default flags, this is merely 0 but can be used  as  live  documenta‐
369       tion.
370
371       Constant:  USTR_FLAG_SPLIT_RET_SEP
372
373       Explanation:
374
375         Return  the  separator  along  with the tokens. For example splitting
376       "a,b," using separator "," will return the tokens "a," and "b," whereas
377       without this flag only "a" and "b" would be returned.
378           .br Constant:  USTR_FLAG_SPLIT_RET_NON
379
380       Explanation:
381
382         Return empty tokens. For example: splitting "a,,b" with separator ","
383       will return the tokens {"a" "" "b"}.
384       Constant:  USTR_FLAG_SPLIT_KEEP_CONFIG
385
386       Explanation:
387
388         Force the returned Ustr's to have same  configuration  parameters  as
389       the Ustr string that is being split.
390
391

Misc constants to use in code

393       Constant:  USTR_NULL
394
395       Explanation:
396
397         This  macro is merely 0 cast to (struct Ustr *), and can be used any‐
398       where NULL would be but "returns" the correct type.
399
400       Constant:  USTR_POOL_NULL
401
402       Explanation:
403
404         This macro is merely 0 cast to (struct Ustr_pool *), and can be  used
405       anywhere NULL would be but "returns" the correct type.
406
407       Constant:  USTR_TRUE
408
409       Explanation:
410
411         This  macro  is  1,  but  shows  the  intent  that a boolean value is
412       expected and not a number.
413
414       Constant:  USTR_FALSE
415
416       Explanation:
417
418         This macro is 0, but  shows  the  intent  that  a  boolean  value  is
419       expected and not a number.
420
421

Constants passed to ustr_cntl_opt()

423       Constant:  USTR_CNTL_OPT_GET_REF_BYTES
424
425       Parameter[1]: Number of bytes for default reference count in Ustr
426       Type[1]: size_t *
427
428       Explanation:
429
430         This option will get the default number of bytes used for a reference
431       count when creating Ustr's.
432
433       Constant:  USTR_CNTL_OPT_SET_REF_BYTES
434
435       Parameter[1]: Number of bytes for default reference count in Ustr
436       Type[1]: size_t
437
438       Explanation:
439
440         This option will set the default number of bytes used for a reference
441       count when creating Ustr's.
442
443       Note:
444
445         For a single instance, the ustr_dupx_*() functions can be used.
446
447       Constant:  USTR_CNTL_OPT_GET_HAS_SIZE
448
449       Parameter[1]: Default flag for whether to include an explicit size in a
450       Ustr
451       Type[1]: int *
452
453       Explanation:
454
455         This option will get  the  default  flag  for  whether  to  store  an
456       explicit size in created Ustr's.
457
458       Constant:  USTR_CNTL_OPT_SET_HAS_SIZE
459
460       Parameter[1]: Default flag for whether to include an explicit size in a
461       Ustr
462       Type[1]: int
463
464       Explanation:
465
466         This option will set  the  default  flag  for  whether  to  store  an
467       explicit size in created Ustr's.
468
469       Note:
470
471         For a single instance, the ustr_dupx_*() functions can be used.
472
473       Constant:  USTR_CNTL_OPT_GET_EXACT_BYTES
474
475       Parameter[1]: Default flag for whether to exactly allocate memory
476       Type[1]: int *
477
478       Explanation:
479
480         This option will get the default flag for whether to exactly allocate
481       memory when a Ustr needs to be resized.
482
483       Constant:  USTR_CNTL_OPT_SET_EXACT_BYTES
484
485       Parameter[1]: Default flag for whether to exactly allocate memory
486       Type[1]: int
487
488       Explanation:
489
490         This option will set the default flag for whether to exactly allocate
491       memory when a Ustr needs to be resized.
492
493       Note:
494
495         For a single instance, the ustr_dupx_*() functions can be used.
496
497       Constant:  USTR_CNTL_OPT_GET_MEM
498       Parameter[1]:  Pointer  to  colleciton  of function pointers for system
499       allocation
500       Type[1]: struct Ustr_cntl_mem *
501
502       Explanation:
503
504         This option will get the "system" allocation functions (malloc, real‐
505       loc, free) for allocated Ustr's.
506
507       Note:
508
509         As you would expect the default values are: malloc, realloc, free.
510
511       Constant:  USTR_CNTL_OPT_SET_MEM
512       Parameter[1]:  Pointer  to  colleciton  of function pointers for system
513       allocation
514       Type[1]: const struct Ustr_cntl_mem *
515
516       Explanation:
517
518         This option will set the "system" allocation functions (malloc, real‐
519       loc, free) for allocated Ustr's.
520
521       Note:
522
523         If  this option is set after a Ustr has been created, then when free‐
524       ing or reallocating the existing Ustr the given functions will be used.
525       So  they  must either be compatible with the default or you must ensure
526       that nothing is allocated before they are set.
527
528       Constant:  USTR_CNTL_OPT_GET_MC_M_SCRUB
529
530       Parameter[1]: Flag for whether to include an explicit size in a Ustr
531       Type[1]: int *
532
533       Explanation:
534
535         This option will get the flag for whether to "scrub"  data  allocated
536       via. malloc check.
537
538       Note:
539
540         Malloc  check  has  to  be  enabled  for  this  to mean anything, Ie.
541       USTR_CNTL_MALLOC_LVL() must be positive.
542
543       Constant:  USTR_CNTL_OPT_SET_MC_M_SCRUB
544
545       Parameter[1]: Flag for whether to include an explicit size in a Ustr
546       Type[1]: int
547
548       Explanation:
549
550         This option will set the flag for whether to "scrub"  data  allocated
551       via. malloc check.
552
553       Note:
554
555         Malloc  check  has  to  be  enabled  for  this  to mean anything, Ie.
556       USTR_CNTL_MALLOC_LVL() must be positive.
557
558       Constant:  USTR_CNTL_OPT_GET_MC_F_SCRUB
559
560       Parameter[1]: Flag for whether to include an explicit size in a Ustr
561       Type[1]: int *
562
563       Explanation:
564
565         This option will get the flag for whether to "scrub" data freed  via.
566       malloc check.
567
568       Note:
569
570         Malloc  check  has  to  be  enabled  for  this  to mean anything, Ie.
571       USTR_CNTL_MALLOC_LVL() must be positive.
572
573       Constant:  USTR_CNTL_OPT_SET_MC_F_SCRUB
574
575       Parameter[1]: Flag for whether to include an explicit size in a Ustr
576       Type[1]: int
577
578       Explanation:
579
580         This option will set the flag for whether to "scrub" data freed  via.
581       malloc check.
582
583       Note:
584
585         Malloc  check  has  to  be  enabled  for  this  to mean anything, Ie.
586       USTR_CNTL_MALLOC_LVL() must be positive.
587
588       Constant:  USTR_CNTL_OPT_GET_MC_R_SCRUB
589
590       Parameter[1]: Flag for whether to include an explicit size in a Ustr
591       Type[1]: int *
592
593       Explanation:
594
595         This option will get the flag for whether to "scrub" data reallocated
596       via.  malloc  check.  This  is done by turning all reallocations into a
597       malloc() and free(), and so is even more costly than normal scrubbing.
598
599       Note:
600
601         Malloc check has to  be  enabled  for  this  to  mean  anything,  Ie.
602       USTR_CNTL_MALLOC_LVL() must be positive.
603
604       Constant:  USTR_CNTL_OPT_SET_MC_R_SCRUB
605
606       Parameter[1]: Flag for whether to include an explicit size in a Ustr
607       Type[1]: int
608
609       Explanation:
610
611         This option will set the flag for whether to "scrub" data reallocated
612       via. malloc check. This is done by turning  all  reallocations  into  a
613       malloc() and free(), and so is even more costly than normal scrubbing.
614
615       Note:
616
617         Malloc  check  has  to  be  enabled  for  this  to mean anything, Ie.
618       USTR_CNTL_MALLOC_LVL() must be positive.
619
620       Constant:  USTR_CNTL_OPT_GET_FMT
621       Parameter[1]: Pointer to colleciton of  function  pointers  for  system
622       formating
623       Type[1]: struct Ustr_cntl_fmt *
624
625       Explanation:
626
627         This  option will get the system formatting functions (vsnprintf) for
628       Ustr's.
629         There are two functions, the first is always called and the second is
630       likely  called  (always  with  the  exact same arguments) if the length
631       passed to the first call was not big enough.
632
633       Note:
634
635         As you would expect the default values are: vsnprintf and vsnprintf
636
637       Constant:  USTR_CNTL_OPT_SET_FMT
638       Parameter[1]: Pointer to colleciton of  function  pointers  for  system
639       formatting
640       Type[1]: const struct Ustr_cntl_fmt *
641
642       Explanation:
643
644         This  option will set the system formatting functions (vsnprintf) for
645       Ustr's.
646
647

Constants passed to ustr_pool_ll_cntl()

649       Constant:  USTR_POOL_LL_CNTL_GET_FREE_CMP
650
651       Parameter[1]: Number of pointers to compare to in the pool
652       Type[1]: unsigned int *
653
654       Explanation:
655
656         This option will get the number of comparisons done on  a  pool  free
657       operation.
658
659       Constant:  USTR_POOL_LL_CNTL_SET_FREE_CMP
660
661       Parameter[1]: Number of pointers to compare to in the pool
662       Type[1]: unsigned int
663
664       Explanation:
665
666         This  option  will  set the number of comparisons done on a pool free
667       operation.
668
669       Note:
670
671         The default is a small non-zero value, as it's  significantly  common
672       to  have very short lived ustr's ... however this doesn't mean that you
673       can't forget to take references even with pool allocated ustrs.
674
675       Constant:  USTR_POOL_LL_CNTL_GET_REALLOC
676
677       Parameter[1]: Flag for if we should call realloc()
678       Type[1]: int *
679
680       Explanation:
681
682         This option will get the flag for if we call realloc() to  make  data
683       bigger, or revert to just allocating anew each time.
684
685       Constant:  USTR_POOL_LL_CNTL_SET_REALLOC
686
687       Parameter[1]: Flag for if we should call realloc()
688       Type[1]: int
689
690       Explanation:
691
692         This  option  will set the flag for if we call realloc() to make data
693       bigger, or revert to just allocating anew each time.
694
695       Note:
696
697         As with USTR_POOL_LL_CNTL_SET_FREE_CMP this option  means  you  can't
698       assume  that  pool allocated data is never freed until ustr_pool_free()
699       is called, and again  it  is  due  to  there  being  significant  speed
700       improvements  for not making that assumption. Instead of disabling this
701       option, just take areference (which will also make sure the ustr  isn't
702       modified behind your back).
703