table of contents
- NAME
- SYNOPSIS
- DESCRIPTION
- Creating read-only Ustr functions
- Creating fixed Ustr functions
- Debugging functions
- Creating allocated Ustr functions
- Deleting a Ustr, or data within a Ustr
- Adding data to a Ustr
- Setting a Ustr to some data
- Inserting data into a Ustr
- Adding, duplicating and setting formatted data to a Ustr
- Accessing the variables of a Ustr
- Setting the flags of a Ustr
- Comparing data in a Ustr
- Searching for data in a Ustr
- Span lengths of data in a Ustr
- Doing IO from or to a Ustr
- String substitution/replacement
- Splitting a Ustr
- Dealing with UTF-8 in a Ustr
- Parsing ASCII integer numbers from a Ustr
- Misc shortcut helper functions for Ustrs
- Adding binary data to a Ustr
- Parsing binary data from a Ustr
- Misc. functions
- Simple Ustr pool API
- SEE ALSO
| ustr(3) | Ustr String Library | ustr(3) |
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 upto 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 upto 65,535 (2**16 - 1) bytes in length.
Function: USTR4()
Returns: Ustr string
Type: struct Ustr *
Parameter[1]: Encoded 4th byte of number of the length of
Ustr string
Type[1]: symbol
Parameter[2]: Encoded 3rd byte of number of the length of
Ustr string
Type[2]: symbol
Parameter[3]: Encoded 2nd byte of number of the length of
Ustr string
Type[3]: symbol
Parameter[4]: Encoded 1st byte of number of the length of
Ustr string
Type[4]: symbol
Parameter[5]: Data for Ustr string
Type[5]: const char[]
Explanation:
This function works in the same way as USTR1() but takes four length bytes,
so the read-only string can be upto 2**32 - 1 bytes in length.
Function: USTR1_CHK()
Returns: Ustr string
Type: struct Ustr *
Parameter[1]: Encoded number of the length of Ustr string
Type[1]: symbol
Parameter[2]: Data for Ustr string
Type[2]: const char[]
Explanation:
This function works in the same way as USTR1() but it does a check against
the length of (Parameter[2]) using sizeof() - 1.
Note:
If the check fails the returned Ustr * will be "", so you can check
ustr_len() to see if you screwed something up.
Function: USTR2_CHK()
Returns: Ustr string
Type: struct Ustr *
Parameter[1]: Encoded 2nd byte of number of the length of
Ustr string
Type[1]: symbol
Parameter[2]: Encoded 1st byte of number of the length of
Ustr string
Type[2]: symbol
Parameter[3]: Data for Ustr string
Type[3]: const char[]
Explanation:
This function works in the same way as USTR2() but it does a check against
the length of (Parameter[2]) using sizeof() - 1.
Note:
If the check fails the returned Ustr * will be "".
Function: USTR4_CHK()
Returns: Ustr string
Type: struct Ustr *
Parameter[1]: Encoded 4th byte of number of the length of
Ustr string
Type[1]: symbol
Parameter[2]: Encoded 3rd byte of number of the length of
Ustr string
Type[2]: symbol
Parameter[3]: Encoded 2nd byte of number of the length of
Ustr string
Type[3]: symbol
Parameter[4]: Encoded 1st byte of number of the length of
Ustr string
Type[4]: symbol
Parameter[5]: Data for Ustr string
Type[5]: const char[]
Explanation:
This function works in the same way as USTR4() but it does a check against
the length of (Parameter[2]) using sizeof() - 1.
Note:
If the check fails the returned Ustr * will be "".
Function: USTRP1()
Returns: Ustr string
Type: struct Ustr *
Parameter[1]: Encoded number of the length of Ustr string
Type[1]: symbol
Parameter[2]: Data for Ustr string
Type[2]: const char[]
Explanation:
This function works like USTR1(), but returns a Ustrp instead.
Function: USTRP2()
Returns: Ustr string
Type: struct Ustr *
Parameter[1]: Encoded 2nd byte of number of the length of
Ustr string
Type[1]: symbol
Parameter[2]: Encoded 1st byte of number of the length of
Ustr string
Type[2]: symbol
Parameter[3]: Data for Ustr string
Type[3]: const char[]
Explanation:
This function works like USTR4(), but returns a Ustrp instead.
Function: USTRP4()
Returns: Ustrp string
Type: struct Ustrp *
Parameter[1]: Encoded 4th byte of number of the length of
Ustrp string
Type[1]: symbol
Parameter[2]: Encoded 3rd byte of number of the length of
Ustrp string
Type[2]: symbol
Parameter[3]: Encoded 2nd byte of number of the length of
Ustrp string
Type[3]: symbol
Parameter[4]: Encoded 1st byte of number of the length of
Ustrp string
Type[4]: symbol
Parameter[5]: Data for Ustr string
Type[5]: const char[]
Explanation:
This function works like USTR2(), but returns a Ustrp instead.
Function: USTRP1_CHK()
Returns: Ustr string
Type: struct Ustr *
Parameter[1]: Encoded number of the length of Ustr string
Type[1]: symbol
Parameter[2]: Data for Ustr string
Type[2]: const char[]
Explanation:
This function works like USTR1_CHK(), but returns a Ustrp instead.
Function: USTRP2_CHK()
Returns: Ustr string
Type: struct Ustr *
Parameter[1]: Encoded 2nd byte of number of the length of
Ustr string
Type[1]: symbol
Parameter[2]: Encoded 1st byte of number of the length of
Ustr string
Type[2]: symbol
Parameter[3]: Data for Ustr string
Type[3]: const char[]
Explanation:
This function works like USTR4_CHK(), but returns a Ustrp instead.
Function: USTRP4_CHK()
Returns: Ustrp string
Type: struct Ustrp *
Parameter[1]: Encoded 4th byte of number of the length of
Ustrp string
Type[1]: symbol
Parameter[2]: Encoded 3rd byte of number of the length of
Ustrp string
Type[2]: symbol
Parameter[3]: Encoded 2nd byte of number of the length of
Ustrp string
Type[3]: symbol
Parameter[4]: Encoded 1st byte of number of the length of
Ustrp string
Type[4]: symbol
Parameter[5]: Data for Ustr string
Type[5]: const char[]
Explanation:
This function works like USTR2_CHK(), but returns a Ustrp instead.
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 implicity sized Ustrp from a pool and then delete some data from
it (which fails) the Ustr layer will think it has an implicit less than the
actual size so this function will fail. This is what
USTR_CNTL_MALLOC_CHECK_MEM_USTRP() is for.
Function: USTR_CNTL_MALLOC_CHECK_MEM_USTRP()
Returns: Success or failure
Type: int
Parameter[1]: Pointer to a Ustrp string
Type[1]: Ustrp *
Explanation:
This function asserts that the pointer (Parameter[1]) is a Ustr allocated
from a builtin pool using malloc checking, if the Ustr is allocated (if not
it returns TRUE).
Function: USTR_CNTL_MALLOC_CHECK_END()
Returns: Success or failure
Type: int
Parameter[1]: Nothing
Type[1]: void
Explanation:
This macro will cleanup any memory used by malloc check, and assert that no
memory is left allocated.
Note:
If any memory is left allocated, each one found is output to stderr with the
file/line/function of the level it was allocated from.
Function: USTR_CNTL_MALLOC_CHECK_ADD()
Returns: Success or failure
Type: int
Parameter[1]: Condition to begin malloc checking or not
Type[1]: int
Explanation:
This function works like USTR_CNTL_MALLOC_CHECK_END() but it fails if the
condition check (Parameter[1]) fails, or if USTR_CNTL_MALLOC_CHECK_LVL() is
zero.
Function: USTR_CNTL_MALLOC_CHECK_DEL()
Returns: Success or failure
Type: int
Parameter[1]: Condition to end malloc checking or not
Type[1]: int
Explanation:
This function works like USTR_CNTL_MALLOC_CHECK_END() but it fails if the
condition check (Parameter[1]) fails, or if USTR_CNTL_MALLOC_CHECK_LVL() is
one.
Note:
The condition (Parameter[1]) to this macro should almost certainly be the
return value from USTR_CNTL_MALLOC_CHECK_ADD().
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 benifit is that you don't have to check for memory failure errors,
if there is a memory failure and you have a non-default configuration the
configuration will revert back to the default.
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 containting data
Type[2]: const void *
Parameter[3]: Length of Buffer
Type[3]: size_t
Explanation:
This function works as if you had called ustr_del() for the entire string and
the ustr_add_buf().
Function: ustr_set_cstr()
Returns: Success or failure
Type: int
Parameter[1]: Pointer to a pointer to a Ustr string
Type[1]: struct Ustr **
Parameter[2]: A pointer to a constant C-style string
Type[2]: const char *
Explanation:
This function works as if you had called ustr_del() for the entire string and
then ustr_add_cstr().
Function: USTR_SET_OSTR()
Returns: Success or failure
Type: int
Parameter[1]: Pointer to a pointer to a Ustr string
Type[1]: struct Ustr **
Parameter[2]: A constant C-style string
Type[2]: const char []
Explanation:
This function works as if you had called ustr_del() for the entire string and
then USTR_ADD_OSTR().
Function: USTR_SET_OBJ()
Returns: Success or failure
Type: int
Parameter[1]: Pointer to a pointer to a Ustr string
Type[1]: struct Ustr **
Parameter[2]: A symbol
Type[2]: ...
Explanation:
This function works as if you had called ustr_del() for the entire string and
then USTR_ADD_OBJ().
Note:
In most cases you'll want to use USTR_SET_OSTR().
Function: ustr_set()
Returns: Success or failure
Type: int
Parameter[1]: Pointer to a pointer to a Ustr string
Type[1]: struct Ustr **
Parameter[2]: A pointer to a constant Ustr string
Type[2]: const struct Ustr *
Explanation:
This function works as if you had called ustr_del() for the entire string and
the ustr_add().
Function: ustr_set_subustr()
Returns: Success or failure
Type: int
Parameter[1]: Pointer to a pointer to a Ustr string
Type[1]: struct Ustr **
Parameter[2]: A pointer to a constant Ustr string
Type[2]: const struct Ustr *
Parameter[3]: Position in the Ustr
Type[3]: size_t
Parameter[4]: Length to set from the Ustr
Type[4]: size_t
Explanation:
This function works as if you had called ustr_del() for the entire string and
the ustr_add_subustr(). 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 amount of times.
Function: ustr_fixed()
Returns: A boolean flag of either USTR_TRUE or USTR_FALSE
Type: int
Parameter[1]: A pointer to a constant Ustr string
Type[1]: const struct Ustr *
Explanation:
This function says if the Ustr is current in fixed size storage.
Fixed size storage is writable but cannot be referenced.
Note:
Fixed size storage always explicitly stores the size of the storage.
Function: ustr_enomem()
Returns: A boolean flag of either USTR_TRUE or USTR_FALSE
Type: int
Parameter[1]: A pointer to a constant Ustr string
Type[1]: const struct Ustr *
Explanation:
This function just returns the value of the user settable flag in the Ustr.
It can be set via. ustr_setf_enomem_err() and cleared by
ustr_setf_enomem_clr().
This function is automatically set to on whever a memory allocation failure
happens for a Ustr.
Note:
If a Ustr is referenced multiple times, ustr_setf_enomem_err() will fail.
This always fails for Ustr's in read-only storage.
Function: ustr_shared()
Returns: A boolean flag of either USTR_TRUE or USTR_FALSE
Type: int
Parameter[1]: A pointer to a constant Ustr string
Type[1]: const struct Ustr *
Explanation:
This function says if the Ustr is in the "shared" mode. It can be
set via. ustr_setf_shared() and cleared by ustr_setf_owner() on allocated
Ustr's.
Shared mode means that a Ustr can be referenced and unreferenced an infinite
number of times.
Note:
This always succeeds for Ustr's in read-only storage.
This always fails for Ustr's in fixed size storage.
Function: ustr_limited()
Returns: A boolean flag of either USTR_TRUE or USTR_FALSE
Type: int
Parameter[1]: A pointer to a constant Ustr string
Type[1]: const struct Ustr *
Explanation:
This function says if the Ustr is currently in fixed size storage and cannot
move to allocated storage.
Note:
This always fails for Ustr's in allocated storage.
This always fails for Ustr's in read-only storage.
Function: ustr_owner()
Returns: A boolean flag of either USTR_TRUE or USTR_FALSE
Type: int
Parameter[1]: A pointer to a constant Ustr string
Type[1]: const struct Ustr *
Explanation:
This function says if there is only a single reference to the Ustr
string.
Note:
This always fails for Ustr's in read-only storage.
This always succeeds for Ustr's in fixed size storage.
Function: ustr_size()
Returns: size_t
Type: size_t
Parameter[1]: A pointer to a constant Ustr string
Type[1]: const struct Ustr *
Explanation:
This function calculates the maximum amount of data that could be stored (Ie.
the max ustr_len()) without having to re-size the Ustr string.
Function: ustr_size_alloc()
Returns: size_t
Type: size_t
Parameter[1]: A pointer to a constant Ustr string
Type[1]: const struct Ustr *
Explanation:
This function returns the size of the storage for the Ustr.
Function: ustr_size_overhead()
Returns: size_t
Type: size_t
Parameter[1]: A pointer to a constant Ustr string
Type[1]: const struct Ustr *
Explanation:
This function returns the difference between the size of the storage and the
maximum amount of data that could be stored without having to re-size the
Ustr string.
Function: ustr_conf()
Returns: Nothing
Type: void
Parameter[1]: A pointer to a constant Ustr string
Type[1]: const struct Ustr *
Parameter[2]: Return size allocated number
Type[2]: size_t *
Parameter[3]: Return number of bytes used in the reference
count
Type[3]: size_t *
Parameter[4]: Return exact allocations flag
Type[4]: int *
Parameter[5]: Return number of bytes used in the length
Type[5]: size_t *
Parameter[5]: Return number of references to this Ustr
Type[5]: size_t *
Explanation:
This function gives the configuration of the current Ustr needed to duplicate
it via. the ustr_dupx_*() functions. It also gives the number of bytes used
for the length and the number of references, which are mainly
informational.
Note:
This function differs from calling the ustr_exact() etc. functions in that it
returns the global options if this Ustr isn't allocated, thus telling you
what the configuration would be if the Ustr was turned into an allocated
Ustr by adding data etc.
Zero references for an allocated Ustr with a non-zero number of bytes for a
reference count means it's in "shared" mode).
Setting the flags of a Ustr¶
Function: ustr_setf_enomem_err()
Returns: Success or failure
Type: int
Parameter[1]: A pointer to a Ustr string
Type[1]: struct Ustr *
Explanation:
This function sets the enomem flag, which can be observed via. the
ustr_enomem() function.
The implication of setting this flag is that a memory error has occured in a
previous function call on this Ustr.
Note:
This function fails if ustr_owner() fails for the Ustr.
Function: ustr_setf_enomem_clr()
Returns: Success or failure
Type: int
Parameter[1]: A pointer to a Ustr string
Type[1]: struct Ustr *
Explanation:
This function clears the enomem flag, which can be observed via. the
ustr_enomem() function.
The implication of this flag being set is that a memory error has occured in
a previous function call on this Ustr, so on clearing the flag you should
know you have brought the Ustr back to a known state.
Note:
This function fails if ustr_owner() fails for the Ustr.
Function: ustr_setf_share()
Returns: Success or failure
Type: int
Parameter[1]: A pointer to a Ustr string
Type[1]: struct Ustr *
Explanation:
This function sets the shared mode, which can be observed via. the
ustr_shared() function.
This is used on a Ustr so that it can have more references than it is able to
hold in it's reference count. After this call the Ustr can be referenced and
unreferenced an infinite number of times.
Note:
After this call the Ustr will never be deleted until ustr_setf_owner() is
called.
This function fails if ustr_alloc() fails for the Ustr.
Function: ustr_setf_owner()
Returns: Success or failure
Type: int
Parameter[1]: A pointer to a Ustr string
Type[1]: struct Ustr *
Explanation:
This function removes the shared mode, which can be observed via. the
ustr_shared() function.
This is used so that a Ustr in shared mode can be free'd.
Note:
This function fails if ustr_alloc() fails for the Ustr.
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 begining, so to do a loop you need to take the position from the
length.
Function: ustr_srch_buf_fwd()
Returns: Position in the Ustr, or zero if not found
Type: size_t
Parameter[1]: A pointer to a constant Ustr string
Type[1]: const struct Ustr *
Parameter[2]: Offset within string to start searching at
Type[2]: size_t
Parameter[3]: A pointer to data to search for
Type[3]: const void *
Parameter[4]: Length of the data to search for
Type[4]: size_t
Explanation:
This function searches for the data (Parameter[3]) of length (Parameter[4])
in the Ustr, skipping an offset (Parameter[2]) number of bytes.
Function: ustr_srch_buf_rev()
Returns: Position in the Ustr, or zero if not found
Type: size_t
Parameter[1]: A pointer to a constant Ustr string
Type[1]: const struct Ustr *
Parameter[2]: Offset within string to start searching at
Type[2]: size_t
Parameter[3]: A pointer to data to search for
Type[3]: const void *
Parameter[4]: Length of the data to search for
Type[4]: size_t
Explanation:
This function works like ustr_srch_buf_fwd() but it searches from the end of
the string to the beginning.
Note:
The searching starts from the end of the string, and so the offset is the
offset from the end. However the position of a byte is always relative to
the begining, so to do a loop you need to take the position from the
length.
Function: ustr_srch_fwd()
Returns: Position in the Ustr, or zero if not found
Type: size_t
Parameter[1]: A pointer to a constant Ustr string
Type[1]: const struct Ustr *
Parameter[2]: Offset within string to start searching at
Type[2]: size_t
Parameter[3]: A pointer to a constant Ustr string, to
search for
Type[3]: const struct Ustr *
Explanation:
This function works like ustr_srch_buf_fwd() but it gets the data pointer by
calling ustr_cstr() and the length by calling ustr_len() on the passed Ustr
(Parameter[3]).
Function: ustr_srch_rev()
Returns: Position in the Ustr, or zero if not found
Type: size_t
Parameter[1]: A pointer to a constant Ustr string
Type[1]: const struct Ustr *
Parameter[2]: Offset within string to start searching at
Type[2]: size_t
Parameter[3]: A pointer to a constant Ustr string, to
search for
Type[3]: const struct Ustr *
Explanation:
This function works like ustr_srch_fwd() but it searches from the end of the
string to the beginning.
Note:
The searching starts from the end of the string, and so the offset is the
offset from the end. However the position of a byte is always relative to
the begining, so to do a loop you need to take the position from the
length.
Function: ustr_srch_cstr_fwd()
Returns: Position in the Ustr, or zero if not found
Type: size_t
Parameter[1]: A pointer to a constant Ustr string
Type[1]: const struct Ustr *
Parameter[2]: Offset within string to start searching at
Type[2]: size_t
Parameter[3]: A pointer to C-style string data, to search
for
Type[3]: const char *
Explanation:
This function works like ustr_srch_buf_fwd() but it gets the length by
calling strlen() on the passed data (Parameter[3]).
Function: ustr_srch_cstr_rev()
Returns: Position in the Ustr, or zero if not found
Type: size_t
Parameter[1]: A pointer to a constant Ustr string
Type[1]: const struct Ustr *
Parameter[2]: Offset within string to start searching at
Type[2]: size_t
Parameter[3]: A pointer to C-style string data, to search
for
Type[3]: const char *
Explanation:
This function works like ustr_srch_cstr_fwd() but it searches from the end of
the string to the beginning.
Note:
The searching starts from the end of the string, and so the offset is the
offset from the end. However the position of a byte is always relative to
the begining, so to do a loop you need to take the position from the
length.
Function: ustr_srch_subustr_fwd()
Returns: Position in the Ustr, or zero if not found
Type: size_t
Parameter[1]: A pointer to a constant Ustr string
Type[1]: const struct Ustr *
Parameter[2]: Offset within string to start searching at
Type[2]: size_t
Parameter[3]: A pointer to a constant Ustr string
Type[3]: const struct Ustr *
Parameter[4]: Position in the Ustr
Type[4]: size_t
Parameter[5]: Length of data to search, from the Ustr
Type[5]: size_t
Explanation:
This function works like ustr_srch_fwd() but it moves the data to start at
the correct position and limits the length to the value specified.
Function: ustr_srch_subustr_rev()
Returns: Position in the Ustr, or zero if not found
Type: size_t
Parameter[1]: A pointer to a constant Ustr string
Type[1]: const struct Ustr *
Parameter[2]: Offset within string to start searching at
Type[2]: size_t
Parameter[3]: A pointer to a constant Ustr string
Type[3]: const struct Ustr *
Parameter[4]: Position in the Ustr
Type[4]: size_t
Parameter[5]: Length of data to search, from the Ustr
Type[5]: size_t
Explanation:
This function works like ustr_srch_rev() but it moves the data to start at
the correct position and limits the length to the value specified.
Note:
The searching starts from the end of the string, and so the offset is the
offset from the end. However the position of a byte is always relative to
the begining, so to do a loop you need to take the position from the
length.
Function: ustr_srch_case_chr_fwd()
Returns: Position in the Ustr, or zero if not found
Type: size_t
Parameter[1]: A pointer to a constant Ustr string
Type[1]: const struct Ustr *
Parameter[2]: Offset within string to start searching at
Type[2]: size_t
Parameter[3]: Byte data to search for
Type[3]: char
Explanation:
This function works like ustr_srch_chr_fwd(), but treats ASCII uppercase and
lowercase as equivalent.
Function: ustr_srch_case_chr_rev()
Returns: Position in the Ustr, or zero if not found
Type: size_t
Parameter[1]: A pointer to a constant Ustr string
Type[1]: const struct Ustr *
Parameter[2]: Offset within string to start searching at
Type[2]: size_t
Parameter[3]: Byte data to search for
Type[3]: char
Explanation:
This function works like ustr_srch_chr_fwd(), but treats ASCII uppercase and
lowercase as equivalent.
Function: ustr_srch_case_buf_fwd()
Returns: Position in the Ustr, or zero if not found
Type: size_t
Parameter[1]: A pointer to a constant Ustr string
Type[1]: const struct Ustr *
Parameter[2]: Offset within string to start searching at
Type[2]: size_t
Parameter[3]: A pointer to data to search for
Type[3]: const void *
Parameter[4]: Length of the data to search for
Type[4]: size_t
Explanation:
This function works like ustr_srch_buf_fwd(), but treats ASCII uppercase and
lowercase as equivalent.
Function: ustr_srch_case_buf_rev()
Returns: Position in the Ustr, or zero if not found
Type: size_t
Parameter[1]: A pointer to a constant Ustr string
Type[1]: const struct Ustr *
Parameter[2]: Offset within string to start searching at
Type[2]: size_t
Parameter[3]: A pointer to data to search for
Type[3]: const void *
Parameter[4]: Length of the data to search for
Type[4]: size_t
Explanation:
This function works like ustr_srch_buf_rev(), but treats ASCII uppercase and
lowercase as equivalent.
Function: ustr_srch_case_fwd()
Returns: Position in the Ustr, or zero if not found
Type: size_t
Parameter[1]: A pointer to a constant Ustr string
Type[1]: const struct Ustr *
Parameter[2]: Offset within string to start searching at
Type[2]: size_t
Parameter[3]: A pointer to a constant Ustr string, to
search for
Type[3]: const struct Ustr *
Explanation:
This function works like ustr_srch_fwd(), but treats ASCII uppercase and
lowercase as equivalent.
Function: ustr_srch_case_rev()
Returns: Position in the Ustr, or zero if not found
Type: size_t
Parameter[1]: A pointer to a constant Ustr string
Type[1]: const struct Ustr *
Parameter[2]: Offset within string to start searching at
Type[2]: size_t
Parameter[3]: A pointer to a constant Ustr string, to
search for
Type[3]: const struct Ustr *
Explanation:
This function works like ustr_srch_rev(), but treats ASCII uppercase and
lowercase as equivalent.
Function: ustr_srch_case_cstr_fwd()
Returns: Position in the Ustr, or zero if not found
Type: size_t
Parameter[1]: A pointer to a constant Ustr string
Type[1]: const struct Ustr *
Parameter[2]: Offset within string to start searching at
Type[2]: size_t
Parameter[3]: A pointer to C-style string data, to search
for
Type[3]: const char *
Explanation:
This function works like ustr_srch_cstr_fwd(), but treats ASCII uppercase and
lowercase as equivalent.
Function: ustr_srch_case_cstr_rev()
Returns: Position in the Ustr, or zero if not found
Type: size_t
Parameter[1]: A pointer to a constant Ustr string
Type[1]: const struct Ustr *
Parameter[2]: Offset within string to start searching at
Type[2]: size_t
Parameter[3]: A pointer to C-style string data, to search
for
Type[3]: const char *
Explanation:
This function works like ustr_srch_cstr_rev(), but treats ASCII uppercase and
lowercase as equivalent.
Function: ustr_srch_case_subustr_fwd()
Returns: Position in the Ustr, or zero if not found
Type: size_t
Parameter[1]: A pointer to a constant Ustr string
Type[1]: const struct Ustr *
Parameter[2]: Offset within string to start searching at
Type[2]: size_t
Parameter[3]: A pointer to a constant Ustr string
Type[3]: const struct Ustr *
Parameter[4]: Position in the Ustr
Type[4]: size_t
Parameter[5]: Length of data to search, from the Ustr
Type[5]: size_t
Explanation:
This function works like ustr_srch_subustr_fwd(), but treats ASCII uppercase
and lowercase as equivalent.
Function: ustr_srch_case_subustr_rev()
Returns: Position in the Ustr, or zero if not found
Type: size_t
Parameter[1]: A pointer to a constant Ustr string
Type[1]: const struct Ustr *
Parameter[2]: Offset within string to start searching at
Type[2]: size_t
Parameter[3]: A pointer to a constant Ustr string
Type[3]: const struct Ustr *
Parameter[4]: Position in the Ustr
Type[4]: size_t
Parameter[5]: Length of data to search, from the Ustr
Type[5]: size_t
Explanation:
This function works like ustr_srch_subustr_rev(), but treats ASCII uppercase
and lowercase as equivalent.
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 writting them to the file.
Note:
Deleting bytes from the begining of a Ustr string is the most inefficient
thing to do, so it is recommended to use ustr_io_putfile().
Function: ustr_io_putline()
Returns: Success or failure
Type: int
Parameter[1]: Pointer to a pointer to a Ustr string
Type[1]: struct Ustr **
Parameter[2]: A pointer to a C file object
Type[2]: FILE *
Parameter[3]: Number of bytes to write
Type[3]: size_t
Explanation:
This function works like calling ustr_io_put(), and then writting a '\n' to
the file.
Note:
This doesn't write a line from the Ustr to the file, if you want that call
ustr_io_put() directly, using the return from ustr_srch_chr_fwd() (with a
'\n') as the number of bytes argument.
Function: ustr_io_putfile()
Returns: Success or failure
Type: int
Parameter[1]: Pointer to a pointer to a Ustr string
Type[1]: struct Ustr **
Parameter[2]: A pointer to a C file object
Type[2]: FILE *
Explanation:
This function works like calling ustr_io_put() with ustr_len() as the number
of bytes.
Function: ustr_io_putfileline()
Returns: Success or failure
Type: int
Parameter[1]: Pointer to a pointer to a Ustr string
Type[1]: struct Ustr **
Parameter[2]: A pointer to a C file object
Type[2]: FILE *
Explanation:
This function works like calling ustr_io_putline() with ustr_len() as the
number of bytes.
Function: ustr_io_putfilename()
Returns: Success or failure
Type: int
Parameter[1]: Pointer to a pointer to a Ustr string
Type[1]: struct Ustr **
Parameter[2]: A C-style string of a filename
Type[2]: const char *
Parameter[3]: A C-style string of a filemode (the second
argument to fopen)
Type[3]: const char *
Explanation:
This function opens a specified file, and then calls ustr_io_putfile().
Finally closing the FILE * object.
Note:
The errno value when this function ends could either be from fopen(),
fwrite(), or if both of the those succeeded from fclose().
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 seperate tasks, one which makes the
current data in the Ustr undefined and the second which adds undefined data
to the ustr to accomodate 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 containting 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 containting search data
Type[2]: const void *
Parameter[3]: Length of search buffer
Type[3]: size_t
Parameter[4]: Buffer containting replacement data
Type[4]: const void *
Parameter[5]: Length of replacement buffer
Type[5]: size_t
Parameter[6]: Maximum number of matches to replace (0 for
unlimited)
Type[6]: size_t
Explanation:
This function scans the "haystack" (Parameter[1]) for
"needle" (Parameter[2]) and replaces max_replacements
(Parameter[6]) matches with the "replacement" (Parameter[4]).
Note:
If max_replacements (Parameter[6]) is 0, this function will replace ALL
occurrences.
Function: ustr_replace_cstr()
Returns: Number of tokens replaced
Type: size_t
Parameter[1]: Pointer to a pointer to a Ustr (haystack)
Type[1]: struct Ustr **
Parameter[2]: A pointer to a constant C-style string,
containing search bytes
Type[2]: const char *
Parameter[3]: A pointer to a constant C-style string,
containing replacement bytes
Type[3]: const char *
Parameter[4]: Maximum number of matches to replace (0 for
unlimited)
Type[4]: size_t
Explanation:
This function works like ustr_replace_buf() but gets the lengths for the
buffer automatically from strlen().
Function: ustr_replace()
Returns: Number of tokens replaced
Type: int
Parameter[1]: Pointer to a pointer to a Ustr (haystack)
Type[1]: struct Ustr **
Parameter[2]: Ustr to search for (needle)
Type[2]: const struct Ustr *
Parameter[3]: Ustr to replace needle with
Type[3]: const struct Ustr *
Parameter[4]: Maximum number of matches to replace (0 for
unlimited)
Type[4]: size_t
Explanation:
This function works like ustr_replace_buf() but gets the lengths from the
ustr automatically.
Function: ustr_replace_rep_chr()
Returns: number of replacements made
Type: size_t
Parameter[1]: pointer to a pointer to a Ustr to be modified
Type[1]: struct Ustr **ps1
Parameter[2]: character to replace
Type[2]: char
Parameter[3]: number of characters to replace
Type[3]: size_t
Parameter[4]: character to replace with
Type[4]: char
Parameter[5]: number of characters to replace with
Type[5]: size_t nlen
Parameter[6]: maximum number of replacements to make (use 0
for unlimited)
Type[6]: size_t lim
Explanation:
This function replaces a repeating sequence of characters with another
repeating sequence of characters.
For example...
Ustr *data = ustr_dup_cstr("xxxBxxCxDxxx");
ustr_replace_rep_chr(&data,'x',2,'y',1, 0)
...would change data to be "yxByCxDyx".
Note:
Changing the same letter the same number of times is considered a No-op since
it is a vast performance improvement this way. So passing in
(&data,'y',2,'y',2 ,0) will have a return value of 0 and the string will
be unchanged.
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 begining of the Ustr (Parameter[1])
that are in the span (Parameter[2]) of the specificed length
(parameter[2]).
Function: ustr_sc_ltrim()
Returns: Success or failure
Type: int
Parameter[1]: A pointer to a pointer to a Ustr string
Type[1]: struct Ustr **
Parameter[2]: A pointer to a constant Ustr string,
containing trimming bytes
Type[2]: const struct Ustr *
Explanation:
This function works as if you had called ustr_sc_ltrim_chrs() and passed
ustr_cstr() and ustr_len() values of the Ustr string (Parameter[2]).
Function: ustr_sc_ltrim_cstr()
Returns: Success or failure
Type: int
Parameter[1]: A pointer to a pointer to a Ustr string
Type[1]: struct Ustr **
Parameter[2]: A pointer to a constant C-style string,
containing trimming bytes
Type[2]: const char *
Explanation:
This function works as if you had called ustr_sc_ltrim_chrs() and passed
strlen() as the length.
Function: ustr_sc_rtrim_chrs()
Returns: Success or failure
Type: int
Parameter[1]: A pointer to a pointer to a Ustr string
Type[1]: struct Ustr **
Parameter[2]: Array of bytes, containing trimming data
Type[2]: const char *
Parameter[3]: Length of byte data
Type[3]: size_t
Explanation:
This function deletes the bytes at the end of the Ustr (Parameter[1]) that
are in the span (Parameter[2]) of the specificed length (parameter[2]).
Function: ustr_sc_rtrim()
Returns: Success or failure
Type: int
Parameter[1]: A pointer to a pointer to a Ustr string
Type[1]: struct Ustr **
Parameter[2]: A pointer to a constant Ustr string,
containing trimming bytes
Type[2]: const struct Ustr *
Explanation:
This function works as if you had called ustr_sc_rtrim_chrs() and passed
ustr_cstr() and ustr_len() values of the Ustr string (Parameter[2]).
Function: ustr_sc_rtrim_cstr()
Returns: Success or failure
Type: int
Parameter[1]: A pointer to a pointer to a Ustr string
Type[1]: struct Ustr **
Parameter[2]: A pointer to a constant C-style string,
containing trimming bytes
Type[2]: const char *
Explanation:
This function works as if you had called ustr_sc_rtrim_chrs() and passed
strlen() as the length.
Function: ustr_sc_trim_chrs()
Returns: Success or failure
Type: int
Parameter[1]: A pointer to a pointer to a Ustr string
Type[1]: struct Ustr **
Parameter[2]: Array of bytes, containing trimming data
Type[2]: const char *
Parameter[3]: Length of byte data
Type[3]: size_t
Explanation:
This function deletes the bytes at the begining or end of the Ustr
(Parameter[1]) that are in the span (Parameter[2]) of the specificed length
(parameter[2]).
Note:
Calling this function is much more efficient than calling
ustr_sc_rtrim_chrs() and then ustr_sc_ltrim_chrs(), as both ends are trimmed
in a single pass.
Function: ustr_sc_trim()
Returns: Success or failure
Type: int
Parameter[1]: A pointer to a pointer to a Ustr string
Type[1]: struct Ustr **
Parameter[2]: A pointer to a constant Ustr string,
containing trimming bytes
Type[2]: const struct Ustr *
Explanation:
This function works as if you had called ustr_sc_trim_chrs() and passed
ustr_cstr() and ustr_len() values of the Ustr string (Parameter[2]).
Function: ustr_sc_trim_cstr()
Returns: Success or failure
Type: int
Parameter[1]: A pointer to a pointer to a Ustr string
Type[1]: struct Ustr **
Parameter[2]: A pointer to a constant C-style string,
containing trimming bytes
Type[2]: const char *
Explanation:
This function works as if you had called ustr_sc_trim_chrs() and passed
strlen() as the length.
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]: Arugments to option
Type[2]: ...
Explanation:
This function views and/or changes global Ustr options, like whether ustr's
have an implicit or explicit size (USTR_CNTL_OPT_GET_HAS_SIZE).
Simple Ustr pool API¶
Function: ustr_pool_ll_make()
Returns: Pointer to a Ustr pool object
Type: struct Ustr_pool *
Parameter[1]: Nothing
Type[1]: void
Explanation:
This allocates a new pool using the "linked list" strategy, each
allocation in the pool is added to a linked list ... and any allocations not
freed directly are freed by the pool when it is cleared or freed.
Function: ustr_pool_make_subpool()
Returns: Pointer to a Ustr pool object
Type: struct Ustr_pool *
Parameter[1]: struct Ustr_pool *
Type[1]: struct Ustr_pool *
Explanation:
This allocates a new pool as a child of the passed in pool (Parameter[1]),
The pool can be freed and cleared independantly of the parent pool however
free and clear operations on the parent pool are automatically applied to
all child pools.
Function: ustr_pool_free()
Returns: Nothing
Type: void
Parameter[1]: Pointer to a Ustr pool object
Type[1]: struct Ustr_pool *
Explanation:
This deallocates a pool, and all sub-pools.
Note:
This also operates on all sub-pools.
Function: ustr_pool_clear()
Returns: Nothing
Type: void
Parameter[1]: Pointer to a Ustr pool object
Type[1]: struct Ustr_pool *
Explanation:
This allows all the data in the pool to be reused, it may also free some/all
of the data in the pool, from the pool API.
Note:
This also operates on all sub-pools.
SEE ALSO¶
| 05-Mar-2008 | Ustr 1.0.4 |