facil.io
Utilities & Parsers

#String Core

c
#define FIO_STR
#include "fio-stl.h"

Binary-safe string helpers for building, editing, escaping, encoding, and comparing text. This module works with the lightweight fio_str_info_s and fio_buf_info_s descriptors, plus two owned string types: copy-on-write fio_bstr and hash-map key string fio_keystr_s.

All authoring helpers take a fio_string_realloc_fn callback so they can grow either a stack buffer or a heap allocation.

#Types

#fio_string_realloc_fn

c
typedef int (*fio_string_realloc_fn)(fio_str_info_s *dest, size_t len);

Callback that grows dest->buf to at least len + 1 bytes and updates dest->capa. Returns 0 on success, -1 on failure.

#fio_string_write_s

c
typedef struct {
  size_t klass;
  union {
    struct { size_t len; const char *buf; } str;
    double f;
    int64_t i;
    uint64_t u;
  } info;
} fio_string_write_s;

Argument item used by fio_string_write2 and fio_bstr_write2. The klass field selects the union member: 1 = string, 2 = signed int, 3 = unsigned int, 4 = hex, 5 = binary, 6 = double.

#Authorship Helpers

#fio_string_write

c
SFUNC int fio_string_write(fio_str_info_s *dest,
                           fio_string_realloc_fn reallocate,
                           const void *restrict src,
                           size_t len);

Appends len bytes from src to dest. Grows dest if reallocate is provided; otherwise truncates when full. Always NUL-terminates on success.

Parameters:

  • dest — target string descriptor. Must have a valid buffer and capa >= len.
  • reallocate — growth callback, may be NULL.
  • src — data to append.
  • len — bytes to append.

Returns: 0 on success, -1 if reallocation was needed and failed.

#fio_string_replace

c
SFUNC int fio_string_replace(fio_str_info_s *dest,
                             fio_string_realloc_fn reallocate,
                             intptr_t start_pos,
                             size_t overwrite_len,
                             const void *src,
                             size_t len);

Inserts, overwrites, or deletes a slice. Negative start_pos counts from the end (-1 = last byte). When overwrite_len is 0, the data is inserted. When len is 0, the slice is deleted.

Parameters:

  • start_pos — byte offset where editing begins.
  • overwrite_len — bytes to overwrite or remove.
  • src — replacement data, ignored if len == 0.
  • len — replacement length.

Returns: 0 on success, -1 on failure.

#fio_string_write2

c
SFUNC int fio_string_write2(fio_str_info_s *restrict dest,
                            fio_string_realloc_fn reallocate,
                            const fio_string_write_s srcs[]);

#define fio_string_write2(dest, reallocate, ...)                               \
  fio_string_write2((dest),                                                    \
                    (reallocate),                                              \
                    (fio_string_write_s[]){__VA_ARGS__, {0}})

Appends a mixed list of strings and numbers in a single pass. The macro builds a temporary fio_string_write_s[] array and appends a zero terminator.

c
fio_string_write2(&str, my_realloc,
                  FIO_STRING_WRITE_STR1("The answer is: "),
                  FIO_STRING_WRITE_NUM(42),
                  FIO_STRING_WRITE_STR2(" (0x", 4),
                  FIO_STRING_WRITE_HEX(42),
                  FIO_STRING_WRITE_STR2(")", 1));

#FIO_STRING_WRITE_*

c
#define FIO_STRING_WRITE_STR1(str_) /* string with FIO_STRLEN length */
#define FIO_STRING_WRITE_STR2(str_, len_) /* string with explicit length */
#define FIO_STRING_WRITE_STR_INFO(str_) /* from fio_str_info_s */
#define FIO_STRING_WRITE_NUM(num)     /* signed integer */
#define FIO_STRING_WRITE_UNUM(num)    /* unsigned integer */
#define FIO_STRING_WRITE_HEX(num)     /* hex representation */
#define FIO_STRING_WRITE_BIN(num)     /* binary representation */
#define FIO_STRING_WRITE_FLOAT(num)   /* double */

Helper macros that build fio_string_write_s items for fio_string_write2.

#Numeral Helpers

#fio_string_write_i

c
SFUNC int fio_string_write_i(fio_str_info_s *dest,
                             fio_string_realloc_fn reallocate,
                             int64_t i);

Appends a signed base-10 integer.

#fio_string_write_u

c
SFUNC int fio_string_write_u(fio_str_info_s *dest,
                             fio_string_realloc_fn reallocate,
                             uint64_t i);

Appends an unsigned base-10 integer.

#fio_string_write_hex

c
SFUNC int fio_string_write_hex(fio_str_info_s *dest,
                               fio_string_realloc_fn reallocate,
                               uint64_t i);

Appends a lowercase hex representation.

#fio_string_write_bin

c
SFUNC int fio_string_write_bin(fio_str_info_s *dest,
                               fio_string_realloc_fn reallocate,
                               uint64_t i);

Appends a binary representation.

#printf Support

#fio_string_printf

c
SFUNC FIO___PRINTF_STYLE(3, 0) int fio_string_printf(
    fio_str_info_s *dest,
    fio_string_realloc_fn reallocate,
    const char *format,
    ...);

Appends formatted output, growing the buffer as needed.

#fio_string_vprintf

c
SFUNC FIO___PRINTF_STYLE(3, 0) int fio_string_vprintf(
    fio_str_info_s *dest,
    fio_string_realloc_fn reallocate,
    const char *format,
    va_list argv);

va_list variant of fio_string_printf.

#Escaping and Encoding

#fio_string_write_escape

c
SFUNC int fio_string_write_escape(fio_str_info_s *restrict dest,
                                  fio_string_realloc_fn reallocate,
                                  const void *raw,
                                  size_t raw_len);

Escapes raw using JSON string rules and appends the result.

#fio_string_write_unescape

c
SFUNC int fio_string_write_unescape(fio_str_info_s *dest,
                                    fio_string_realloc_fn reallocate,
                                    const void *enscaped,
                                    size_t enscaped_len);

Unescapes JSON-style data and appends it.

#fio_string_write_base32enc / fio_string_write_base32dec

c
SFUNC int fio_string_write_base32enc(fio_str_info_s *dest,
                                     fio_string_realloc_fn reallocate,
                                     const void *raw,
                                     size_t raw_len);
SFUNC int fio_string_write_base32dec(fio_str_info_s *dest,
                                     fio_string_realloc_fn reallocate,
                                     const void *encoded,
                                     size_t encoded_len);

Base32 encode / decode.

#fio_string_write_base64enc / fio_string_write_base64dec

c
SFUNC int fio_string_write_base64enc(fio_str_info_s *dest,
                                     fio_string_realloc_fn reallocate,
                                     const void *raw,
                                     size_t raw_len,
                                     uint8_t url_encoded);
SFUNC int fio_string_write_base64dec(fio_str_info_s *dest,
                                     fio_string_realloc_fn reallocate,
                                     const void *encoded,
                                     size_t encoded_len);

Base64 encode / decode. Pass url_encoded = 1 to use URL-safe alphabet.

#fio_string_write_url_enc / fio_string_write_url_dec / fio_string_write_path_dec

c
SFUNC int fio_string_write_url_enc(fio_str_info_s *dest,
                                   fio_string_realloc_fn reallocate,
                                   const void *raw,
                                   size_t raw_len);
SFUNC int fio_string_write_url_dec(fio_str_info_s *dest,
                                   fio_string_realloc_fn reallocate,
                                   const void *encoded,
                                   size_t encoded_len);
SFUNC int fio_string_write_path_dec(fio_str_info_s *dest,
                                    fio_string_realloc_fn reallocate,
                                    const void *encoded,
                                    size_t encoded_len);

URL (percent) encoding and decoding. url_dec converts + to space; path_dec does not.

#fio_string_write_html_escape / fio_string_write_html_unescape

c
SFUNC int fio_string_write_html_escape(fio_str_info_s *dest,
                                       fio_string_realloc_fn reallocate,
                                       const void *raw,
                                       size_t raw_len);
SFUNC int fio_string_write_html_unescape(fio_str_info_s *dest,
                                         fio_string_realloc_fn reallocate,
                                         const void *enscaped,
                                         size_t enscaped_len);

HTML escape / unescape. The unescape implementation is minimal and incomplete.

#File Reading

#fio_string_readfd

c
SFUNC int fio_string_readfd(fio_str_info_s *dest,
                            fio_string_realloc_fn reallocate,
                            int fd,
                            intptr_t start_at,
                            size_t limit);

Reads up to limit bytes from seekable file descriptor fd starting at start_at. Negative start_at counts from EOF. limit == 0 reads to EOF.

#fio_string_readfile

c
SFUNC int fio_string_readfile(fio_str_info_s *dest,
                              fio_string_realloc_fn reallocate,
                              const char *filename,
                              intptr_t start_at,
                              size_t limit);

Opens filename and reads its contents (or a slice) into dest.

#fio_string_getdelim_fd

c
SFUNC int fio_string_getdelim_fd(fio_str_info_s *dest,
                                 fio_string_realloc_fn reallocate,
                                 int fd,
                                 intptr_t start_at,
                                 char delim,
                                 size_t limit);

Reads from fd until delim or EOF.

#fio_string_getdelim_file

c
SFUNC int fio_string_getdelim_file(fio_str_info_s *dest,
                                   fio_string_realloc_fn reallocate,
                                   const char *filename,
                                   intptr_t start_at,
                                   char delim,
                                   size_t limit);

Same as fio_string_getdelim_fd but opens and closes the file.

#Memory Helpers

#fio_string_capa4len

c
FIO_IFUNC size_t fio_string_capa4len(size_t new_len);

Returns a 16-byte-aligned capacity for new_len.

#Default Allocator Callbacks

c
#define FIO_STRING_SYS_REALLOC   fio_string_sys_reallocate
#define FIO_STRING_REALLOC       fio_string_default_reallocate
#define FIO_STRING_ALLOC_COPY    fio_string_default_allocate_copy
#define FIO_STRING_ALLOC_KEY     fio_string_default_key_alloc
#define FIO_STRING_FREE          fio_string_default_free
#define FIO_STRING_FREE2         fio_string_default_free2
#define FIO_STRING_FREE_KEY      fio_string_default_free_key
#define FIO_STRING_FREE_NOOP     fio_string_default_free_noop
#define FIO_STRING_FREE_NOOP2    fio_string_default_free_noop2

Convenience macros pointing to the default callbacks.

#fio_string_default_reallocate

c
SFUNC int fio_string_default_reallocate(fio_str_info_s *dst, size_t len);

Grows dst using the current facil.io allocator (FIO_MEM_REALLOC_).

#fio_string_default_allocate_copy

c
SFUNC int fio_string_default_allocate_copy(fio_str_info_s *dest, size_t new_capa);

Allocates a new buffer and copies existing data into it.

#fio_string_default_free

c
SFUNC void fio_string_default_free(void *);

Frees a buffer allocated with the default callbacks.

#UTF-8 Helpers

#fio_string_utf8_valid

c
SFUNC bool fio_string_utf8_valid(fio_str_info_s str);

Returns true if str is valid UTF-8.

#fio_string_utf8_len

c
SFUNC size_t fio_string_utf8_len(fio_str_info_s str);

Returns the number of Unicode code points, or 0 if invalid.

#fio_string_utf8_valid_code_point

c
SFUNC size_t fio_string_utf8_valid_code_point(const void *u8c, size_t buf_len);

Returns the byte length of the UTF-8 code point at u8c (1–4), or 0 if invalid.

#fio_string_utf8_select

c
SFUNC int fio_string_utf8_select(fio_str_info_s str,
                                 intptr_t *pos,
                                 size_t *len);

Converts a UTF-8 character range (pos, len) into raw byte offsets. Returns -1 on error and sets pos to -1 if the string is invalid before the selection.

#Comparison Helpers

#fio_string_is_greater_buf

c
SFUNC int fio_string_is_greater_buf(fio_buf_info_s a, fio_buf_info_s b);

Returns 1 if a is lexicographically greater than b; 0 otherwise (including equality).

#fio_string_is_greater

c
FIO_IFUNC int fio_string_is_greater(fio_str_info_s a, fio_str_info_s b);

Same comparison for fio_str_info_s.

#Binary String (fio_bstr)

A reference-counted, copy-on-write, NUL-terminated binary string. The public pointer points at the first character; metadata lives just before it.

#fio_bstr_reserve

c
FIO_IFUNC char *fio_bstr_reserve(char *bstr, size_t len);

Ensures at least len additional bytes are available.

#fio_bstr_copy

c
FIO_IFUNC char *fio_bstr_copy(char *bstr);

Returns a shallow copy, incrementing the reference count. Falls back to a real copy if the reference count overflows.

#fio_bstr_free

c
FIO_IFUNC void fio_bstr_free(char *bstr);

Decrements the reference count and frees memory when it reaches zero.

#fio_bstr_info / fio_bstr_buf / fio_bstr_len / fio_bstr_len_set

c
FIO_IFUNC fio_str_info_s fio_bstr_info(const char *bstr);
FIO_IFUNC fio_buf_info_s fio_bstr_buf(const char *bstr);
FIO_IFUNC size_t fio_bstr_len(const char *bstr);
FIO_IFUNC char *fio_bstr_len_set(char *bstr, size_t len);

Inspect or resize the string. fio_bstr_len_set may reallocate if the string is shared or too small.

#fio_bstr_write and Friends

c
FIO_IFUNC char *fio_bstr_write(char *bstr, const void *src, size_t len);
FIO_IFUNC char *fio_bstr_replace(char *bstr, intptr_t start_pos,
                                 size_t overwrite_len, const void *src,
                                 size_t len);
FIO_IFUNC char *fio_bstr_write2(char *bstr, const fio_string_write_s srcs[]);
#define fio_bstr_write2(bstr, ...) \
  fio_bstr_write2(bstr, (fio_string_write_s[]){__VA_ARGS__, {0}})
FIO_IFUNC char *fio_bstr_write_i(char *bstr, int64_t num);
FIO_IFUNC char *fio_bstr_write_u(char *bstr, uint64_t num);
FIO_IFUNC char *fio_bstr_write_hex(char *bstr, uint64_t num);
FIO_IFUNC char *fio_bstr_write_bin(char *bstr, uint64_t num);
FIO_IFUNC char *fio_bstr_write_escape(char *bstr, const void *src, size_t len);
FIO_IFUNC char *fio_bstr_write_unescape(char *bstr, const void *src, size_t len);
FIO_IFUNC char *fio_bstr_write_base64enc(char *bstr, const void *src,
                                         size_t len, uint8_t url_encoded);
FIO_IFUNC char *fio_bstr_write_base64dec(char *bstr, const void *src, size_t len);
FIO_IFUNC char *fio_bstr_write_url_enc(char *bstr, const void *data, size_t len);
FIO_IFUNC char *fio_bstr_write_url_dec(char *bstr, const void *encoded, size_t len);
FIO_IFUNC char *fio_bstr_write_html_escape(char *bstr, const void *raw, size_t len);
FIO_IFUNC char *fio_bstr_write_html_unescape(char *bstr, const void *escaped,
                                             size_t len);
FIO_IFUNC char *fio_bstr_readfd(char *bstr, int fd, intptr_t start_at,
                                intptr_t limit);
FIO_IFUNC char *fio_bstr_readfile(char *bstr, const char *filename,
                                  intptr_t start_at, intptr_t limit);
FIO_IFUNC char *fio_bstr_getdelim_file(char *bstr, const char *filename,
                                       intptr_t start_at, char delim,
                                       size_t limit);
FIO_IFUNC char *fio_bstr_getdelim_fd(char *bstr, int fd, intptr_t start_at,
                                     char delim, size_t limit);
FIO_IFUNC char *fio_bstr_printf(char *bstr, const char *format, ...);

Every fio_bstr_* function returns the possibly-reallocated string pointer. Always assign the result back.

#fio_bstr_is_greater / fio_bstr_is_eq / fio_bstr_is_eq2info / fio_bstr_is_eq2buf

c
FIO_SFUNC int fio_bstr_is_greater(const char *a, const char *b);
FIO_SFUNC int fio_bstr_is_eq(const char *a_, const char *b_);
FIO_SFUNC int fio_bstr_is_eq2info(const char *a_, fio_str_info_s b);
FIO_SFUNC int fio_bstr_is_eq2buf(const char *a_, fio_buf_info_s b);

Comparison helpers.

#fio_bstr_reallocate

c
SFUNC int fio_bstr_reallocate(fio_str_info_s *dest, size_t len);

Default reallocate callback for fio_bstr.

#Key String (fio_keystr_s)

A compact key type used by hash maps. Small strings are embedded in the struct; larger ones store a pointer and length. Not NUL-terminated.

#fio_keystr_tmp

c
FIO_IFUNC fio_keystr_s fio_keystr_tmp(const char *buf, uint32_t len);

Returns a temporary key referencing buf/len.

#fio_keystr_init

c
FIO_SFUNC fio_keystr_s fio_keystr_init(fio_str_info_s str,
                                       void *(*alloc_func)(size_t len));

Copies str into a persistent key. Strings short enough are embedded; otherwise alloc_func is used. Pass capa == FIO_KEYSTR_CONST to store a borrowed pointer.

#fio_keystr_destroy

c
FIO_SFUNC void fio_keystr_destroy(fio_keystr_s *key,
                                  void (*free_func)(void *, size_t));

Releases a key allocated by fio_keystr_init.

#fio_keystr_buf / fio_keystr_info / fio_keystr_is_eq / fio_keystr_is_eq2 / fio_keystr_is_eq3 / fio_keystr_hash

c
FIO_IFUNC fio_buf_info_s fio_keystr_buf(fio_keystr_s *str);
FIO_IFUNC fio_str_info_s fio_keystr_info(fio_keystr_s *str);
FIO_IFUNC int fio_keystr_is_eq(fio_keystr_s a, fio_keystr_s b);
FIO_IFUNC int fio_keystr_is_eq2(fio_keystr_s a_, fio_str_info_s b);
FIO_IFUNC int fio_keystr_is_eq3(fio_keystr_s a_, fio_buf_info_s b);
FIO_IFUNC uint64_t fio_keystr_hash(fio_keystr_s a);

Inspect, compare, and hash key strings.

#FIO_KEYSTR_CONST

c
#define FIO_KEYSTR_CONST ((size_t)-1LL)

Magic capa value for fio_keystr_init that keeps a borrowed pointer instead of allocating.

#Example

c
#define FIO_STR
#include "fio-stl.h"

int my_realloc(fio_str_info_s *dest, size_t len) {
  size_t capa = fio_string_capa4len(len);
  char *tmp = realloc(dest->buf, capa);
  if (!tmp) return -1;
  dest->buf = tmp;
  dest->capa = capa;
  return 0;
}

int main(void) {
  char buf[32];
  fio_str_info_s str = FIO_STR_INFO3(buf, 0, 32);

  fio_string_write(&str, my_realloc, "answer: ", 8);
  fio_string_write_i(&str, my_realloc, 42);
  fprintf(stderr, "%s\n", str.buf);

  char *b = NULL;
  b = fio_bstr_write(b, "hello ", 6);
  b = fio_bstr_write(b, "world", 5);
  fprintf(stderr, "%s (len=%zu)\n", b, fio_bstr_len(b));
  fio_bstr_free(b);
  return 0;
}