ustr(3)
🦋 ustr(3) — Ustr String Library, bestie 🦋
Okay so welcome to ustr(3), aka the Ustr String Library page. This part is the big roll call of functions, and every signature below is literally the lineup. No skipping, no “tl;dr” — the whole squad is here. 💅
✨ NAME ✨
ustr — ustr string library functions. That’s the name, and it’s giving “useful string library functions” in the most direct way possible. 🎀
✨ SYNOPSIS ✨
Here’s the whole guest list, exactly as written. Do not come for me about the line wraps — they’re canon. 😭
#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 💖
okay so here's the super-simple overview, bestie: you can use ustr_dup_cstr() to convert a C-style string into a Ustr, and ustr_cstr() to convert it right back. You can also use USTR1() to create constant/read-only strings, and USTR_SC_INIT_AUTO() to create strings that use stack space up to a certain amount. ✨
The way this library gets used is kind of its own thing ngl: by default, it has an average overhead of only 55% 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 🦋
okay bestie, this whole batch is about making Ustr strings that live in read-only memory — like, they're literally just constant data with a tiny header vibe. no allocation, no drama 💅
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. that's it, that's the whole tea ☕
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 "". same energy as USTR(), just the Ustrp flavor ✨
Note: there is basically just a simple cast behind the macro. again. iconic of it honestly.
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 it's 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. we love a safety net bestie 🫶
USTR2()
- Returns: Ustr string
- Type:
struct Ustr * - Parameter[1]: Encoded 2nd byte of number of the length of Ustr string
- Type[1]:
symbol - Parameter[2]: Encoded 1st byte of number of the length of Ustr string
- Type[2]:
symbol - Parameter[3]: Data for Ustr string
- Type[3]:
const char[]
Explanation: this function works in the same way as USTR1() but takes two length bytes, so the read-only string can be up to 65,535 (2**16 - 1) bytes in length. big string energy 💖
USTR4()
- Returns: Ustr string
- Type:
struct Ustr * - Parameter[1]: Encoded 4th byte of number of the length of Ustr string
- Type[1]:
symbol - Parameter[2]: Encoded 3rd byte of number of the length of Ustr string
- Type[2]:
symbol - Parameter[3]: Encoded 2nd byte of number of the length of Ustr string
- Type[3]:
symbol - Parameter[4]: Encoded 1st byte of number of the length of Ustr string
- Type[4]:
symbol - Parameter[5]: Data for Ustr string
- Type[5]:
const char[]
Explanation: this function works in the same way as USTR1() but takes four length bytes, so the read-only string can be up to 2**32 - 1 bytes in length. absolute unit of a string, no cap 😭
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. bestie check your work fr 💀
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 "". yep, empty string, that's the tell 🫶
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 "". same deal as the others, check ustr_len() and go "oh" 😭
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. ✨
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. (yes, that's what the page says — we're just relaying the vibes verbatim 🎀)
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. 💅
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. 🔥
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. 🦋
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 🌈
okay so now we're in the fixed-size era — where you bring the memory and Ustr just moves in and decorates 🎀
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. periodt 💅
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. (yes — the glow-up into allocated memory is real, and yes, you should still call ustr_free() just in case 😌)
Note: for simplicity you probably want to use USTR_SC_INIT_AUTO() or USTR_SC_INIT_AUTO() when possible. (that's literally what the page says, both of them, same name twice — we don't gatekeep, we report 📋)
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. 🙈 like, sizeof() can't see through a pointer bestie, it's doing its best.
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. same rule as before, the sizeof() vibe check does not pass for pointers, sorry bestie 💀
🫶 Debugging functions 🫶
Okay bestie, this is the "wait, is my Ustr actually okay?" toolbox. Use it when things smell weird.
ustr_assert_valid()
- Returns: Success or failure
- Type:
int - Parameter[1]: Pointer to a Ustr string — Type[1]:
Ustr *
This one runs a few internal consistency checks and is literally there to help you catch it when a Ustr has gone invalid. Little vibe check for your string 💅
Note: it callsustr_assert_ret(), so even whenUSTR_DEBUGis off the checks still get performed and the result still comes back to you. No sneaky silent skipping ✨
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
Calls ustr_assert_valid() and also checks that the position and length actually sit inside the Ustr. Not valid? You get 0. Valid? You get ustr_len(). That's the whole deal 🎀
USTR_CNTL_MALLOC_CHECK_BEG()
- Returns: Success or failure
- Type:
int - Parameter[1]: Condition for begin malloc checking or not — Type[1]:
int
Starts malloc checking, meaning every ustr allocation goes through the malloc check routines. But heads up: it fails if the condition check (Parameter[1]) fails. 🙈
Note: turning malloc checking on after one or more allocations have already happened will give you false failures — unless you truly, genuinely know what you're doing. Like, iykyk. You can also auto-turn it on by giving theUSTR_CNTL_MCenvironment variable the value of"1","yes"or"on".
USTR_CNTL_MALLOC_CHECK_LVL()
- Returns: Level of current malloc check
- Type:
int - Parameter[1]: Nothing — Type[1]:
void
Returns the current "level" of the malloc check — 0 means malloc check isn't enabled at all. The level goes up by one every time USTR_CNTL_MALLOC_CHECK_BEG() or USTR_CNTL_MALLOC_CHECK_ADD() returns success, and goes down by one every time USTR_CNTL_MALLOC_CHECK_DEL() or USTR_CNTL_MALLOC_CHECK_END() returns success. Nesting slay 🧚
USTR_CNTL_MALLOC_CHECK_MEM()
- Returns: Success or failure
- Type:
int - Parameter[1]: Pointer returned from malloc check — Type[1]:
void *
Asserts that the pointer (Parameter[1]) was allocated from malloc checking. That's it.
Note: unless you're doing something special, or you're using a builtinUstr_pool, it is very likely you just want to callUSTR_CNTL_MALLOC_CHECK_MEM_USTR()instead. Fr fr, save yourself the trouble 💀
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
Asserts the pointer (Parameter[1]) was allocated from malloc checking and that it has the specified size (Parameter[2]). Exact match energy 👑
Note: unless you're doing something special, or you're using a builtinUstr_pool, you very likely want to just callUSTR_CNTL_MALLOC_CHECK_MEM_USTR().
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
Same situation, but chiller: asserts the pointer (Parameter[1]) was allocated from malloc checking and has at least the specified size (Parameter[2]). Minimum, not exact 🌸
Note: unless you're doing something special, or you're using a builtinUstr_pool, it's very likely you just wantUSTR_CNTL_MALLOC_CHECK_MEM_USTR().
USTR_CNTL_MALLOC_CHECK_MEM_USTR()
- Returns: Success or failure
- Type:
int - Parameter[1]: Pointer to a Ustr string — Type[1]:
Ustr *
Asserts that the pointer (Parameter[1]) is a Ustr allocated from malloc checking. But if the Ustr isn't allocated at all? It returns TRUE — no drama, babe 🦋
Note: because of the layering between the Ustr code and the pool code, there's a trap: if you allocate an implicitly sizedUstrpfrom 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. That's literally whatUSTR_CNTL_MALLOC_CHECK_MEM_USTRP()exists for. Not me being dramatic, it's just the architecture 😭
USTR_CNTL_MALLOC_CHECK_MEM_USTRP()
- Returns: Success or failure
- Type:
int - Parameter[1]: Pointer to a Ustrp string — Type[1]:
Ustrp *
Asserts the pointer (Parameter[1]) is a Ustr allocated from a builtin pool using malloc checking. And again, if the Ustr isn't allocated, it returns TRUE. We love a forgiving queen 💖
USTR_CNTL_MALLOC_CHECK_END()
- Returns: Success or failure
- Type:
int - Parameter[1]: Nothing — Type[1]:
void
This macro cleans up any memory used by malloc check and asserts that no memory is left allocated. The grand finale cleanup 🎀
Note: if any memory is left allocated, every single one that's found gets output to stderr, along with the file/line/function of the level it was allocated from. Receipts, bestie 🧾
USTR_CNTL_MALLOC_CHECK_ADD()
- Returns: Success or failure
- Type:
int - Parameter[1]: Condition to begin malloc checking or not — Type[1]:
int
Works like USTR_CNTL_MALLOC_CHECK_END(), except it fails if the condition check (Parameter[1]) fails or if USTR_CNTL_MALLOC_CHECK_LVL() is zero. Two ways to fail, zero ways to be boring ✨
USTR_CNTL_MALLOC_CHECK_DEL()
- Returns: Success or failure
- Type:
int - Parameter[1]: Condition to end malloc checking or not — Type[1]:
int
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]) you pass to this macro should almost certainly be the return value from USTR_CNTL_MALLOC_CHECK_ADD(). Like, that's the intended pairing, don't fight it 🙏
💜 Creating allocated Ustr functions 💜
Now we're making brand-new Ustrs that you own. Main character allocation hours 🔥
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
Figuring out the exact amount of memory you need to store a Ustr with the config you picked. Math era 🧮
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
This creates a new Ustr string. Important though: you should have allocated that data via USTR_CONF_MALLOC() — otherwise bad things will happen if the Ustr string is ever free'd or reallocated. Like, genuinely bad. Do not skip this 💀
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
Creates an empty Ustr, owned by you, allocated from system memory — or it returns NULL. 🌈
The size (Parameter[1]) is the desired allocation size for the entire Ustr, including the overhead for metadata. It gets rounded up if it's too small, so passing 1 as the size means you want a stored size but want to allocate the smallest amount of memory possible. Tiny but mighty 🍓
The exact memory allocation flag (Parameter[3]) says whether 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 (Parameter[4]) sets the initial state of the user-visible flag for memory allocation errors. Examples: ustr_enomem(), ustr_setf_enomem_clr() and ustr_setf_enomem_err().
Note: the reference byte count can only be one of these values:0,1,2or4, or8(on environments with a 64bitsize_t). No improvising, bestie 🙈 It can be useful to ensure the Ustr is in system memory, so you can add things to it and check for errors withustr_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 of2.
ustr_dup_empty()
- Returns: Ustr string
- Type:
struct Ustr * - Parameter[1]: Nothing — Type[1]:
void
Same as calling ustr_dupx_empty() with the current set of default options. Convenience icon ✨
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
Works exactly like you called ustr_dupx_empty() and then ustr_add_undef(). Combo move 🎀
ustr_dup_undef()
- Returns: Pointer to a Ustr string
- Type:
struct Ustr * - Parameter[1]: Length of new undefined data — Type[1]:
size_t
Same as calling ustr_dupx_undef() with the current set of default options. Defaults forever 💅
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 *
This one tries to bump up the reference count on the Ustr string you passed in, and if that succeeds, it just returns that back to you. If it fails, it creates a brand-new Ustr string that looks identical to the old one — apart from the reference count. Either way you get a string, so, slay 🦋
Note:
Okay so real talk, bestie: because the new Ustr string is configured identically to the old Ustr string, the result can be very different from what you get if you call ustr_dup_buf() with ustr_cstr() and ustr_len() from the original string — because that route just uses whatever the default configuration is. 💅
Especially worth noting: 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. No cap. ✨
Function: ustr_dupx()
Returns: pointer to a Ustr string — struct Ustr *
- Parameter[1]: Size of allocated storage —
size_t - Parameter[2]: Number of bytes to use for reference count —
size_t - Parameter[3]: Exact memory allocations —
int - Parameter[4]:
ENOMEM, memory error flag —int - Parameter[5]: Pointer to a constant Ustr string —
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 — struct Ustr *
- Parameter[1]: A pointer to a pointer to a Ustr string —
struct Ustr **
Explanation: This function works like calling ustr_dup(), but if the reference count is maxed out and a new Ustr string has been allocated, that new string 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 to, 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 — struct Ustr *
- Parameter[1]: Size of allocated storage —
size_t - Parameter[2]: Number of bytes to use for reference count —
size_t - Parameter[3]: Exact memory allocations —
int - Parameter[4]:
ENOMEM, memory error flag —int - Parameter[5]: A pointer to a pointer to a Ustr string —
struct Ustr **
Explanation: This function works like calling ustr_dupx(), but if the reference count is maxed out and a new Ustr string is allocated, that new string 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 to, 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 — struct Ustr *
- Parameter[1]: Pointer to data —
const void * - Parameter[2]: Length of data —
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 — struct Ustr *
- Parameter[1]: Size of allocated storage —
size_t - Parameter[2]: Number of bytes to use for reference count —
size_t - Parameter[3]: Exact memory allocations —
int - Parameter[4]:
ENOMEM, memory error flag —int - Parameter[5]: Pointer to data —
const void * - Parameter[6]: Length of data —
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 — struct Ustr *
- Parameter[1]: Pointer to constant C-style string —
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 — struct Ustr *
- Parameter[1]: Size of allocated storage —
size_t - Parameter[2]: Number of bytes to use for reference count —
size_t - Parameter[3]: Exact memory allocations —
int - Parameter[4]:
ENOMEM, memory error flag —int - Parameter[5]: Pointer to constant C-style string —
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 — struct Ustr *
- Parameter[1]: A constant C-style string —
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 — struct Ustr *
- Parameter[1]: A symbol —
...
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 — struct Ustr *
- Parameter[1]: A pointer to a constant Ustr string —
const struct Ustr * - Parameter[2]: Position in the Ustr —
size_t - Parameter[3]: Length to add from the Ustr —
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 — struct Ustr *
- Parameter[1]: Size of allocated storage —
size_t - Parameter[2]: Number of bytes to use for reference count —
size_t - Parameter[3]: Exact memory allocations —
int - Parameter[4]:
ENOMEM, memory error flag —int - Parameter[5]: A pointer to a constant Ustr string —
const struct Ustr * - Parameter[6]: Position in the Ustr —
size_t - Parameter[7]: Length to add from the Ustr —
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 — struct Ustr *
- Parameter[1]: Byte value of data —
char - Parameter[2]: Length of bytes as data —
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 — struct Ustr *
- Parameter[1]: Size of allocated storage —
size_t - Parameter[2]: Number of bytes to use for reference count —
size_t - Parameter[3]: Exact memory allocations —
int - Parameter[4]:
ENOMEM, memory error flag —int - Parameter[5]: Byte value of data —
char - Parameter[6]: Length of bytes as data —
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 — struct Ustr *
- Parameter[1]: Separator to go between Ustr strings —
const struct Ustr * - Parameter[2]: A pointer to the first constant Ustr string —
const struct Ustr * - Parameter[3]: A pointer to the second constant Ustr string —
const struct Ustr * - Parameter[4]: Variable argument list variable, from
va_start()—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 — struct Ustr *
- Parameter[1]: Separator to go between Ustr strings —
const struct Ustr * - Parameter[2]: A pointer to the first constant Ustr string —
const struct Ustr * - Parameter[3]: A pointer to the second constant Ustr string —
const struct Ustr * - Parameter[4]: Zero or more pointers to constant Ustr strings and then
USTR_NULL—...
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 — struct Ustr *
- Parameter[1]: Size of allocated storage —
size_t - Parameter[2]: Number of bytes to use for reference count —
size_t - Parameter[3]: Exact memory allocations —
int - Parameter[4]:
ENOMEM, memory error flag —int - Parameter[5]: Separator to go between Ustr strings —
const struct Ustr * - Parameter[6]: A pointer to the first constant Ustr string —
const struct Ustr * Parameter[7]— a pointer to the second constant Ustr stringType[7]—const struct Ustr *
Parameter[8]— the variable argument list variable, straight fromva_start()Type[8]—va_list
Explanation:
It's literally the same energy as calling ustr_dupx() on the first Ustr string (Parameter[2]), then ustr_add() on the separator (Parameter[1]), then ustr_add() on the second Ustr string (Parameter[3]). And then that whole little routine repeats for every Ustr string chilling in the variable argument list (Parameter[4]) until it bumps into a USTR_NULL. 🌸
Note: bestie, this function does not pinky-promise to just take a reference to one of the Ustr strings you passed in — even if that's exactly what would've happened if you'd done all that manual calling yourself. No cap.
Function: ustr_sc_joinx()
Returns: pointer to a Ustr string — Type: struct Ustr *
Parameter[1]— size of allocated storageType[1]—size_t
Parameter[2]— number of bytes to use for the reference countType[2]—size_t
Parameter[3]— exact memory allocationsType[3]—int
Parameter[4]—ENOMEM, the memory error flagType[4]—int
Parameter[5]— the separator that goes between the Ustr stringsType[5]—const struct Ustr *
Parameter[6]— a pointer to the first constant Ustr stringType[6]—const struct Ustr *
Parameter[7]— a pointer to the second constant Ustr stringType[7]—const struct Ustr *
Parameter[8]— zero or more pointers to constant Ustr strings, and thenUSTR_NULLType[8]—...
Explanation:
This one just calls va_start() to grab a variable argument list, and then hands everything off to ustr_sc_vjoinx(). Middle-man behaviour honestly, but it slays. ✨
Function: ustr_sc_vconcat()
Returns: pointer to a Ustr string — Type: struct Ustr *
Parameter[1]— a pointer to the first constant Ustr stringType[1]—const struct Ustr *
Parameter[2]— the variable argument list variable, fromva_start()Type[2]—va_list
Explanation:
Works exactly like you called ustr_dup() on the first Ustr string (Parameter[1]), then ustr_add() on the second Ustr string (Parameter[3]). Then the whole thing loops for every Ustr string in the variable argument list (Parameter[4]) until a USTR_NULL shows up. 🦋
Note: again, no guarantee that it'll simply take a reference to one of the Ustr strings you handed over — even if that's what would've gone down if you'd done it manually. It's giving "trust me bro" energy but make it documented.
Function: ustr_sc_concat()
Returns: pointer to a Ustr string — Type: struct Ustr *
Parameter[1]— a pointer to the first constant Ustr stringType[1]—const struct Ustr *
Parameter[2]— zero or more pointers to constant Ustr strings, and thenUSTR_NULLType[2]—...
Explanation:
Calls va_start() to get a variable argument list, then calls ustr_sc_vconcat(). That's it, that's the whole personality. 💅
Function: ustr_sc_vconcatx()
Returns: pointer to a Ustr string — Type: struct Ustr *
Parameter[1]— size of allocated storageType[1]—size_t
Parameter[2]— number of bytes to use for the reference countType[2]—size_t
Parameter[3]— exact memory allocationsType[3]—int
Parameter[4]—ENOMEM, the memory error flagType[4]—int
Parameter[5]— a pointer to the first constant Ustr stringType[5]—const struct Ustr *
Parameter[6]— the variable argument list variable, fromva_start()Type[6]—va_list
Explanation:
Same deal as calling ustr_dupx() on the first Ustr string (Parameter[1]), then ustr_add() on the second Ustr string (Parameter[3]), repeating for everything in the variable argument list (Parameter[4]) until a USTR_NULL is reached. 🎀
Note: and once more for the people in the back — it doesn't guarantee it'll just take a reference to one of the Ustr strings you passed, even if that's what would happen if you did the above manually. iykyk.
Function: ustr_sc_concatx()
Returns: pointer to a Ustr string — Type: struct Ustr *
Parameter[1]— size of allocated storageType[1]—size_t
Parameter[2]— number of bytes to use for the reference countType[2]—size_t
Parameter[3]— exact memory allocationsType[3]—int
Parameter[4]—ENOMEM, the memory error flagType[4]—int
Parameter[5]— a pointer to the first constant Ustr stringType[5]—const struct Ustr *
Parameter[6]— zero or more pointers to constant Ustr strings, and thenUSTR_NULLType[6]—...
Explanation:
Calls va_start() to get the variable argument list, then calls ustr_sc_vconcatx(). Short king of a function. 👑
🗑️ Deleting a Ustr, or data within a Ustr 🗑️
Function: ustr_free()
Returns: nothing — Type: void
Parameter[1]— pointer to a UstrType[1]—struct Ustr *
Explanation:
Decrements the reference count on a Ustr (if there is one), and frees it if it's allocated and the reference count has dropped to zero. Cleanup era. 🧹
Note: if you pass it USTR_NULL, it does absolutely nothing. Zero drama.
Function: ustrp_free()
Returns: nothing — Type: void
Parameter[1]— pointer to a Ustr pool objectType[1]—struct Ustr_pool *
Parameter[2]— pointer to a Ustrp (a pool-allocated Ustr)Type[2]—struct Ustrp *
Explanation:
Acts like ustr_free(), except instead of the ustr system free it calls the pool_free member function of the Ustr_pool (Parameter[1]). Pool party rules. 🫧
Function: ustr_sc_free()
Returns: nothing — Type: void
Parameter[1]— a pointer to a pointer to a Ustr stringType[1]—struct Ustr **
Explanation:
Calls ustr_free() and then sets the pointer (Parameter[1]) to USTR_NULL — which is a noop when you hand it to ustr_free(). This is the anti-"double free" error hack, and honestly it's iconic for that. 🔥
Note: the point-to-the-pointer must be non-NULL, but the function also accepts a NULL ustr and just does nothing. So you can pass the same pointer to this thing a bunch of times and only the very first call does anything at all. no cap, spam it safely.
Function: ustr_sc_free2()
Returns: nothing — Type: void
Parameter[1]— a pointer to a pointer to a Ustr stringType[1]—struct Ustr **
Parameter[2]— pointer to a Ustr stringType[2]—struct Ustr *
Explanation:
Behaves like ustr_sc_free(), but instead of setting the pointer (Parameter[1]) to USTR_NULL, it sets it to the Ustr string (Parameter[2]). Swapping one for another, main character energy. 🌈
Note: the point-to-the-pointer must be non-NULL, and this function also accepts a NULL ustr to be freed and does nothing. So you can safely pass the same pointer toustr_sc_free()and then to this function. 💀 The passed value (Parameter[2]) shouldn't beUSTR_NULL— and in debugging mode the function willassert()that it isn't. literally do not test it.
Function: ustr_sc_free_shared()
Returns: nothing — Type: void
Parameter[1]— a pointer to a pointer to a Ustr stringType[1]—struct Ustr **
Explanation:
This is the easy-peasy way to "free" a Ustr string that's been shared (ustr_shared() returns USTR_TRUE) — because normally ustr_free() just gets ignored on a shared Ustr string. It simply calls ustr_setf_owner() and then ustr_sc_free(). Two steps, one slay. 🎀
Function: ustr_del()
Returns: success or failure — Type: int
Parameter[1]— pointer to a pointer to a Ustr stringType[1]—struct Ustr **
Parameter[2]— length to delete from the UstrType[2]—size_t
Explanation:
Deletes data off the end of the Ustr, and it might re-size the Ustr while it's at it.
Note: the Ustr is never re-sized when the size is stored explicitly, so the pointer never changes. Your pointer stays exactly where you left it, bestie. 📍
Function: ustr_del_subustr()
Returns: success or failure — Type: int
Parameter[1]— pointer to a pointer to a Ustr stringType[1]—struct Ustr **
Parameter[2]— position in the UstrType[2]—size_t
Parameter[3]— length to delete from the UstrType[3]—size_t
Explanation:
Works like ustr_del(), but it can delete an arbitrary section of the Ustr instead of just the tail end. Surgical. ✂️
Function: ustr_sc_del()
Returns: nothing — Type: void
Parameter[1]— a pointer to a pointer to a Ustr stringType[1]—struct Ustr **
Explanation:
Basically calling ustr_del() with ustr_len() as the length — except if that fails, it does a ustr_free() and then sets the pointer to USTR(""). Nuking it from orbit, gracefully. 💅
Note: the upside is that you don't have to check for memory failure errors yourself. The catch? If there is a memory failure and you're running a non-default configuration, the configuration reverts back to the default. trade-offs, babe.
💖 Adding data to a Ustr 💖
okay bestie, this cluster is all about making your Ustr bigger and pushing more data into it. every single one of these returns success or failure as an int, and they all take that pointer-to-a-pointer-to-a-Ustr situation, so keep an eye on your struct 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 🦋
now we're not just adding, we're setting — like a full little reset-and-fill moment, except every function here is still returning success or failure as an int, and still doing the struct Ustr ** dance 💖
💅 Function: ustr_set_undef() 💅
Returns: Success or failure — type int 💖
- Parameter[1]: Pointer to a pointer to a Ustr string — Type[1]:
struct Ustr ** - Parameter[2]:
size_t— Type[2]:size_t
Explanation: This function works as if you had called ustr_del() for the entire string and the ustr_add_undef() ✨.
🎀 Function: ustr_set_empty() 🎀
Returns: Success or failure — type int 💖
- Parameter[1]: Pointer to a pointer to a Ustr string — Type[1]:
struct Ustr **
Explanation: This function works as if you had called ustr_del() for the entire string, however the string will be allocated if this completes 🫶.
🌸 Function: ustr_set_buf() 🌸
Returns: Success or failure — type int 💖
- Parameter[1]: Pointer to a pointer to a Ustr string — Type[1]:
struct Ustr ** - Parameter[2]: Buffer containing data — Type[2]:
const void * - Parameter[3]: Length of Buffer — Type[3]:
size_t
Explanation: This function works as if you had called ustr_del() for the entire string and the ustr_add_buf() ✨.
🌈 Function: ustr_set_cstr() 🌈
Returns: Success or failure — type int 💖
- Parameter[1]: Pointer to a pointer to a Ustr string — Type[1]:
struct Ustr ** - Parameter[2]: A pointer to a constant C-style string — Type[2]:
const char *
Explanation: This function works as if you had called ustr_del() for the entire string and then ustr_add_cstr() 🫶.
💜 Function: USTR_SET_OSTR() 💜
Returns: Success or failure — type int 💖
- Parameter[1]: Pointer to a pointer to a Ustr string — Type[1]:
struct Ustr ** - Parameter[2]: A constant C-style string — Type[2]:
const char []
Explanation: This function works as if you had called ustr_del() for the entire string and then USTR_ADD_OSTR() ✨.
🍓 Function: USTR_SET_OBJ() 🍓
Returns: Success or failure — type int 💖
- Parameter[1]: Pointer to a pointer to a Ustr string — Type[1]:
struct Ustr ** - Parameter[2]: A symbol — Type[2]:
...
Explanation: This function works as if you had called ustr_del() for the entire string and then USTR_ADD_OBJ() 👑
Note: In most cases you'll want to use USTR_SET_OSTR() 💅
🧚 Function: ustr_set() 🧚
Returns: Success or failure — type int 💖
- Parameter[1]: Pointer to a pointer to a Ustr string — Type[1]:
struct Ustr ** - Parameter[2]: A pointer to a constant Ustr string — Type[2]:
const struct Ustr *
Explanation: This function works as if you had called ustr_del() for the entire string and the ustr_add() 🫶.
🌟 Function: ustr_set_subustr() 🌟
Returns: Success or failure — type int 💖
- Parameter[1]: Pointer to a pointer to a Ustr string — Type[1]:
struct Ustr ** - Parameter[2]: A pointer to a constant Ustr string — Type[2]:
const struct Ustr * - Parameter[3]: Position in the Ustr — Type[3]:
size_t - Parameter[4]: Length to set from the Ustr — Type[4]:
size_t
Explanation: This function works as if you had called ustr_del() for the entire string and the ustr_add_subustr(). The exception being if you set a ustr to itself, while only having a single reference count, the simple method would access a free'd ustr data, but this function just works 😭✨.
🎀 Function: ustr_set_rep_chr() 🎀
Returns: Success or failure — type int 💖
- Parameter[1]: Pointer to a pointer to a Ustr string — Type[1]:
struct Ustr ** - Parameter[2]: Byte value of data — Type[2]:
char - Parameter[3]: Length of bytes as data — Type[3]:
size_t
Explanation: This function works as if you had called ustr_del() for the entire string and the ustr_add_rep_chr() 🫶.
🎀 Inserting data into a Ustr 🎀
okay so inserting is the ✨glow-up✨ version of adding, because you get to say where. Every one of these takes a position after which the new data goes, and ngl that + 1 detail matters — iykyk.
🌸 ustr_ins_undef()
- Returns: success or failure
- Type:
int - Parameter[1]: a pointer to a pointer to a Ustr string —
struct Ustr ** - Parameter[2]: position after which the data should be added —
size_t - Parameter[3]: length of new undefined data —
size_t
Explanation: the Ustr string gets expanded (possibly reallocated, so bestie, watch that pointer 👀) so 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, rip 😭. The data in the Ustr is moved as needed to put the new data at position (Parameter[2]) + 1.
🦋 ustr_ins_buf()
- Returns: success or failure
- Type:
int - Parameter[1]: pointer to a pointer to a Ustr string —
struct Ustr ** - Parameter[2]: position after which the data should be added —
size_t - Parameter[3]: pointer to data —
const void * - Parameter[4]: length of data —
size_t
Explanation: this one works as if you'd called ustr_ins_undef() and then copied the data into the new undefined space. That's it, that's the vibe 💅
🧚 ustr_ins_cstr()
- Returns: success or failure
- Type:
int - Parameter[1]: pointer to a pointer to a Ustr string —
struct Ustr ** - Parameter[2]: position after which the data should be added —
size_t - Parameter[3]: pointer to constant C-style string —
const char *
Explanation: works as if you'd called ustr_ins_buf() and passed strlen() as the length. classic, no notes ✨
💜 USTR_INS_OSTR()
- Returns: success or failure
- Type:
int - Parameter[1]: pointer to a pointer to a Ustr string —
struct Ustr ** - Parameter[2]: position after which the data should be added —
size_t - Parameter[3]: a constant C-style string —
const char []
Explanation: works as if you'd called ustr_ins_buf() and passed sizeof() - 1 as the length. (You're inserting a string literal here, and it ate 🔥)
👑 USTR_INS_OBJ()
- Returns: success or failure
- Type:
int - Parameter[1]: pointer to a pointer to a Ustr string —
struct Ustr ** - Parameter[2]: position after which the data should be added —
size_t - Parameter[3]: a symbol —
...
Explanation: works as if you'd called ustr_ins_buf() and passed sizeof() as the length.
Note: in most cases you'll want to use USTR_INS_OSTR(). Like, fr fr, that's the one.
🍓 ustr_ins()
- Returns: success or failure
- Type:
int - Parameter[1]: pointer to a pointer to a Ustr string —
struct Ustr ** - Parameter[2]: position after which the data should be added —
size_t - Parameter[3]: a pointer to a constant Ustr string —
const struct Ustr *
Explanation: works as if you'd called ustr_ins_buf() with the ustr_cstr() and ustr_len() values of the Ustr string to be added. Ustr-on-Ustr action, we love to see it 🫶
🌈 ustr_ins_subustr()
- Returns: success or failure
- Type:
int - Parameter[1]: pointer to a pointer to a Ustr string —
struct Ustr ** - Parameter[2]: position after which the data should be added —
size_t - Parameter[2]: a pointer to a constant Ustr string —
const struct Ustr * - Parameter[3]: position in the Ustr —
size_t - Parameter[4]: length to ins from the Ustr —
size_t
Explanation: this one mostly works as if you'd called ustr_ins_buf() with the ustr_cstr() + position - 1 and length values of the Ustr string to be insed. The exception — and this is the iconic part — is if you insert a ustr into itself while only having a single reference count: the simple method would go and access freed ustr data 💀, but this function just works. main character energy, honestly.
⭐ ustr_ins_rep_chr()
- Returns: success or failure
- Type:
int - Parameter[1]: pointer to a pointer to a Ustr string —
struct Ustr ** - Parameter[2]: position after which the data should be added —
size_t - Parameter[2]: byte value of data —
char - Parameter[3]: length of bytes as data —
size_t
Explanation: works as if you'd called ustr_ins_undef() and then copied the byte value to each position. repeated char moment, we love a pattern 🌸
💖 Adding, duplicating and setting formatted data to a Ustr 💖
the *fmt* girlies are here and they're all basically "do the snprintf() thing, then hand it to the buffer function." every single one of them. no cap. keep an eye on which parameter number each explanation points at, because that's just how it's written 🫠
🎀 ustr_add_vfmt_lim()
- Returns: success or failure
- Type:
int - Parameter[1]: a pointer to a pointer to a Ustr string —
struct Ustr ** - Parameter[2]: limit of data to add —
size_t - Parameter[3]: a pointer to a constant C-style string —
const char * - Parameter[4]: variable argument list variable, from
va_start()—va_list
Explanation: works like calling the system vsnprintf() with the limit (Parameter[2]) as the limit to vsnprintf() and then calling ustr_add_buf().
🦋 ustr_add_vfmt()
- Returns: success or failure
- Type:
int - Parameter[1]: a pointer to a pointer to a Ustr string —
struct Ustr ** - Parameter[2]: a pointer to a constant C-style string —
const char * - Parameter[3]: variable argument list variable, from
va_start()—va_list
Explanation: works like calling the system vsnprintf() and then calling ustr_add_buf().
✨ ustr_add_fmt_lim()
- Returns: success or failure
- Type:
int - Parameter[1]: a pointer to a pointer to a Ustr string —
struct Ustr ** - Parameter[2]: limit of data to add —
size_t - Parameter[3]: a pointer to a constant C-style string —
const char * - Parameter[4]: options depending on value of Parameter[3] —
...
Explanation: works like calling the system snprintf() with the limit (Parameter[2]) as the limit to snprintf() and then calling ustr_add_buf().
🔥 ustr_add_fmt()
- Returns: success or failure
- Type:
int - Parameter[1]: a pointer to a pointer to a Ustr string —
struct Ustr ** - Parameter[2]: a pointer to a constant C-style string —
const char * - Parameter[3]: options depending on value of Parameter[2] —
...
Explanation: works like calling the system snprintf() and then calling ustr_add_buf().
💜 ustr_dup_vfmt_lim()
- Returns: pointer to a Ustr string
- Type:
struct Ustr * - Parameter[1]: limit of data to dup —
size_t - Parameter[2]: pointer to a constant Ustr string —
const char * - Parameter[3]: variable argument list variable, from
va_start()—va_list
Explanation: works like calling the system vsnprintf() with the limit (Parameter[2]) as the limit to vsnprintf() and then calling ustr_dup_buf().
🧚 ustr_dup_vfmt()
- Returns: pointer to a Ustr string
- Type:
struct Ustr * - Parameter[1]: limit of data to dup —
size_t - Parameter[2]: pointer to a constant Ustr string —
const char * - Parameter[3]: variable argument list variable, from
va_start()—va_list
Explanation: works like calling the system vsnprintf() and then calling ustr_dup_buf().
🌸 ustr_dup_fmt_lim()
- Returns: pointer to a Ustr string
- Type:
struct Ustr * - Parameter[1]: limit of data to dup —
size_t - Parameter[2]: pointer to a constant Ustr string —
const char * - Parameter[3]: options depending on value of Parameter[2] —
...
Explanation: works like calling the system snprintf() with the limit (Parameter[2]) as the limit to snprintf() and then calling ustr_dup_buf().
👑 ustr_dup_fmt()
- Returns: pointer to a Ustr string
- Type:
struct Ustr * - Parameter[1]: pointer to a constant Ustr string —
const char * - Parameter[2]: options depending on value of Parameter[1] —
...
Explanation: works like calling the system snprintf() and then calling ustr_dup_buf().
🌈 ustr_dupx_fmt_lim()
- Returns: pointer to a Ustr string
- Type:
struct Ustr * - Parameter[1]: size of allocated storage —
size_t - Parameter[2]: number of bytes to use for reference count —
size_t - Parameter[3]: exact memory allocations —
int - Parameter[4]:
ENOMEM, memory error flag —int - Parameter[5]: limit of data to dup —
size_t - Parameter[6]: pointer to a constant Ustr string —
const char * - Parameter[7]: options depending on value of Parameter[6] —
...
Explanation: works like calling the system snprintf() with the limit (Parameter[2]) as the limit to snprintf() and then calling ustr_dupx_buf(). (yes, seven parameters. she's that girl 💅)
⭐ ustr_dupx_fmt()
- Returns: pointer to a Ustr string
- Type:
struct Ustr * - Parameter[1]: size of allocated storage —
size_t - Parameter[2]: number of bytes to use for reference count —
size_t - Parameter[3]: exact memory allocations —
int - Parameter[4]:
ENOMEM, memory error flag —int - Parameter[5]: pointer to a constant Ustr string —
const char * - Parameter[6]: options depending on value of Parameter[5] —
...
Explanation: works like calling the system snprintf() and then calling ustr_dup_bufx().
🍓 ustr_set_vfmt_lim()
- Returns: success or failure
- Type:
int - Parameter[1]: a pointer to a pointer to a Ustr string —
struct Ustr ** - Parameter[2]: limit of data to set —
size_t - Parameter[3]: a pointer to a constant C-style string —
const char * - Parameter[4]: variable argument list variable, from
va_start()—va_list
Explanation: works like calling ustr_del() for all the data and then ustr_add_vfmt_lim(). wipe the slate, then go off ✨
🦋 ustr_set_vfmt()
- Returns: success or failure
- Type:
int - Parameter[1]: a pointer to a pointer to a Ustr string —
struct Ustr ** - Parameter[2]: a pointer to a constant C-style string —
const char * - Parameter[3]: variable argument list variable, from
va_start()—va_list
Explanation: works like calling ustr_del() for all the data and then ustr_add_vfmt().
🎀 ustr_set_fmt_lim()
- Returns: success or failure
- Type:
int - Parameter[1]: a pointer to a pointer to a Ustr string —
struct Ustr ** - Parameter[2]: limit of data to set —
size_t - Parameter[3]: a pointer to a constant C-style string —
const char * - Parameter[4]: options depending on value of Parameter[3] —
...
Explanation: okay so this one's explanation is literally mid-thought over here 😭 hold that thought — it picks up right where this leaves off, and I am not about to improvise on you 🫶
This function works like calling ustr_del() for all the data and then ustr_add_fmt_lim(). Short, sweet, and lowkey iconic. 💅
🌸 Function: ustr_set_fmt() 🌸
Returns: Success or failure — Type: int
Parameter[1]— A pointer to a pointer to a Ustr string — Type:struct Ustr **Parameter[2]— A pointer to a constant C-style string — Type:const char *Parameter[3]— Options depending on value ofParameter[2]— Type:...
Explanation:
This function works like calling ustr_del() for all the data and then ustr_add_fmt(). Clean slate energy, no cap. ✨
🦋 Function: ustr_ins_vfmt_lim() 🦋
Returns: Success or failure — Type: int
Parameter[1]— A pointer to a pointer to a Ustr string — Type:struct Ustr **Parameter[2]— Position after which the data should be added — Type:size_tParameter[3]— Limit of data to insert — Type:size_tParameter[4]— A pointer to a constant C-style string — Type:const char *Parameter[5]— Variable argument list variable, fromva_start()— Type: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(). Basically: format it with a cap, then insert it. Obsessed. 💖
🎀 Function: ustr_ins_vfmt() 🎀
Returns: Success or failure — Type: int
Parameter[1]— A pointer to a pointer to a Ustr string — Type:struct Ustr **Parameter[2]— Position after which the data should be added — Type:size_tParameter[3]— A pointer to a constant C-style string — Type:const char *Parameter[4]— Variable argument list variable, fromva_start()— Type:va_list
Explanation:
This function works like calling the system vsnprintf() and then calling ustr_ins_buf(). No limit era — just vibes and formatting. 🌈
⭐ Function: ustr_ins_fmt_lim() ⭐
Returns: Success or failure — Type: int
Parameter[1]— A pointer to a pointer to a Ustr string — Type:struct Ustr **Parameter[2]— Position after which the data should be added — Type:size_tParameter[3]— Limit of data to insert — Type:size_tParameter[4]— A pointer to a constant C-style string — Type:const char *Parameter[5]— Options depending on value ofParameter[4]— Type:...
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(). Limit set, boundaries respected, we love to see it. 👑
💜 Function: ustr_ins_fmt() 💜
Returns: Success or failure — Type: int
Parameter[1]— A pointer to a pointer to a Ustr string — Type:struct Ustr **Parameter[2]— Position after which the data should be added — Type:size_tParameter[3]— A pointer to a constant C-style string — Type:const char *Parameter[4]— Options depending on value ofParameter[3]— Type:...
Explanation:
This function works like calling the system snprintf() and then calling ustr_ins_buf(). Format, then insert — the classic duo. 🫶
🌺 Function: ustr_sub_vfmt_lim() 🌺
Returns: Success or failure — Type: int
Parameter[1]— A pointer to a pointer to a Ustr string — Type:struct Ustr **Parameter[2]— Position where to start substitution — Type:size_tParameter[3]— Limit of data to substitute — Type:size_tParameter[4]— A pointer to a constant C-style string — Type:const char *Parameter[5]— Variable argument list variable, fromva_start()— Type: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(). Swap-in with a cap, periodt. 🍓
🧚 Function: ustr_sub_vfmt() 🧚
Returns: Success or failure — Type: int
Parameter[1]— A pointer to a pointer to a Ustr string — Type:struct Ustr **Parameter[2]— Position where to start substitution — Type:size_tParameter[3]— A pointer to a constant C-style string — Type:const char *Parameter[4]— Variable argument list variable, fromva_start()— Type:va_list
Explanation:
This function works like calling the system vsnprintf() and then calling ustr_sub_buf(). Substitute era, unlimited format energy. ✨
🔥 Function: ustr_sub_fmt_lim() 🔥
Returns: Success or failure — Type: int
Parameter[1]— A pointer to a pointer to a Ustr string — Type:struct Ustr **Parameter[2]— Position where to start substitution — Type:size_tParameter[3]— Limit of data to substitute — Type:size_tParameter[4]— A pointer to a constant C-style string — Type:const char *Parameter[5]— Options depending on value ofParameter[4]— Type:...
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(). Cap it, format it, substitute it. Slay. 💅
👑 Function: ustr_sub_fmt() 👑
Returns: Success or failure — Type: int
Parameter[1]— A pointer to a pointer to a Ustr string — Type:struct Ustr **Parameter[2]— Position where to start substitution — Type:size_tParameter[3]— A pointer to a constant C-style string — Type:const char *Parameter[4]— Options depending on value ofParameter[3]— Type:...
Explanation:
This function works like calling the system snprintf() and then calling ustr_sub_buf(). Formatting and substitution, bestie — the main character combo. 🌟
🌈 Function: ustr_sc_sub_vfmt_lim() 🌈
Returns: Success or failure — Type: int
Parameter[1]— A pointer to a pointer to a Ustr string — Type:struct Ustr **Parameter[2]— Position where to start substitution — Type:size_tParameter[3]— Length of substitution — Type:size_tParameter[4]— Limit of data to substitute — Type:size_tParameter[5]— A pointer to a constant C-style string — Type:const char *Parameter[6]— Variable argument list variable, fromva_start()— Type: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(). Length plus limit plus format — she's doing the most, and honestly? Ate. 💖
💀 Function: ustr_sc_sub_vfmt() 💀
Returns: Success or failure — Type: int
Parameter[1]— A pointer to a pointer to a Ustr string — Type:struct Ustr **Parameter[2]— Position where to start substitution — Type:size_tParameter[3]— Length of substitution — Type:size_tParameter[4]— A pointer to a constant C-style string — Type:const char *Parameter[5]— Variable argument list variable, fromva_start()— Type:va_list
Explanation:
This function works like calling the system vsnprintf() and then calling ustr_sc_sub_buf(). Length-aware substitute with va-list energy — no cap, just format. 🦋
🌸 Function: ustr_sc_sub_fmt_lim() 🌸
Returns: Success or failure — Type: int
Parameter[1]— A pointer to a pointer to a Ustr string — Type:struct Ustr **Parameter[2]— Position where to start substitution — Type:size_tParameter[3]— Length of substitution — Type:size_tParameter[4]— Limit of data to substitute — Type:size_tParameter[5]— A pointer to a constant C-style string — Type:const char *Parameter[6]— Options depending on value ofParameter[5]— Type:...
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(). Yes — the manual says Parameter[3] here, and we're just reporting it exactly, bestie. 💀✨
🎀 Function: ustr_sc_sub_fmt() 🎀
Returns: Success or failure — Type: int
Parameter[1]— A pointer to a pointer to a Ustr string — Type:struct Ustr **Parameter[2]— Position where to start substitution — Type:size_tParameter[3]— Length of substitution — Type:size_tParameter[4]— A pointer to a constant C-style string — Type:const char *Parameter[5]— Options depending on value ofParameter[5]— Type:...
Explanation:
This function works like calling the system snprintf() and then calling ustr_sc_sub_buf(). Format it, substitute it with a length, and let the function handle the rest. 💅
✨ Accessing the variables of a Ustr ✨
Okay bestie, this is the part where you peek at what a Ustr is actually holding. No cap, these little functions are the vibe check for your string’s internals 💅
🌸 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 one hands you the length of the data inside the Ustr, kinda like strlen() but it won’t get the answer wrong when there are extra NIL bytes chilling in there. Iconic behavior, honestly.
🦋 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 gives you a read-only pointer to the beginning of the Ustr’s data. And because a Ustr always has a terminating NIL byte, this pointer is also a valid C-style string. Slay.
🎀 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 gives you a writable pointer to the start of the Ustr’s data. Again, since there’s always a terminating NIL byte, it doubles as a valid C-style string. However, if the ustr is read-only (ustr_ro() == USTR_TRUE), this function returns NULL.
Note: Unless the string is owned (ustr_owner() == USTR_TRUE), changing data through this pointer can be a very bad idea, because then every reference gets updated too. Seeustr_sc_wstr(). Like, don’t just start editing shared data, bestie 😭
💜 Function: ustr_alloc() 💜
- Returns: A boolean flag of either
USTR_TRUEorUSTR_FALSE - Type:
int - Parameter[1]: A pointer to a constant Ustr string
- Type[1]:
const struct Ustr *
Explanation: Tells you if the Ustr is currently living in allocated storage. Simple as that.
🌈 Function: ustr_exact() 🌈
- Returns: A boolean flag of either
USTR_TRUEorUSTR_FALSE - Type:
int - Parameter[1]: A pointer to a constant Ustr string
- Type[1]:
const struct Ustr *
Explanation: This one tells you if the Ustr is doing exact allocations, meaning as it grows it only gets storage allocated exactly as needed, not in half powers of two.
Note: This will always beUSTR_FALSEfor read-onlyUstrstrings (ustr_ro() == USTR_TRUE), even though the default may be to use exact sized allocations when adding data to them etc.
💫 Function: ustr_sized() 💫
- Returns: A boolean flag of either
USTR_TRUEorUSTR_FALSE - Type:
int - Parameter[1]: A pointer to a constant Ustr string
- Type[1]:
const struct Ustr *
Explanation: Tells you if the Ustr stores an explicit allocation size. If not, the size is implied as the next highest half power of two. Math but make it string storage ✨
🍓 Function: ustr_ro() 🍓
- Returns: A boolean flag of either
USTR_TRUEorUSTR_FALSE - Type:
int - Parameter[1]: A pointer to a constant Ustr string
- Type[1]:
const struct Ustr *
Explanation: Says if the Ustr is currently in read-only storage. Read-only storage is not writable, but it can be referenced via ustr_dup() an infinite number of times. Obsessed with a storage mode that never gets tired.
🌸 Function: ustr_fixed() 🌸
- Returns: A boolean flag of either
USTR_TRUEorUSTR_FALSE - Type:
int - Parameter[1]: A pointer to a constant Ustr string
- Type[1]:
const struct Ustr *
Explanation: Says if the Ustr is currently in fixed size storage. Fixed size storage is writable, but it 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_TRUEorUSTR_FALSE - Type:
int - Parameter[1]: A pointer to a constant Ustr string
- Type[1]:
const struct Ustr *
Explanation: This 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(). It gets automatically set to on whenever a memory allocation failure happens for a Ustr.
Note: If aUstris referenced multiple times,ustr_setf_enomem_err()will fail. This always fails forUstr’s in read-only storage.
🦋 Function: ustr_shared() 🦋
- Returns: A boolean flag of either
USTR_TRUEorUSTR_FALSE - Type:
int - Parameter[1]: A pointer to a constant Ustr string
- Type[1]:
const struct Ustr *
Explanation: 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 a Ustr can be referenced and unreferenced an infinite number of times.
Note: This always succeeds forUstr’s in read-only storage. This always fails forUstr’s in fixed size storage.
💅 Function: ustr_limited() 💅
- Returns: A boolean flag of either
USTR_TRUEorUSTR_FALSE - Type:
int - Parameter[1]: A pointer to a constant Ustr string
- Type[1]:
const struct Ustr *
Explanation: Says if the Ustr is currently in fixed size storage and cannot move to allocated storage.
Note: This always fails forUstr’s in allocated storage. This always fails forUstr’s in read-only storage.
👑 Function: ustr_owner() 👑
- Returns: A boolean flag of either
USTR_TRUEorUSTR_FALSE - Type:
int - Parameter[1]: A pointer to a constant Ustr string
- Type[1]:
const struct Ustr *
Explanation: Says if there is only a single reference to the Ustr string. Main character energy: it’s the only one holding the string.
Note: This always fails forUstr’s in read-only storage. This always succeeds forUstr’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: Calculates the maximum amount of data that could be stored (i.e. 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: 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: 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: Gives you the configuration of the current Ustr that you need 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 theustr_exact()etc. functions in that it returns the global options if thisUstrisn’t allocated, thus telling you what the configuration would be if theUstrwas turned into an allocatedUstrby adding data etc. Zero references for an allocatedUstrwith 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: Sets the enomem flag, which you can observe via the ustr_enomem() function. The implication of setting this flag is that a memory error has occurred in a previous function call on this Ustr.
Note: This function fails ifustr_owner()fails for theUstr.
🌸 Function: ustr_setf_enomem_clr() 🌸
- Returns: Success or failure
- Type:
int - Parameter[1]: A pointer to a Ustr string
- Type[1]:
struct Ustr *
Explanation: Clears the enomem flag, which you can observe via the ustr_enomem() function. The implication of this flag being set is that a memory error has occurred in a previous function call on this Ustr, so on clearing the flag you should know you have brought the Ustr back to a known state.
Note: This function fails ifustr_owner()fails for theUstr.
🦋 Function: ustr_setf_share() 🦋
- Returns: Success or failure
- Type:
int - Parameter[1]: A pointer to a Ustr string
- Type[1]:
struct Ustr *
Explanation: Sets the shared mode, which you can observe 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 its reference count. After this call the Ustr can be referenced and unreferenced an infinite number of times.
Note: After this call theUstrwill never be deleted untilustr_setf_owner()is called. This function fails ifustr_alloc()fails for theUstr.
👑 Function: ustr_setf_owner() 👑
- Returns: Success or failure
- Type:
int - Parameter[1]: A pointer to a Ustr string
- Type[1]:
struct Ustr *
Explanation: Removes the shared mode, which you can observe via the ustr_shared() function. This is used so that a Ustr in shared mode can be freed.
Note: This function fails ifustr_alloc()fails for theUstr.
🌈 Comparing data in a Ustr 🌈
💫 Function: ustr_cmp_buf() 💫
- Returns: Less than 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: Works like memcmp() on the Ustr and the passed data.
🍓 Function: ustr_cmp() 🍓
- Returns: Less than 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: Works like ustr_cmp_buf() but with the data from ustr_cstr() and the length from ustr_len().
💅 Function: ustr_cmp_subustr() 💅
- Returns: Less than 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 —
size_t - Parameter[4]: Length to compare from the Ustr —
size_t
Explanation: This function works like ustr_cmp() but with a limit on the data and length. (yes bestie, it's the "only look at this slice" version 💅)
🦋 ustr_cmp_cstr()
Returns: Less than zero, zero, or greater than zero depending on the comparison Type: int
- Parameter[1]: A pointer to a constant Ustr string —
const struct Ustr * - Parameter[2]: A pointer to a constant C-style string —
const char *
Explanation: This function works like ustr_cmp_buf() but with a length from strlen().
🦋 ustr_cmp_fast_buf()
Returns: Less than zero, zero, or greater than zero depending on the comparison Type: int
- Parameter[1]: A pointer to a constant Ustr string —
const struct Ustr * - Parameter[2]: A pointer to constant bytes, to compare —
const void * - Parameter[3]: Length of comparison bytes —
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. like, it ate and left no crumbs for readability 😭 the machine is thriving, your eyeballs are not
🦋 ustr_cmp_fast()
Returns: Less than zero, zero, or greater than zero depending on the comparison Type: int
- Parameter[1]: A pointer to a constant Ustr string —
const struct Ustr * - Parameter[2]: A pointer to a constant Ustr string —
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().
🦋 ustr_cmp_fast_subustr()
Returns: Less than zero, zero, or greater than zero depending on the comparison Type: int
- Parameter[1]: A pointer to a constant Ustr string —
const struct Ustr * - Parameter[2]: A pointer to a constant Ustr string —
const struct Ustr * - Parameter[3]: Position in the Ustr —
size_t - Parameter[4]: Length to compare from the Ustr —
size_t
Explanation: This function works like ustr_cmp_fast() but with a limit on the data and length.
🦋 ustr_cmp_fast_cstr()
Returns: Less than zero, zero, or greater than zero depending on the comparison Type: int
- Parameter[1]: A pointer to a constant Ustr string —
const struct Ustr * - Parameter[2]: A pointer to a constant C-style string —
const char *
Explanation: This function works like ustr_cmp_fast_buf() but with a length from strlen().
🎀 ustr_cmp_case_buf()
Returns: Less than zero, zero, or greater than zero depending on the comparison Type: int
- Parameter[1]: A pointer to a constant Ustr string —
const struct Ustr * - Parameter[2]: A pointer to constant bytes, to compare —
const void * - Parameter[3]: Length of comparison bytes —
size_t
Explanation: This function works like ustr_cmp_buf() but the order of comparison ignores ASCII case. so A and a are the same girlie here, no cap 💖
🎀 ustr_cmp_case()
Returns: Less than zero, zero, or greater than zero depending on the comparison Type: int
- Parameter[1]: A pointer to a constant Ustr string —
const struct Ustr * - Parameter[2]: A pointer to a constant Ustr string —
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().
🎀 ustr_cmp_case_subustr()
Returns: Less than zero, zero, or greater than zero depending on the comparison Type: int
- Parameter[1]: A pointer to a constant Ustr string —
const struct Ustr * - Parameter[2]: A pointer to a constant Ustr string —
const struct Ustr * - Parameter[3]: Position in the Ustr —
size_t - Parameter[4]: Length to compare from the Ustr —
size_t
Explanation: This function works like ustr_cmp_case() but with a limit on the data and length.
🎀 ustr_cmp_case_cstr()
Returns: Less than zero, zero, or greater than zero depending on the comparison Type: int
- Parameter[1]: A pointer to a constant Ustr string —
const struct Ustr * - Parameter[2]: A pointer to a constant C-style string —
const char *
Explanation: This function works like ustr_cmp_case_buf() but with a length from strlen().
✨ the _eq girlies — same energy, just a yes/no answer ✨
Heads up bestie: all of these return success or failure as an int, instead of the whole less-than/zero/greater-than situation. So much chiller to read 🫶
💜 ustr_cmp_eq()
Returns: Success or failure Type: int
- Parameter[1]: A pointer to a constant Ustr string —
const struct Ustr * - Parameter[2]: A pointer to a constant Ustr string —
const struct Ustr *
Explanation: This function works like comparing ustr_cmp() against 0.
💜 ustr_cmp_buf_eq()
Returns: Success or failure Type: int
- Parameter[1]: A pointer to a constant Ustr string —
const struct Ustr * - Parameter[2]: A pointer to constant bytes, to compare —
const void * - Parameter[3]: Length of comparison bytes —
size_t
Explanation: This function works like comparing ustr_cmp_buf() against 0.
💜 ustr_cmp_subustr_eq()
Returns: Success or failure Type: int
- Parameter[1]: A pointer to a constant Ustr string —
const struct Ustr * - Parameter[2]: A pointer to a constant Ustr string —
const struct Ustr * - Parameter[3]: Position in the Ustr —
size_t - Parameter[4]: Length to compare from the Ustr —
size_t
Explanation: This function works like comparing ustr_cmp_subustr() against 0.
💜 ustr_cmp_cstr_eq()
Returns: Success or failure Type: int
- Parameter[1]: A pointer to a constant Ustr string —
const struct Ustr * - Parameter[2]: A pointer to a constant C-style string —
const char *
Explanation: This function works like comparing ustr_cmp_cstr() against 0.
💜 ustr_cmp_case_eq()
Returns: Success or failure Type: int
- Parameter[1]: A pointer to a constant Ustr string —
const struct Ustr * - Parameter[2]: A pointer to a constant Ustr string —
const struct Ustr *
Explanation: This function works like comparing ustr_cmp_case() against 0.
💜 ustr_cmp_case_buf_eq()
Returns: Success or failure Type: int
- Parameter[1]: A pointer to a constant Ustr string —
const struct Ustr * - Parameter[2]: A pointer to constant bytes, to compare —
const void * - Parameter[3]: Length of comparison bytes —
size_t
Explanation: This function works like comparing ustr_cmp_case_buf() against 0.
💜 ustr_cmp_case_subustr_eq()
Returns: Success or failure Type: int
- Parameter[1]: A pointer to a constant Ustr string —
const struct Ustr * - Parameter[2]: A pointer to a constant Ustr string —
const struct Ustr * - Parameter[3]: Position in the Ustr —
size_t - Parameter[4]: Length to compare from the Ustr —
size_t
Explanation: This function works like comparing ustr_cmp_case_subustr() against 0.
💜 ustr_cmp_case_cstr_eq()
Returns: Success or failure Type: int
- Parameter[1]: A pointer to a constant Ustr string —
const struct Ustr * - Parameter[2]: A pointer to a constant C-style string —
const char *
Explanation: This function works like comparing ustr_cmp_case_cstr() against 0.
🌈 the _prefix_eq besties — "does it start with this?" energy 🌈
Okay so these ones are the iconique "is this a prefix of that?" checks. The comparison is capped at the length of the right hand side, so the left side gets to be longer and it's still a slay ✅
🌸 ustr_cmp_prefix_eq()
Returns: Success or failure Type: int
- Parameter[1]: A pointer to a constant Ustr string —
const struct Ustr * - Parameter[2]: A pointer to a constant Ustr string —
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.
🌸 ustr_cmp_prefix_buf_eq()
Returns: Success or failure Type: int
- Parameter[1]: A pointer to a constant Ustr string —
const struct Ustr * - Parameter[2]: A pointer to constant bytes, to compare —
const void * - Parameter[3]: Length of comparison bytes —
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]).
🌸 ustr_cmp_prefix_cstr_eq()
Returns: Success or failure Type: int
- Parameter[1]: A pointer to a constant Ustr string —
const struct Ustr * - Parameter[2]: A pointer to a constant C-style string —
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.
🌸 ustr_cmp_prefix_subustr_eq()
Returns: Success or failure Type: int
- Parameter[1]: A pointer to a constant Ustr string —
const struct Ustr * - Parameter[2]: A pointer to a constant Ustr string —
const struct Ustr * - Parameter[3]: Position in the Ustr —
size_t - Parameter[4]: Length to compare from the Ustr —
size_t
Explanation: This function works like comparing ustr_cmp_subustr() against 0, but the comparison is limited to the given length (Parameter[4]).
🌸 ustr_cmp_case_prefix_eq()
Returns: Success or failure Type: int
- Parameter[1]: A pointer to a constant Ustr string —
const struct Ustr * - Parameter[2]: A pointer to a constant Ustr string —
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. (and yes, it's still ignoring ASCII case, bestie — the case is right there in the name 💅)
🌸 ustr_cmp_case_prefix_buf_eq()
Returns: Success or failure Type: int
- Parameter[1]: A pointer to a constant Ustr string —
const struct Ustr * - Parameter[2]: A pointer to constant bytes, to compare —
const void * - Parameter[3]: Length of comparison bytes —
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]).
🌸 ustr_cmp_case_prefix_cstr_eq()
Returns: Success or failure Type: int
- Parameter[1]: A pointer to a constant Ustr string —
const struct Ustr * - Parameter[2]: A pointer to a constant C-style string —
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.
🌸 ustr_cmp_case_prefix_subustr_eq()
Returns: Success or failure Type: int
- Parameter[1]: A pointer to a constant Ustr string —
const struct Ustr * - Parameter[2]: A pointer to a constant Ustr string —
const struct Ustr *
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 one does the same thing as comparing ustr_cmp_subustr() against 0, except it's looking at the end of the left hand side. Tail-end energy only 💅
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:
Works exactly like ustr_cmp_case_prefix_eq(), but it's checking the end of the left hand side instead of the start. Same vibe, opposite end 🎀
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:
Just like ustr_cmp_case_prefix_buf_eq(), except the comparison happens at the end of the left hand side. Case-insensitive, backwards-leaning, iconic 💖
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:
Behaves like ustr_cmp_case_prefix_cstr_eq() but the end of the left hand side is what's getting compared. Periodt ✨
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:
It works like comparing ustr_cmp_case_subustr() against 0, but bestie, it compares the end of the left hand side. That's it, that's the whole gig 🦋
🔎 Searching for data in a Ustr 🔎
Okay this whole section is the "where tf is it" section and honestly it's lowkey the most useful one. Pay attention to the notes on the reverse ones though, they're sneaky 👀
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 hunts down the data in Parameter[3] inside the Ustr, but it first skips Parameter[2] bytes. Forward direction, always 🌈
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:
Same as ustr_srch_chr_fwd() but it goes from the end of the string back to the beginning. Backwards baddie behaviour 💅
Note: The searching starts from the end of the string, so the offset is an offset from the end. BUT the position of a byte is always relative to the beginning. So if you're doing a loop you have to take the position from the length. Do not skip this note, I'm literally begging 😭
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:
Searches for the data at Parameter[3], which is Parameter[4] bytes long, inside the Ustr, skipping Parameter[2] bytes first. Buffers, forward, flawless 🫶
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:
Exactly like ustr_srch_buf_fwd() except it travels from the end of the string toward the beginning.
Note: Searching starts from the end, so the offset is the offset from the end. The position of a byte though? Always relative to the beginning. For loops, take the position from the length. Same note, same chaos 🙈
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:
Acts like ustr_srch_buf_fwd(), but it grabs the data pointer by calling ustr_cstr() and the length by calling ustr_len() on the Ustr you handed it in Parameter[3]. Convenient? Extremely 💖
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:
Like ustr_srch_fwd() but it starts at the end of the string and works its way to the beginning.
Note: The offset is from the end because that's where searching starts. Byte positions are still relative to the beginning though, so for a loop you take the position from the length. Not me repeating myself, the manpage is repeating itself, blame the manpage 💀
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:
Works like ustr_srch_buf_fwd() except it figures out the length by calling strlen() on Parameter[3]. So like, you don't have to pass a length. Slay 🌸
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:
Like ustr_srch_cstr_fwd() but reversed — end of string to the beginning, bestie.
Note: Searching starts from the end, so that offset is measured from the end. Position of a byte is always relative to the beginning, so loops need you to take the position from the length. Third time's the charm 🍓
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:
Behaves like ustr_srch_fwd() but it shifts the data to start at the right position, then limits the length to the value you passed. Substring searching, but make it ✨precise✨
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:
Like ustr_srch_rev() but it moves the data to start at the correct position and caps the length at the value you gave it.
Note: Searching kicks off from the end of the string, so the offset is an offset from the end. Byte positions remain relative to the beginning, so for loops you take the position from the length. Yes, again. It's important, okay 😤
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:
(…okay this one's explanation is literally getting picked up in the next part, hold that thought bestie 💅)
the case-insensitive searches, cont'd 💅
Ok so the rest of the ustr_srch_case_* squad — every single one of these is literally just its normal twin but it treats ASCII uppercase and lowercase as the same thing. Slay, case-insensitivity ate.
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 🌸
New section bestie!! This one is all about spans — like, how far does a run of matching bytes go from one end? spn = "how many bytes HERE are in the set", cspn = "how many bytes here are NOT in the set" (the complement, hence the c). Two directions: _fwd scans from the start, _rev scans from the end. Iconic symmetry, no cap. ✨
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
okay so picking right back up with the tail end of that last function — here's its full param roster 👇
- Parameter[1]: a pointer to a constant Ustr string — Type:
const struct Ustr * - Parameter[2]: offset within the string, where the compliment spanning starts — Type:
size_t - Parameter[3]: an array of byte data — Type:
const char * - Parameter[4]: length of that byte data — Type:
size_t
Explanation: this one hands you back the length of the end of the Ustr (Parameter[1]) that only contains bytes which are not equal to any byte in the data (Parameter[3]), skipping Parameter[2] bytes first. no cap, that's the whole vibe 💅
🎀 ustr_cspn_fwd()
Returns: number of bytes not in the span — Type: size_t
- Parameter[1]: a pointer to a constant Ustr string — Type:
const struct Ustr * - Parameter[2]: offset within the string, where the compliment spanning starts — Type:
size_t - Parameter[3]: a pointer to a constant Ustr string holding the spanning bytes — Type:
const struct Ustr *
Explanation: works exactly like ustr_cspn_buf_fwd(), it's just passing ustr_cstr() and ustr_len() for you. convenience king 👑
🎀 ustr_cspn_rev()
Returns: number of bytes not in the span — Type: size_t
- Parameter[1]: a pointer to a constant Ustr string — Type:
const struct Ustr * - Parameter[2]: offset within the string, where the compliment spanning starts — Type:
size_t - Parameter[3]: a pointer to a constant Ustr string holding the spanning bytes — Type:
const struct Ustr *
Explanation: works like ustr_cspn_buf_rev(), again just passing ustr_cstr() and ustr_len() ✨
🎀 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:
const struct Ustr * - Parameter[2]: offset within the string, where the compliment spanning starts — Type:
size_t - Parameter[3]: a pointer to a constant C-style string holding the spanning bytes — Type:
const char *
Explanation: works like ustr_cspn_buf_fwd() but it passes strlen() for the length. classic C-string behavior, we love a shortcut 🫶
🎀 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:
const struct Ustr * - Parameter[2]: offset within the string, to start spanning from — Type:
size_t - Parameter[3]: a pointer to a constant C-style string holding the spanning bytes — Type:
const char *
Explanation: works like ustr_cspn_buf_rev() but it passes strlen() for the length 🌸
🦋 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:
const struct Ustr * - Parameter[2]: offset within the string, in UTF-8 characters, where spanning starts — Type:
size_t - Parameter[3]: a pointer to a constant C-style UTF-8 string — Type:
const char * - Parameter[4]: length of the C-style UTF-8 string — Type:
size_t
Explanation: works like ustr_spn_chrs_fwd() but the return value, the offset and the length all count UTF-8 characters, not bytes. character girl math, not byte math 💅
Note: this is much slower than ustr_spn_chrs_fwd(), but like — give it "xy" as a multi-byte UTF-8 character and it actually understands that the span over "xyxz" is 1 UTF-8 character and not 3 bytes. she's thorough, not fast 😭
🦋 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:
const struct Ustr * - Parameter[2]: offset within the string, in UTF-8 characters, where spanning starts — Type:
size_t - Parameter[3]: a pointer to a constant C-style UTF-8 string — Type:
const char * - Parameter[4]: (the manpage literally leaves this one blank, bestie — the type is all it gives us) — Type:
size_t
Explanation: works like ustr_spn_chrs_rev() but the return value, the offset and the length all use UTF-8 characters instead of bytes 🌈
Note: much slower than ustr_spn_chrs_rev(), but hand it "xy" as a multi-byte UTF-8 character and it gets that the span over "xyxz" is 1 UTF-8 character and not 3 bytes. iconic attention to detail ✨
🦋 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:
const struct Ustr * - Parameter[2]: offset within the string, in UTF-8 characters, where spanning starts — Type:
size_t - Parameter[3]: a pointer to a constant Ustr UTF-8 string — Type:
const struct Ustr *
Explanation: works like ustr_spn_fwd() but the return value, the offset and the length all use UTF-8 characters, not bytes 🎀
Note: much slower than ustr_spn_fwd(), but with "xy" as a multi-byte UTF-8 character it knows the span over "xyxz" is 1 UTF-8 character and not 3 bytes 💖
🦋 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:
const struct Ustr * - Parameter[2]: offset within the string, in UTF-8 characters, where spanning starts — Type:
size_t - Parameter[3]: a pointer to a constant Ustr UTF-8 string — Type:
const struct Ustr *
Explanation: works like ustr_spn_rev() but the return value, the offset and the length all use UTF-8 characters, not bytes 🌸
Note: much slower than ustr_spn_rev(), but given "xy" as a multi-byte UTF-8 character it understands the span over "xyxz" is 1 UTF-8 character and not 3 bytes 👑
🦋 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:
const struct Ustr * - Parameter[2]: offset within the string, in UTF-8 characters, where spanning starts — Type:
size_t - Parameter[3]: a pointer to a constant C-style UTF-8 string — Type:
const char *
Explanation: works like ustr_spn_cstr_fwd() but the return value, the offset and the length all use UTF-8 characters, not bytes 💜
Note: much slower than ustr_spn_cstr_fwd(), but with "xy" as a multi-byte UTF-8 character it understands the span over "xyxz" is 1 UTF-8 character, not 3 bytes 🦋
🦋 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:
const struct Ustr * - Parameter[2]: offset within the string, in UTF-8 characters, where spanning starts — Type:
size_t - Parameter[3]: a pointer to a constant C-style UTF-8 string — Type:
const char *
Explanation: works like ustr_spn_cstr_rev() but the return value, the offset and the length all use UTF-8 characters, not bytes 🍓
Note: much slower than ustr_spn_cstr_rev(), but given "xy" as a multi-byte UTF-8 character it gets that the span over "xyxz" is 1 UTF-8 character and not 3 bytes 🧚
🔥 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:
const struct Ustr * - Parameter[2]: offset within the string, in UTF-8 characters, where compliment spanning starts — Type:
size_t - Parameter[3]: a pointer to a constant C-style UTF-8 string — Type:
const char * - Parameter[4]: length of the C-style UTF-8 string — Type:
size_t
Explanation: works like ustr_cspn_chrs_fwd() but the return value, the offset and the length all use UTF-8 characters, not bytes 💅
Note: much slower than ustr_cspn_chrs_fwd(), but given "xy" as a multi-byte UTF-8 character it understands the compliment span over "xzxy" is 1 UTF-8 character and not 0 bytes. yes bestie, one, not zero 😭
🔥 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:
const struct Ustr * - Parameter[2]: offset within the string, in UTF-8 characters, where compliment spanning starts — Type:
size_t - Parameter[3]: a pointer to a constant C-style UTF-8 string — Type:
const char * - Parameter[4]: length of the C-style UTF-8 string — Type:
size_t
Explanation: works like ustr_cspn_chrs_rev() but the return value, the offset and the length all use UTF-8 characters, not bytes 🎀
Note: much slower than ustr_cspn_chrs_rev(), but with "xy" as a multi-byte UTF-8 character it understands the compliment span over "xzxy" is 1 UTF-8 character and not 0 bytes ✨
🔥 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:
const struct Ustr * - Parameter[2]: offset within the string, in UTF-8 characters, where compliment spanning starts — Type:
size_t - Parameter[3]: a pointer to a constant Ustr UTF-8 string holding the spanning data — Type:
const struct Ustr *
Explanation: works like ustr_cspn_fwd() but the return value, the offset and the length all use UTF-8 characters, not bytes 🌈
Note: much slower than ustr_cspn_fwd(), but given "xy" as a multi-byte UTF-8 character it understands the compliment span over "xzxy" is 1 UTF-8 character and not 0 bytes 💖
🔥 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:
const struct Ustr * - Parameter[2]: offset within the string, in UTF-8 characters, where compliment spanning starts — Type:
size_t - Parameter[3]: a pointer to constant Ustr UTF-8 string data holding the spanning data — Type:
const struct Ustr *
Explanation: works like ustr_cspn_rev() but the return value, the offset and the length all use UTF-8 characters, not bytes 🦋
Note: much slower than ustr_cspn_rev(), but with "xy" as a multi-byte UTF-8 character it understands the compliment span over "xzxy" is 1 UTF-8 character and not 0 bytes 🌸
🔥 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:
const struct Ustr * - Parameter[2]: offset within the string, in UTF-8 characters, where compliment spanning starts — Type:
size_t - Parameter[3]: a pointer to constant C-style UTF-8 string data holding the spanning data — Type:
const char *
Explanation: works like ustr_cspn_cstr_fwd() but the return value, the offset and the length all use UTF-8 characters, not bytes 👑
Note:
Note (still carrying on from the last function): This is much slower thanustr_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 *
- Type[1]:
- Parameter[2]: Offset within string, in UTF-8 characters, to start compliment spanning from
- Type[2]:
size_t
- Type[2]:
- Parameter[3]: A pointer to C-style UTF-8 string data, containing spanning data
- Type[3]:
const char *
- Type[3]:
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 thanustr_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 🌈
okay bestie, this is the file-IO era: reading bytes into a Ustr and writing bytes back out. We’ve got FILE * objects, delimiters, errno notes, the whole vibe. Let’s go 🫶
🎀 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 **
- Type[1]:
- Parameter[2]: A pointer to a C file object
- Type[2]:
FILE *
- Type[2]:
- Parameter[3]: Number of bytes to read
- Type[3]:
size_t
- Type[3]:
- Parameter[4]: Returned number of bytes read
- Type[4]:
size_t *
- Type[4]:
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 **
- Type[1]:
- Parameter[2]: A pointer to a C file object
- Type[2]:
FILE *
- Type[2]:
Explanation: This function calls ustr_io_get() repeatedly until EOF is encountered.
Note: Theerrnovalue when this function ends could either be fromfopen(),fread(), or if both of those succeeded fromfclose().
🦋 Function: ustr_io_getfilename() 🦋
- Returns: Success or failure
- Type:
int - Parameter[1]: Pointer to a pointer to a Ustr string
- Type[1]:
struct Ustr **
- Type[1]:
- Parameter[2]: A C-style string of a filename
- Type[2]:
const char *
- Type[2]:
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 **
- Type[1]:
- Parameter[2]: A pointer to a C file object
- Type[2]:
FILE *
- Type[2]:
- Parameter[3]: A delimiter byte to stop reading at
- Type[3]:
char
- Type[3]:
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 **
- Type[1]:
- Parameter[2]: A pointer to a C file object
- Type[2]:
FILE *
- Type[2]:
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 **
- Type[1]:
- Parameter[2]: A pointer to a C file object
- Type[2]:
FILE *
- Type[2]:
- Parameter[3]: Number of bytes to write
- Type[3]:
size_t
- Type[3]:
Explanation: This function is the opposite of ustr_io_get(), taking bytes from the beginning of the Ustr and writing them to the file.
Note: Deleting bytes from the beginning of a Ustr string is the most inefficient thing to do, so it is recommended to use ustr_io_putfile().
🧚 Function: ustr_io_putline() 🧚
- Returns: Success or failure
- Type:
int - Parameter[1]: Pointer to a pointer to a Ustr string
- Type[1]:
struct Ustr **
- Type[1]:
- Parameter[2]: A pointer to a C file object
- Type[2]:
FILE *
- Type[2]:
- Parameter[3]: Number of bytes to write
- Type[3]:
size_t
- Type[3]:
Explanation: This function works like calling ustr_io_put(), and then writing a '\n' to the file.
Note: This doesn't write a line from the Ustr to the file, if you want that callustr_io_put()directly, using the return fromustr_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 **
- Type[1]:
- Parameter[2]: A pointer to a C file object
- Type[2]:
FILE *
- Type[2]:
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 **
- Type[1]:
- Parameter[2]: A pointer to a C file object
- Type[2]:
FILE *
- Type[2]:
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 **
- Type[1]:
- Parameter[2]: A C-style string of a filename
- Type[2]:
const char *
- Type[2]:
- Parameter[3]: A C-style string of a filemode (the second argument to
fopen)- Type[3]:
const char *
- Type[3]:
Explanation: This function opens a specified file, and then calls ustr_io_putfile(). Finally closing the FILE * object.
Note: Theerrnovalue when this function ends could either be fromfopen(),fwrite(), or if both of those succeeded fromfclose().
✨ String substitution/replacement ✨
String substitution/replacement — the part where we swap out a chunk and slide new data in. Let’s go, bestie 💖
🎀 Function: ustr_sub_undef() 🎀
- Returns: Success or failure
- Type:
int - Parameter[1]: Pointer to a pointer to a Ustr
- Type[1]:
struct Ustr **
- Type[1]:
- Parameter[2]: Position where to start substitution
- Type[2]:
size_t
- Type[2]:
- Parameter[3]: Length of undefined data
- Type[3]:
size_t
- Type[3]:
Explanation: The Ustr string is expanded as required (possibly reallocated) so that it can contain length (Parameter[2]) data, from the required position. If the length is not zero the Ustr will be writable. Or it'll return USTR_FALSE (zero) on failure.
Note: You can think of the operation as two separate tasks, one which makes the current data in the Ustr undefined and the second which adds undefined data to the ustr to accommodate the desired length.
🌈 Function: ustr_sub_buf() 🌈
- Returns: Success or failure
- Type:
int - Parameter[1]: Pointer to a pointer to a Ustr
- Type[1]:
struct Ustr **
- Type[1]:
- Parameter[2]: Position where to start substitution
- Type[2]:
size_t
- Type[2]:
- Parameter[3]: Buffer containing substitution string
- Type[3]:
const void *
- Type[3]:
- Parameter[4]: Length of buffer
- Type[4]:
size_t
- Type[4]:
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 **
- Type[1]:
- Parameter[2]: Position where to start substitution
- Type[2]:
size_t
- Type[2]:
- Parameter[3]: A pointer to a constant C-style string, which is the substitution
- Type[3]:
const char *
- Type[3]:
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 **
- Type[1]:
- Parameter[2]: Position where to start substitution
- Type[2]:
size_t
- Type[2]:
- Parameter[3]: A constant C-style string
- Type[3]:
const char []
- Type[3]:
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 **
- Type[1]:
- Parameter[2]: Position where to start substitution
- Type[2]:
size_t
- Type[2]:
- Parameter[3]: A symbol
- Type[3]:
...
- 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 **
- Type[1]:
- Parameter[2]: Position where to start substitution
- Type[2]:
size_t
- Type[2]:
- Parameter[3]: A pointer to a constant Ustr string
- Type[3]:
const struct Ustr *
- Type[3]:
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 **
- Type[1]:
- Parameter[2]: Position where to start substitution
- Type[2]:
size_t
- Type[2]:
- Parameter[3]: A pointer to a constant Ustr string
- Type[3]:
const struct Ustr *
- Type[3]:
- Parameter[4]: Position in the Ustr
- Type[4]:
size_t
- Type[4]:
- Parameter[5]: Length to substitute from the Ustr
- Type[5]:
size_t
- Type[5]:
Explanation: This function works 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 **
- Type[1]:
- Parameter[2]: Position where to start substitution
- Type[2]:
size_t
- Type[2]:
- Parameter[3]: Length of substitution
- Type[3]:
size_t
- Type[3]:
- Parameter[4]: Length of undefined data
- Type[4]:
size_t
- Type[4]:
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 **
- Type[1]:
- Parameter[2]: Position where to start substitution
- Type[2]:
size_t
- Type[2]:
- Parameter[3]: Length of substitution
- Type[3]:
size_t
- Type[3]:
- Parameter[4]: Buffer containing substitute data
- Type[4]:
const void *
- Type[4]:
- Parameter[5]: Length of Buffer
- Type[5]:
size_t
- Type[5]:
Explanation: …
okay so this function will substitute a specific number of characters in a Ustr with the data from a buffer, and it 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 one works like ustr_sc_sub_buf(), except the length is worked out automatically by strlen(). cute and convenient, honestly. ✨
🦋 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 is when 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. no cap, that's the whole point. 💀
🌸 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 works as if you had called ustr_sc_sub_buf() with the ustr_cstr() + position - 1 and length values of the Ustr string you're putting in. The exception is if you insert a ustr into 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. periodt. 💖
👑 Function: USTR_SC_SUB_OBJ()
Returns: Success or failure Type: int
- Parameter[1]: Pointer to a pointer to a Ustr string — Type[1]:
struct Ustr ** - Parameter[2]: Position where to start substitution — Type[2]:
size_t - Parameter[3]: Length of substitution — Type[3]:
size_t - Parameter[4]: A symbol — Type[4]:
...
Explanation:
This function works as if you had called ustr_sc_sub_buf() and passed sizeof() as the length. 🌈
💡 Note: In most cases you'll want to use USTR_SUB_OSTR().
🍓 Function: ustr_replace_buf()
Returns: Number of tokens replaced Type: size_t
- Parameter[1]: Pointer to a pointer to a Ustr (haystack) — Type[1]:
struct Ustr ** - Parameter[2]: Buffer containing search data — Type[2]:
const void * - Parameter[3]: Length of search buffer — Type[3]:
size_t - Parameter[4]: Buffer containing replacement data — Type[4]:
const void * - Parameter[5]: Length of replacement buffer — Type[5]:
size_t - Parameter[6]: Maximum number of matches to replace (0 for unlimited) — Type[6]:
size_t
Explanation:
This function scans the "haystack" (Parameter[1]) for the "needle" (Parameter[2]) and replaces max_replacements (Parameter[6]) matches with the "replacement" (Parameter[4]). 🔥
🌟 Note: Ifmax_replacements(Parameter[6]) is0, 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(). bestie behavior, honestly. ✨
💜 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. lowkey iconic. 💅
🎀 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
0for 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 of0and the string will be unchanged.
✨ Splitting a Ustr ✨
okay so next up: splitting a Ustr into tokens. Think strtok() energy, but with way more control and way more flags. Bestie, read the notes — especially the memory-freeing bits, because that's the main-character plot twist. 💅
ustr_split_buf()
- Returns: pointer to a
Ustrrepresenting the next token (struct Ustr *) - Parameter[1]: pointer to a constant
Ustrto be split (const struct Ustr *) - Parameter[2]: pointer to an offset (
size_t *) - Parameter[3]: buffer to use as split search pattern (
const void *) - Parameter[4]: length of buffer (
size_t) - Parameter[5]: pointer to a
Ustrto be used as the return value (struct Ustr *) - Parameter[6]: flags with the prefix
USTR_FLAG_SPLIT_(unsigned int)
This function works in a manner similar to strtok(). Each time you call it, the string inside 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 pointer to a Ustr where the return value will be placed. Passing 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 with the prefixUSTR_FLAG_SPLIT_and the default beingUSTR_FLAG_SPLIT_DEF.
If you are calling this function directly, it is very likely that you'd want to use ustr_split_cstr() instead.
ustr_split()
- Returns: pointer to a
Ustrrepresenting the next token (struct Ustr *) - Parameter[1]: pointer to a constant
Ustrto be split (const struct Ustr *) - Parameter[2]: pointer to an offset variable (
size_t *) - Parameter[3]: pointer to a constant
Ustrto use as the split search pattern (const struct Ustr *) - Parameter[4]: pointer to a
Ustrwhere the return value will be placed (struct Ustr *) - Parameter[5]: flags (
unsigned int)
Works like ustr_split_buf() but takes a Ustr as the split search pattern instead. Same vibe, different separator container. 🎀
ustr_split_cstr()
- Returns: pointer to a
Ustrrepresenting the next token (struct Ustr *) - Parameter[1]: pointer to a constant
Ustrto be split (const struct Ustr *) - Parameter[2]: pointer to an offset variable (
size_t *) - Parameter[3]: C string to use as split search pattern (
const char *) - Parameter[4]: pointer to a
Ustrwhere the return value will be placed (struct Ustr *) - Parameter[5]: flags (
unsigned int)
Works like ustr_split_buf() but takes a C string as the split search pattern, and so gets the length via strlen(). Classic C-string behavior, no cap. ✨
ustr_split_spn_chrs()
- Returns: pointer to a
Ustrrepresenting the next token (struct Ustr *) - Parameter[1]: pointer to a
Ustrto be split (const struct Ustr *) - Parameter[2]: pointer to an offset variable (
size_t *) - Parameter[3]: string representing a set of bytes to use as split chars (
const char *) - Parameter[4]: length of the string of set of bytes (
size_t) - Parameter[5]: pointer to a
Ustrwhere the return value will be placed (struct Ustr *) - Parameter[6]: flags (
unsigned int)
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.
ustr_split_spn_cstr()
- Returns: pointer to a
Ustrrepresenting the next token (struct Ustr *) - Parameter[1]: pointer to a
Ustrto be split (const struct Ustr *) - Parameter[2]: pointer to an offset variable (
size_t *) - Parameter[3]: string representing a set of bytes to use as split chars (
const char *) - Parameter[4]: pointer to a
Ustrwhere the return value will be placed (struct Ustr *) - Parameter[5]: flags (
unsigned int)
Works like ustr_split_spn_chrs() but gets the length automatically via strlen(). So convenient, honestly. 💖
ustr_split_spn()
- Returns: pointer to a
Ustrrepresenting the next token (struct Ustr *) - Parameter[1]: pointer to a constant
Ustrto be split (const struct Ustr *) - Parameter[2]: pointer to an offset variable (
size_t *) - Parameter[3]: pointer to a constant
Ustrto use as the split search pattern (const struct Ustr *) - Parameter[4]: pointer to a
Ustrwhere the return value will be placed (struct Ustr *) - Parameter[5]: flags (
unsigned int)
Works like ustr_split_spn_chrs() but takes a Ustr as the split chars instead. Same split-char logic, but the separator set is a whole Ustr now. 🦋
🌈 Dealing with UTF-8 in a Ustr 🌈
Now we're getting into the cute-but-technical part: UTF-8. These functions are here to help you validate, count, measure, convert, and even reverse UTF-8 strings. Unicode bestie era fr fr. 🧚
ustr_utf8_valid()
- Returns: a boolean flag of either
USTR_TRUEorUSTR_FALSE(int) - Parameter[1]: a pointer to a constant
Ustrstring (const struct Ustr *)
This function tries its best to find out if the string is a valid UTF-8 string. It's giving "vibe check but for byte sequences." ✅
ustr_utf8_len()
- Returns: the number of the UTF-8 characters in the
Ustr(size_t) - Parameter[1]: a pointer to a constant
Ustrstring (const struct Ustr *)
This function counts the number of UTF-8 characters in the Ustr.
Note: this function gives undefined answers on strings that aren't UTF-8 valid. So maybe don't do that, bestie. 😭
ustr_utf8_width()
- Returns:
ssize_t(ssize_t) - Parameter[1]: a pointer to a constant
Ustrstring (const struct Ustr *)
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(). It's literally the "how wide does this look on screen" function. 👑
ustr_utf8_chars2bytes()
- Returns: length of span in bytes (
size_t) - Parameter[1]: a pointer to a constant
Ustrstring (const struct Ustr *) - Parameter[2]: position of a span in UTF-8 characters (
size_t) - Parameter[3]: length of a span in UTF-8 characters (
size_t) - Parameter[4]: returns the position of the span in bytes (
size_t *)
This function converts a span, in UTF-8 characters, to the same span in bytes. Character math → byte math, slay. 🔥
ustr_utf8_bytes2chars()
- Returns: returns the position of a span in UTF-8 characters (
size_t) - Parameter[1]: a pointer to a constant
Ustrstring (const struct Ustr *) - Parameter[2]: position of a span in bytes (
size_t) - Parameter[3]: length of a span in bytes (
size_t) - Parameter[4]: returns length of a span in UTF-8 characters (
size_t *)
This function converts a span, in bytes, to the same span in UTF-8 characters. Byte math → character math, iconic. 💅
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). So don't expect a perfect round trip every time — it's giving "close enough, bestie." 🙈
ustr_sc_utf8_reverse()
- Returns: success or failure (
int) - Parameter[1]: a pointer to a pointer to a
Ustrstring (struct Ustr **)
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. Not me making the whole string do a 180. 🔄✨
✨ Parsing ASCII integer numbers from a Ustr ✨
okay bestie, this is the part where we teach a Ustr to read numbers out of itself 👑 like full on "hey string, what does this text actually mean as an int?" energy. Literally every function here returns the parsed number or zero on error (yes, zero is the "something went sideways" vibe check), and every single one takes a base of 2–36 plus flags starting with USTR_FLAG_PARSE_NUM_. periodt.
🌸 Function: ustr_parse_uintmaxx()
- Returns — parsed number, or zero on error
- Type —
uintmax_t - Parameter[1] — a pointer to a constant Ustr string —
const struct Ustr * - Parameter[2] — offset within string to start parsing at —
size_t - Parameter[3] — base (
2-36) and flags, starting withUSTR_FLAG_PARSE_NUM_—unsigned int - Parameter[4] — absolute minimum value —
uintmax_t - Parameter[5] — absolute maximum value —
uintmax_t - Parameter[6] — thousands separator —
const char * - Parameter[7] — return length of parsed number —
size_t * - Parameter[8] — return error code, starting with
USTR_TYPE_PARSE_NUM_ERR_—unsigned int *
Explanation 💅
This function parses an ASCII representation of a number from a Ustr (Parameter[1]) starting at the offset (Parameter[2]). it's the full-control version — you hand it the min, the max, the separator, and out it comes 🫶
🎀 Note: if stdint.h isn't available this function won't be available. no stdint, no entry, sorry bestie.
🦋 Function: ustr_parse_uintmax()
- Returns — parsed number, or zero on error
- Type —
uintmax_t - Parameter[1] — a pointer to a constant Ustr string —
const struct Ustr * - Parameter[2] — offset within string to start parsing at —
size_t - Parameter[3] — base (
2-36) and flags, starting withUSTR_FLAG_PARSE_NUM_—unsigned int - Parameter[4] — return length of parsed number —
size_t * - Parameter[5] — return error code, starting with
USTR_TYPE_PARSE_NUM_ERR_—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 "_". the chill version of the icon above ⭐
🎀 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 —
const struct Ustr * - Parameter[2] — offset within string to start parsing at —
size_t - Parameter[3] — base (
2-36) and flags, starting withUSTR_FLAG_PARSE_NUM_—unsigned int - Parameter[4] — return length of parsed number —
size_t * - Parameter[5] — return error code, starting with
USTR_TYPE_PARSE_NUM_ERR_—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 "_". signed gang, we're so back 😤
🎀 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 —
const struct Ustr * - Parameter[2] — offset within string to start parsing at —
size_t - Parameter[3] — base (
2-36) and flags, starting withUSTR_FLAG_PARSE_NUM_—unsigned int - Parameter[4] — absolute minimum value —
unsigned long - Parameter[5] — absolute maximum value —
unsigned long - Parameter[6] — thousands separator —
const char * - Parameter[7] — return length of parsed number —
size_t * - Parameter[8] — return error code, starting with
USTR_TYPE_PARSE_NUM_ERR_—unsigned int *
Explanation 👑
This function works like ustr_parse_uintmaxx() but returns an unsigned long. and here's the main character detail: it is always available even when stdint.h isn't. no cap, this one shows up no matter what 🔥
🍓 Function: ustr_parse_ulong()
- Returns — parsed number, or zero on error
- Type —
unsigned long - Parameter[1] — a pointer to a constant Ustr string —
const struct Ustr * - Parameter[2] — offset within string to start parsing at —
size_t - Parameter[3] — base (
2-36) and flags, starting withUSTR_FLAG_PARSE_NUM_—unsigned int - Parameter[4] — return length of parsed number —
size_t * - Parameter[5] — return error code, starting with
USTR_TYPE_PARSE_NUM_ERR_—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 "_". classic defaults, ate 💅
🫶 Function: ustr_parse_long()
- Returns — parsed number, or zero on error
- Type —
long - Parameter[1] — a pointer to a constant Ustr string —
const struct Ustr * - Parameter[2] — offset within string to start parsing at —
size_t - Parameter[3] — base (
2-36) and flags, starting withUSTR_FLAG_PARSE_NUM_—unsigned int - Parameter[4] — return length of parsed number —
size_t * - Parameter[5] — return error code, starting with
USTR_TYPE_PARSE_NUM_ERR_—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 "_". negative numbers finally get their moment ✨
🎀 Function: ustr_parse_uint()
- Returns — parsed number, or zero on error
- Type —
unsigned int - Parameter[1] — a pointer to a constant Ustr string —
const struct Ustr * - Parameter[2] — offset within string to start parsing at —
size_t - Parameter[3] — base (
2-36) and flags, starting withUSTR_FLAG_PARSE_NUM_—unsigned int - Parameter[4] — return length of parsed number —
size_t * - Parameter[5] — return error code, starting with
USTR_TYPE_PARSE_NUM_ERR_—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 "_". your everyday unsigned lil guy, lowkey iconic 🌟
🌟 Function: ustr_parse_int()
- Returns — parsed number, or zero on error
- Type —
int - Parameter[1] — a pointer to a constant Ustr string —
const struct Ustr * - Parameter[2] — offset within string to start parsing at —
size_t - Parameter[3] — base (
2-36) and flags, starting withUSTR_FLAG_PARSE_NUM_—unsigned int - Parameter[4] — return length of parsed number —
size_t * - Parameter[5] — return error code, starting with
USTR_TYPE_PARSE_NUM_ERR_—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 "_". the people's champion fr fr 💖
🧊 Function: ustr_parse_ushort()
- Returns — parsed number, or zero on error
- Type —
unsigned short - Parameter[1] — a pointer to a constant Ustr string —
const struct Ustr * - Parameter[2] — offset within string to start parsing at —
size_t - Parameter[3] — base (
2-36) and flags, starting withUSTR_FLAG_PARSE_NUM_—unsigned int - Parameter[4] — return length of parsed number —
size_t * - Parameter[5] — return error code, starting with
USTR_TYPE_PARSE_NUM_ERR_—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 "_". smol but mighty 🫧
🧸 Function: ustr_parse_short()
- Returns — parsed number, or zero on error
- Type —
short - Parameter[1] — a pointer to a constant Ustr string —
const struct Ustr * - Parameter[2] — offset within string to start parsing at —
size_t - Parameter[3] — base (
2-36) and flags, starting withUSTR_FLAG_PARSE_NUM_—unsigned int - Parameter[4] — return length of parsed number —
size_t * - Parameter[5] — return error code, starting with
USTR_TYPE_PARSE_NUM_ERR_—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 "_". last one of the number-parsing crew, and she's signed and cute about it 💐
Misc shortcut helper functions for Ustrs 💅
These are the little besties that do a whole bunch of work so you don't have to. Shortcuts, but make them ✨ competent ✨.
ustr_sc_ensure_owner()
- Returns: Success or failure —
int - Parameter[1]: A pointer to a pointer to a Ustr string —
struct Ustr **
This one makes sure the Ustr string is actually owned by the time it returns (like, ustr_owner() returns USTR_TRUE, no cap), or it just fails to allocate. That's the whole vibe check.
ustr_sc_wstr()
- Returns: Writable pointer to the start of data in the Ustr, or
NULL—char * - Parameter[1]: A pointer to a pointer to a Ustr string —
struct Ustr **
Basically does a ustr_sc_ensure_owner() first to make sure the string is writable, and if that slays, it hands you back ustr_wstr(). If it doesn't work out? NULL. We move on. 💀
ustr_sc_export_subustr()
- Returns: A pointer to newly allocated block of memory —
char * - Parameter[1]: A pointer to a constant Ustr string —
const struct Ustr * - Parameter[2]: Position in the Ustr —
size_t - Parameter[3]: Length to export from the Ustr —
size_t - Parameter[4]: Allocation function (like
malloc) —void *(*)(size_t)
This function allocates a block of memory of size Length (Parameter[3]) + 1 using the allocation function you gave it (Parameter[4]), then copies the data starting from Position (Parameter[2]) inside the ustr. Fresh memory, your allocator, iconic behaviour.
ustr_sc_export()
- Returns: A pointer to newly allocated block of memory —
char * - Parameter[1]: A pointer to a constant Ustr string —
const struct Ustr * - Parameter[2]: Allocation function (like
malloc) —void *(*)(size_t)
Works exactly like calling ustr_sc_export_subustr() with a position of 1 and a length of ustr_len(). Basically "gimme the whole thing, bestie". 🫶
ustrp_sc_export_subustrp()
- Returns: A pointer to newly allocated block of memory —
char * - Parameter[1]: Pointer to a Ustr pool object —
struct Ustr_pool * - Parameter[2]: A pointer to a constant Ustr string —
const struct Ustr * - Parameter[3]: Position in the Ustr —
size_t - Parameter[4]: Length to export from the Ustr —
size_t - Parameter[5]: Allocation function (like
malloc), orNULL—void *(*)(size_t)
Allocates a block of memory of size Length (Parameter[4]) + 1 using either the allocation function you passed (Parameter[5]) or, if that allocation function is NUL, from the pool object instead. Then it copies the data starting from Position (Parameter[3]) inside the ustr. Pool edition, we love a flexible queen. 💅
ustrp_sc_export()
- Returns: A pointer to newly allocated block of memory —
char * - Parameter[1]: Pointer to a Ustr pool object —
struct Ustr_pool * - Parameter[2]: A pointer to a constant Ustr string —
const struct Ustr * - Parameter[3]: Allocation function (like
malloc) —void *(*)(size_t)
Same deal as ustrp_sc_export_subustrp(), just with a position of 1 and a length of ustrp_len(). Whole string, pool flavoured. 🍓
ustr_sc_reverse()
- Returns: Success or failure —
int - Parameter[1]: A pointer to a pointer to a Ustr string —
struct Ustr **
Reverses all the bytes in the Ustr string. Last one becomes first, second-to-last becomes second, etc. Full glow-up in reverse. 🔄
ustr_sc_tolower()
- Returns: Success or failure —
int - Parameter[1]: A pointer to a pointer to a Ustr string —
struct Ustr **
Changes any ASCII upper case bytes into ASCII lower case bytes. Quiet, unbothered, lowercase. 🌸
ustr_sc_toupper()
- Returns: Success or failure —
int - Parameter[1]: A pointer to a pointer to a Ustr string —
struct Ustr **
Changes any ASCII lower case bytes into ASCII upper case bytes. SHOUTY ENERGY. 📣
ustr_sc_ltrim_chrs()
- Returns: Success or failure —
int - Parameter[1]: A pointer to a pointer to a Ustr string —
struct Ustr ** - Parameter[2]: Array of bytes, containing trimming data —
const char * - Parameter[3]: Length of byte data —
size_t
Deletes the bytes at the beginning of the Ustr (Parameter[1]) that show up in the span (Parameter[2]) of the specified length. (The page itself says parameter[2] for the length there — bless it — but length is the third argument, so 🫶 that's the one you're passing.)
ustr_sc_ltrim()
- Returns: Success or failure —
int - Parameter[1]: A pointer to a pointer to a Ustr string —
struct Ustr ** - Parameter[2]: A pointer to a constant Ustr string, containing trimming bytes —
const struct Ustr *
Works exactly as if you'd called ustr_sc_ltrim_chrs() and passed in the ustr_cstr() and ustr_len() values of the Ustr string (Parameter[2]). Trim from the front, string-style.
ustr_sc_ltrim_cstr()
- Returns: Success or failure —
int - Parameter[1]: A pointer to a pointer to a Ustr string —
struct Ustr ** - Parameter[2]: A pointer to a constant C-style string, containing trimming bytes —
const char *
Works as if you'd called ustr_sc_ltrim_chrs() and passed strlen() as the length. C-string girlies, this one's for you. 🎀
ustr_sc_rtrim_chrs()
- Returns: Success or failure —
int - Parameter[1]: A pointer to a pointer to a Ustr string —
struct Ustr ** - Parameter[2]: Array of bytes, containing trimming data —
const char * - Parameter[3]: Length of byte data —
size_t
Deletes the bytes at the end of the Ustr (Parameter[1]) that are in the span (Parameter[2]) of the specified length. Bye from the back. 👋
ustr_sc_rtrim()
- Returns: Success or failure —
int - Parameter[1]: A pointer to a pointer to a Ustr string —
struct Ustr ** - Parameter[2]: A pointer to a constant Ustr string, containing trimming bytes —
const struct Ustr *
Works as if you'd called ustr_sc_rtrim_chrs() and passed the ustr_cstr() and ustr_len() values of the Ustr string (Parameter[2]). Trim from the end, string-style.
ustr_sc_rtrim_cstr()
- Returns: Success or failure —
int - Parameter[1]: A pointer to a pointer to a Ustr string —
struct Ustr ** - Parameter[2]: A pointer to a constant C-style string, containing trimming bytes —
const char *
Works as if you'd called ustr_sc_rtrim_chrs() and passed strlen() as the length.
ustr_sc_trim_chrs()
- Returns: Success or failure —
int - Parameter[1]: A pointer to a pointer to a Ustr string —
struct Ustr ** - Parameter[2]: Array of bytes, containing trimming data —
const char * - Parameter[3]: Length of byte data —
size_t
Deletes the bytes at the beginning or end of the Ustr (Parameter[1]) that are in the span (Parameter[2]) of the specified length. Both ends, one function, main character energy. 👑
Note: calling this is much more efficient than callingustr_sc_rtrim_chrs()and thenustr_sc_ltrim_chrs(), because both ends get trimmed in a single pass. One pass. Iconic. Don't do it the long way.
ustr_sc_trim()
- Returns: Success or failure —
int - Parameter[1]: A pointer to a pointer to a Ustr string —
struct Ustr ** - Parameter[2]: A pointer to a constant Ustr string, containing trimming bytes —
const struct Ustr *
Works as if you'd called ustr_sc_trim_chrs() and passed the ustr_cstr() and ustr_len() values of the Ustr string (Parameter[2]).
ustr_sc_trim_cstr()
- Returns: Success or failure —
int - Parameter[1]: A pointer to a pointer to a Ustr string —
struct Ustr ** - Parameter[2]: A pointer to a constant C-style string, containing trimming bytes —
const char *
Works as if you'd called ustr_sc_trim_chrs() and passed strlen() as the length. Clean edges, no drama. ✨
Adding binary data to a Ustr 🧚
Not text — binary. Numbers go in raw. Ate. 🔥
ustr_add_b_uint16()
- Returns: Success or failure —
int - Parameter[1]: Pointer to a pointer to a Ustr string —
struct Ustr ** - Parameter[2]: Binary value to add to the Ustr —
uint_least16_t
Adds a binary representation of a value (Parameter[2]) onto the Ustr (Parameter[1]).
ustr_add_b_uint32()
- Returns: Success or failure —
int - Parameter[1]: Pointer to a pointer to a Ustr string —
struct Ustr ** - Parameter[2]: Binary value to add to the Ustr —
uint_least32_t
Adds a binary representation of a value (Parameter[2]) onto the Ustr (Parameter[1]).
ustr_add_b_uint64()
- Returns: Success or failure —
int - Parameter[1]: Pointer to a pointer to a Ustr string —
struct Ustr ** - Parameter[2]: Binary value to add to the Ustr —
uint_least64_t
Adds a binary representation of a value (Parameter[2]) onto the Ustr (Parameter[1]). Big number, big vibes. 💜
Parsing binary data from a Ustr 🦋
The reverse trip — pulling raw binary numbers back out. Ngl, this one's satisfying.
ustr_parse_b_uint16()
- Returns:
uint_least16_t—uint_least16_t - Parameter[1]: A pointer to a constant Ustr string —
const struct Ustr * - Parameter[2]: Offset within string to start parsing at —
size_t
Parses a binary representation out of a Ustr (Parameter[1]), starting at the offset (Parameter[2]).
ustr_parse_b_uint32()
- Returns:
uint_least32_t—uint_least32_t - Parameter[1]: A pointer to a constant Ustr string —
const struct Ustr * - Parameter[2]: Offset within string to start parsing at —
size_t
Parses a binary representation out of a Ustr (Parameter[1]), starting at the offset (Parameter[2]).
ustr_parse_b_uint64()
- Returns:
uint_least64_t—uint_least64_t - Parameter[1]: A pointer to a constant Ustr string —
const struct Ustr * - Parameter[2]: Offset within string to start parsing at —
size_t
Parses a binary representation out of a Ustr (Parameter[1]), starting at the offset (Parameter[2]). Sixty-four bits of pure potential. ⭐
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 **
- Type[1]:
- Parameter[2]: Size of allocation
- Type[2]:
size_t
- Type[2]:
Okay so this one resizes the Ustr to the size you pass in Parameter[2], bestie. It’s mostly used to shrink a sized Ustr that’s now way smaller than it used to be — though fr fr it can also grow a Ustr too. 💖
Note: To have a size that isn’t implied from the length, the Ustr has to store a size value as well as a length (ustr_sized()must returnUSTR_TRUE). Periodt.
Function: ustr_cntl_opt() 🦋
- Returns: Success or failure
- Type:
int - Parameter[1]: Optional value starting with
USTR_CNTL_OPT_- Type[1]:
int
- Type[1]:
- Parameter[2]: Arguments to option
- Type[2]:
...
- Type[2]:
This is the one that views and/or changes the global Ustr options — like whether Ustrs have an implicit or explicit size (USTR_CNTL_OPT_GET_HAS_SIZE). Lowkey iconic control-panel energy. 👑
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
- Type[1]:
This allocates a new pool using the “linked list” strategy. Each allocation in the pool gets added to a linked list … and any allocations that weren’t freed directly are freed by the pool when it’s cleared or freed. Cleanup queen behavior. 💅
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 *
- Type[1]:
This allocates a new pool as a child of the pool you pass in (Parameter[1]). The pool can be freed and cleared independently of the parent pool — BUT free and clear operations on the parent pool are automatically applied to all child pools. Family business, no cap. 🫶
Function: ustr_pool_free() 💀
- Returns: Nothing
- Type:
void - Parameter[1]: Pointer to a Ustr pool object
- Type[1]:
struct Ustr_pool *
- Type[1]:
This deallocates a pool, and all sub-pools. Bye bestie, whole tree’s gone. 😭
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 *
- Type[1]:
This lets all the data in the pool be reused — it may also free some/all of the data in the pool, from the pool API. Recycling era. ♻️
Note: This also operates on all sub-pools.
SEE ALSO 👀💖
And that’s the whole ustr(3) page, bestie — this gem is from Ustr 1.0.4, dated 05-Mar-2008, page ustr(3). Slay and stay hydrated! 💅🫶🎀
📦 where this page comes from
- debian bookworm: libustr-dev 1.0.4-6.1
- ubuntu jammy: libustr-dev 1.0.4-6
- ubuntu noble: libustr-dev 1.0.4-6.1build1
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on : a language model's rewrite of the original, under its terms