Section: Creating read-only Ustr functions
Function: USTR()
 Returns: Ustr string
 Type: struct Ustr *

 Parameter[1]: Pointer to Ustr data
 Type[1]: void *

 Explanation:

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

 Note:

  There is basically just a simple cast behind the macro.


Function: USTRP()
 Returns: Ustrp string
 Type: struct Ustrp *

 Parameter[1]: Pointer to Ustrp data
 Type[1]: void *

 Explanation:

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

 Note:

  There is basically just a simple cast behind the macro.


Function: USTR1()
 Returns: Ustr string
 Type: struct Ustr *

 Parameter[1]: Encoded number of the length of Ustr string
 Type[1]: symbol

 Parameter[2]: Data for Ustr string
 Type[2]: const char[]

 Explanation:

  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.

 Note:

  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.


Function: USTR2()
 Returns: Ustr string
 Type: struct Ustr *

 Parameter[1]: Encoded 2nd byte of number of the length of Ustr string
 Type[1]: symbol

 Parameter[2]: Encoded 1st byte of number of the length of Ustr string
 Type[2]: symbol

 Parameter[3]: Data for Ustr string
 Type[3]: const char[]

 Explanation:

  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.


Function: USTR4()
 Returns: Ustr string
 Type: struct Ustr *

 Parameter[1]: Encoded 4th byte of number of the length of Ustr string
 Type[1]: symbol

 Parameter[2]: Encoded 3rd byte of number of the length of Ustr string
 Type[2]: symbol

 Parameter[3]: Encoded 2nd byte of number of the length of Ustr string
 Type[3]: symbol

 Parameter[4]: Encoded 1st byte of number of the length of Ustr string
 Type[4]: symbol

 Parameter[5]: Data for Ustr string
 Type[5]: const char[]

 Explanation:

  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.


Function: USTR1_CHK()
 Returns: Ustr string
 Type: struct Ustr *

 Parameter[1]: Encoded number of the length of Ustr string
 Type[1]: symbol

 Parameter[2]: Data for Ustr string
 Type[2]: const char[]

 Explanation:

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

 Note:

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


Function: USTR2_CHK()
 Returns: Ustr string
 Type: struct Ustr *

 Parameter[1]: Encoded 2nd byte of number of the length of Ustr string
 Type[1]: symbol

 Parameter[2]: Encoded 1st byte of number of the length of Ustr string
 Type[2]: symbol

 Parameter[3]: Data for Ustr string
 Type[3]: const char[]

 Explanation:

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

 Note:

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


Function: USTR4_CHK()
 Returns: Ustr string
 Type: struct Ustr *

 Parameter[1]: Encoded 4th byte of number of the length of Ustr string
 Type[1]: symbol

 Parameter[2]: Encoded 3rd byte of number of the length of Ustr string
 Type[2]: symbol

 Parameter[3]: Encoded 2nd byte of number of the length of Ustr string
 Type[3]: symbol

 Parameter[4]: Encoded 1st byte of number of the length of Ustr string
 Type[4]: symbol

 Parameter[5]: Data for Ustr string
 Type[5]: const char[]

 Explanation:

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

 Note:

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


Function: USTRP1()
 Returns: Ustr string
 Type: struct Ustr *

 Parameter[1]: Encoded number of the length of Ustr string
 Type[1]: symbol

 Parameter[2]: Data for Ustr string
 Type[2]: const char[]

 Explanation:

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


Function: USTRP2()
 Returns: Ustr string
 Type: struct Ustr *

 Parameter[1]: Encoded 2nd byte of number of the length of Ustr string
 Type[1]: symbol

 Parameter[2]: Encoded 1st byte of number of the length of Ustr string
 Type[2]: symbol

 Parameter[3]: Data for Ustr string
 Type[3]: const char[]

 Explanation:

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


Function: USTRP4()
 Returns: Ustrp string
 Type: struct Ustrp *

 Parameter[1]: Encoded 4th byte of number of the length of Ustrp string
 Type[1]: symbol

 Parameter[2]: Encoded 3rd byte of number of the length of Ustrp string
 Type[2]: symbol

 Parameter[3]: Encoded 2nd byte of number of the length of Ustrp string
 Type[3]: symbol

 Parameter[4]: Encoded 1st byte of number of the length of Ustrp string
 Type[4]: symbol

 Parameter[5]: Data for Ustr string
 Type[5]: const char[]

 Explanation:

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


Function: USTRP1_CHK()
 Returns: Ustr string
 Type: struct Ustr *

 Parameter[1]: Encoded number of the length of Ustr string
 Type[1]: symbol

 Parameter[2]: Data for Ustr string
 Type[2]: const char[]

 Explanation:

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


Function: USTRP2_CHK()
 Returns: Ustr string
 Type: struct Ustr *

 Parameter[1]: Encoded 2nd byte of number of the length of Ustr string
 Type[1]: symbol

 Parameter[2]: Encoded 1st byte of number of the length of Ustr string
 Type[2]: symbol

 Parameter[3]: Data for Ustr string
 Type[3]: const char[]

 Explanation:

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


Function: USTRP4_CHK()
 Returns: Ustrp string
 Type: struct Ustrp *

 Parameter[1]: Encoded 4th byte of number of the length of Ustrp string
 Type[1]: symbol

 Parameter[2]: Encoded 3rd byte of number of the length of Ustrp string
 Type[2]: symbol

 Parameter[3]: Encoded 2nd byte of number of the length of Ustrp string
 Type[3]: symbol

 Parameter[4]: Encoded 1st byte of number of the length of Ustrp string
 Type[4]: symbol

 Parameter[5]: Data for Ustr string
 Type[5]: const char[]

 Explanation:

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


Section: Creating fixed Ustr functions
Function: USTR_SIZE_FIXED()
 Returns: Size of area of memory
 Type: size_t

 Parameter[1]: Size of area of memory
 Type[1]: size_t

 Explanation:

  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.

 Note:

  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.


Function: ustr_init_fixed()
 Returns: Ustr string
 Type: struct Ustr *

 Parameter[1]: Pointer to area of memory to use as a Ustr string
 Type[1]: void *

 Parameter[2]: Size of area of memory
 Type[2]: size_t

 Parameter[3]: Whether the fixed size Ustr should be limited
 Type[3]: int

 Parameter[4]: The initial length of the Ustr
 Type[4]: size_t

 Explanation:

  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.

 Note:

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


Function: USTR_SC_INIT_AUTO()
 Returns: Ustr string
 Type: struct Ustr *

 Parameter[1]: Area of memory to use as a Ustr string
 Type[1]: char[]

 Parameter[2]: Whether the fixed size Ustr should be limited
 Type[2]: int

 Parameter[3]: The initial length of the Ustr
 Type[3]: size_t

 Explanation:

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

 Note:

  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.


Function: USTR_SC_INIT_AUTO_OSTR()
 Returns: Ustr string
 Type: struct Ustr *

 Parameter[1]: Area of memory to use as a Ustr string
 Type[1]: char[]

 Parameter[2]: Whether the fixed size Ustr should be limited
 Type[2]: int

 Parameter[3]: The initial string in the buffer, as a constant string
 Type[3]: size_t

 Explanation:

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

 Note:

  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.


Section: Debugging functions
Function: ustr_assert_valid()
 Returns: Success or failure
 Type: int

 Parameter[1]: Pointer to a Ustr string
 Type[1]: Ustr *

 Explanation:

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

 Note:

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


Function: ustr_assert_valid_subustr()
 Returns: Success or failure
 Type: int

 Parameter[1]: Pointer to a Ustr string
 Type[1]: Ustr *

 Parameter[2]: Position in the Ustr
 Type[2]: size_t

 Parameter[3]: Length to delete from the Ustr
 Type[3]:  size_t

 Explanation:

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


Function: USTR_CNTL_MALLOC_CHECK_BEG()
 Returns: Success or failure
 Type: int

 Parameter[1]: Condition for begin malloc checking or not
 Type[1]: int


 Explanation:

  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.

 Note:

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


Function: USTR_CNTL_MALLOC_CHECK_LVL()
 Returns: Level of current malloc check
 Type: int

 Parameter[1]: Nothing
 Type[1]: void

 Explanation:

  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.


Function: USTR_CNTL_MALLOC_CHECK_MEM()
 Returns: Success or failure
 Type: int

 Parameter[1]: Pointer returned from malloc check
 Type[1]: void *

 Explanation:

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

 Note:

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


Function: USTR_CNTL_MALLOC_CHECK_MEM_SZ()
 Returns: Success or failure
 Type: int

 Parameter[1]: Pointer returned from malloc check
 Type[1]: void *

 Parameter[2]: Length of allocated memory
 Type[2]: size_t

 Explanation:

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

 Note:

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


Function: USTR_CNTL_MALLOC_CHECK_MEM_MINSZ()
 Returns: Success or failure
 Type: int

 Parameter[1]: Pointer returned from malloc check
 Type[1]: void *

 Parameter[2]: Length of allocated memory
 Type[2]: size_t

 Explanation:

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

 Note:

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


Function: USTR_CNTL_MALLOC_CHECK_MEM_USTR()
 Returns: Success or failure
 Type: int

 Parameter[1]: Pointer to a Ustr string
 Type[1]: Ustr *

 Explanation:

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

 Note:

  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.


Function: USTR_CNTL_MALLOC_CHECK_MEM_USTRP()
 Returns: Success or failure
 Type: int

 Parameter[1]: Pointer to a Ustrp string
 Type[1]: Ustrp *

 Explanation:

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


Function: USTR_CNTL_MALLOC_CHECK_END()
 Returns: Success or failure
 Type: int

 Parameter[1]: Nothing
 Type[1]: void

 Explanation:

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

 Note:

  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.


Function: USTR_CNTL_MALLOC_CHECK_ADD()
 Returns: Success or failure
 Type: int

 Parameter[1]: Condition to begin malloc checking or not
 Type[1]: int

 Explanation:

  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.


Function: USTR_CNTL_MALLOC_CHECK_DEL()
 Returns: Success or failure
 Type: int

 Parameter[1]: Condition to end malloc checking or not
 Type[1]: int

 Explanation:

  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.

 Note:

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


Section: Creating allocated Ustr functions
Function: ustr_init_size()
 Returns: Size that needs to be allocated
 Type: size_t 

 Parameter[1]: Size of allocated storage
 Type[1]: size_t

 Parameter[2]: Number of bytes to use for reference count
 Type[2]: size_t

 Parameter[3]: Exact memory allocations
 Type[3]: int

 Parameter[4]: Length of data in the Ustr
 Type[4]: size_t

 Explanation:

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


Function: ustr_init_alloc()
 Returns: Ustr string
 Type: struct Ustr *

 Parameter[1]: Pointer to area of memory to use as a Ustr string
 Type[1]: void *

 Parameter[2]: Size of area of memory
 Type[2]: size_t

 Parameter[3]: Whether Ustr should store the size
 Type[3]: size_t

 Parameter[4]: Number of bytes to use for references
 Type[4]: size_t

 Parameter[5]: Whether the Ustr should use exact allocations
 Type[5]: int

 Parameter[6]: Whether the Ustr should have the "enomem" flag set
 Type[6]: int

 Parameter[7]: The initial length of the Ustr
 Type[7]: size_t

 Explanation:

  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.


Function: ustr_dupx_empty()
 Returns: Ustr string
 Type: struct Ustr *

 Parameter[1]: Size of allocated storage
 Type[1]: size_t

 Parameter[2]: Number of bytes to use for reference count
 Type[2]: size_t

 Parameter[3]: Exact memory allocation flag
 Type[3]: int

 Parameter[4]: ENOMEM, memory error flag
 Type[4]: int

 Explanation:

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

 Note:

  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.


Function: ustr_dup_empty()
 Returns: Ustr string
 Type: struct Ustr *

 Parameter[1]: Nothing
 Type[1]: void

 Explanation:

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


Function: ustr_dupx_undef()
 Returns: Ustr string
 Type: struct Ustr *

 Parameter[1]: Size of allocated storage
 Type[1]: size_t

 Parameter[2]: Number of bytes to use for reference count
 Type[2]: size_t

 Parameter[3]: Exact memory allocations
 Type[3]: int

 Parameter[4]: ENOMEM, memory error flag
 Type[4]: int

 Parameter[5]: Length of new undefined data
 Type[5]: size_t

 Explanation:

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


Function: ustr_dup_undef()
 Returns: Pointer to a Ustr string
 Type: struct Ustr *

 Parameter[1]: Length of new undefined data
 Type[1]: size_t

 Explanation:

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


Function: ustr_dup()
 Returns: A pointer to a Ustr string
 Type: struct Ustr *

 Parameter[1]: Pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Explanation:

  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.

 Note:

  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.


Function: ustr_dupx()
 Returns: Pointer to a Ustr string
 Type: struct Ustr *

 Parameter[1]: Size of allocated storage
 Type[1]: size_t

 Parameter[2]: Number of bytes to use for reference count
 Type[2]: size_t

 Parameter[3]: Exact memory allocations
 Type[3]: int

 Parameter[4]: ENOMEM, memory error flag
 Type[4]: int

 Parameter[5]: Pointer to a constant Ustr string
 Type[5]: const struct Ustr *

 Explanation:

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


Function: ustr_sc_dup()
 Returns: A pointer to a Ustr string
 Type: struct Ustr *

 Parameter[1]: A pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Explanation:

  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.

 Note:

  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.


Function: ustr_sc_dupx()
 Returns: Pointer to a Ustr string
 Type: struct Ustr *

 Parameter[1]: Size of allocated storage
 Type[1]: size_t

 Parameter[2]: Number of bytes to use for reference count
 Type[2]: size_t

 Parameter[3]: Exact memory allocations
 Type[3]: int

 Parameter[4]: ENOMEM, memory error flag
 Type[4]: int

 Parameter[5]: A pointer to a pointer to a Ustr string
 Type[5]: struct Ustr **

 Explanation:

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

 Note:

  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.


Function: ustr_dup_buf()
 Returns: A pointer to a Ustr string
 Type: struct Ustr *

 Parameter[1]: Pointer to data
 Type[1]: const void *

 Parameter[2]: Length of data
 Type[2]: size_t

 Explanation:

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


Function: ustr_dupx_buf()
 Returns: Pointer to a Ustr string
 Type: struct Ustr *

 Parameter[1]: Size of allocated storage
 Type[1]: size_t

 Parameter[2]: Number of bytes to use for reference count
 Type[2]: size_t

 Parameter[3]: Exact memory allocations
 Type[3]: int

 Parameter[4]: ENOMEM, memory error flag
 Type[4]: int

 Parameter[5]: Pointer to data
 Type[5]: const void *

 Parameter[6]: Length of data
 Type[6]: size_t

 Explanation:

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


Function: ustr_dup_cstr()
 Returns: A pointer to a Ustr string
 Type: struct Ustr *

 Parameter[1]: Pointer to constant C-style string
 Type[1]: const char *

 Explanation:

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


Function: ustr_dupx_cstr()
 Returns: Pointer to a Ustr string
 Type: struct Ustr *

 Parameter[1]: Size of allocated storage
 Type[1]: size_t

 Parameter[2]: Number of bytes to use for reference count
 Type[2]: size_t

 Parameter[3]: Exact memory allocations
 Type[3]: int

 Parameter[4]: ENOMEM, memory error flag
 Type[4]: int

 Parameter[5]: Pointer to constant C-style string
 Type[5]: const char *

 Explanation:

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


Function: USTR_DUP_OSTR()
 Returns: A pointer to a Ustr string
 Type: struct Ustr *

 Parameter[1]: A constant C-style string
 Type[1]: const char []

 Explanation:

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


Function: USTR_DUP_OBJ()
 Returns: A pointer to a Ustr string
 Type: struct Ustr *

 Parameter[1]: A symbol
 Type[1]: ...

 Explanation:

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

 Note:

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


Function: ustr_dup_subustr()
 Returns: A pointer to a Ustr string
 Type: struct Ustr *

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Position in the Ustr
 Type[2]: size_t

 Parameter[3]: Length to add from the Ustr
 Type[3]: size_t

 Explanation:

  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.

 Note:

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


Function: ustr_dupx_subustr()
 Returns: Pointer to a Ustr string
 Type: struct Ustr *

 Parameter[1]: Size of allocated storage
 Type[1]: size_t

 Parameter[2]: Number of bytes to use for reference count
 Type[2]: size_t

 Parameter[3]: Exact memory allocations
 Type[3]: int

 Parameter[4]: ENOMEM, memory error flag
 Type[4]: int

 Parameter[5]: A pointer to a constant Ustr string
 Type[5]: const struct Ustr *

 Parameter[6]: Position in the Ustr
 Type[6]: size_t

 Parameter[7]: Length to add from the Ustr
 Type[7]: size_t

 Explanation:

  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.

 Note:

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


Function: ustr_dup_rep_chr()
 Returns: A pointer to a Ustr string
 Type: struct Ustr *

 Parameter[1]: Byte value of data
 Type[1]: char

 Parameter[2]: Length of bytes as data
 Type[2]: size_t

 Explanation:

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


Function: ustr_dupx_rep_chr()
 Returns: Pointer to a Ustr string
 Type: struct Ustr *

 Parameter[1]: Size of allocated storage
 Type[1]: size_t

 Parameter[2]: Number of bytes to use for reference count
 Type[2]: size_t

 Parameter[3]: Exact memory allocations
 Type[3]: int

 Parameter[4]: ENOMEM, memory error flag
 Type[4]: int

 Parameter[5]: Byte value of data
 Type[5]: char

 Parameter[6]: Length of bytes as data
 Type[6]: size_t

 Explanation:

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


Section: Deleting a Ustr, or data within a Ustr
Function: ustr_free()
 Returns: Nothing
 Type: void 

 Parameter[1]: Pointer to a Ustr
 Type[1]: struct Ustr *

 Explanation:

  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.

Function: ustrp_free()
 Returns: Nothing
 Type: void 

 Parameter[1]: Pointer to a Ustr pool object
 Type[1]: struct Ustr_pool *

 Parameter[2]: Pointer to a Ustrp (pool allocated Ustr)
 Type[2]: struct Ustrp *

 Explanation:

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


Function: ustr_sc_free()
 Returns: Nothing
 Type: void 

 Parameter[1]: A pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Explanation:

  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.


Function: ustr_sc_free2()
 Returns: Nothing
 Type: void 

 Parameter[1]: A pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: Pointer to a Ustr string
 Type[2]: struct Ustr *

 Explanation:

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

 Note:

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


Function: ustr_sc_free_shared()
 Returns: Nothing
 Type: void 

 Parameter[1]: A pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Explanation:

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


Function: ustr_del()
 Returns: Success or failure
 Type: int 

 Parameter[1]: Pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: Length to delete from the Ustr
 Type[2]: size_t

 Explanation:

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

 Note:

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


Function: ustr_del_subustr()
 Returns: Success or failure
 Type: int 

 Parameter[1]: Pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: Position in the Ustr
 Type[2]: size_t

 Parameter[3]: Length to delete from the Ustr
 Type[3]:  size_t

 Explanation:

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


Function: ustr_sc_del()
 Returns: Nothing
 Type: void 

 Parameter[1]: A pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Explanation:

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

 Note:

  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.


Section: Adding data to a Ustr
Function: ustr_add_undef()
 Returns: Success or failure
 Type: int

 Parameter[1]: A pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: Length of new undefined data
 Type[2]: size_t

 Explanation:

  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.


Function: ustr_add_buf()
 Returns: Success or failure
 Type: int

 Parameter[1]: Pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: Pointer to data
 Type[2]: const void *

 Parameter[3]: Length of data
 Type[3]: size_t

 Explanation:

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


Function: ustr_add_cstr()
 Returns: Success or failure
 Type: int 

 Parameter[1]: Pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: Pointer to constant C-style string
 Type[2]: const char *

 Explanation:

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


Function: USTR_ADD_OSTR()
 Returns: Success or failure
 Type: int 

 Parameter[1]: Pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: A constant C-style string
 Type[2]: const char []

 Explanation:

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


Function: USTR_ADD_OBJ()
 Returns: Success or failure
 Type: int 

 Parameter[1]: Pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: A symbol
 Type[2]: ...

 Explanation:

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

 Note:

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


Function: ustr_add()
 Returns: Success or failure
 Type: int 

 Parameter[1]: Pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: A pointer to a constant Ustr string
 Type[2]: const struct Ustr *

 Explanation:

  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.

 Note:

  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.


Function: ustr_add_subustr()
 Returns: Success or failure
 Type: int 

 Parameter[1]: Pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: A pointer to a constant Ustr string
 Type[2]: const struct Ustr *

 Parameter[3]: Position in the Ustr
 Type[3]: size_t

 Parameter[4]: Length to add from the Ustr
 Type[4]: size_t

 Explanation:

  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.

 Note:

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


Function: ustr_add_rep_chr()
 Returns: Success or failure
 Type: int 

 Parameter[1]: Pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: Byte value of data
 Type[2]: char

 Parameter[3]: Length of bytes as data
 Type[3]: size_t

 Explanation:

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


Section: Setting a Ustr to some data
Function: ustr_set_undef()
 Returns: Success or failure 
 Type: int 

 Parameter[1]: Pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]:  size_t
 Type[2]:  size_t

 Explanation:

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


Function: ustr_set_empty()
 Returns: Success or failure
 Type: int

 Parameter[1]: Pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Explanation:

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


Function: ustr_set_buf()
 Returns: Success or failure
 Type: int

 Parameter[1]: Pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: Buffer containting data
 Type[2]:  const void *

 Parameter[3]: Length of Buffer
 Type[3]: size_t

 Explanation:

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


Function: ustr_set_cstr()
 Returns: Success or failure
 Type: int

 Parameter[1]: Pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: A pointer to a constant C-style string
 Type[2]: const char *

 Explanation:

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


Function: USTR_SET_OSTR()
 Returns: Success or failure
 Type: int

 Parameter[1]: Pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: A constant C-style string
 Type[2]: const char []

 Explanation:

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


Function: USTR_SET_OBJ()
 Returns: Success or failure
 Type: int

 Parameter[1]: Pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: A symbol
 Type[2]: ...

 Explanation:

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

 Note:

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


Function: ustr_set()
 Returns: Success or failure
 Type: int

 Parameter[1]: Pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: A pointer to a constant Ustr string
 Type[2]: const struct Ustr *

 Explanation:

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


Function: ustr_set_subustr()
 Returns: Success or failure
 Type: int

 Parameter[1]: Pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: A pointer to a constant Ustr string
 Type[2]: const struct Ustr *

 Parameter[3]: Position in the Ustr
 Type[3]: size_t

 Parameter[4]: Length to set from the Ustr
 Type[4]: size_t

 Explanation:

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


Function: ustr_set_rep_chr()
 Returns: Success or failure
 Type: int

 Parameter[1]: Pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: Byte value of data
 Type[2]: char

 Parameter[3]: Length of bytes as data
 Type[3]: size_t

 Explanation:

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


Section: Inserting data into a Ustr
Function: ustr_ins_undef()
 Returns: Success or failure
 Type: int

 Parameter[1]: A pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: Position after which the data should be added
 Type[2]: size_t

 Parameter[3]: Length of new undefined data
 Type[3]: size_t

 Explanation:

  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.


Function: ustr_ins_buf()
 Returns: Success or failure
 Type: int

 Parameter[1]: Pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: Position after which the data should be added
 Type[2]: size_t

 Parameter[3]: Pointer to data
 Type[3]: const void *

 Parameter[4]: Length of data
 Type[4]: size_t

 Explanation:

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


Function: ustr_ins_cstr()
 Returns: Success or failure
 Type: int 

 Parameter[1]: Pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: Position after which the data should be added
 Type[2]: size_t

 Parameter[3]: Pointer to constant C-style string
 Type[3]: const char *

 Explanation:

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


Function: USTR_INS_OSTR()
 Returns: Success or failure
 Type: int 

 Parameter[1]: Pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: Position after which the data should be added
 Type[2]: size_t

 Parameter[3]: A constant C-style string
 Type[3]: const char []

 Explanation:

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


Function: USTR_INS_OBJ()
 Returns: Success or failure
 Type: int 

 Parameter[1]: Pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: Position after which the data should be added
 Type[2]: size_t

 Parameter[3]: A symbol
 Type[3]: ...

 Explanation:

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

 Note:

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


Function: ustr_ins()
 Returns: Success or failure
 Type: int 

 Parameter[1]: Pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: Position after which the data should be added
 Type[2]: size_t

 Parameter[3]: A pointer to a constant Ustr string
 Type[3]: const struct Ustr *

 Explanation:

  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.

 Note:

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


Function: ustr_ins_subustr()
 Returns: Success or failure
 Type: int 

 Parameter[1]: Pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: Position after which the data should be added
 Type[2]: size_t

 Parameter[2]: A pointer to a constant Ustr string
 Type[2]: const struct Ustr *

 Parameter[3]: Position in the Ustr
 Type[3]: size_t

 Parameter[4]: Length to ins from the Ustr
 Type[4]: size_t

 Explanation:

  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.

 Note:

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


Function: ustr_ins_rep_chr()
 Returns: Success or failure
 Type: int 

 Parameter[1]: Pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: Position after which the data should be added
 Type[2]: size_t

 Parameter[2]: Byte value of data
 Type[2]: char

 Parameter[3]: Length of bytes as data
 Type[3]: size_t

 Explanation:

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


Section: Adding, duplicating and setting formatted data to a Ustr
Function: ustr_add_vfmt_lim()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: Limit of data to add
 Type[2]: size_t

 Parameter[3]: A pointer to a constant C-style string
 Type[3]: const char *

 Parameter[4]: Variable argument list variable
 Type[4]: va_list

 Explanation:

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


Function: ustr_add_vfmt()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: A pointer to a constant C-style string
 Type[2]: const char *

 Parameter[3]: Variable argument list variable, from va_start()
 Type[3]: va_list

 Explanation:

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


Function: ustr_add_fmt_lim()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: Limit of data to add
 Type[2]: size_t

 Parameter[3]: A pointer to a constant C-style string
 Type[3]: const char *

 Parameter[4]: Options depending on value of Parameter[3]
 Type[4]: ...

 Explanation:

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


Function: ustr_add_fmt()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: A pointer to a constant C-style string
 Type[2]: const char *

 Parameter[3]: Options depending on value of Parameter[2]
 Type[3]: ...

 Explanation:

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


Function: ustr_dup_vfmt_lim()
 Returns: Pointer to a Ustr string
 Type: struct Ustr *

 Parameter[1]: Limit of data to dup
 Type[1]: size_t

 Parameter[2]: Pointer to a constant Ustr string
 Type[2]: const char *

 Parameter[3]: Variable argument list variable, from va_start()
 Type[3]: va_list

 Explanation:

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


Function: ustr_dup_vfmt()
 Returns: Pointer to a Ustr string
 Type: struct Ustr *

 Parameter[1]: Limit of data to dup
 Type[1]: size_t

 Parameter[2]: Pointer to a constant Ustr string
 Type[2]: const char *

 Parameter[3]: Variable argument list variable, from va_start()
 Type[3]: va_list

 Explanation:

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


Function: ustr_dup_fmt_lim()
 Returns: Pointer to a Ustr string
 Type: struct Ustr *

 Parameter[1]: Limit of data to dup
 Type[1]: size_t

 Parameter[2]: Pointer to a constant Ustr string
 Type[2]: const char *

 Parameter[3]: Options depending on value of Parameter[2]
 Type[3]: ...

 Explanation:

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


Function: ustr_dup_fmt()
 Returns: Pointer to a Ustr string
 Type: struct Ustr *

 Parameter[1]: Pointer to a constant Ustr string
 Type[1]: const char *

 Parameter[2]: Options depending on value of Parameter[1]
 Type[2]: ...

 Explanation:

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


Function: ustr_dupx_fmt_lim()
 Returns: Pointer to a Ustr string
 Type: struct Ustr *

 Parameter[1]: Size of allocated storage
 Type[1]: size_t

 Parameter[2]: Number of bytes to use for reference count
 Type[2]: size_t

 Parameter[3]: Exact memory allocations
 Type[3]: int

 Parameter[4]: ENOMEM, memory error flag
 Type[4]: int

 Parameter[5]: Limit of data to dup
 Type[5]: size_t

 Parameter[6]: Pointer to a constant Ustr string
 Type[6]: const char *

 Parameter[7]: Options depending on value of Parameter[6]
 Type[7]: ...

 Explanation:

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


Function: ustr_dupx_fmt()
 Returns: Pointer to a Ustr string
 Type: struct Ustr *

 Parameter[1]: Size of allocated storage
 Type[1]: size_t

 Parameter[2]: Number of bytes to use for reference count
 Type[2]: size_t

 Parameter[3]: Exact memory allocations
 Type[3]: int

 Parameter[4]: ENOMEM, memory error flag
 Type[4]: int

 Parameter[5]: Pointer to a constant Ustr string
 Type[5]: const char *

 Parameter[6]: Options depending on value of Parameter[5]
 Type[6]: ...

 Explanation:

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


Function: ustr_set_vfmt_lim()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: Limit of data to set
 Type[2]: size_t

 Parameter[3]: A pointer to a constant C-style string
 Type[3]: const char *

 Parameter[4]: Variable argument list variable, from va_start()
 Type[4]: va_list

 Explanation:

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


Function: ustr_set_vfmt()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: A pointer to a constant C-style string
 Type[2]: const char *

 Parameter[3]: Variable argument list variable, from va_start()
 Type[3]: va_list

 Explanation:

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


Function: ustr_set_fmt_lim()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: Limit of data to set
 Type[2]: size_t

 Parameter[3]: A pointer to a constant C-style string
 Type[3]: const char *

 Parameter[4]: Options depending on value of Parameter[3]
 Type[4]: ...

 Explanation:

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


Function: ustr_set_fmt()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: A pointer to a constant C-style string
 Type[2]: const char *

 Parameter[3]: Options depending on value of Parameter[2]
 Type[3]: ...

 Explanation:

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


Section: Accessing the "variables" of a Ustr
Function: ustr_len()
 Returns: The length of the Ustr
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Explanation:

  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.


Function: ustr_cstr()
 Returns: Read-only pointer to the start of data in the Ustr
 Type: const char *

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Explanation:

  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.


Function: ustr_wstr()
 Returns: Writable pointer to the start of data in the Ustr, or NULL
 Type: char *

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: struct Ustr *

 Explanation:

  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.

 Note:

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


Function: ustr_alloc()
 Returns: A boolean flag of either USTR_TRUE or USTR_FALSE
 Type: int

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Explanation:

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


Function: ustr_exact()
 Returns: A boolean flag of either USTR_TRUE or USTR_FALSE
 Type: int

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Explanation:

  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.

 Note:

  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.


Function: ustr_sized()
 Returns: A boolean flag of either USTR_TRUE or USTR_FALSE
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Explanation:

  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.


Function: ustr_ro()
 Returns: A boolean flag of either USTR_TRUE or USTR_FALSE
 Type: int

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Explanation:

  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.


Function: ustr_fixed()
 Returns: A boolean flag of either USTR_TRUE or USTR_FALSE
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Explanation:

  This function says if the Ustr is current in fixed size storage.
  Fixed size storage is writable but cannot be referenced.

 Note:

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


Function: ustr_enomem()
 Returns: A boolean flag of either USTR_TRUE or USTR_FALSE
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Explanation:

  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.

 Note:

  If a Ustr is referenced multiple times, ustr_setf_enomem_err() will fail.
  This always fails for Ustr's in read-only storage.


Function: ustr_shared()
 Returns: A boolean flag of either USTR_TRUE or USTR_FALSE
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Explanation:

  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.

 Note:

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


Function: ustr_limited()
 Returns: A boolean flag of either USTR_TRUE or USTR_FALSE
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Explanation:

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

 Note:

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


Function: ustr_owner()
 Returns: A boolean flag of either USTR_TRUE or USTR_FALSE
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Explanation:

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

 Note:

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


Function: ustr_size()
 Returns: size_t 
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Explanation:

  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.


Function: ustr_size_alloc()
 Returns: size_t 
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Explanation:

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


Function: ustr_size_overhead()
 Returns: size_t 
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Explanation:

  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.


Function: ustr_conf()
 Returns: Nothing
 Type: void 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Return size allocated number
 Type[2]: size_t *

 Parameter[3]: Return number of bytes used in the reference count
 Type[3]: size_t *

 Parameter[4]: Return exact allocations flag
 Type[4]: int *

 Parameter[5]: Return number of bytes used in the length
 Type[5]: size_t *

 Parameter[5]: Return number of references to this Ustr
 Type[5]: size_t *

 Explanation:

  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.

 Note:

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


Section: Setting the "flags" of a Ustr
Function: ustr_setf_enomem_err()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a Ustr string
 Type[1]: struct Ustr *

 Explanation:

  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.

 Note:

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


Function: ustr_setf_enomem_clr()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a Ustr string
 Type[1]: struct Ustr *

 Explanation:

  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.

 Note:

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


Function: ustr_setf_share()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a Ustr string
 Type[1]: struct Ustr *

 Explanation:

  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.

 Note:

  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.


Function: ustr_setf_owner()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a Ustr string
 Type[1]: struct Ustr *

 Explanation:

  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.

 Note:

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


Section: Comparing data in a Ustr
Function: ustr_cmp_buf()
 Returns: Less then zero, zero or greater than zero depending on comparison
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: A pointer to constant bytes, to compare
 Type[2]: const void *

 Parameter[3]: Length of comparison bytes
 Type[3]: size_t

 Explanation:

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


Function: ustr_cmp()
 Returns: Less then zero, zero or greater than zero depending on comparison
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: A pointer to a constant Ustr string
 Type[2]: const struct Ustr *

 Explanation:

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


Function: ustr_cmp_subustr()
 Returns: Less then zero, zero or greater than zero depending on comparison
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: A pointer to a constant Ustr string
 Type[2]: const struct Ustr *

 Parameter[3]: Position in the Ustr
 Type[3]: size_t

 Parameter[4]: Length to compare from the Ustr
 Type[4]: size_t

 Explanation:

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


Function: ustr_cmp_cstr()
 Returns: Less then zero, zero or greater than zero depending on comparison
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: A pointer to a constant C-style string
 Type[2]: const char *

 Explanation:

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


Function: ustr_cmp_fast_buf()
 Returns: Less then zero, zero or greater than zero depending on comparison
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: A pointer to constant bytes, to compare
 Type[2]: const void *

 Parameter[3]: Length of comparison bytes
 Type[3]: size_t

 Explanation:

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


Function: ustr_cmp_fast()
 Returns: Less then zero, zero or greater than zero depending on comparison
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: A pointer to a constant Ustr string
 Type[2]: const struct Ustr *

 Explanation:

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


Function: ustr_cmp_fast_subustr()
 Returns: Less then zero, zero or greater than zero depending on comparison
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: A pointer to a constant Ustr string
 Type[2]: const struct Ustr *

 Parameter[3]: Position in the Ustr
 Type[3]: size_t

 Parameter[4]: Length to compare from the Ustr
 Type[4]: size_t

 Explanation:

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


Function: ustr_cmp_fast_cstr()
 Returns: Less then zero, zero or greater than zero depending on comparison
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: A pointer to a constant C-style string
 Type[2]: const char *

 Explanation:

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


Function: ustr_cmp_case_buf()
 Returns: Less then zero, zero or greater than zero depending on comparison
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: A pointer to constant bytes, to compare
 Type[2]: const void *

 Parameter[3]: Length of comparison bytes
 Type[3]: size_t

 Explanation:

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


Function: ustr_cmp_case()
 Returns: Less then zero, zero or greater than zero depending on comparison
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: A pointer to a constant Ustr string
 Type[2]: const struct Ustr *

 Explanation:

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


Function: ustr_cmp_case_subustr()
 Returns: Less then zero, zero or greater than zero depending on comparison
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: A pointer to a constant Ustr string
 Type[2]: const struct Ustr *

 Parameter[3]: Position in the Ustr
 Type[3]: size_t

 Parameter[4]: Length to compare from the Ustr
 Type[4]: size_t

 Explanation:

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


Function: ustr_cmp_case_cstr()
 Returns: Less then zero, zero or greater than zero depending on comparison
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: A pointer to a constant C-style string
 Type[2]: const char *

 Explanation:

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


Function: ustr_cmp_eq()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: A pointer to a constant Ustr string
 Type[2]: const struct Ustr *

 Explanation:

  This function works like comparing ustr_cmp() against 0.


Function: ustr_cmp_buf_eq()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: A pointer to constant bytes, to compare
 Type[2]: const void *

 Parameter[3]: Length of comparison bytes
 Type[3]: size_t

 Explanation:

  This function works like comparing ustr_cmp_buf() against 0.


Function: ustr_cmp_subustr_eq()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: A pointer to a constant Ustr string
 Type[2]: const struct Ustr *

 Parameter[3]: Position in the Ustr
 Type[3]: size_t

 Parameter[4]: Length to compare from the Ustr
 Type[4]: size_t

 Explanation:

  This function works like comparing ustr_cmp_subustr() against 0.


Function: ustr_cmp_cstr_eq()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: A pointer to a constant C-style string
 Type[2]: const char *

 Explanation:

  This function works like comparing ustr_cmp_cstr() against 0.


Function: ustr_cmp_case_eq()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: A pointer to a constant Ustr string
 Type[2]: const struct Ustr *

 Explanation:

  This function works like comparing ustr_cmp_case() against 0.


Function: ustr_cmp_case_buf_eq()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: A pointer to constant bytes, to compare
 Type[2]: const void *

 Parameter[3]: Length of comparison bytes
 Type[3]: size_t

 Explanation:

  This function works like comparing ustr_cmp_case_buf() against 0.


Function: ustr_cmp_case_subustr_eq()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: A pointer to a constant Ustr string
 Type[2]: const struct Ustr *

 Parameter[3]: Position in the Ustr
 Type[3]: size_t

 Parameter[4]: Length to compare from the Ustr
 Type[4]: size_t

 Explanation:

  This function works like comparing ustr_cmp_case_subustr() against 0.


Function: ustr_cmp_case_cstr_eq()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: A pointer to a constant C-style string
 Type[2]: const char *

 Explanation:

  This function works like comparing ustr_cmp_case_cstr() against 0.


Function: ustr_cmp_prefix_eq()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: A pointer to a constant Ustr string
 Type[2]: const struct Ustr *

 Explanation:

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


Function: ustr_cmp_prefix_buf_eq()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: A pointer to constant bytes, to compare
 Type[2]: const void *

 Parameter[3]: Length of comparison bytes
 Type[3]: size_t

 Explanation:

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


Function: ustr_cmp_prefix_cstr_eq()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: A pointer to a constant C-style string
 Type[2]: const char *

 Explanation:

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


Function: ustr_cmp_prefix_subustr_eq()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: A pointer to a constant Ustr string
 Type[2]: const struct Ustr *

 Parameter[3]: Position in the Ustr
 Type[3]: size_t

 Parameter[4]: Length to compare from the Ustr
 Type[4]: size_t

 Explanation:

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


Function: ustr_cmp_case_prefix_eq()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: A pointer to a constant Ustr string
 Type[2]: const struct Ustr *

 Explanation:

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


Function: ustr_cmp_case_prefix_buf_eq()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: A pointer to constant bytes, to compare
 Type[2]: const void *

 Parameter[3]: Length of comparison bytes
 Type[3]: size_t

 Explanation:

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


Function: ustr_cmp_case_prefix_cstr_eq()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: A pointer to a constant C-style string
 Type[2]: const char *

 Explanation:

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


Function: ustr_cmp_case_prefix_subustr_eq()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: A pointer to a constant Ustr string
 Type[2]: const struct Ustr *

 Parameter[3]: Position in the Ustr
 Type[3]: size_t

 Parameter[4]: Length to compare from the Ustr
 Type[4]: size_t

 Explanation:

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


Function: ustr_cmp_suffix_eq()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: A pointer to a constant Ustr string
 Type[2]: const struct Ustr *

 Explanation:

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


Function: ustr_cmp_suffix_buf_eq()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: A pointer to constant bytes, to compare
 Type[2]: const void *

 Parameter[3]: Length of comparison bytes
 Type[3]: size_t

 Explanation:

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


Function: ustr_cmp_suffix_cstr_eq()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: A pointer to a constant C-style string
 Type[2]: const char *

 Explanation:

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


Function: ustr_cmp_suffix_subustr_eq()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: A pointer to a constant Ustr string
 Type[2]: const struct Ustr *

 Parameter[3]: Position in the Ustr
 Type[3]: size_t

 Parameter[4]: Length to compare from the Ustr
 Type[4]: size_t

 Explanation:

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


Function: ustr_cmp_case_suffix_eq()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: A pointer to a constant Ustr string
 Type[2]: const struct Ustr *

 Explanation:

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


Function: ustr_cmp_case_suffix_buf_eq()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: A pointer to constant bytes, to compare
 Type[2]: const void *

 Parameter[3]: Length of comparison bytes
 Type[3]: size_t

 Explanation:

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


Function: ustr_cmp_case_suffix_cstr_eq()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: A pointer to a constant C-style string
 Type[2]: const char *

 Explanation:

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


Function: ustr_cmp_case_suffix_subustr_eq()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: A pointer to a constant Ustr string
 Type[2]: const struct Ustr *

 Parameter[3]: Position in the Ustr
 Type[3]: size_t

 Parameter[4]: Length to compare from the Ustr
 Type[4]: size_t

 Explanation:

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


Section: Searching for data in a Ustr
Function: ustr_srch_chr_fwd()
 Returns: Position in the Ustr, or zero if not found
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string to start searching at
 Type[2]: size_t

 Parameter[3]: Byte data to search for
 Type[3]: char

 Explanation:

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


Function: ustr_srch_chr_rev()
 Returns: Position in the Ustr, or zero if not found
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string to start searching at
 Type[2]: size_t

 Parameter[3]: Byte data to search for
 Type[3]: char

 Explanation:

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

 Note:

  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.


Function: ustr_srch_buf_fwd()
 Returns: Position in the Ustr, or zero if not found
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string to start searching at
 Type[2]: size_t

 Parameter[3]: A pointer to data to search for
 Type[3]: const void *

 Parameter[4]: Length of the data to search for
 Type[4]: size_t

 Explanation:

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


Function: ustr_srch_buf_rev()
 Returns: Position in the Ustr, or zero if not found
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string to start searching at
 Type[2]: size_t

 Parameter[3]: A pointer to data to search for
 Type[3]: const void *

 Parameter[4]: Length of the data to search for
 Type[4]: size_t

 Explanation:

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

 Note:

  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.


Function: ustr_srch_fwd()
 Returns: Position in the Ustr, or zero if not found
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string to start searching at
 Type[2]: size_t

 Parameter[3]: A pointer to a constant Ustr string, to search for
 Type[3]: const struct Ustr *

 Explanation:

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


Function: ustr_srch_rev()
 Returns: Position in the Ustr, or zero if not found
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string to start searching at
 Type[2]: size_t

 Parameter[3]: A pointer to a constant Ustr string, to search for
 Type[3]: const struct Ustr *

 Explanation:

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

 Note:

  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.


Function: ustr_srch_cstr_fwd()
 Returns: Position in the Ustr, or zero if not found
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string to start searching at
 Type[2]: size_t

 Parameter[3]: A pointer to C-style string data, to search for
 Type[3]: const char *

 Explanation:

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


Function: ustr_srch_cstr_rev()
 Returns: Position in the Ustr, or zero if not found
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string to start searching at
 Type[2]: size_t

 Parameter[3]: A pointer to C-style string data, to search for
 Type[3]: const char *

 Explanation:

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

 Note:

  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.


Function: ustr_srch_subustr_fwd()
 Returns: Position in the Ustr, or zero if not found
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string to start searching at
 Type[2]: size_t

 Parameter[3]: A pointer to a constant Ustr string
 Type[3]: const struct Ustr *

 Parameter[4]: Position in the Ustr
 Type[4]: size_t

 Parameter[5]: Length of data to search, from the Ustr
 Type[5]: size_t

 Explanation:

  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.


Function: ustr_srch_subustr_rev()
 Returns: Position in the Ustr, or zero if not found
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string to start searching at
 Type[2]:  size_t

 Parameter[3]: A pointer to a constant Ustr string
 Type[3]: const struct Ustr *

 Parameter[4]: Position in the Ustr
 Type[4]: size_t

 Parameter[5]: Length of data to search, from the Ustr
 Type[5]: size_t

 Explanation:

  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.

 Note:

  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.


Function: ustr_srch_case_chr_fwd()
 Returns: Position in the Ustr, or zero if not found
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string to start searching at
 Type[2]: size_t

 Parameter[3]: Byte data to search for
 Type[3]: char

 Explanation:

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


Function: ustr_srch_case_chr_rev()
 Returns: Position in the Ustr, or zero if not found
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string to start searching at
 Type[2]: size_t

 Parameter[3]: Byte data to search for
 Type[3]: char

 Explanation:

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


Function: ustr_srch_case_buf_fwd()
 Returns: Position in the Ustr, or zero if not found
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string to start searching at
 Type[2]: size_t

 Parameter[3]: A pointer to data to search for
 Type[3]: const void *

 Parameter[4]: Length of the data to search for
 Type[4]: size_t

 Explanation:

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


Function: ustr_srch_case_buf_rev()
 Returns: Position in the Ustr, or zero if not found
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string to start searching at
 Type[2]: size_t

 Parameter[3]: A pointer to data to search for
 Type[3]: const void *

 Parameter[4]: Length of the data to search for
 Type[4]: size_t

 Explanation:

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


Function: ustr_srch_case_fwd()
 Returns: Position in the Ustr, or zero if not found
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string to start searching at
 Type[2]: size_t

 Parameter[3]: A pointer to a constant Ustr string, to search for
 Type[3]: const struct Ustr *

 Explanation:

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


Function: ustr_srch_case_rev()
 Returns: Position in the Ustr, or zero if not found
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string to start searching at
 Type[2]: size_t

 Parameter[3]: A pointer to a constant Ustr string, to search for
 Type[3]: const struct Ustr *

 Explanation:

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


Function: ustr_srch_case_cstr_fwd()
 Returns: Position in the Ustr, or zero if not found
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string to start searching at
 Type[2]: size_t

 Parameter[3]: A pointer to C-style string data, to search for
 Type[3]: const char *

 Explanation:

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


Function: ustr_srch_case_cstr_rev()
 Returns: Position in the Ustr, or zero if not found
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string to start searching at
 Type[2]: size_t

 Parameter[3]: A pointer to C-style string data, to search for
 Type[3]: const char *

 Explanation:

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


Function: ustr_srch_case_subustr_fwd()
 Returns: Position in the Ustr, or zero if not found
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string to start searching at
 Type[2]: size_t

 Parameter[3]: A pointer to a constant Ustr string
 Type[3]: const struct Ustr *

 Parameter[4]: Position in the Ustr
 Type[4]: size_t

 Parameter[5]: Length of data to search, from the Ustr
 Type[5]: size_t

 Explanation:

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


Function: ustr_srch_case_subustr_rev()
 Returns: Position in the Ustr, or zero if not found
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string to start searching at
 Type[2]:  size_t

 Parameter[3]: A pointer to a constant Ustr string
 Type[3]: const struct Ustr *

 Parameter[4]: Position in the Ustr
 Type[4]: size_t

 Parameter[5]: Length of data to search, from the Ustr
 Type[5]: size_t

 Explanation:

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


Section: Span lengths of data in a Ustr
Function: ustr_spn_chr_fwd()
 Returns: Number of bytes in the span
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string, to start spanning from
 Type[2]: size_t

 Parameter[3]: Byte data
 Type[3]: char

 Explanation:

  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.


Function: ustr_spn_chr_rev()
 Returns: Number of bytes in the span
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string, to start spanning from
 Type[2]: size_t

 Parameter[3]: Byte data
 Type[3]: char

 Explanation:

  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.


Function: ustr_spn_chrs_fwd()
 Returns: Number of bytes in the span
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string, to start spanning from
 Type[2]: size_t

 Parameter[3]: Array of byte data, for spanning
 Type[3]: const char *

 Parameter[4]: Length of byte data, for spanning
 Type[4]: size_t

 Explanation:

  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.


Function: ustr_spn_chrs_rev()
 Returns: Number of bytes in the span
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string, to start spanning from
 Type[2]: size_t

 Parameter[3]: Array of byte data
 Type[3]: const char *

 Parameter[4]: Length of byte data
 Type[4]: size_t

 Explanation:

  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.


Function: ustr_spn_fwd()
 Returns: Number of bytes in the span
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string, to start spanning from
 Type[2]: size_t

 Parameter[3]: A pointer to a constant Ustr string, containing spanning bytes
 Type[3]: const struct Ustr *

 Explanation:

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


Function: ustr_spn_rev()
 Returns: Number of bytes in the span
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string, to start spanning from
 Type[2]: size_t

 Parameter[3]: A pointer to a constant Ustr string, containing spanning bytes
 Type[3]: const struct Ustr *

 Explanation:

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


Function: ustr_spn_cstr_fwd()
 Returns: Number of bytes in the span
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string, to start spanning from
 Type[2]: size_t

 Parameter[3]: A pointer to a constant C-style string, containing spanning bytes
 Type[3]: const char *

 Explanation:

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


Function: ustr_spn_cstr_rev()
 Returns: Number of bytes in the span
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string, to start spanning from
 Type[2]: size_t

 Parameter[3]: A pointer to a constant C-style string, containing spanning bytes
 Type[3]: const char *

 Explanation:

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


Function: ustr_cspn_chr_fwd()
 Returns: Number of bytes not in the span
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string, to start compliment spanning from
 Type[2]: size_t

 Parameter[3]: Byte data
 Type[3]: char

 Explanation:

  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.


Function: ustr_cspn_chr_rev()
 Returns: Number of bytes not in the span
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string, to start compliment spanning from
 Type[2]: size_t

 Parameter[3]: Byte data
 Type[3]: char

 Explanation:

  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.


Function: ustr_cspn_chrs_fwd()
 Returns: Number of bytes not in the span
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string, to start compliment spanning from
 Type[2]: size_t

 Parameter[3]: Array of byte data
 Type[3]: const char *

 Parameter[4]: Length of byte data
 Type[4]: size_t

 Explanation:

  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.


Function: ustr_cspn_chrs_rev()
 Returns: Number of bytes not in the span
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string, to start compliment spanning from
 Type[2]: size_t

 Parameter[3]: Array of byte data
 Type[3]: const char *

 Parameter[4]: Length of byte data
 Type[4]: size_t

 Explanation:

  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.


Function: ustr_cspn_fwd()
 Returns: Number of bytes not in the span
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string, to start compliment spanning from
 Type[2]: size_t

 Parameter[3]: A pointer to a constant Ustr string, containing spanning bytes
 Type[3]: const struct Ustr *

 Explanation:

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


Function: ustr_cspn_rev()
 Returns: Number of bytes not in the span
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string, to start compliment spanning from
 Type[2]: size_t

 Parameter[3]: A pointer to a constant Ustr string, containing spanning bytes
 Type[3]: const struct Ustr *

 Explanation:

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


Function: ustr_cspn_cstr_fwd()
 Returns: Number of bytes not in the span
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string, to start compliment spanning from
 Type[2]: size_t

 Parameter[3]: A pointer to a constant C-style string, containing spanning bytes
 Type[3]: const char *

 Explanation:

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


Function: ustr_cspn_cstr_rev()
 Returns: Number of bytes not in the span
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string, to start spanning from
 Type[2]: size_t

 Parameter[3]: A pointer to a constant C-style string, containing spanning bytes
 Type[3]: const char *

 Explanation:

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


Function: ustr_utf8_spn_chrs_fwd()
 Returns: Number of UTF-8 characters not in the span
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr UTF-8 string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string, in UTF-8 characters, to start spanning from
 Type[2]: size_t

 Parameter[3]: A pointer to a constant C-style UTF-8 string
 Type[3]: const char *

 Parameter[4]: Length of the C-style UTF-8 string
 Type[4]: size_t

 Explanation:

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

 Note:

  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.


Function: ustr_utf8_spn_chrs_rev()
 Returns: Number of UTF-8 characters not in the span
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr UTF-8 string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string, in UTF-8 characters, to start spanning from
 Type[2]: size_t

 Parameter[3]: A pointer to a constant C-style UTF-8 string
 Type[3]: const char *

 Parameter[4]: 
 Type[4]: size_t

 Explanation:

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

 Note:

  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.


Function: ustr_utf8_spn_fwd()
 Returns: Number of UTF-8 characters not in the span
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr UTF-8 string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string, in UTF-8 characters, to start spanning from
 Type[2]: size_t

 Parameter[3]: A pointer to a constant Ustr UTF-8 string
 Type[3]: const struct Ustr *

 Explanation:

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

 Note:

  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.


Function: ustr_utf8_spn_rev()
 Returns: Number of UTF-8 characters not in the span
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr UTF-8 string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string, in UTF-8 characters, to start spanning from
 Type[2]: size_t

 Parameter[3]: A pointer to a constant Ustr UTF-8 string
 Type[3]: const struct Ustr *

 Explanation:

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

 Note:

  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.


Function: ustr_utf8_spn_cstr_fwd()
 Returns: Number of UTF-8 characters not in the span
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr UTF-8 string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string, in UTF-8 characters, to start spanning from
 Type[2]: size_t

 Parameter[3]: A pointer to a constant C-style UTF-8 string
 Type[3]: const char *

 Explanation:

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

 Note:

  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.


Function: ustr_utf8_spn_cstr_rev()
 Returns: Number of UTF-8 characters not in the span
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr UTF-8 string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string, in UTF-8 characters, to start spanning from
 Type[2]: size_t

 Parameter[3]: A pointer to a constant C-style UTF-8 string
 Type[3]: const char *

 Explanation:

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

 Note:

  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.


Function: ustr_utf8_cspn_chrs_fwd()
 Returns: Number of UTF-8 characters not in the span
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr UTF-8 string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string, in UTF-8 characters, to start compliment spanning from
 Type[2]: size_t

 Parameter[3]: A pointer to a constant C-style UTF-8 string
 Type[3]: const char *

 Parameter[4]: Length of the C-style UTF-8 string
 Type[4]: size_t

 Explanation:

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

 Note:

  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.


Function: ustr_utf8_cspn_chrs_rev()
 Returns: Number of UTF-8 characters not in the span
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr UTF-8 string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string, in UTF-8 characters, to start compliment spanning from
 Type[2]: size_t

 Parameter[3]: A pointer to a constant C-style UTF-8 string
 Type[3]: const char *

 Parameter[4]: Length of the C-style UTF-8 string
 Type[4]: size_t

 Explanation:

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

 Note:

  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.


Function: ustr_utf8_cspn_fwd()
 Returns: Number of UTF-8 characters not in the span
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr UTF-8 string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string, in UTF-8 characters, to start compliment spanning from
 Type[2]: size_t

 Parameter[3]: A pointer to a constant Ustr UTF-8 string, containing spanning data
 Type[3]: const struct Ustr *

 Explanation:

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

 Note:

  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.


Function: ustr_utf8_cspn_rev()
 Returns: Number of UTF-8 characters not in the span
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr UTF-8 string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string, in UTF-8 characters, to start compliment spanning from
 Type[2]: size_t

 Parameter[3]: A pointer to constant Ustr UTF-8 string data, containing spanning data
 Type[3]: const struct Ustr *

 Explanation:

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

 Note:

  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.


Function: ustr_utf8_cspn_cstr_fwd()
 Returns: Number of UTF-8 characters not in the span
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr UTF-8 string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string, in UTF-8 characters, to start compliment spanning from
 Type[2]: size_t

 Parameter[3]: A pointer to constant C-style UTF-8 string data, containing spanning data
 Type[3]: const char *

 Explanation:

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

 Note:

  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.


Function: ustr_utf8_cspn_cstr_rev()
 Returns: Number of UTF-8 characters not in the span
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr UTF-8 string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string, in UTF-8 characters, to start compliment spanning from
 Type[2]: size_t

 Parameter[3]: A pointer to C-style UTF-8 string data, containing spanning data
 Type[3]: const char *

 Explanation:

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

 Note:

  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.


Section: Doing IO from or to a Ustr
Function: ustr_io_get()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: A pointer to a C file object
 Type[2]: FILE *

 Parameter[3]: Number of bytes to read
 Type[3]: size_t

 Parameter[4]: Returned number of bytes read
 Type[4]: size_t *

 Explanation:

  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.


Function: ustr_io_getfile()
 Returns: Success or failure
 Type: int 

 Parameter[1]: Pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: A pointer to a C file object
 Type[2]: FILE *

 Explanation:

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

 Note:

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


Function: ustr_io_getfilename()
 Returns: Success or failure
 Type: int 

 Parameter[1]: Pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: A C-style string of a filename
 Type[2]: const char *

 Explanation:

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


Function: ustr_io_getdelim()
 Returns: Success or failure
 Type: int 

 Parameter[1]: Pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: A pointer to a C file object
 Type[2]: FILE *

 Parameter[3]: A delimiter byte to stop reading at
 Type[3]: char

 Explanation:

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

 Note:

  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.


Function: ustr_io_getline()
 Returns: Success or failure
 Type: int 

 Parameter[1]: Pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: A pointer to a C file object
 Type[2]: FILE *

 Explanation:

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


Function: ustr_io_put()
 Returns: Success or failure
 Type: int

 Parameter[1]: Pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: A pointer to a C file object
 Type[2]: FILE *

 Parameter[3]: Number of bytes to write
 Type[3]: size_t

 Explanation:

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

 Note:

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


Function: ustr_io_putline()
 Returns: Success or failure
 Type: int 

 Parameter[1]: Pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: A pointer to a C file object
 Type[2]: FILE *

 Parameter[3]: Number of bytes to write
 Type[3]: size_t

 Explanation:

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

 Note:

  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.


Function: ustr_io_putfile()
 Returns: Success or failure
 Type: int 

 Parameter[1]: Pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: A pointer to a C file object
 Type[2]: FILE *

 Explanation:

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


Function: ustr_io_putfileline()
 Returns: Success or failure
 Type: int 

 Parameter[1]: Pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: A pointer to a C file object
 Type[2]: FILE *

 Explanation:

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


Function: ustr_io_putfilename()
 Returns: Success or failure
 Type: int 

 Parameter[1]: Pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: A C-style string of a filename
 Type[2]: const char *

 Parameter[3]: A C-style string of a filemode (the second argument to fopen)
 Type[3]: const char *

 Explanation:

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

 Note:

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


Section: String substitution/replacement
Function: ustr_sub_buf()
 Returns: success or failure 
 Type: int 

 Parameter[1]: Pointer to a pointer to a Ustr
 Type[1]: struct Ustr **

 Parameter[2]: Position where to start substitution
 Type[2]: size_t

 Parameter[3]: Buffer containing substitution string 
 Type[3]: const void *

 Parameter[4]: Length of buffer
 Type[4]: size_t

 Explanation:

  This function will substitute the characters in the Ustr starting at the
 specified position using data from the buffer.

 Note:

  The Ustr will be automatically be resized to be big enough, if necessary.


Function: ustr_sub_cstr()
 Returns: success or failure 
 Type: int 

 Parameter[1]: Pointer to a pointer to a Ustr
 Type[1]: struct Ustr **

 Parameter[2]: Position where to start substitution
 Type[2]: size_t

 Parameter[3]: A pointer to a constant C-style string, which is the substitution
 Type[3]: const char *

 Explanation:

  This function works like ustr_sub_buf() but the length is worked out
 automatically by strlen().


Function: USTR_SUB_OSTR()
 Returns: Success or failure
 Type: int 

 Parameter[1]: Pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: Position where to start substitution
 Type[2]: size_t

 Parameter[3]: A constant C-style string
 Type[3]: const char []

 Explanation:

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


Function: USTR_SUB_OBJ()
 Returns: Success or failure
 Type: int 

 Parameter[1]: Pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: Position where to start substitution
 Type[2]: size_t

 Parameter[3]: A symbol
 Type[3]: ...

 Explanation:

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

 Note:

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


Function: ustr_sub()
 Returns: Success or failure
 Type: int 

 Parameter[1]: Pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: Position where to start substitution
 Type[2]: size_t

 Parameter[3]: A pointer to a constant Ustr string
 Type[3]: const struct Ustr *

 Explanation:

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


Function: ustr_sc_sub()
 Returns: success or failure 
 Type: int 

 Parameter[1]: Pointer to a pointer to a Ustr
 Type[1]: struct Ustr **

 Parameter[2]: Position where to start substitution
 Type[2]: size_t

 Parameter[3]: Length of substitution
 Type[3]: size_t

 Parameter[4]: Pointer to a Ustr containing the substitute string
 Type[4]: const struct Ustr *

 Explanation:

  Substitutes a specified number of characters starting at the given position
 with the characters from the given Ustr. 


Function: ustr_sc_sub_buf()
 Returns: Success or failure 
 Type: int 

 Parameter[1]: Pointer to a pointer to a Ustr
 Type[1]: struct Ustr **

 Parameter[2]: Position where to start substitution
 Type[2]: size_t 

 Parameter[3]: Length of substitute
 Type[3]: size_t 

 Parameter[4]: Buffer containting substitute data
 Type[4]: const void *

 Parameter[5]: Length of Buffer
 Type[5]: size_t 

 Explanation:

  This function will replace a specific number of characters in a Ustr with
 the data from a buffer, this function does the job of one or more of
 ustr_add_buf(), ustr_sub_buf() and ustr_del().


Function: ustr_sc_sub_cstr()
 Returns: Success or failure 
 Type: int 

 Parameter[1]: Pointer to a pointer to a Ustr
 Type[1]: struct Ustr **

 Parameter[2]: Position where to start replacement 
 Type[2]: size_t

 Parameter[3]: Length of replacement
 Type[3]: size_t

 Parameter[4]: A pointer to a constant C-style string, containing spanning bytes
 Type[4]: const char *

 Explanation:

  This function works like ustr_sc_sub_buf() but the length is worked out
 automatically by strlen().


Function: ustr_replace_buf()
 Returns: Number of tokens replaced 
 Type: size_t 

 Parameter[1]: Pointer to a pointer to a Ustr (haystack)
 Type[1]: struct Ustr **

 Parameter[2]: Buffer containting search data
 Type[2]: const void *

 Parameter[3]: Length of search buffer
 Type[3]: size_t

 Parameter[4]: Buffer containting replacement data
 Type[4]: const void *

 Parameter[5]: Length of replacement buffer
 Type[5]: size_t

 Parameter[6]: Maximum number of matches to replace (0 for unlimited)
 Type[6]: size_t

 Explanation:

  This function scans the "haystack" (Parameter[1]) for "needle" (Parameter[2])
 and replaces max_replacements (Parameter[6]) matches with the
 "replacement" (Parameter[4]).

 Note: 

  If max_replacements (Parameter[6]) is 0, this function will replace ALL
 occurrences.


Function: ustr_replace_cstr()
 Returns: Number of tokens replaced 
 Type: size_t 

 Parameter[1]: Pointer to a pointer to a Ustr (haystack)
 Type[1]: struct Ustr **

 Parameter[2]: A pointer to a constant C-style string, containing search bytes
 Type[2]: const char *

 Parameter[3]: A pointer to a constant C-style string, containing replacement bytes
 Type[3]: const char *

 Parameter[4]: Maximum number of matches to replace (0 for unlimited)
 Type[4]: size_t

 Explanation:

  This function works like ustr_replace_buf() but gets the lengths for the
 buffer automatically from strlen().


Function: ustr_replace()
 Returns: Number of tokens replaced 
 Type: int 

 Parameter[1]: Pointer to a pointer to a Ustr (haystack)
 Type[1]: struct Ustr **

 Parameter[2]: Ustr to search for (needle)
 Type[2]: const struct Ustr *

 Parameter[3]: Ustr to replace needle with
 Type[3]: const struct Ustr *

 Parameter[4]: Maximum number of matches to replace (0 for unlimited)
 Type[4]: size_t

 Explanation:

  This function works like ustr_replace_buf() but gets the lengths from the
 ustr automatically.


Function: ustr_replace_rep_chr()
 Returns: number of replacements made
 Type: size_t

 Parameter[1]: pointer to a pointer to a Ustr to be modified
 Type[1]: struct Ustr **ps1

 Parameter[2]: character to replace
 Type[2]: char

 Parameter[3]: number of characters to replace
 Type[3]: size_t

 Parameter[4]: character to replace with
 Type[4]: char

 Parameter[5]: number of characters to replace with
 Type[5]: size_t nlen

 Parameter[6]: maximum number of replacements to make (use 0 for unlimited)
 Type[6]: size_t lim

 Explanation:

  This function replaces a repeating sequence of characters with another
 repeating sequence of characters. 

  For example...

  Ustr *data = ustr_dup_cstr("xxxBxxCxDxxx");
  ustr_replace_rep_chr(&data,'x',2,'y',1, 0)

 ...would change data to be "yxByCxDyx".


 Note:

  Changing the same letter the same number of times is considered a No-op
 since it is a vast performance improvement this way. So passing in 
 (&data,'y',2,'y',2 ,0) will have a return value of 0 and the string will be
 unchanged.


Section: Splitting a Ustr
Function: ustr_split_buf()
 Returns: pointer to a Ustr representing the next token
 Type: struct Ustr *

 Parameter[1]: Pointer to a constant Ustr to be split
 Type[1]: const struct Ustr *

 Parameter[2]: Pointer to an offset
 Type[2]: size_t *

 Parameter[3]: Buffer to use as split search pattern 
 Type[3]: const void *

 Parameter[4]: Length of buffer
 Type[4]: size_t

 Parameter[5]: Pointer to a Ustr to be used as the return value
 Type[5]: struct Ustr *

 Parameter[6]: Flags with the prefix USTR_FLAG_SPLIT_
 Type[6]: unsigned int

 Explanation:

  This function works in a manner similar to strtok(). Each time the function
 is called, the string inside of the buffer (Parameter[3]) is used as a search
 pattern at which to split. If the pattern is not found, the entire string
 will be returned. A USTR_NULL return value indicates there are no more
 tokens remaining.
  Parameter[5] is a a pointer to a Ustr where the return value will be placed.
 Passing a USTR_NULL to this parameter will cause the string to be allocated
 and **MUST** be freed **manually**. If, however, you pass in a non-null Ustr to
 this parameter, each call to ustr_split_buf() will free what is in this
 pointer and place the new token there (when USTR_NULL is returned, nothing
 needs to be free'd).
  For example, given...

  Ustr *data = ...;
  Ustr *tok = USTR_NULL;
  const char *sep = ",";
  size_t off = 0;
  unsigned int flags = USTR_FLAGS_SPLIT_DEF;

 ...there are two options...

  while ((tok = ustr_split_buf(data, &off, sep, strlen(sep), tok, flags)))
  {
    /* Do something with tok -- but next iteration of the loop will free
     * and overwrite tok, so you must ustr_dup() if you want to keep it */
  }
  /* tok is now NULL again after the loop */

 ...or...

  while ((tok = ustr_split_buf(data, &off, sep, strlen(sep), USTR_NULL, flags)))
  {
    /* Do something with tok, and it will NOT be freed in the next iteration of
     * the loop */
      ustr_free(tok); /* have to free to avoid mem leaks */
  }

 ...the former of which being the safer option.

 Note:

  There are several flags that will alter the behaviour of this function,
 all of which have a common with the default being USTR_FLAG_SPLIT_DEF.
  If you are calling this function directly, it is very likely that you'd want
 to use ustr_split_cstr() instead.


Function: ustr_split()
 Returns: Pointer to a Ustr representing the next token
 Type: struct Ustr *

 Parameter[1]: Pointer to a constant Ustr to be split
 Type[1]: const struct Ustr *

 Parameter[2]: Pointer to an offset variable
 Type[2]: size_t *

 Parameter[3]: Pointer to a constant Ustr to use as the split search pattern
 Type[3]: const struct Ustr *

 Parameter[4]: Pointer to a Ustr where the return value will be placed
 Type[4]: struct Ustr *

 Parameter[5]: Flags
 Type[5]: unsigned int

 Explanation:

   Works like ustr_split_buf() but takes a Ustr as the split search pattern
  instead.


Function: ustr_split_cstr()
 Returns: Pointer to a Ustr representing the next token
 Type: struct Ustr *

 Parameter[1]: Pointer to a constant Ustr to be split
 Type[1]: const struct Ustr *

 Parameter[2]: Pointer to an offset variable
 Type[2]: size_t *

 Parameter[3]: C string to use as split search pattern
 Type[3]: const char *

 Parameter[4]: Pointer to a Ustr where the return value will be placed
 Type[4]: struct Ustr *

 Parameter[5]: Flags
 Type[5]: unsigned int

 Explanation:

  Works like ustr_split_buf() but takes a C string as the split search
 pattern, and so gets the length via. strlen().


Function: ustr_split_spn_chrs()
 Returns: Pointer to a Ustr representing the next token
 Type: struct Ustr *

 Parameter[1]: Pointer to a Ustr to be split
 Type[1]: const struct Ustr *

 Parameter[2]: Pointer to an offset variable
 Type[2]: size_t *

 Parameter[3]: String representing a set of bytes to use as split chars
 Type[3]: const char *

 Parameter[4]: Length of the string of set of bytes
 Type[4]: size_t

 Parameter[5]: Pointer to a Ustr where the return value will be placed
 Type[5]: struct Ustr *

 Parameter[6]: flags
 Type[6]: unsigned int

 Explanation:

  Works like ustr_split_buf() but uses the individual ASCII bytes in the
 separator string (Parameter[3]) as search patterns. It will split if **ANY** of
 these individual characters are matched (much like strtok()). For example:
 if splitting "this, is,a test" with the separator string ", " the tokens
 returned would be {"this" "is" "a" "test"};

 Note:

  If you are calling this function directly, it is very likely that you'd want
 to use ustr_split_spn_cstr() instead.


Function: ustr_split_spn_cstr()
 Returns: Pointer to a Ustr representing the next token
 Type: struct Ustr *

 Parameter[1]: Pointer to a Ustr to be split
 Type[1]: const struct Ustr *

 Parameter[2]: Pointer to an offset variable
 Type[2]: size_t *

 Parameter[3]: String representing a set of bytes to use as split chars
 Type[3]: const char *

 Parameter[4]: Pointer to a Ustr where the return value will be placed
 Type[4]: struct Ustr *

 Parameter[5]: flags
 Type[5]: unsigned int

 Explanation:

  Works like ustr_split_spn_chrs() but gets the length automatically via.
 strlen().


Function: ustr_split_spn()
 Returns: Pointer to a Ustr representing the next token
 Type: struct Ustr *

 Parameter[1]: Pointer to a constant Ustr to be split
 Type[1]: const struct Ustr *

 Parameter[2]: Pointer to an offset variable
 Type[2]: size_t *

 Parameter[3]: Pointer to a constant Ustr to use as the split search pattern
 Type[3]: const struct Ustr *

 Parameter[4]: Pointer to a Ustr where the return value will be placed
 Type[4]: struct Ustr *

 Parameter[5]: Flags
 Type[5]: unsigned int

 Explanation:

  Works like ustr_split_spn_chrs() but takes a Ustr as the split chars instead.


Section: Dealing with UTF-8 in a Ustr
Function: ustr_utf8_valid()
 Returns: A boolean flag of either USTR_TRUE or USTR_FALSE
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Explanation:

  This function tries it's best to find out if the string is a valid utf-8
 string.


Function: ustr_utf8_len()
 Returns: The number of the utf-8 characters in the Ustr
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Explanation:

  This function counts the number of utf-8 characters inn the Ustr.

 Note:

  This function gives undefined answers on strings that aren't utf-8 valid.


Function: ustr_utf8_width()
 Returns: ssize_t 
 Type: ssize_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Explanation:

  This function returns the visible width of the string, assuming it is a valid
 utf-8 string. This is like converting to wide characters and using wcwidth().


Function: ustr_utf8_chars2bytes()
 Returns: Length of span in bytes 
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Position of a span in utf-8 characters
 Type[2]: size_t

 Parameter[3]: Length of a span in utf-8 characters
 Type[3]: size_t

 Parameter[4]: Returns the position of the span in bytes
 Type[4]: size_t *

 Explanation:

  This function converts a span, in utf-8 characters, to the same span in bytes.


Function: ustr_utf8_bytes2chars()
 Returns: Returns the position of a span in utf-8 characters
 Type: size_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Position of a span in bytes
 Type[2]: size_t

 Parameter[3]: Length of a span in bytes
 Type[3]: size_t

 Parameter[4]: Returns length of a span in utf-8 characters
 Type[4]: size_t *

 Explanation:

  This function converts a span, in bytes, to the same span in utf-8 characters.

 Note:

  Because a byte span can start or end within a utf-8 character, converting the
 return values back into bytes via. ustr_utf8_chars2bytes() may make the span
 be slightly bigger (position slightly earlier, and the length slightly longer).


Function: ustr_sc_utf8_reverse()
 Returns: Success or failure
 Type: int

 Parameter[1]: A pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Explanation:

  This function reverses the utf-8 characters in the Ustr string, assuming it
 is a valid utf-8 string, so the last one becomes the first and the second to
 last becomes the second etc.


Section: Parsing ASCII integer numbers from a Ustr
Function: ustr_parse_uintmaxx()
 Returns: Parsed number, or zero on error
 Type: uintmax_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string to start parsing at
 Type[2]: size_t

 Parameter[3]: Base (2-36) and flags, starting with USTR_FLAG_PARSE_NUM_
 Type[3]: unsigned int

 Parameter[4]: Absolute minimum value
 Type[4]: uintmax_t

 Parameter[5]: Absolute maximum value
 Type[5]: uintmax_t

 Parameter[6]: Thousands seperator
 Type[6]: const char *

 Parameter[7]: Return length of parsed number
 Type[7]: size_t *

 Parameter[8]: Return error code, starting with USTR_TYPE_PARSE_NUM_ERR_
 Type[8]: unsigned int *

 Explanation:

  This function parses an ASCII representation of a number from a
 Ustr (Parameter[1]) starting at the offset (Parameter[2]).

 Note:

  If stdint.h isn't available this function won't be available.


Function: ustr_parse_uintmax()
 Returns: Parsed number, or zero on error
 Type: uintmax_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string to start parsing at
 Type[2]: size_t

 Parameter[3]: Base (2-36) and flags, starting with USTR_FLAG_PARSE_NUM_
 Type[3]: unsigned int

 Parameter[4]: Return length of parsed number
 Type[4]: size_t *

 Parameter[5]: Return error code, starting with USTR_TYPE_PARSE_NUM_ERR_
 Type[5]: unsigned int *

 Explanation:

  This function works like ustr_parse_uintmaxx() with the minimum and maximum
 values taken as 0 and UINTMAX_MAX, and the thousands seperator as "_".

 Note:

  If stdint.h isn't available this function won't be available.


Function: ustr_parse_intmax()
 Returns: Parsed number, or zero on error
 Type: intmax_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string to start parsing at
 Type[2]: size_t

 Parameter[3]: Base (2-36) and flags, starting with USTR_FLAG_PARSE_NUM_
 Type[3]: unsigned int

 Parameter[4]: Return length of parsed number
 Type[4]: size_t *

 Parameter[5]: Return error code, starting with USTR_TYPE_PARSE_NUM_ERR_
 Type[5]: unsigned int *

 Explanation:

  This function works like ustr_parse_uintmaxx() with the minimum and maximum
 values taken as -INTMAX_MIN and INTMAX_MAX, and the thousands seperator as "_".

 Note:

  If stdint.h isn't available this function won't be available.


Function: ustr_parse_ulongx()
 Returns: Parsed number, or zero on error
 Type: unsigned long 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string to start parsing at
 Type[2]:  size_t

 Parameter[3]: Base (2-36) and flags, starting with USTR_FLAG_PARSE_NUM_
 Type[3]:  unsigned int

 Parameter[4]: Absolute minimum value
 Type[4]:  unsigned long

 Parameter[5]: Absolute maximum value
 Type[5]:  unsigned long

 Parameter[6]: Thousands seperator
 Type[6]: const char *

 Parameter[7]: Return length of parsed number
 Type[7]:  size_t *

 Parameter[8]: Return error code, starting with USTR_TYPE_PARSE_NUM_ERR_
 Type[8]: unsigned int *

 Explanation:

  This function works like ustr_parse_uintmaxx() but returns an unsigned long,
 it is always available even when stdint.h isn't.


Function: ustr_parse_ulong()
 Returns: Parsed number, or zero on error
 Type: unsigned long 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string to start parsing at
 Type[2]: size_t

 Parameter[3]: Base (2-36) and flags, starting with USTR_FLAG_PARSE_NUM_
 Type[3]: unsigned int

 Parameter[4]: Return length of parsed number
 Type[4]: size_t *

 Parameter[5]: Return error code, starting with USTR_TYPE_PARSE_NUM_ERR_
 Type[5]: unsigned int *

 Explanation:

  This function works like ustr_parse_ulongx() with the minimum and maximum
 values taken as 0 and ULONG_MAX, and the thousands seperator as "_".


Function: ustr_parse_long()
 Returns: Parsed number, or zero on error
 Type: long 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string to start parsing at
 Type[2]: size_t

 Parameter[3]: Base (2-36) and flags, starting with USTR_FLAG_PARSE_NUM_
 Type[3]: unsigned int

 Parameter[4]: Return length of parsed number
 Type[4]: size_t *

 Parameter[5]: Return error code, starting with USTR_TYPE_PARSE_NUM_ERR_
 Type[5]: unsigned int *

 Explanation:

  This function works like ustr_parse_ulongx() with the minimum and maximum
 values taken as -LONG_MIN and LONG_MAX, and the thousands seperator as "_".


Function: ustr_parse_uint()
 Returns: Parsed number, or zero on error
 Type: unsigned int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string to start parsing at
 Type[2]: size_t

 Parameter[3]: Base (2-36) and flags, starting with USTR_FLAG_PARSE_NUM_
 Type[3]: unsigned int

 Parameter[4]: Return length of parsed number
 Type[4]: size_t *

 Parameter[5]: Return error code, starting with USTR_TYPE_PARSE_NUM_ERR_
 Type[5]: unsigned int *

 Explanation:

  This function works like ustr_parse_ulongx() with the minimum and maximum
 values taken as 0 and UINT_MAX, and the thousands seperator as "_".


Function: ustr_parse_int()
 Returns: Parsed number, or zero on error
 Type: int 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string to start parsing at
 Type[2]: size_t

 Parameter[3]: Base (2-36) and flags, starting with USTR_FLAG_PARSE_NUM_
 Type[3]: unsigned int

 Parameter[4]: Return length of parsed number
 Type[4]: size_t *

 Parameter[5]: Return error code, starting with USTR_TYPE_PARSE_NUM_ERR_
 Type[5]: unsigned int *

 Explanation:

  This function works like ustr_parse_ulongx() with the minimum and maximum
 values taken as -INT_MIN and INT_MAX, and the thousands seperator as "_".


Function: ustr_parse_ushort()
 Returns: Parsed number, or zero on error
 Type: unsigned short 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string to start parsing at
 Type[2]: size_t

 Parameter[3]: Base (2-36) and flags, starting with USTR_FLAG_PARSE_NUM_
 Type[3]: unsigned int

 Parameter[4]: Return length of parsed number
 Type[4]: size_t *

 Parameter[5]: Return error code, starting with USTR_TYPE_PARSE_NUM_ERR_
 Type[5]: unsigned int *

 Explanation:

  This function works like ustr_parse_ulongx() with the minimum and maximum
 values taken as 0 and USHRT_MAX, and the thousands seperator as "_".


Function: ustr_parse_short()
 Returns: Parsed number, or zero on error
 Type: short 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string to start parsing at
 Type[2]: size_t

 Parameter[3]: Base (2-36) and flags, starting with USTR_FLAG_PARSE_NUM_
 Type[3]: unsigned int

 Parameter[4]: Return length of parsed number
 Type[4]: size_t *

 Parameter[5]: Return error code, starting with USTR_TYPE_PARSE_NUM_ERR_
 Type[5]: unsigned int *

 Explanation:

  This function works like ustr_parse_ulongx() with the minimum and maximum
 values taken as -SHRT_MIN and SHRT_MAX, and the thousands seperator as "_".


Section: Misc shortcut helper functions for Ustrs
Function: ustr_sc_ensure_owner()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Explanation:

  This function makes sure that the Ustr string is owned when it returns (Ie.
 ustr_owner() returns USTR_TRUE), or it fails to allocate.


Function: ustr_sc_wstr()
 Returns: Writable pointer to the start of data in the Ustr, or NULL
 Type: char *

 Parameter[1]: A pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Explanation:

  This function works like calling ustr_sc_ensure_owner(), to make sure the
 Ustr string is writable, and if that succeeds it returns ustr_wstr(). On
 failure it returns NULL.


Function: ustr_sc_export_subustr()
 Returns: A pointer to newly allocated block of memory
 Type: char *

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Position in the Ustr
 Type[2]: size_t

 Parameter[3]: Length to export from the Ustr
 Type[3]: size_t

 Parameter[4]: Allocation function (like malloc)
 Type[4]: void *(*)(size_t)

 Explanation:

  This function allocates a block of memory of size Length (Parameter[3]) + 1 
 using the provided allocation function (Parameter[4]) and copies the data
 starting from Position (Parameter[2]) within the ustr.


Function: ustr_sc_export()
 Returns: A pointer to newly allocated block of memory
 Type: char *

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Allocation function (like malloc)
 Type[2]: void *(*)(size_t)

 Explanation:

  This function works like calling ustr_sc_export_subustr() with a position of
 1 and a length of ustr_len().


Function: ustrp_sc_export_subustrp()
 Returns: A pointer to newly allocated block of memory
 Type: char *

 Parameter[1]: Pointer to a Ustr pool object
 Type[1]: struct Ustr_pool *

 Parameter[2]: A pointer to a constant Ustr string
 Type[2]: const struct Ustr *

 Parameter[3]: Position in the Ustr
 Type[3]: size_t

 Parameter[4]: Length to export from the Ustr
 Type[4]: size_t

 Parameter[5]: Allocation function (like malloc), or NULL
 Type[5]: void *(*)(size_t)

 Explanation:

  This function allocates a block of memory of size Length (Parameter[4]) + 1 
 using either the provided allocation function (Parameter[5]), or from the pool
 object if the allocation function is NUL, and copies the data starting from
 Position (Parameter[3]) within the ustr.


Function: ustrp_sc_export()
 Returns: A pointer to newly allocated block of memory
 Type: char *

 Parameter[1]: Pointer to a Ustr pool object
 Type[1]: struct Ustr_pool *

 Parameter[2]: A pointer to a constant Ustr string
 Type[2]: const struct Ustr *

 Parameter[3]: Allocation function (like malloc)
 Type[3]: void *(*)(size_t)

 Explanation:

  This function works like calling ustrp_sc_export_subustrp() with a position of
 1 and a length of ustrp_len().


Function: ustr_sc_reverse()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Explanation:

  This function reverses all the bytes in the Ustr string, so the last one
 becomes the first and the second to last becomes the second etc.


Function: ustr_sc_tolower()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Explanation:

  This function changes any ASCII upper case bytes into ASCII lower case bytes.


Function: ustr_sc_toupper()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Explanation:

  This function changes any ASCII lower case bytes into ASCII upper case bytes.


Function: ustr_sc_ltrim_chrs()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: Array of bytes, containing trimming data
 Type[2]: const char *

 Parameter[3]: Length of byte data
 Type[3]: size_t

 Explanation:

  This function deletes the bytes at the begining of the Ustr (Parameter[1])
 that are in the span (Parameter[2]) of the specificed length (parameter[2]).


Function: ustr_sc_ltrim()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: A pointer to a constant Ustr string, containing trimming bytes
 Type[2]: const struct Ustr *

 Explanation:

  This function works as if you had called ustr_sc_ltrim_chrs() and passed
 ustr_cstr() and ustr_len() values of the Ustr string (Parameter[2]).


Function: ustr_sc_ltrim_cstr()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: A pointer to a constant C-style string, containing trimming bytes
 Type[2]: const char *

 Explanation:

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


Function: ustr_sc_rtrim_chrs()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: Array of bytes, containing trimming data
 Type[2]: const char *

 Parameter[3]: Length of byte data
 Type[3]: size_t

 Explanation:

  This function deletes the bytes at the end of the Ustr (Parameter[1])
 that are in the span (Parameter[2]) of the specificed length (parameter[2]).


Function: ustr_sc_rtrim()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: A pointer to a constant Ustr string, containing trimming bytes
 Type[2]: const struct Ustr *

 Explanation:

  This function works as if you had called ustr_sc_rtrim_chrs() and passed
 ustr_cstr() and ustr_len() values of the Ustr string (Parameter[2]).


Function: ustr_sc_rtrim_cstr()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: A pointer to a constant C-style string, containing trimming bytes
 Type[2]: const char *

 Explanation:

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


Function: ustr_sc_trim_chrs()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: Array of bytes, containing trimming data
 Type[2]: const char *

 Parameter[3]: Length of byte data
 Type[3]: size_t

 Explanation:

  This function deletes the bytes at the begining or end of the
 Ustr (Parameter[1]) that are in the span (Parameter[2]) of the specificed
 length (parameter[2]).

 Note:

  Calling this function is much more efficient than calling ustr_sc_rtrim_chrs()
 and then ustr_sc_ltrim_chrs(), as both ends are trimmed in a single pass.


Function: ustr_sc_trim()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: A pointer to a constant Ustr string, containing trimming bytes
 Type[2]: const struct Ustr *

 Explanation:

  This function works as if you had called ustr_sc_trim_chrs() and passed
 ustr_cstr() and ustr_len() values of the Ustr string (Parameter[2]).


Function: ustr_sc_trim_cstr()
 Returns: Success or failure
 Type: int 

 Parameter[1]: A pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: A pointer to a constant C-style string, containing trimming bytes
 Type[2]: const char *

 Explanation:

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


Section: Adding binary data to a Ustr
Function: ustr_add_b_uint16()
 Returns: Success or failure
 Type: int 

 Parameter[1]: Pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: Binary value to add to the Ustr
 Type[2]: uint_least16_t

 Explanation:

  This function adds a binary representation of a value (Parameter[2]) to the
 Ustr (Parameter[1]).


Function: ustr_add_b_uint32()
 Returns: Success or failure
 Type: int 

 Parameter[1]: Pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: Binary value to add to the Ustr
 Type[2]: uint_least32_t

 Explanation:

  This function adds a binary representation of a value (Parameter[2]) to the
 Ustr (Parameter[1]).


Function: ustr_add_b_uint64()
 Returns: Success or failure
 Type: int 

 Parameter[1]: Pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: Binary value to add to the Ustr
 Type[2]: uint_least64_t

 Explanation:

  This function adds a binary representation of a value (Parameter[2]) to the
 Ustr (Parameter[1]).


Section: Parsing binary data from a Ustr
Function: ustr_parse_b_uint16()
 Returns: uint_least16_t 
 Type: uint_least16_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string to start parsing at
 Type[2]: size_t

 Explanation:

  This function parses a binary representation from a Ustr (Parameter[1]) 
 starting at the offset (Parameter[2]).


Function: ustr_parse_b_uint32()
 Returns: uint_least32_t 
 Type: uint_least32_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string to start parsing at
 Type[2]: size_t

 Explanation:

  This function parses a binary representation from a Ustr (Parameter[1]) 
 starting at the offset (Parameter[2]).


Function: ustr_parse_b_uint64()
 Returns: uint_least64_t 
 Type: uint_least64_t 

 Parameter[1]: A pointer to a constant Ustr string
 Type[1]: const struct Ustr *

 Parameter[2]: Offset within string to start parsing at
 Type[2]: size_t

 Explanation:

  This function parses a binary representation from a Ustr (Parameter[1]) 
 starting at the offset (Parameter[2]).


Section: Misc. functions
Function: ustr_realloc()
 Returns: Success or failure
 Type: int

 Parameter[1]: Pointer to a pointer to a Ustr string
 Type[1]: struct Ustr **

 Parameter[2]: Size of allocation
 Type[2]: size_t

 Explanation:

  This function is re-sizes the Ustr to the specified size (Parameter[2]).
  This is mostly used to shrink a sized Ustr that is now significantly
 smaller than it once was. Although this function can also grow a Ustr.

 Note:

  To have a size that isn't implied from the length the Ustr must store a size
 value as well as a length (ustr_sized() must return USTR_TRUE).


Function: ustr_cntl_opt()
 Returns: Success or failure
 Type: int 

 Parameter[1]: Optional value starting with USTR_CNTL_OPT_
 Type[1]: int

 Parameter[2]: Arugments to option
 Type[2]: ...

 Explanation:

  This function views and/or changes global Ustr options, like whether ustr's
 have an implicit or explicit size (USTR_CNTL_OPT_GET_HAS_SIZE).


Section: Simple Ustr pool API
Function: ustr_pool_ll_make()
 Returns: Pointer to a Ustr pool object
 Type: struct Ustr_pool *

 Parameter[1]: Nothing
 Type[1]: void

 Explanation:

  This allocates a new pool using the "linked list" strategy, each allocation
 in the pool is added to a linked list ... and any allocations not freed
 directly are freed by the pool when it is cleared or freed.


Function: ustr_pool_make_subpool()
 Returns: Pointer to a Ustr pool object
 Type: struct Ustr_pool *

 Parameter[1]: struct Ustr_pool *
 Type[1]: struct Ustr_pool *

 Explanation:

  This allocates a new pool as a child of the passed in pool (Parameter[1]),
 The pool can be freed and cleared independantly of the parent pool however
 free and clear operations on the parent pool are automatically applied to all
 child pools.


Function: ustr_pool_free()
 Returns: Nothing
 Type: void

 Parameter[1]: Pointer to a Ustr pool object
 Type[1]: struct Ustr_pool *

 Explanation:

  This deallocates a pool, and all sub-pools.

 Note:

  This also operates on all sub-pools.


Function: ustr_pool_clear()
 Returns: Nothing
 Type: void

 Parameter[1]: Pointer to a Ustr pool object
 Type[1]: struct Ustr_pool *

 Explanation:

  This allows all the data in the pool to be reused, it may also free some/all
 of the data in the pool, from the pool API.

 Note:

  This also operates on all sub-pools.

