Ustr - 1.0.3 reference documentation -- functions (275)

Index of sections

• Creating read-only Ustr functions (14)
• Creating fixed Ustr functions (4)
• Debugging functions (12)
• Creating allocated Ustr functions (20)
• 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 (14)
• 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 (12)
• 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()
• 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()
• 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_buf()
  • ustr_sub_cstr()
  • USTR_SUB_OSTR()
  • USTR_SUB_OBJ()
  • ustr_sub()
  • ustr_sc_sub()
  • ustr_sc_sub_buf()
  • ustr_sc_sub_cstr()
  • 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 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 works like ustr_free() but calls the pool_free member function of the Ustr_pool (Parameter[1]) instead of the 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.

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]).

The passed value 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.

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().

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, 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.

While the ustr_add() function may add references, this function never does even when it is sematically the same as ustr_add().

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.

Again while ustr_add_subustr() has certain optimizations, this version does not.

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().

This function returns the length of the data within the Ustr, much like strlen() but without getting the value wrong in the case of extra NIL bytes.

This function returns a read-only pointer to the start of the data of the Ustr string. Due to there always being a terminating NIL byte in a Ustr, this is also a valid C-style string.

This function returns a writable pointer to the start of the data of the Ustr string. Due to there always being a terminating NIL byte in a Ustr, this is also a valid C-style string.

If the ustr is read-only (ustr_ro() == USTR_TRUE) then this function will return NULL.

Unless the string is owned (ustr_owner() == USTR_TRUE) it can be a very bad idea to use this to change data, as then all references will be updated. See ustr_sc_wstr().

This function says if the Ustr is currently in allocated storage.

This function says if the Ustr is doing exact allocations, so as the Ustr grows it will only have storage allocated exactly as required and not in half powers of two.

This will always be USTR_FALSE for read-only Ustr strings (ustr_ro() == USTR_TRUE), even though the default may be to used exact sized allocations when adding data to them etc.

This function says if the Ustr stores an explicit allocation size, if not the size is implied as the next highest half power of two.

This function says if the Ustr is current in read-only storage.

Read-only storage is not writable but can be referenced via. ustr_dup() an infinite amount of times.

This function says if the Ustr is current in fixed size storage.

Fixed size storage is writable but cannot be referenced.

Fixed size storage always explicitly stores the size of the storage.

This function just returns the value of the user settable flag in the Ustr. It can be set via. ustr_setf_enomem_err() and cleared by ustr_setf_enomem_clr().

This function is automatically set to on whever a memory allocation failure happens for a Ustr.

If a Ustr is referenced multiple times, ustr_setf_enomem_err() will fail.

This always fails for Ustr's in read-only storage.

This function says if the Ustr is in the "shared" mode. It can be set via. ustr_setf_shared() and cleared by ustr_setf_owner() on allocated Ustr's.

Shared mode means that a Ustr can be referenced and unreferenced an infinite number of times.

This always succeeds for Ustr's in read-only storage.

This always fails for Ustr's in fixed size storage.

This function says if the Ustr is currently in fixed size storage and cannot move to allocated storage.

This always fails for Ustr's in allocated storage.

This always fails for Ustr's in read-only storage.

This function says if there is only a single reference to the Ustr string.

This always fails for Ustr's in read-only storage.

This always succeeds for Ustr's in fixed size storage.

This function calculates the maximum amount of data that could be stored (Ie. the max ustr_len()) without having to re-size the Ustr string.

This function returns the size of the storage for the Ustr.

This function returns the difference between the size of the storage and the maximum amount of data that could be stored without having to re-size the Ustr string.

This function gives the configuration of the current Ustr needed to duplicate it via. the ustr_dupx_*() functions. It also gives the number of bytes used for the length and the number of references, which are mainly informational.

This function differs from calling the ustr_exact() etc. functions in that it returns the global options if this Ustr isn't allocated, thus telling you what the configuration would be if the Ustr was turned into an allocated Ustr by adding data etc.

Zero references for an allocated Ustr with a non-zero number of bytes for a reference count means it's in "shared" mode).

This function sets the enomem flag, which can be observed via. the ustr_enomem() function.

The implication of setting this flag is that a memory error has occured in a previous function call on this Ustr.

This function fails if ustr_owner() fails for the Ustr.

This function clears the enomem flag, which can be observed via. the ustr_enomem() function.

The implication of this flag being set is that a memory error has occured in a previous function call on this Ustr, so on clearing the flag you should know you have brought the Ustr back to a known state.

This function fails if ustr_owner() fails for the Ustr.

This function sets the shared mode, which can be observed via. the ustr_shared() function.

This is used on a Ustr so that it can have more references than it is able to hold in it's reference count. After this call the Ustr can be referenced and unreferenced an infinite number of times.

After this call the Ustr will never be deleted until ustr_setf_owner() is called.

This function fails if ustr_alloc() fails for the Ustr.

This function removes the shared mode, which can be observed via. the ustr_shared() function.

This is used so that a Ustr in shared mode can be free'd.

This function fails if ustr_alloc() fails for the Ustr.

This function works like memcmp() on the Ustr and the passed data.

This function works like ustr_cmp_buf() but with the data from ustr_cstr() and the length from ustr_len().

This function works like ustr_cmp() but with a limit on the data and length.

This function works like ustr_cmp_buf() but with a length from strlen().

This function works like ustr_cmp_buf() but the order of comparison is optimized for speed, but is much less friendly to humans.

This function works like ustr_cmp_fast_buf() but with the data from ustr_cstr() and the length from ustr_len().

This function works like ustr_cmp_fast() but with a limit on the data and length.

This function works like ustr_cmp_fast_buf() but with a length from strlen().

This function works like ustr_cmp_buf() but the order of comparison ignores ASCII case.

This function works like ustr_cmp_case_buf() but with the data from ustr_cstr() and the length from ustr_len().

This function works like ustr_cmp_case() but with a limit on the data and length.

This function works like ustr_cmp_case_buf() but with a length from strlen().

This function works like comparing ustr_cmp() against 0.

This function works like comparing ustr_cmp_buf() against 0.

This function works like comparing ustr_cmp_subustr() against 0.

This function works like comparing ustr_cmp_cstr() against 0.

This function works like comparing ustr_cmp_case() against 0.

This function works like comparing ustr_cmp_case_buf() against 0.

This function works like comparing ustr_cmp_case_subustr() against 0.

This function works like comparing ustr_cmp_case_cstr() against 0.

This function works like comparing ustr_cmp() against 0, but the comparison is limited to the length of the right hand side.

This function works like comparing ustr_cmp_buf() against 0, but the comparison is limited to the length of the right hand side (Parameter[3]).

This function works like comparing ustr_cmp_cstr() against 0, but the comparison is limited to the length of the right hand side.

This function works like comparing ustr_cmp_subustr() against 0, but the comparison is limited to the given length (Parameter[4]).

This function works like comparing ustr_cmp_case() against 0, but the comparison is limited to the length of the right hand side.

This function works like comparing ustr_cmp_case_buf() against 0, but the comparison is limited to the length of the right hand side (Parameter[3]).

This function works like comparing ustr_cmp_case_cstr() against 0, but the comparison is limited to the length of the right hand side.

This function works like comparing ustr_cmp_case_subustr() against 0, but the comparison is limited to the given length (Parameter[4]).

This function works like ustr_cmp_prefix_eq() but compares the end of the left hand side.

This function works like ustr_cmp_prefix_buf_eq() but compares the end of the left hand side.

This function works like ustr_cmp_prefix_cstr_eq() but compares the end of the left hand side.

This function works like comparing ustr_cmp_subustr() against 0, but compares the end of the left hand side.

This function works like ustr_cmp_case_prefix_eq() but compares the end of the left hand side.

This function works like ustr_cmp_case_prefix_buf_eq() but compares the end of the left hand side.

This function works like ustr_cmp_case_prefix_cstr_eq() but compares the end of the left hand side.

This function works like comparing ustr_cmp_case_subustr() against 0, but compares the end of the left hand side.

This function searches for the data (Parameter[3]) in the Ustr, skipping an offset (Parameter[2]) number of bytes.

This function works like ustr_srch_chr_fwd() but it searches from the end of the string to the beginning.

The searching starts from the end of the string, and so the offset is the offset from the end. However the position of a byte is always relative to the begining, so to do a loop you need to take the position from the length.

This function searches for the data (Parameter[3]) of length (Parameter[4]) in the Ustr, skipping an offset (Parameter[2]) number of bytes.

This function works like ustr_srch_buf_fwd() but it searches from the end of the string to the beginning.

The searching starts from the end of the string, and so the offset is the offset from the end. However the position of a byte is always relative to the begining, so to do a loop you need to take the position from the length.

This function works like ustr_srch_buf_fwd() but it gets the data pointer by calling ustr_cstr() and the length by calling ustr_len() on the passed Ustr (Parameter[3]).

This function works like ustr_srch_fwd() but it searches from the end of the string to the beginning.

The searching starts from the end of the string, and so the offset is the offset from the end. However the position of a byte is always relative to the begining, so to do a loop you need to take the position from the length.

This function works like ustr_srch_buf_fwd() but it gets the length by calling strlen() on the passed data (Parameter[3]).

This function works like ustr_srch_cstr_fwd() but it searches from the end of the string to the beginning.

The searching starts from the end of the string, and so the offset is the offset from the end. However the position of a byte is always relative to the begining, so to do a loop you need to take the position from the length.

This function works like ustr_srch_fwd() but it moves the data to start at the correct position and limits the length to the value specified.

This function works like ustr_srch_rev() but it moves the data to start at the correct position and limits the length to the value specified.

The searching starts from the end of the string, and so the offset is the offset from the end. However the position of a byte is always relative to the begining, so to do a loop you need to take the position from the length.

This function works like ustr_srch_chr_fwd(), but treats ASCII uppercase and lowercase as equivalent.

This function works like ustr_srch_chr_fwd(), but treats ASCII uppercase and lowercase as equivalent.

This function works like ustr_srch_buf_fwd(), but treats ASCII uppercase and lowercase as equivalent.

This function works like ustr_srch_buf_rev(), but treats ASCII uppercase and lowercase as equivalent.

This function works like ustr_srch_fwd(), but treats ASCII uppercase and lowercase as equivalent.

This function works like ustr_srch_rev(), but treats ASCII uppercase and lowercase as equivalent.

This function works like ustr_srch_cstr_fwd(), but treats ASCII uppercase and lowercase as equivalent.

This function works like ustr_srch_cstr_rev(), but treats ASCII uppercase and lowercase as equivalent.

This function works like ustr_srch_subustr_fwd(), but treats ASCII uppercase and lowercase as equivalent.

This function works like ustr_srch_subustr_rev(), but treats ASCII uppercase and lowercase as equivalent.

This function returns the length of the start of the Ustr (Parameter[1]) that only contains bytes that are equal to the data (Parameter[3]), skipping offset (Parameter[2]) bytes.

This function returns the length of the end of the Ustr (Parameter[1]) that only contains bytes that are equal to the data (Parameter[3]), skipping offset (Parameter[2]) bytes.

This function returns the length of the start of the Ustr (Parameter[1]) that only contains bytes that are equal to any byte in the data (Parameter[3]), skipping offset (Parameter[2]) bytes.

This function returns the length of the end of the Ustr (Parameter[1]) that only contains bytes that are equal to any byte in the data (Parameter[3]), skipping offset (Parameter[2]) bytes.

This function works like ustr_spn_buf_fwd() but passing ustr_cstr() and ustr_len()

This function works like ustr_spn_buf_rev() but passing ustr_cstr() and ustr_len()

This function works like ustr_spn_buf_fwd() but passing strlen() for the length.

This function works like ustr_spn_buf_rev() but passing strlen() for the length.

This function returns the length of the start of the Ustr (Parameter[1]) that only contains bytes that are not equal to the data (Parameter[3]), skipping offset (Parameter[2]) bytes.

This function returns the length of the end of the Ustr (Parameter[1]) that only contains bytes that are not equal to the data (Parameter[3]), skipping offset (Parameter[2]) bytes.

This function returns the length of the start of the Ustr (Parameter[1]) that only contains bytes that are not equal to any byte in the data (Parameter[3]), skipping offset (Parameter[2]) bytes.

This function returns the length of the end of the Ustr (Parameter[1]) that only contains bytes that are not equal to any byte in the data (Parameter[3]), skipping offset (Parameter[2]) bytes.

This function works like ustr_cspn_buf_fwd() but passing ustr_cstr() and ustr_len()

This function works like ustr_cspn_buf_rev() but passing ustr_cstr() and ustr_len()

This function works like ustr_cspn_buf_fwd() but passing strlen() for the length.

This function works like ustr_cspn_buf_rev() but passing strlen() for the length.

This function works like ustr_spn_chrs_fwd() but the return value, offset, and length all use UTF-8 characters and not bytes.

This is much slower than ustr_spn_chrs_fwd() but given "xy" as a multi-byte UTF-8 character it understands that the span over "xyxz" is 1 UTF-8 character and not 3 bytes.

This function works like ustr_spn_chrs_rev() but the return value, offset, and length all use UTF-8 characters and not bytes.

This is much slower than ustr_spn_chrs_rev() but given "xy" as a multi-byte UTF-8 character it understands that the span over "xyxz" is 1 UTF-8 character and not 3 bytes.

This function works like ustr_spn_fwd() but the return value, offset, and length all use UTF-8 characters and not bytes.

This is much slower than ustr_spn_fwd() but given "xy" as a multi-byte UTF-8 character it understands that the span over "xyxz" is 1 UTF-8 character and not 3 bytes.

This function works like ustr_spn_rev() but the return value, offset, and length all use UTF-8 characters and not bytes.

This is much slower than ustr_spn_rev() but given "xy" as a multi-byte UTF-8 character it understands that the span over "xyxz" is 1 UTF-8 character and not 3 bytes.

This function works like ustr_spn_cstr_fwd() but the return value, offset, and length all use UTF-8 characters and not bytes.

This is much slower than ustr_spn_cstr_fwd() but given "xy" as a multi-byte UTF-8 character it understands that the span over "xyxz" is 1 UTF-8 character and not 3 bytes.

This function works like ustr_spn_cstr_rev() but the return value, offset, and length all use UTF-8 characters and not bytes.

This is much slower than ustr_spn_cstr_rev() but given "xy" as a multi-byte UTF-8 character it understands that the span over "xyxz" is 1 UTF-8 character and not 3 bytes.

This function works like ustr_cspn_chrs_fwd() but the return value, offset, and length all use UTF-8 characters and not bytes.

This is much slower than ustr_cspn_chrs_fwd() but given "xy" as a multi-byte UTF-8 character it understands that the compliment span over "xzxy" is 1 UTF-8 character and not 0 bytes.

This function works like ustr_cspn_chrs_rev() but the return value, offset, and length all use UTF-8 characters and not bytes.

This is much slower than ustr_cspn_chrs_rev() but given "xy" as a multi-byte UTF-8 character it understands that the compliment span over "xzxy" is 1 UTF-8 character and not 0 bytes.

This function works like ustr_cspn_fwd() but the return value, offset, and length all use UTF-8 characters and not bytes.

This is much slower than ustr_cspn_fwd() but given "xy" as a multi-byte UTF-8 character it understands that the compliment span over "xzxy" is 1 UTF-8 character and not 0 bytes.

This function works like ustr_cspn_rev() but the return value, offset, and length all use UTF-8 characters and not bytes.

This is much slower than ustr_cspn_rev() but given "xy" as a multi-byte UTF-8 character it understands that the compliment span over "xzxy" is 1 UTF-8 character and not 0 bytes.

This function works like ustr_cspn_cstr_fwd() but the return value, offset, and length all use UTF-8 characters and not bytes.

This is much slower than ustr_cspn_cstr_fwd() but given "xy" as a multi-byte UTF-8 character it understands that the compliment span over "xzxy" is 1 UTF-8 character and not 0 bytes.

This function works like ustr_cspn_cstr_rev() but the return value, offset, and length all use UTF-8 characters and not bytes.

This is much slower than ustr_spn_cstr_rev() but given "xy" as a multi-byte UTF-8 character it understands that the compliment span over "xzxy" is 1 UTF-8 character and not 0 bytes.

This function tries to read a minimum number of bytes from the file object, into the Ustr string. The exact number read is returned, unless (Parameter[4]) is NULL.

This function calls ustr_io_get() rpeatedly until EOF is encountered.

The errno value when this function ends could either be from fopen(), fread(), or if both of the those succeeded from fclose().

This function opens a specified file, and then calls ustr_io_getfile(). Finally closing the FILE * object.

This function reads bytes from the file until it hits the delimiter byte.

The delimiter is included, use ustr_del() to remove 1 byte from the end if you don't want it.

This function assumes a delimiter will happen every 80 bytes or so.

This function works like calling ustr_io_getdelim() with '\n' as the delimiter.

This function is the opposite of ustr_io_get(), taking bytes from the beginning of the Ustr and writting them to the file.

Deleting bytes from the begining of a Ustr string is the most inefficient thing to do, so it is recommended to use ustr_io_putfile().

This function works like calling ustr_io_put(), and then writting a '\n' to the file.

This doesn't write a line from the Ustr to the file, if you want that call ustr_io_put() directly, using the return from ustr_srch_chr_fwd() (with a '\n') as the number of bytes argument.

This function works like calling ustr_io_put() with ustr_len() as the number of bytes.

This function works like calling ustr_io_putline() with ustr_len() as the number of bytes.