Provided by: libustr-dev_1.0.4-6_amd64 bug

NAME

       ustr - ustr string library functions

SYNOPSIS

  #include "ustr.h"

  struct Ustr *USTR(void *);
  struct Ustrp *USTRP(void *);
  struct Ustr *USTR1(symbol, const char[]);
  struct Ustr *USTR2(symbol, symbol, const char[]);
  struct Ustr *USTR4(symbol, symbol, symbol, symbol, const char[]);
  struct Ustr *USTR1_CHK(symbol, const char[]);
  struct Ustr *USTR2_CHK(symbol, symbol, const char[]);
  struct Ustr *USTR4_CHK(symbol, symbol, symbol, symbol, const char[]);
  struct Ustr *USTRP1(symbol, const char[]);
  struct Ustr *USTRP2(symbol, symbol, const char[]);
  struct Ustrp *USTRP4(symbol, symbol, symbol, symbol, const char[]);
  struct Ustr *USTRP1_CHK(symbol, const char[]);
  struct Ustr *USTRP2_CHK(symbol, symbol, const char[]);
  struct Ustrp *USTRP4_CHK(symbol, symbol, symbol, symbol, const char[]);

  size_t USTR_SIZE_FIXED(size_t);
  struct Ustr *ustr_init_fixed(void *, size_t, int, size_t);
  struct Ustr *USTR_SC_INIT_AUTO(char[], int, size_t);
  struct Ustr *USTR_SC_INIT_AUTO_OSTR(char[], int, size_t);

  int ustr_assert_valid(Ustr *);
  int ustr_assert_valid_subustr(Ustr *, size_t,  size_t);
  int USTR_CNTL_MALLOC_CHECK_BEG(int);
  int USTR_CNTL_MALLOC_CHECK_LVL(void);
  int USTR_CNTL_MALLOC_CHECK_MEM(void *);
  int USTR_CNTL_MALLOC_CHECK_MEM_SZ(void *, size_t);
  int USTR_CNTL_MALLOC_CHECK_MEM_MINSZ(void *, size_t);
  int USTR_CNTL_MALLOC_CHECK_MEM_USTR(Ustr *);
  int USTR_CNTL_MALLOC_CHECK_MEM_USTRP(Ustrp *);
  int USTR_CNTL_MALLOC_CHECK_END(void);
  int USTR_CNTL_MALLOC_CHECK_ADD(int);
  int USTR_CNTL_MALLOC_CHECK_DEL(int);

  size_t  ustr_init_size(size_t, size_t, int, size_t);
  struct Ustr *ustr_init_alloc(void *, size_t, size_t, size_t, int, int, size_t);
  struct Ustr *ustr_dupx_empty(size_t, size_t, int, int);
  struct Ustr *ustr_dup_empty(void);
  struct Ustr *ustr_dupx_undef(size_t, size_t, int, int, size_t);
  struct Ustr *ustr_dup_undef(size_t);
  struct Ustr *ustr_dup(const struct Ustr *);
  struct Ustr *ustr_dupx(size_t, size_t, int, int, const struct Ustr *);
  struct Ustr *ustr_sc_dup(struct Ustr **);
  struct Ustr *ustr_sc_dupx(size_t, size_t, int, int, struct Ustr **);
  struct Ustr *ustr_dup_buf(const void *, size_t);
  struct Ustr *ustr_dupx_buf(size_t, size_t, int, int, const void *, size_t);
  struct Ustr *ustr_dup_cstr(const char *);
  struct Ustr *ustr_dupx_cstr(size_t, size_t, int, int, const char *);
  struct Ustr *USTR_DUP_OSTR(const char []);
  struct Ustr *USTR_DUP_OBJ(...);
  struct Ustr *ustr_dup_subustr(const struct Ustr *, size_t, size_t);
  struct Ustr *ustr_dupx_subustr(size_t, size_t, int, int, const struct Ustr *, size_t, size_t);
  struct Ustr *ustr_dup_rep_chr(char, size_t);
  struct Ustr *ustr_dupx_rep_chr(size_t, size_t, int, int, char, size_t);
  struct  Ustr  *ustr_sc_vjoin(const  struct  Ustr  *,  const struct Ustr *, const struct Ustr *,
                             va_list);
  struct Ustr *ustr_sc_join(const struct Ustr *, const struct Ustr *, const struct Ustr *, ...);
  struct Ustr *ustr_sc_vjoinx(size_t, size_t, int, int, const struct Ustr *, const struct Ustr *,
                              const struct Ustr *, va_list);
  struct  Ustr *ustr_sc_joinx(size_t, size_t, int, int, const struct Ustr *, const struct Ustr *,
                             const struct Ustr *, ...);
  struct Ustr *ustr_sc_vconcat(const struct Ustr *, va_list);
  struct Ustr *ustr_sc_concat(const struct Ustr *, ...);
  struct Ustr *ustr_sc_vconcatx(size_t, size_t, int, int, const struct Ustr *, va_list);
  struct Ustr *ustr_sc_concatx(size_t, size_t, int, int, const struct Ustr *, ...);

  void  ustr_free(struct Ustr *);
  void  ustrp_free(struct Ustr_pool *, struct Ustrp *);
  void  ustr_sc_free(struct Ustr **);
  void  ustr_sc_free2(struct Ustr **, struct Ustr *);
  void  ustr_sc_free_shared(struct Ustr **);
  int  ustr_del(struct Ustr **, size_t);
  int  ustr_del_subustr(struct Ustr **, size_t,  size_t);
  void  ustr_sc_del(struct Ustr **);

  int ustr_add_undef(struct Ustr **, size_t);
  int ustr_add_buf(struct Ustr **, const void *, size_t);
  int  ustr_add_cstr(struct Ustr **, const char *);
  int  USTR_ADD_OSTR(struct Ustr **, const char []);
  int  USTR_ADD_OBJ(struct Ustr **, ...);
  int  ustr_add(struct Ustr **, const struct Ustr *);
  int  ustr_add_subustr(struct Ustr **, const struct Ustr *, size_t, size_t);
  int  ustr_add_rep_chr(struct Ustr **, char, size_t);

  int  ustr_set_undef(struct Ustr **,  size_t);
  int ustr_set_empty(struct Ustr **);
  int ustr_set_buf(struct Ustr **,  const void *, size_t);
  int ustr_set_cstr(struct Ustr **, const char *);
  int USTR_SET_OSTR(struct Ustr **, const char []);
  int USTR_SET_OBJ(struct Ustr **, ...);
  int ustr_set(struct Ustr **, const struct Ustr *);
  int ustr_set_subustr(struct Ustr **, const struct Ustr *, size_t, size_t);
  int ustr_set_rep_chr(struct Ustr **, char, size_t);

  int ustr_ins_undef(struct Ustr **, size_t, size_t);
  int ustr_ins_buf(struct Ustr **, size_t, const void *, size_t);
  int  ustr_ins_cstr(struct Ustr **, size_t, const char *);
  int  USTR_INS_OSTR(struct Ustr **, size_t, const char []);
  int  USTR_INS_OBJ(struct Ustr **, size_t, ...);
  int  ustr_ins(struct Ustr **, size_t, const struct Ustr *);
  int  ustr_ins_subustr(struct Ustr **, size_t, const struct Ustr *, size_t, size_t);
  int  ustr_ins_rep_chr(struct Ustr **, size_t, char, size_t);

  int  ustr_add_vfmt_lim(struct Ustr **, size_t, const char *, va_list);
  int  ustr_add_vfmt(struct Ustr **, const char *, va_list);
  int  ustr_add_fmt_lim(struct Ustr **, size_t, const char *, ...);
  int  ustr_add_fmt(struct Ustr **, const char *, ...);
  struct Ustr *ustr_dup_vfmt_lim(size_t, const char *, va_list);
  struct Ustr *ustr_dup_vfmt(size_t, const char *, va_list);
  struct Ustr *ustr_dup_fmt_lim(size_t, const char *, ...);
  struct Ustr *ustr_dup_fmt(const char *, ...);
  struct Ustr *ustr_dupx_fmt_lim(size_t, size_t, int, int, size_t, const char *, ...);
  struct Ustr *ustr_dupx_fmt(size_t, size_t, int, int, const char *, ...);
  int  ustr_set_vfmt_lim(struct Ustr **, size_t, const char *, va_list);
  int  ustr_set_vfmt(struct Ustr **, const char *, va_list);
  int  ustr_set_fmt_lim(struct Ustr **, size_t, const char *, ...);
  int  ustr_set_fmt(struct Ustr **, const char *, ...);
  int  ustr_ins_vfmt_lim(struct Ustr **, size_t, size_t, const char *, va_list);
  int  ustr_ins_vfmt(struct Ustr **, size_t, const char *, va_list);
  int  ustr_ins_fmt_lim(struct Ustr **, size_t, size_t, const char *, ...);
  int  ustr_ins_fmt(struct Ustr **, size_t, const char *, ...);
  int  ustr_sub_vfmt_lim(struct Ustr **, size_t, size_t, const char *, va_list);
  int  ustr_sub_vfmt(struct Ustr **, size_t, const char *, va_list);
  int  ustr_sub_fmt_lim(struct Ustr **, size_t, size_t, const char *, ...);
  int  ustr_sub_fmt(struct Ustr **, size_t, const char *, ...);
  int  ustr_sc_sub_vfmt_lim(struct Ustr **, size_t, size_t, size_t, const char *, va_list);
  int  ustr_sc_sub_vfmt(struct Ustr **, size_t, size_t, const char *, va_list);
  int  ustr_sc_sub_fmt_lim(struct Ustr **, size_t, size_t, size_t, const char *, ...);
  int  ustr_sc_sub_fmt(struct Ustr **, size_t, size_t, const char *, ...);

  size_t  ustr_len(const struct Ustr *);
  const char *ustr_cstr(const struct Ustr *);
  char *ustr_wstr(struct Ustr *);
  int ustr_alloc(const struct Ustr *);
  int ustr_exact(const struct Ustr *);
  int  ustr_sized(const struct Ustr *);
  int ustr_ro(const struct Ustr *);
  int  ustr_fixed(const struct Ustr *);
  int  ustr_enomem(const struct Ustr *);
  int  ustr_shared(const struct Ustr *);
  int  ustr_limited(const struct Ustr *);
  int  ustr_owner(const struct Ustr *);
  size_t  ustr_size(const struct Ustr *);
  size_t  ustr_size_alloc(const struct Ustr *);
  size_t  ustr_size_overhead(const struct Ustr *);
  void  ustr_conf(const struct Ustr *, size_t *, size_t *, int *, size_t *, size_t *);

  int  ustr_setf_enomem_err(struct Ustr *);
  int  ustr_setf_enomem_clr(struct Ustr *);
  int  ustr_setf_share(struct Ustr *);
  int  ustr_setf_owner(struct Ustr *);

  int  ustr_cmp_buf(const struct Ustr *, const void *, size_t);
  int  ustr_cmp(const struct Ustr *, const struct Ustr *);
  int  ustr_cmp_subustr(const struct Ustr *, const struct Ustr *, size_t, size_t);
  int  ustr_cmp_cstr(const struct Ustr *, const char *);
  int  ustr_cmp_fast_buf(const struct Ustr *, const void *, size_t);
  int  ustr_cmp_fast(const struct Ustr *, const struct Ustr *);
  int  ustr_cmp_fast_subustr(const struct Ustr *, const struct Ustr *, size_t, size_t);
  int  ustr_cmp_fast_cstr(const struct Ustr *, const char *);
  int  ustr_cmp_case_buf(const struct Ustr *, const void *, size_t);
  int  ustr_cmp_case(const struct Ustr *, const struct Ustr *);
  int  ustr_cmp_case_subustr(const struct Ustr *, const struct Ustr *, size_t, size_t);
  int  ustr_cmp_case_cstr(const struct Ustr *, const char *);
  int  ustr_cmp_eq(const struct Ustr *, const struct Ustr *);
  int  ustr_cmp_buf_eq(const struct Ustr *, const void *, size_t);
  int  ustr_cmp_subustr_eq(const struct Ustr *, const struct Ustr *, size_t, size_t);
  int  ustr_cmp_cstr_eq(const struct Ustr *, const char *);
  int  ustr_cmp_case_eq(const struct Ustr *, const struct Ustr *);
  int  ustr_cmp_case_buf_eq(const struct Ustr *, const void *, size_t);
  int  ustr_cmp_case_subustr_eq(const struct Ustr *, const struct Ustr *, size_t, size_t);
  int  ustr_cmp_case_cstr_eq(const struct Ustr *, const char *);
  int  ustr_cmp_prefix_eq(const struct Ustr *, const struct Ustr *);
  int  ustr_cmp_prefix_buf_eq(const struct Ustr *, const void *, size_t);
  int  ustr_cmp_prefix_cstr_eq(const struct Ustr *, const char *);
  int  ustr_cmp_prefix_subustr_eq(const struct Ustr *, const struct Ustr *, size_t, size_t);
  int  ustr_cmp_case_prefix_eq(const struct Ustr *, const struct Ustr *);
  int  ustr_cmp_case_prefix_buf_eq(const struct Ustr *, const void *, size_t);
  int  ustr_cmp_case_prefix_cstr_eq(const struct Ustr *, const char *);
  int  ustr_cmp_case_prefix_subustr_eq(const struct Ustr *, const struct Ustr *, size_t, size_t);
  int  ustr_cmp_suffix_eq(const struct Ustr *, const struct Ustr *);
  int  ustr_cmp_suffix_buf_eq(const struct Ustr *, const void *, size_t);
  int  ustr_cmp_suffix_cstr_eq(const struct Ustr *, const char *);
  int  ustr_cmp_suffix_subustr_eq(const struct Ustr *, const struct Ustr *, size_t, size_t);
  int  ustr_cmp_case_suffix_eq(const struct Ustr *, const struct Ustr *);
  int  ustr_cmp_case_suffix_buf_eq(const struct Ustr *, const void *, size_t);
  int  ustr_cmp_case_suffix_cstr_eq(const struct Ustr *, const char *);
  int  ustr_cmp_case_suffix_subustr_eq(const struct Ustr *, const struct Ustr *, size_t, size_t);

  size_t  ustr_srch_chr_fwd(const struct Ustr *, size_t, char);
  size_t  ustr_srch_chr_rev(const struct Ustr *, size_t, char);
  size_t  ustr_srch_buf_fwd(const struct Ustr *, size_t, const void *, size_t);
  size_t  ustr_srch_buf_rev(const struct Ustr *, size_t, const void *, size_t);
  size_t  ustr_srch_fwd(const struct Ustr *, size_t, const struct Ustr *);
  size_t  ustr_srch_rev(const struct Ustr *, size_t, const struct Ustr *);
  size_t  ustr_srch_cstr_fwd(const struct Ustr *, size_t, const char *);
  size_t  ustr_srch_cstr_rev(const struct Ustr *, size_t, const char *);
  size_t  ustr_srch_subustr_fwd(const struct  Ustr  *,  size_t,  const  struct  Ustr  *,  size_t,
                                size_t);
  size_t   ustr_srch_subustr_rev(const  struct  Ustr  *,   size_t,  const  struct Ustr *, size_t,
                                size_t);
  size_t  ustr_srch_case_chr_fwd(const struct Ustr *, size_t, char);
  size_t  ustr_srch_case_chr_rev(const struct Ustr *, size_t, char);
  size_t  ustr_srch_case_buf_fwd(const struct Ustr *, size_t, const void *, size_t);
  size_t  ustr_srch_case_buf_rev(const struct Ustr *, size_t, const void *, size_t);
  size_t  ustr_srch_case_fwd(const struct Ustr *, size_t, const struct Ustr *);
  size_t  ustr_srch_case_rev(const struct Ustr *, size_t, const struct Ustr *);
  size_t  ustr_srch_case_cstr_fwd(const struct Ustr *, size_t, const char *);
  size_t  ustr_srch_case_cstr_rev(const struct Ustr *, size_t, const char *);
  size_t  ustr_srch_case_subustr_fwd(const struct Ustr *, size_t, const struct  Ustr  *,  size_t,
                                     size_t);
  size_t   ustr_srch_case_subustr_rev(const  struct Ustr *,  size_t, const struct Ustr *, size_t,
                                     size_t);

  size_t  ustr_spn_chr_fwd(const struct Ustr *, size_t, char);
  size_t  ustr_spn_chr_rev(const struct Ustr *, size_t, char);
  size_t  ustr_spn_chrs_fwd(const struct Ustr *, size_t, const char *, size_t);
  size_t  ustr_spn_chrs_rev(const struct Ustr *, size_t, const char *, size_t);
  size_t  ustr_spn_fwd(const struct Ustr *, size_t, const struct Ustr *);
  size_t  ustr_spn_rev(const struct Ustr *, size_t, const struct Ustr *);
  size_t  ustr_spn_cstr_fwd(const struct Ustr *, size_t, const char *);
  size_t  ustr_spn_cstr_rev(const struct Ustr *, size_t, const char *);
  size_t  ustr_cspn_chr_fwd(const struct Ustr *, size_t, char);
  size_t  ustr_cspn_chr_rev(const struct Ustr *, size_t, char);
  size_t  ustr_cspn_chrs_fwd(const struct Ustr *, size_t, const char *, size_t);
  size_t  ustr_cspn_chrs_rev(const struct Ustr *, size_t, const char *, size_t);
  size_t  ustr_cspn_fwd(const struct Ustr *, size_t, const struct Ustr *);
  size_t  ustr_cspn_rev(const struct Ustr *, size_t, const struct Ustr *);
  size_t  ustr_cspn_cstr_fwd(const struct Ustr *, size_t, const char *);
  size_t  ustr_cspn_cstr_rev(const struct Ustr *, size_t, const char *);
  size_t  ustr_utf8_spn_chrs_fwd(const struct Ustr *, size_t, const char *, size_t);
  size_t  ustr_utf8_spn_chrs_rev(const struct Ustr *, size_t, const char *, size_t);
  size_t  ustr_utf8_spn_fwd(const struct Ustr *, size_t, const struct Ustr *);
  size_t  ustr_utf8_spn_rev(const struct Ustr *, size_t, const struct Ustr *);
  size_t  ustr_utf8_spn_cstr_fwd(const struct Ustr *, size_t, const char *);
  size_t  ustr_utf8_spn_cstr_rev(const struct Ustr *, size_t, const char *);
  size_t  ustr_utf8_cspn_chrs_fwd(const struct Ustr *, size_t, const char *, size_t);
  size_t  ustr_utf8_cspn_chrs_rev(const struct Ustr *, size_t, const char *, size_t);
  size_t  ustr_utf8_cspn_fwd(const struct Ustr *, size_t, const struct Ustr *);
  size_t  ustr_utf8_cspn_rev(const struct Ustr *, size_t, const struct Ustr *);
  size_t  ustr_utf8_cspn_cstr_fwd(const struct Ustr *, size_t, const char *);
  size_t  ustr_utf8_cspn_cstr_rev(const struct Ustr *, size_t, const char *);

  int  ustr_io_get(struct Ustr **, FILE *, size_t, size_t *);
  int  ustr_io_getfile(struct Ustr **, FILE *);
  int  ustr_io_getfilename(struct Ustr **, const char *);
  int  ustr_io_getdelim(struct Ustr **, FILE *, char);
  int  ustr_io_getline(struct Ustr **, FILE *);
  int ustr_io_put(struct Ustr **, FILE *, size_t);
  int  ustr_io_putline(struct Ustr **, FILE *, size_t);
  int  ustr_io_putfile(struct Ustr **, FILE *);
  int  ustr_io_putfileline(struct Ustr **, FILE *);
  int  ustr_io_putfilename(struct Ustr **, const char *, const char *);

  int  ustr_sub_undef(struct Ustr **, size_t, size_t);
  int  ustr_sub_buf(struct Ustr **, size_t, const void *, size_t);
  int  ustr_sub_cstr(struct Ustr **, size_t, const char *);
  int  USTR_SUB_OSTR(struct Ustr **, size_t, const char []);
  int  USTR_SUB_OBJ(struct Ustr **, size_t, ...);
  int  ustr_sub(struct Ustr **, size_t, const struct Ustr *);
  int  ustr_sub_subustr(struct Ustr **, size_t, const struct Ustr *, size_t, size_t);
  int  ustr_sc_sub_undef(struct Ustr **, size_t, size_t, size_t);
  int  ustr_sc_sub_buf(struct Ustr **, size_t , size_t , const void *, size_t );
  int  ustr_sc_sub_cstr(struct Ustr **, size_t, size_t, const char *);
  int  ustr_sc_sub(struct Ustr **, size_t, size_t, const struct Ustr *);
  int  ustr_sc_sub_subustr(struct Ustr **, size_t, size_t, const struct Ustr *, size_t, size_t);
  int  USTR_SC_SUB_OSTR(struct Ustr **, size_t, size_t, const char []);
  int  USTR_SC_SUB_OBJ(struct Ustr **, size_t, size_t, ...);
  size_t  ustr_replace_buf(struct Ustr **, const void *, size_t, const void *, size_t, size_t);
  size_t  ustr_replace_cstr(struct Ustr **, const char *, const char *, size_t);
  int  ustr_replace(struct Ustr **, const struct Ustr *, const struct Ustr *, size_t);
  size_t ustr_replace_rep_chr(struct Ustr **ps1, char, size_t, char, size_t nlen, size_t lim);

  struct Ustr *ustr_split_buf(const struct Ustr *, size_t *, const void *, size_t, struct Ustr *,
                              unsigned int);
  struct  Ustr  *ustr_split(const  struct  Ustr  *, size_t *, const struct Ustr *, struct Ustr *,
                          unsigned int);
  struct Ustr *ustr_split_cstr(const struct Ustr *, size_t  *,  const  char  *,  struct  Ustr  *,
                               unsigned int);
  struct  Ustr  *ustr_split_spn_chrs(const  struct Ustr *, size_t *, const char *, size_t, struct
                                   Ustr *, unsigned int);
  struct Ustr *ustr_split_spn_cstr(const struct Ustr *, size_t *, const char *,  struct  Ustr  *,
                                   unsigned int);
  struct  Ustr *ustr_split_spn(const struct Ustr *, size_t *, const struct Ustr *, struct Ustr *,
                              unsigned int);

  int  ustr_utf8_valid(const struct Ustr *);
  size_t  ustr_utf8_len(const struct Ustr *);
  ssize_t  ustr_utf8_width(const struct Ustr *);
  size_t  ustr_utf8_chars2bytes(const struct Ustr *, size_t, size_t, size_t *);
  size_t  ustr_utf8_bytes2chars(const struct Ustr *, size_t, size_t, size_t *);
  int ustr_sc_utf8_reverse(struct Ustr **);

  uintmax_t  ustr_parse_uintmaxx(const struct Ustr *, size_t, unsigned int, uintmax_t, uintmax_t,
                                 const char *, size_t *, unsigned int *);
  uintmax_t  ustr_parse_uintmax(const struct Ustr *, size_t, unsigned int, size_t *, unsigned int
                                *);
  intmax_t  ustr_parse_intmax(const struct Ustr *, size_t, unsigned int, size_t *,  unsigned  int
                              *);
  unsigned  long   ustr_parse_ulongx(const struct Ustr *,  size_t,  unsigned int,  unsigned long,
                                   unsigned long, const char *,  size_t *, unsigned int *);
  unsigned long  ustr_parse_ulong(const struct Ustr *, size_t, unsigned int, size_t  *,  unsigned
                                  int *);
  long  ustr_parse_long(const struct Ustr *, size_t, unsigned int, size_t *, unsigned int *);
  unsigned int  ustr_parse_uint(const struct Ustr *, size_t, unsigned int, size_t *, unsigned int
                                *);
  int  ustr_parse_int(const struct Ustr *, size_t, unsigned int, size_t *, unsigned int *);
  unsigned short  ustr_parse_ushort(const struct Ustr *, size_t, unsigned int, size_t *, unsigned
                                    int *);
  short  ustr_parse_short(const struct Ustr *, size_t, unsigned int, size_t *, unsigned int *);

  int  ustr_sc_ensure_owner(struct Ustr **);
  char *ustr_sc_wstr(struct Ustr **);
  char *ustr_sc_export_subustr(const struct Ustr *, size_t, size_t, void *(*)(size_t));
  char *ustr_sc_export(const struct Ustr *, void *(*)(size_t));
  char  *ustrp_sc_export_subustrp(struct  Ustr_pool  *, const struct Ustr *, size_t, size_t, void
                                 *(*)(size_t));
  char *ustrp_sc_export(struct Ustr_pool *, const struct Ustr *, void *(*)(size_t));
  int  ustr_sc_reverse(struct Ustr **);
  int  ustr_sc_tolower(struct Ustr **);
  int  ustr_sc_toupper(struct Ustr **);
  int  ustr_sc_ltrim_chrs(struct Ustr **, const char *, size_t);
  int  ustr_sc_ltrim(struct Ustr **, const struct Ustr *);
  int  ustr_sc_ltrim_cstr(struct Ustr **, const char *);
  int  ustr_sc_rtrim_chrs(struct Ustr **, const char *, size_t);
  int  ustr_sc_rtrim(struct Ustr **, const struct Ustr *);
  int  ustr_sc_rtrim_cstr(struct Ustr **, const char *);
  int  ustr_sc_trim_chrs(struct Ustr **, const char *, size_t);
  int  ustr_sc_trim(struct Ustr **, const struct Ustr *);
  int  ustr_sc_trim_cstr(struct Ustr **, const char *);

  int  ustr_add_b_uint16(struct Ustr **, uint_least16_t);
  int  ustr_add_b_uint32(struct Ustr **, uint_least32_t);
  int  ustr_add_b_uint64(struct Ustr **, uint_least64_t);

  uint_least16_t  ustr_parse_b_uint16(const struct Ustr *, size_t);
  uint_least32_t  ustr_parse_b_uint32(const struct Ustr *, size_t);
  uint_least64_t  ustr_parse_b_uint64(const struct Ustr *, size_t);

  int ustr_realloc(struct Ustr **, size_t);
  int  ustr_cntl_opt(int, ...);

  struct Ustr_pool *ustr_pool_ll_make(void);
  struct Ustr_pool *ustr_pool_make_subpool(struct Ustr_pool *);
  void ustr_pool_free(struct Ustr_pool *);
  void ustr_pool_clear(struct Ustr_pool *);

DESCRIPTION

        A very simple overview is that you can use ustr_dup_cstr() to  convert  a  C-style  to  a
       Ustr,   and  ustr_cstr()  to  convert  it  back.  You  can  also  use  USTR1()  to  create
       constant/read-only strings, and USTR_SC_INIT_AUTO() to create strings that use stack space
       up to a certain amount.
        Use  is  somewhat  unique  in  that,  by  default, it has an average overhead of only 55%
       overhead over strdup(), for strings in the range of 0 to 20 bytes. Or, to put  it  another
       way it only uses 8 bytes to store a 2 byte string where strdup() uses 3.

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 up to 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 up to 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.

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.

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

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.

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

       Parameter[1]: Separator to go between Ustr strings
       Type[1]: const struct Ustr *

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

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

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

       Explanation:

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

       Note:

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

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

       Parameter[1]: Separator to go between Ustr strings
       Type[1]: const struct Ustr *

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

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

       Parameter[4]: Zero or more pointers to constant Ustr strings and then USTR_NULL
       Type[4]: ...

       Explanation:

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

       Note:

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

     Function:  ustr_sc_vjoinx()
       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]: Separator to go between Ustr strings
       Type[5]: const struct Ustr *

       Parameter[6]: A pointer to the first constant Ustr string
       Type[6]: const struct Ustr *

       Parameter[7]: A pointer to the second constant Ustr string
       Type[7]: const struct Ustr *

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

       Explanation:

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

       Note:

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

     Function:  ustr_sc_joinx()
       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]: Separator to go between Ustr strings
       Type[5]: const struct Ustr *

       Parameter[6]: A pointer to the first constant Ustr string
       Type[6]: const struct Ustr *

       Parameter[7]: A pointer to the second constant Ustr string
       Type[7]: const struct Ustr *

       Parameter[8]: Zero or more pointers to constant Ustr strings and then USTR_NULL
       Type[8]: ...

       Explanation:

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

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

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

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

       Explanation:

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

       Note:

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

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

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

       Parameter[2]: Zero or more pointers to constant Ustr strings and then USTR_NULL
       Type[2]: ...

       Explanation:

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

     Function:  ustr_sc_vconcatx()
       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 the first constant Ustr string
       Type[5]: const struct Ustr *

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

       Explanation:

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

       Note:

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

     Function:  ustr_sc_concatx()
       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 the first constant Ustr string
       Type[5]: const struct Ustr *

       Parameter[6]: Zero or more pointers to constant Ustr strings and then USTR_NULL
       Type[6]: ...

       Explanation:

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

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.

       Note:

         This function does nothing if passed USTR_NULL.

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

       Note:

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

     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:

         While  the point to the pointer must be non-NULL, this function also accepts a NULL ustr
       to be free'd and does nothing. So you can pass the same pointer to ustr_sc_free() and then
       this function safely.
         The  passed  value  (Parameter[2])  shouldn't  be  USTR_NULL,  and in debugging mode the
       function will assert() that it isn't.

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

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. The exception being if you
       add a ustr to itself, while only having a single reference count, the simple method  would
       access a free'd ustr, but this function just works.

       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.

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 containing 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().  The  exception being if you set a ustr to itself, while only having a
       single reference count, the simple method would  access  a  free'd  ustr  data,  but  this
       function just works.

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

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, from after the required position. If the length is not zero the
       Ustr will be writable. Or it'll return USTR_FALSE (zero) on failure. The data in the  Ustr
       is moved as needed to put the new data at position (Parameter[2]) + 1.

     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.

     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. The exception being if you insert a
       ustr to itself, while only having a single reference count, the simple method would access
       a free'd ustr data, but this function just works.

     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.

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, from va_start()
       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().

     Function:  ustr_ins_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]: Position after which the data should be added
       Type[2]: size_t

       Parameter[3]: Limit of data to insert
       Type[3]: size_t

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

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

       Explanation:

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

     Function:  ustr_ins_vfmt()
       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]: 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 the system vsnprintf() and then calling ustr_ins_buf().

     Function:  ustr_ins_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]: Position after which the data should be added
       Type[2]: size_t

       Parameter[3]: Limit of data to insert
       Type[3]: size_t

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

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

       Explanation:

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

     Function:  ustr_ins_fmt()
       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]: 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() and then calling ustr_ins_buf().

     Function:  ustr_sub_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]: Position where to start substitution
       Type[2]: size_t

       Parameter[3]: Limit of data to substitute
       Type[3]: size_t

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

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

       Explanation:

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

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

       Parameter[1]: A 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 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 the system vsnprintf() and then calling ustr_sub_buf().

     Function:  ustr_sub_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]: Position where to start substitution
       Type[2]: size_t

       Parameter[3]: Limit of data to substitute
       Type[3]: size_t

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

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

       Explanation:

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

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

       Parameter[1]: A 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 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() and then calling ustr_sub_buf().

     Function:  ustr_sc_sub_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]: Position where to start substitution
       Type[2]: size_t

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

       Parameter[4]: Limit of data to substitute
       Type[4]: size_t

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

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

       Explanation:

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

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

       Parameter[1]: A 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]: Length of substitution
       Type[3]: size_t

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

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

       Explanation:

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

     Function:  ustr_sc_sub_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]: Position where to start substitution
       Type[2]: size_t

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

       Parameter[4]: Limit of data to substitute
       Type[4]: size_t

       Parameter[5]: A pointer to a constant C-style 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() with the limit (Parameter[3]) as
       the limit to snprintf() and then calling ustr_sc_sub_buf().

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

       Parameter[1]: A 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]: Length of substitution
       Type[3]: size_t

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

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

       Explanation:

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

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

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

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.

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

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.

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 writing them to the file.

       Note:

         Deleting  bytes from the beginning 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 writing 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().

String substitution/replacement

     Function:  ustr_sub_undef()
       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 undefined data
       Type[3]: size_t

       Explanation:

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

       Note:

         You  can  think of the operation as two separate tasks, one which makes the current data
       in the Ustr undefined and the second which adds undefined data to the ustr to  accommodate
       the desired length.

     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 works as if you had called ustr_sub_undef() and then copied the data into
       the new undefined space.

     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. The exception being if you substitute  a
       ustr  into  itself,  while  only  having a single reference count, the simple method could
       access a free'd ustr data, but this function just works.

     Function:  ustr_sub_subustr()
       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 *

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

       Parameter[5]: Length to substitute from the Ustr
       Type[5]: size_t

       Explanation:

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

     Function:  ustr_sc_sub_undef()
       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]: Length of undefined data
       Type[4]: size_t

       Explanation:

         This  function works as if you had done ustr_del_subustr() followed by ustr_ins_undef(),
       however it is significantly more efficient.

     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 substitution
       Type[3]: size_t

       Parameter[4]: Buffer containing substitute data
       Type[4]: const void *

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

       Explanation:

         This function will substitute 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 substitution
       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_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:

         This  function  works  as  if  you had called ustr_sc_sub_buf() with the ustr_cstr() and
       ustr_len() values of the Ustr string to be added. The exception being if you substitute  a
       ustr  into  itself,  while  only  having a single reference count, the simple method could
       access a free'd ustr data, but this function just works.

     Function:  ustr_sc_sub_subustr()
       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]: A pointer to a constant Ustr string
       Type[4]: const struct Ustr *

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

       Parameter[6]: Length to substitute from the Ustr
       Type[6]: size_t

       Explanation:

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

     Function:  USTR_SC_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]: Length of substitution
       Type[3]: size_t

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

       Explanation:

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

     Function:  USTR_SC_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]: Length of substitution
       Type[3]: size_t

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

       Explanation:

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

       Note:

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

     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 containing search data
       Type[2]: const void *

       Parameter[3]: Length of search buffer
       Type[3]: size_t

       Parameter[4]: Buffer containing 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.

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.

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.

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 separator
       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 separator 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 separator 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 separator
       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 separator 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 separator 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 separator 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 separator 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 separator 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 separator as "_".

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

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

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

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

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

SEE ALSO

       ustr_const(3)