Ustr - 1.0.4 reference documentation -- functions (301)

Index of sections

• Creating read-only Ustr functions (14)
• Creating fixed Ustr functions (4)
• Debugging functions (12)
• Creating allocated Ustr functions (28)
• Deleting a Ustr, or data within a Ustr (8)
• Adding data to a Ustr (8)
• Setting a Ustr to some data (9)
• Inserting data into a Ustr (8)
• Adding, duplicating and setting formatted data to a Ustr (26)
• Accessing the "variables" of a Ustr (16)
• Setting the "flags" of a Ustr (4)
• Comparing data in a Ustr (36)
• Searching for data in a Ustr (20)
• Span lengths of data in a Ustr (28)
• Doing IO from or to a Ustr (10)
• String substitution/replacement (18)
• Splitting a Ustr (6)
• Dealing with UTF-8 in a Ustr (6)
• Parsing ASCII integer numbers from a Ustr (10)
• Misc shortcut helper functions for Ustrs (18)
• Adding binary data to a Ustr (3)
• Parsing binary data from a Ustr (3)
• Misc. functions (2)
• Simple Ustr pool API (4)

Index of sections, and their contents

• Creating read-only Ustr functions
  • USTR()
  • USTRP()
  • USTR1()
  • USTR2()
  • USTR4()
  • USTR1_CHK()
  • USTR2_CHK()
  • USTR4_CHK()
  • USTRP1()
  • USTRP2()
  • USTRP4()
  • USTRP1_CHK()
  • USTRP2_CHK()
  • USTRP4_CHK()
• Creating fixed Ustr functions
  • USTR_SIZE_FIXED()
  • ustr_init_fixed()
  • USTR_SC_INIT_AUTO()
  • USTR_SC_INIT_AUTO_OSTR()
• Debugging functions
  • ustr_assert_valid()
  • ustr_assert_valid_subustr()
  • USTR_CNTL_MALLOC_CHECK_BEG()
  • USTR_CNTL_MALLOC_CHECK_LVL()
  • USTR_CNTL_MALLOC_CHECK_MEM()
  • USTR_CNTL_MALLOC_CHECK_MEM_SZ()
  • USTR_CNTL_MALLOC_CHECK_MEM_MINSZ()
  • USTR_CNTL_MALLOC_CHECK_MEM_USTR()
  • USTR_CNTL_MALLOC_CHECK_MEM_USTRP()
  • USTR_CNTL_MALLOC_CHECK_END()
  • USTR_CNTL_MALLOC_CHECK_ADD()
  • USTR_CNTL_MALLOC_CHECK_DEL()
• Creating allocated Ustr functions
  • ustr_init_size()
  • ustr_init_alloc()
  • ustr_dupx_empty()
  • ustr_dup_empty()
  • ustr_dupx_undef()
  • ustr_dup_undef()
  • ustr_dup()
  • ustr_dupx()
  • ustr_sc_dup()
  • ustr_sc_dupx()
  • ustr_dup_buf()
  • ustr_dupx_buf()
  • ustr_dup_cstr()
  • ustr_dupx_cstr()
  • USTR_DUP_OSTR()
  • USTR_DUP_OBJ()
  • ustr_dup_subustr()
  • ustr_dupx_subustr()
  • ustr_dup_rep_chr()
  • ustr_dupx_rep_chr()
  • ustr_sc_vjoin()
  • ustr_sc_join()
  • ustr_sc_vjoinx()
  • ustr_sc_joinx()
  • ustr_sc_vconcat()
  • ustr_sc_concat()
  • ustr_sc_vconcatx()
  • ustr_sc_concatx()
• Deleting a Ustr, or data within a Ustr
  • ustr_free()
  • ustrp_free()
  • ustr_sc_free()
  • ustr_sc_free2()
  • ustr_sc_free_shared()
  • ustr_del()
  • ustr_del_subustr()
  • ustr_sc_del()
• Adding data to a Ustr
  • ustr_add_undef()
  • ustr_add_buf()
  • ustr_add_cstr()
  • USTR_ADD_OSTR()
  • USTR_ADD_OBJ()
  • ustr_add()
  • ustr_add_subustr()
  • ustr_add_rep_chr()
• Setting a Ustr to some data
  • ustr_set_undef()
  • ustr_set_empty()
  • ustr_set_buf()
  • ustr_set_cstr()
  • USTR_SET_OSTR()
  • USTR_SET_OBJ()
  • ustr_set()
  • ustr_set_subustr()
  • ustr_set_rep_chr()
• Inserting data into a Ustr
  • ustr_ins_undef()
  • ustr_ins_buf()
  • ustr_ins_cstr()
  • USTR_INS_OSTR()
  • USTR_INS_OBJ()
  • ustr_ins()
  • ustr_ins_subustr()
  • ustr_ins_rep_chr()
• Adding, duplicating and setting formatted data to a Ustr
  • ustr_add_vfmt_lim()
  • ustr_add_vfmt()
  • ustr_add_fmt_lim()
  • ustr_add_fmt()
  • ustr_dup_vfmt_lim()
  • ustr_dup_vfmt()
  • ustr_dup_fmt_lim()
  • ustr_dup_fmt()
  • ustr_dupx_fmt_lim()
  • ustr_dupx_fmt()
  • ustr_set_vfmt_lim()
  • ustr_set_vfmt()
  • ustr_set_fmt_lim()
  • ustr_set_fmt()
  • ustr_ins_vfmt_lim()
  • ustr_ins_vfmt()
  • ustr_ins_fmt_lim()
  • ustr_ins_fmt()
  • ustr_sub_vfmt_lim()
  • ustr_sub_vfmt()
  • ustr_sub_fmt_lim()
  • ustr_sub_fmt()
  • ustr_sc_sub_vfmt_lim()
  • ustr_sc_sub_vfmt()
  • ustr_sc_sub_fmt_lim()
  • ustr_sc_sub_fmt()
• Accessing the "variables" of a Ustr
  • ustr_len()
  • ustr_cstr()
  • ustr_wstr()
  • ustr_alloc()
  • ustr_exact()
  • ustr_sized()
  • ustr_ro()
  • ustr_fixed()
  • ustr_enomem()
  • ustr_shared()
  • ustr_limited()
  • ustr_owner()
  • ustr_size()
  • ustr_size_alloc()
  • ustr_size_overhead()
  • ustr_conf()
• Setting the "flags" of a Ustr
  • ustr_setf_enomem_err()
  • ustr_setf_enomem_clr()
  • ustr_setf_share()
  • ustr_setf_owner()
• Comparing data in a Ustr
  • ustr_cmp_buf()
  • ustr_cmp()
  • ustr_cmp_subustr()
  • ustr_cmp_cstr()
  • ustr_cmp_fast_buf()
  • ustr_cmp_fast()
  • ustr_cmp_fast_subustr()
  • ustr_cmp_fast_cstr()
  • ustr_cmp_case_buf()
  • ustr_cmp_case()
  • ustr_cmp_case_subustr()
  • ustr_cmp_case_cstr()
  • ustr_cmp_eq()
  • ustr_cmp_buf_eq()
  • ustr_cmp_subustr_eq()
  • ustr_cmp_cstr_eq()
  • ustr_cmp_case_eq()
  • ustr_cmp_case_buf_eq()
  • ustr_cmp_case_subustr_eq()
  • ustr_cmp_case_cstr_eq()
  • ustr_cmp_prefix_eq()
  • ustr_cmp_prefix_buf_eq()
  • ustr_cmp_prefix_cstr_eq()
  • ustr_cmp_prefix_subustr_eq()
  • ustr_cmp_case_prefix_eq()
  • ustr_cmp_case_prefix_buf_eq()
  • ustr_cmp_case_prefix_cstr_eq()
  • ustr_cmp_case_prefix_subustr_eq()
  • ustr_cmp_suffix_eq()
  • ustr_cmp_suffix_buf_eq()
  • ustr_cmp_suffix_cstr_eq()
  • ustr_cmp_suffix_subustr_eq()
  • ustr_cmp_case_suffix_eq()
  • ustr_cmp_case_suffix_buf_eq()
  • ustr_cmp_case_suffix_cstr_eq()
  • ustr_cmp_case_suffix_subustr_eq()
• Searching for data in a Ustr
  • ustr_srch_chr_fwd()
  • ustr_srch_chr_rev()
  • ustr_srch_buf_fwd()
  • ustr_srch_buf_rev()
  • ustr_srch_fwd()
  • ustr_srch_rev()
  • ustr_srch_cstr_fwd()
  • ustr_srch_cstr_rev()
  • ustr_srch_subustr_fwd()
  • ustr_srch_subustr_rev()
  • ustr_srch_case_chr_fwd()
  • ustr_srch_case_chr_rev()
  • ustr_srch_case_buf_fwd()
  • ustr_srch_case_buf_rev()
  • ustr_srch_case_fwd()
  • ustr_srch_case_rev()
  • ustr_srch_case_cstr_fwd()
  • ustr_srch_case_cstr_rev()
  • ustr_srch_case_subustr_fwd()
  • ustr_srch_case_subustr_rev()
• Span lengths of data in a Ustr
  • ustr_spn_chr_fwd()
  • ustr_spn_chr_rev()
  • ustr_spn_chrs_fwd()
  • ustr_spn_chrs_rev()
  • ustr_spn_fwd()
  • ustr_spn_rev()
  • ustr_spn_cstr_fwd()
  • ustr_spn_cstr_rev()
  • ustr_cspn_chr_fwd()
  • ustr_cspn_chr_rev()
  • ustr_cspn_chrs_fwd()
  • ustr_cspn_chrs_rev()
  • ustr_cspn_fwd()
  • ustr_cspn_rev()
  • ustr_cspn_cstr_fwd()
  • ustr_cspn_cstr_rev()
  • ustr_utf8_spn_chrs_fwd()
  • ustr_utf8_spn_chrs_rev()
  • ustr_utf8_spn_fwd()
  • ustr_utf8_spn_rev()
  • ustr_utf8_spn_cstr_fwd()
  • ustr_utf8_spn_cstr_rev()
  • ustr_utf8_cspn_chrs_fwd()
  • ustr_utf8_cspn_chrs_rev()
  • ustr_utf8_cspn_fwd()
  • ustr_utf8_cspn_rev()
  • ustr_utf8_cspn_cstr_fwd()
  • ustr_utf8_cspn_cstr_rev()
• Doing IO from or to a Ustr
  • ustr_io_get()
  • ustr_io_getfile()
  • ustr_io_getfilename()
  • ustr_io_getdelim()
  • ustr_io_getline()
  • ustr_io_put()
  • ustr_io_putline()
  • ustr_io_putfile()
  • ustr_io_putfileline()
  • ustr_io_putfilename()
• String substitution/replacement
  • ustr_sub_undef()
  • ustr_sub_buf()
  • ustr_sub_cstr()
  • USTR_SUB_OSTR()
  • USTR_SUB_OBJ()
  • ustr_sub()
  • ustr_sub_subustr()
  • ustr_sc_sub_undef()
  • ustr_sc_sub_buf()
  • ustr_sc_sub_cstr()
  • ustr_sc_sub()
  • ustr_sc_sub_subustr()
  • USTR_SC_SUB_OSTR()
  • USTR_SC_SUB_OBJ()
  • ustr_replace_buf()
  • ustr_replace_cstr()
  • ustr_replace()
  • ustr_replace_rep_chr()
• Splitting a Ustr
  • ustr_split_buf()
  • ustr_split()
  • ustr_split_cstr()
  • ustr_split_spn_chrs()
  • ustr_split_spn_cstr()
  • ustr_split_spn()
• Dealing with UTF-8 in a Ustr
  • ustr_utf8_valid()
  • ustr_utf8_len()
  • ustr_utf8_width()
  • ustr_utf8_chars2bytes()
  • ustr_utf8_bytes2chars()
  • ustr_sc_utf8_reverse()
• Parsing ASCII integer numbers from a Ustr
  • ustr_parse_uintmaxx()
  • ustr_parse_uintmax()
  • ustr_parse_intmax()
  • ustr_parse_ulongx()
  • ustr_parse_ulong()
  • ustr_parse_long()
  • ustr_parse_uint()
  • ustr_parse_int()
  • ustr_parse_ushort()
  • ustr_parse_short()
• Misc shortcut helper functions for Ustrs
  • ustr_sc_ensure_owner()
  • ustr_sc_wstr()
  • ustr_sc_export_subustr()
  • ustr_sc_export()
  • ustrp_sc_export_subustrp()
  • ustrp_sc_export()
  • ustr_sc_reverse()
  • ustr_sc_tolower()
  • ustr_sc_toupper()
  • ustr_sc_ltrim_chrs()
  • ustr_sc_ltrim()
  • ustr_sc_ltrim_cstr()
  • ustr_sc_rtrim_chrs()
  • ustr_sc_rtrim()
  • ustr_sc_rtrim_cstr()
  • ustr_sc_trim_chrs()
  • ustr_sc_trim()
  • ustr_sc_trim_cstr()
• Adding binary data to a Ustr
  • ustr_add_b_uint16()
  • ustr_add_b_uint32()
  • ustr_add_b_uint64()
• Parsing binary data from a Ustr
  • ustr_parse_b_uint16()
  • ustr_parse_b_uint32()
  • ustr_parse_b_uint64()
• Misc. functions
  • ustr_realloc()
  • ustr_cntl_opt()
• Simple Ustr pool API
  • ustr_pool_ll_make()
  • ustr_pool_make_subpool()
  • ustr_pool_free()
  • ustr_pool_clear()

This macro function is normally used with the empty string "".

There is basically just a simple cast behind the macro.

This macro function is normally used with the empty string "".

There is basically just a simple cast behind the macro.

This macro function simplifies the creation of read-only Ustr string's. And is normally used like...

  USTR1(\x4, "abcd")

...it is worth pointing out that running with debugging turned on (USTR_CONF_USE_ASSERT) will complain if the length isn't encoded correctly, as in...

  USTR1(\x3, "abcd")

...here ustr_assert_valid() will fail, which is called before most functions do anything in debugging mode. Note also that extra debugging (USTR_CONF_USE_EOS_MARK) will still catch cases like...

  USTR1(\x3, "abc\0d")

...at least using debugging is esp. important if you are putting UTF-8 characters into the strings.

Having ustr_ro() return true means that the Ustr cannot be written to without be reallocated into allocation space ... not that ustr_add() etc. will fail.

There is now USTR1_CHK() which performs a compile time check so you can never have an invalid ustr.

This function works in the same way as USTR1() but takes two length bytes, so the read-only string can be upto 65,535 (2**16 - 1) bytes in length.

This function works in the same way as USTR1() but takes four length bytes, so the read-only string can be upto 2**32 - 1 bytes in length.

This function works in the same way as USTR1() but it does a check against the length of (Parameter[2]) using sizeof() - 1.

If the check fails the returned Ustr * will be "", so you can check ustr_len() to see if you screwed something up.

This function works in the same way as USTR2() but it does a check against the length of (Parameter[2]) using sizeof() - 1.

If the check fails the returned Ustr * will be "".

This function works in the same way as USTR4() but it does a check against the length of (Parameter[2]) using sizeof() - 1.

If the check fails the returned Ustr * will be "".

This function works like USTR1(), but returns a Ustrp instead.

This function works like USTR4(), but returns a Ustrp instead.

This function works like USTR2(), but returns a Ustrp instead.

This function works like USTR1_CHK(), but returns a Ustrp instead.

This function works like USTR4_CHK(), but returns a Ustrp instead.

This function works like USTR2_CHK(), but returns a Ustrp instead.

This macro function is replaced by a static conversion from the max length desired (Parameter[1]) to the storage size needed. In other words it works out what ustr_size_overhead() will be, and adds that value.

This is useful is you want a small fixed size allocation, as you can declare it like so:

char buf[USTR_SIZE_FIXED(4)]; ...to give you exactly 4 bytes as a maximum, this is esp. useful if you want a limited (ustr_limited() == USTR_TRUE) Ustr string.

This creates a new Ustr string, which is "fixed". This means the Ustr storage is managed outside of the ustr_* API, it is often used for stack allocated strings.

As you add data to the Ustr past the size allowed via. the fixed storge the Ustr will automatically be converted into an allocated Ustr. So if this is possible you should always call ustr_free(), as this does nothing if given a fixed size Ustr.

For simplicity you probably want to use USTR_SC_INIT_AUTO() or USTR_SC_INIT_AUTO() when possible.

This calls ustr_init_fixed() with sizeof() the area of memory (Parameter[1]) as the second argument.

This does mean that the first argument must be the correct size, as far as sizeof() is concerned, as in...

 char buf_sz[1024];
 Ustr *s1 = USTR_SC_INIT_AUTO(buf_sz, USTR_FALSE, 0);

...so passing pointers to memory from malloc() will probably just return NULL.

This calls ustr_init_fixed() with sizeof() the area of memory (Parameter[1]) as the second argument, given as an "object string".

This does mean that the first argument must be the correct size, as far as sizeof() is concerned, as in...

 char buf_sz[1024] = USTR_BEG_FIXED2 "abcd";
 Ustr *s1 = USTR_SC_INIT_AUTO_OSTR(buf_sz, USTR_FALSE, "abcd");

...so passing pointers to memory from malloc() will probably just return NULL.

This function asserts a few internal consistency checks, and can help point out when a Ustr is invalid.

This calls ustr_assert_ret() so that when USTR_DEBUG if off the checks are still performed and the result is returned.

This function calls ustr_assert_valid() and also checks that the position and length are within the Ustr. If they aren't valid it returns 0, if they are valid it returns ustr_len().

This function begins malloc checking, meaning all ustr allocations will go through the malloc check routines, but it fails if the condition check (Parameter[1]) fails.

Turning malloc checking on after one or more allocations has happened will lead to false failures unless you really known what you are doing.

You can automatically turn malloc checking on by giving the USTR_CNTL_MC environment variable the value of "1", "yes" or "on".

This function returns the current "level" of the malloc check, with 0 indicating that malloc check isn't enabled.

The level goes up by one whenever USTR_CNTL_MALLOC_CHECK_BEG() or USTR_CNTL_MALLOC_CHECK_ADD() returns success, and goes down by one whenever USTR_CNTL_MALLOC_CHECK_DEL() or USTR_CNTL_MALLOC_CHECK_END() returns success.

This function asserts that the pointer (Parameter[1]) was allocated from malloc checking.

Unless you are doing something special, or using a builtin Ustr_pool it is very likely you want to just call USTR_CNTL_MALLOC_CHECK_MEM_USTR().

This function asserts that the pointer (Parameter[1]) was allocated from malloc checking, and has the specified size (Parameter[2]).

Unless you are doing something special, or using a builtin Ustr_pool it is very likely you want to just call USTR_CNTL_MALLOC_CHECK_MEM_USTR().

This function asserts that the pointer (Parameter[1]) was allocated from malloc checking, and has at least the specified size (Parameter[2]).

Unless you are doing something special, or using a builtin Ustr_pool it is very likely you want to just call USTR_CNTL_MALLOC_CHECK_MEM_USTR().

This function asserts that the pointer (Parameter[1]) is a Ustr allocated from malloc checking, if the Ustr is allocated (if not it returns TRUE).

Because of the layering between the Ustr code and the pool code, if you allocate an implicity sized Ustrp from a pool and then delete some data from it (which fails) the Ustr layer will think it has an implicit less than the actual size so this function will fail. This is what USTR_CNTL_MALLOC_CHECK_MEM_USTRP() is for.

This function asserts that the pointer (Parameter[1]) is a Ustr allocated from a builtin pool using malloc checking, if the Ustr is allocated (if not it returns TRUE).

This macro will cleanup any memory used by malloc check, and assert that no memory is left allocated.

If any memory is left allocated, each one found is output to stderr with the file/line/function of the level it was allocated from.

This function works like USTR_CNTL_MALLOC_CHECK_END() but it fails if the condition check (Parameter[1]) fails, or if USTR_CNTL_MALLOC_CHECK_LVL() is zero.

This function works like USTR_CNTL_MALLOC_CHECK_END() but it fails if the condition check (Parameter[1]) fails, or if USTR_CNTL_MALLOC_CHECK_LVL() is one.

The condition (Parameter[1]) to this macro should almost certainly be the return value from USTR_CNTL_MALLOC_CHECK_ADD().

This function finds out the exact size of memory needed to store the specified Ustr of the given configuration.

This creates a new Ustr string, you should have allocated the data via. USTR_CONF_MALLOC() or bad things will happen if the Ustr string is ever free'd or reallocated.

This function creates an empty Ustr, owned by you, that is allocated from system memory, or it returns NULL.

The size is the desired allocation size for the entire Ustr, including overhead for metadata. This value will be rounded up, if it's too small, so passing 1 as the size means you want a stored size but to allocate the smallest amount of memory possible.

The exact memory allocation flag says if the Ustr should round allocations up to the nearest half power of two or should be no more than needed.

The ENOMEM memory error flag sets the iniital state of the user visible flag for memory allocation errors. Eg. ustr_enomem(), ustr_setf_enomem_clr() and ustr_setf_enomem_err()

The reference byte count can only be one of the following values: 0, 1, 2 or 4, or 8 (on environments with a 64bit size_t).

It can be useful to ensure that the Ustr is in system memory, so that you can add things to it and check for errors with ustr_enomem().

If you chose to store the allocated size in the Ustr then the number of bytes allocated for the reference count will be a minimum of 2.

This function is the same as calling ustr_dupx_empty() with the current set of default options.

This function works like you called ustr_dupx_empty() and then ustr_add_undef().

This function is the same as calling ustr_dupx_undef() with the current set of default options.

This function tries to increase the reference count on the passed Ustr string, and if that succeeds returns that as an argument. If that fails it tries creates a new Ustr string that looks identical to the old Ustr string, apart from the reference count.

Because the new Ustr string is configured identically to the old Ustr string this means the result can be very different to what you get if you call ustr_dup_buf() with ustr_cstr() and ustr_len() from the original string where the configuration would be whatever the default is.

Esp. worth of note is that if you ustr_dup() a Ustr string with an explicit size of 900 but a length of 1, and the reference count is full the returned Ustr string will have a size of 900 bytes and so will have allocated a little over that. ustr_dup_buf(), even with a sized configuration would only allocate about 12 bytes and have a size a little less than that.

This function tries to add a reference if the value of the size, reference bytes, exact memory allocations and ENOMEM are the same as those in the passed Ustr string (Parameter[5]). If the comparison fails or the addition of a reference fails it works like ustr_dupx_buf() using ustr_cstr() and ustr_len().

This function works like calling ustr_dup(), but if the reference count is maxed out then and so a new Ustr string has been allocated then that is stored in the passed argument (Parameter[1]) and the "old" Ustr string is returned.

The reason to use this is that if you have a "main" Ustr string pointer that a lot of things are getting references too then when the reference count maxes out you'll degrade into worst case behaviour which acts as though there are no reference counts. This function stops that problem.

As an example, if you have a 1 byte reference count and have 255 * 2 references then using ustr_dup() will create 256 Ustr strings using this function will create 4 Ustr strings.

This function works like calling ustr_dupx(), but if the reference count is maxed out then and so a new Ustr string is allocated then that is stored in the passed argument (Parameter[1]) and the "old" Ustr string is returned.

If the configurations of the new Ustr string and the old Ustr string are not the same, this function works identically to ustr_dupx().

The reason to use this is that if you have a "main" Ustr string pointer that a lot of things are getting references too then when the reference count maxes out you'll degrade into worst case behaviour which acts as though there are no reference counts. This function stops that problem.

As an example, if you have a 1 byte reference count and have 255 * 2 references then using ustr_dupx() will create 256 Ustr strings using this function will create 4 Ustr strings.

This function works as if you had called ustr_dup_undef() and then copied the data into the new undefined space.

This function works as if you had called ustr_dupx_undef() and then copied the data into the new undefined space.

This function works as if you had called ustr_dup_buf() and passed strlen() as the length.

This function works as if you had called ustr_dupx_buf() and passed strlen() as the length.

This function works as if you had called ustr_dup_buf() and passed sizeof() - 1 as the length.

This function works as if you had called ustr_dup_buf() and passed sizeof() as the length.

In most cases you'll want to use USTR_DUP_OSTR().

This function mostly works as if you had called ustr_dup_buf() with the ustr_cstr() + position - 1 and length values of the Ustr string to be added.

If the position is 1 and the length is the length of the Ustr string then it just calls ustr_dup().

This function mostly works as if you had called ustr_dupx_buf() with the ustr_cstr() + position - 1 and length values of the Ustr string to be added.

If the position is 1 and the length is the length of the Ustr string then it just calls ustr_dupx().

This function works as if you had called ustr_dup_undef() and then copied the byte value to each position.

This function works as if you had called ustr_dupx_undef() and then copied the byte value to each position.

This function works as if you called ustr_dup() on the first Ustr string (Parameter[2]), and then ustr_add() on the separator (Parameter[1]) followed by ustr_add() on the second Ustr string (Parameter[3]). This process then repeats for all the Ustr strings in the variable argument list (Parameter[4]) until a USTR_NULL is reached.

This function doesn't guarantee to just take a reference to one of the passed Ustr strings, even if that is what would happen if you called the above manually.

This function calls va_start() to get a variable argument list and then calls ustr_sc_vjoin().

This function doesn't guarantee to just take a reference to one of the passed Ustr strings, even if that is what would happen if you called the above manually.

This function works as if you called ustr_dupx() on the first Ustr string (Parameter[2]), and then ustr_add() on the separator (Parameter[1]) followed by ustr_add() on the second Ustr string (Parameter[3]). This process then repeats for all the Ustr strings in the variable argument list (Parameter[4]) until a USTR_NULL is reached.

This function doesn't guarantee to just take a reference to one of the passed Ustr strings, even if that is what would happen if you called the above manually.

This function calls va_start() to get a variable argument list and then calls ustr_sc_vjoinx().

This function works as if you called ustr_dup() on the first Ustr string (Parameter[1]), and then ustr_add() on the second Ustr string (Parameter[3]). This process then repeats for all the Ustr strings in the variable argument list (Parameter[4]) until a USTR_NULL is reached.

This function doesn't guarantee to just take a reference to one of the passed Ustr strings, even if that is what would happen if you called the above manually.

This function calls va_start() to get a variable argument list and then calls ustr_sc_vconcat().

This function works as if you called ustr_dupx() on the first Ustr string (Parameter[1]), and then ustr_add() on the second Ustr string (Parameter[3]). This process then repeats for all the Ustr strings in the variable argument list (Parameter[4]) until a USTR_NULL is reached.

This function doesn't guarantee to just take a reference to one of the passed Ustr strings, even if that is what would happen if you called the above manually.

This function calls va_start() to get a variable argument list and then calls ustr_sc_vconcatx().

This function decrements the reference count on a Ustr, if there is one, and free's it if it is allocated and the reference count becomes zero.

This function does nothing if passed USTR_NULL.

This function works like ustr_free() but calls the pool_free member function of the Ustr_pool (Parameter[1]) instead of the ustr system free.

This function calls ustr_free() and then sets the pointer (Parameter[1]) to USTR_NULL, which is a noop when passed to ustr_free(). This can be used to help prevent "double free" errors.

While the point to the pointer must be non-NULL, this function also accepts a NULL ustr and does nothing. So you can pass the same pointer to this function multiple times and only the first one will do anything.

This function works like ustr_sc_free() but instead of setting the pointer (Parameter[1]) to USTR_NULL it sets it to the Ustr string (Parameter[2]).

While the point to the pointer must be non-NULL, this function also accepts a NULL ustr to be free'd and does nothing. So you can pass the same pointer to ustr_sc_free() and then this function safely.

The passed value (Parameter[2]) shouldn't be USTR_NULL, and in debugging mode the function will assert() that it isn't.

This function is a simple way to "free" a Ustr string that has been shared (ustr_shared() returns USTR_TRUE), normally ustr_free() is ignored on a shared Ustr string. It just calls ustr_setf_owner() and then ustr_sc_free().

This function deletes data from the end of Ustr, possibly re-sizing the Ustr at the same time.

The Ustr is never re-sized when the size is stored explicitly, so the pointer never changes.

This function works like ustr_del() but can delete an arbitrary section of the Ustr.

This function is like calling ustr_del() with ustr_len() as the length, however if that fails it does a ustr_free() and then sets the pointer to USTR("").

While the benifit is that you don't have to check for memory failure errors, if there is a memory failure and you have a non-default configuration the configuration will revert back to the default.

The Ustr string is expanded (possibly reallocated) so that it can contain length (Parameter[2]) extra data, if the length is not zero the Ustr will be writable. Or it'll return USTR_FALSE (zero) on failure.

This function works as if you had called ustr_add_undef() and then copied the data into the new undefined space.

This function works as if you had called ustr_add_buf() and passed strlen() as the length.

This function works as if you had called ustr_add_buf() and passed sizeof() - 1 as the length.

This function works as if you had called ustr_add_buf() and passed sizeof() as the length.

In most cases you'll want to use USTR_ADD_OSTR().

This function mostly works as if you had called ustr_add_buf() with the ustr_cstr() and ustr_len() values of the Ustr string to be added.

If the Ustr string is zero length and isn't writable this function may just add a reference, this is fine for Ustr strings that are "constant" because if the Ustr is read-only then the memory will not be written to.

This function mostly works as if you had called ustr_add_buf() with the ustr_cstr() + position - 1 and length values of the Ustr string to be added. The exception being if you add a ustr to itself, while only having a single reference count, the simple method would access a free'd ustr, but this function just works.

If the position is 1 and the length is the length of the Ustr string then it just calls ustr_add().

This function works as if you had called ustr_add_undef() and then copied the byte value to each position.

This function works as if you had called ustr_del() for the entire string and the ustr_add_undef().

This function works as if you had called ustr_del() for the entire string, however the string will be allocated if this completes.

This function works as if you had called ustr_del() for the entire string and the ustr_add_buf().

This function works as if you had called ustr_del() for the entire string and then ustr_add_cstr().

This function works as if you had called ustr_del() for the entire string and then USTR_ADD_OSTR().

This function works as if you had called ustr_del() for the entire string and then USTR_ADD_OBJ().

In most cases you'll want to use USTR_SET_OSTR().

This function works as if you had called ustr_del() for the entire string and the ustr_add().

This function works as if you had called ustr_del() for the entire string and the ustr_add_subustr(). The exception being if you set a ustr to itself, while only having a single reference count, the simple method would access a free'd ustr data, but this function just works.

This function works as if you had called ustr_del() for the entire string and the ustr_add_rep_chr().

The Ustr string is expanded (possibly reallocated) so that it can contain length (Parameter[2]) extra data, from after the required position. If the length is not zero the Ustr will be writable. Or it'll return USTR_FALSE (zero) on failure. The data in the Ustr is moved as needed to put the new data at position (Parameter[2]) + 1.

This function works as if you had called ustr_ins_undef() and then copied the data into the new undefined space.

This function works as if you had called ustr_ins_buf() and passed strlen() as the length.

This function works as if you had called ustr_ins_buf() and passed sizeof() - 1 as the length.

This function works as if you had called ustr_ins_buf() and passed sizeof() as the length.

In most cases you'll want to use USTR_INS_OSTR().

This function works as if you had called ustr_ins_buf() with the ustr_cstr() and ustr_len() values of the Ustr string to be added.

This function mostly as if you had called ustr_ins_buf() with the ustr_cstr() + position - 1 and length values of the Ustr string to be insed. The exception being if you insert a ustr to itself, while only having a single reference count, the simple method would access a free'd ustr data, but this function just works.

This function works as if you had called ustr_ins_undef() and then copied the byte value to each position.

This function works like calling the system vsnprintf() with the limit (Parameter[2]) as the limit to vsnprintf() and then calling ustr_add_buf().

This function works like calling the system vsnprintf() and then calling ustr_add_buf().

This function works like calling the system snprintf() with the limit (Parameter[2]) as the limit to snprintf() and then calling ustr_add_buf().

This function works like calling the system snprintf() and then calling ustr_add_buf().

This function works like calling the system vsnprintf() with the limit (Parameter[2]) as the limit to vsnprintf() and then calling ustr_dup_buf().

This function works like calling the system vsnprintf() and then calling ustr_dup_buf().

This function works like calling the system snprintf() with the limit (Parameter[2]) as the limit to snprintf() and then calling ustr_dup_buf().

This function works like calling the system snprintf() and then calling ustr_dup_buf().

This function works like calling the system snprintf() with the limit (Parameter[2]) as the limit to snprintf() and then calling ustr_dupx_buf().

This function works like calling the system snprintf() and then calling ustr_dup_bufx().

This function works like calling ustr_del() for all the data and then ustr_add_vfmt_lim().

This function works like calling ustr_del() for all the data and then ustr_add_vfmt().

This function works like calling ustr_del() for all the data and then ustr_add_fmt_lim().

This function works like calling ustr_del() for all the data and then ustr_add_fmt().