#./fio-stl/011 string core.h

103 public symbols.

#Macros

#FIO_STRING_WRITE_STR1

#define FIO_STRING_WRITE_STR1(str_)   \
  ((fio_string_write_s){   \
      .klass = 1,   \
      .info.str = {.len = (size_t)FIO_STRLEN((str_)), .buf = (str_)}})

A macro to add a String to fio_string_write2.

Symbol type: macro

#FIO_STRING_WRITE_STR2

#define FIO_STRING_WRITE_STR2(str_, len_)   \
  ((fio_string_write_s){.klass = 1, .info.str = {.len = (len_), .buf = (str_)}})

A macro to add a String with known length to fio_string_write2.

Symbol type: macro

#FIO_STRING_WRITE_STR_INFO

#define FIO_STRING_WRITE_STR_INFO(str_)   \
  ((fio_string_write_s){.klass = 1,   \
                        .info.str = {.len = (str_).len, .buf = (str_).buf}})

A macro to add a String with known length to fio_string_write2.

Symbol type: macro

#FIO_STRING_WRITE_NUM

#define FIO_STRING_WRITE_NUM(num)   \
  ((fio_string_write_s){.klass = 2, .info.i = (int64_t)(num)})

A macro to add a signed number to fio_string_write2.

Symbol type: macro

#FIO_STRING_WRITE_UNUM

#define FIO_STRING_WRITE_UNUM(num)   \
  ((fio_string_write_s){.klass = 3, .info.u = (uint64_t)(num)})

A macro to add an unsigned number to fio_string_write2.

Symbol type: macro

#FIO_STRING_WRITE_HEX

#define FIO_STRING_WRITE_HEX(num)   \
  ((fio_string_write_s){.klass = 4, .info.u = (uint64_t)(num)})

A macro to add a hex representation to fio_string_write2.

Symbol type: macro

#FIO_STRING_WRITE_BIN

#define FIO_STRING_WRITE_BIN(num)   \
  ((fio_string_write_s){.klass = 5, .info.u = (uint64_t)(num)})

A macro to add a binary representation to fio_string_write2.

Symbol type: macro

#FIO_STRING_WRITE_FLOAT

#define FIO_STRING_WRITE_FLOAT(num)   \
  ((fio_string_write_s){.klass = 6, .info.f = (double)(num)})

A macro to add a float (double) to fio_string_write2.

Symbol type: macro

#FIO_STRING_SYS_REALLOC

#define FIO_STRING_SYS_REALLOC fio_string_sys_reallocate

Default reallocation callback implementation using libc realloc.

Symbol type: macro

#FIO_STRING_REALLOC

#define FIO_STRING_REALLOC fio_string_default_reallocate

Default reallocation callback implementation using the default allocator

Symbol type: macro

#FIO_STRING_ALLOC_COPY

#define FIO_STRING_ALLOC_COPY fio_string_default_allocate_copy

Default reallocation callback for memory that mustn't be freed.

Symbol type: macro

#FIO_STRING_ALLOC_KEY

#define FIO_STRING_ALLOC_KEY fio_string_default_key_alloc

default allocator for the fio_keystr_s string data..

Symbol type: macro

#FIO_STRING_FREE

#define FIO_STRING_FREE fio_string_default_free

Frees memory that was allocated with the default callbacks.

Symbol type: macro

#FIO_STRING_FREE2

#define FIO_STRING_FREE2 fio_string_default_free2

Frees memory that was allocated with the default callbacks.

Symbol type: macro

#FIO_STRING_FREE_KEY

#define FIO_STRING_FREE_KEY fio_string_default_free_key

Frees memory that was allocated for a key string.

Symbol type: macro

#FIO_STRING_FREE_NOOP

#define FIO_STRING_FREE_NOOP fio_string_default_free_noop

Does nothing.

Symbol type: macro

#FIO_STRING_FREE_NOOP2

#define FIO_STRING_FREE_NOOP2 fio_string_default_free_noop2

Does nothing.

Symbol type: macro

#FIO_KEYSTR_CONST

#define FIO_KEYSTR_CONST ((size_t)-1LL)

Symbol type: macro

#Types

#fio_string_realloc_fn

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

A reallocation callback type for buffers in a fio_str_info_s.

The callback MUST allocate at least len + 1 bytes, setting the new capacity in dest->capa.

Returns 0 on success, -1 on error.

Symbol type: type

#fio_string_write_s

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 type used by fio_string_write2.

Symbol type: type

#fio_keystr_s

struct fio_keystr_s

a semi-opaque type used for the fio_keystr functions

Symbol type: type

#Functions

#fio_string_write

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

Writes data to the end of the string in the fio_string_s struct, returning an updated fio_string_s struct.

The returned string is NUL terminated if edited.

• dest an fio_string_s struct containing the destination string.

• reallocate is a callback that attempts to reallocate more memory (i.e., using realloc) and returns an updated fio_string_s struct containing the updated capacity and buffer pointer (as well as the original length).

  On failure the original fio_string_s should be returned. if reallocate is NULL or fails, the data copied will be truncated.

• src is the data to be written to the end of dest.

• len is the length of the data to be written to the end of dest.

Note: this function performs only minimal checks and assumes that dest is fully valid - i.e., that dest.capa >= dest.len, that dest.buf is valid, etc'.

An example for a reallocate callback using the system's realloc function:

 int fio_string_realloc_system(fio_str_info_s *dest, size_t len_no_nul) {
  const size_t new_capa = fio_string_capa4len(len_no_nul);
  void *tmp = realloc(dest.buf, new_capa);
  if (!tmp)
    return -1;
  dest.capa = new_capa;
  dest.buf = (char *)tmp;
  return 0;
}

An example for using the function:

void example(void) {
  char buf[32];
  fio_str_info_s str = FIO_STR_INFO3(buf, 0, 32);
  fio_string_write(&str, NULL, "The answer is: 0x", 17);
  str.len += fio_ltoa(str.buf + str.len, 42, 16);
  fio_string_write(&str, NULL, "!\n", 2);
  printf("%s", str.buf);
}

Symbol type: function

#fio_string_replace

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)

Similar to fio_string_write, only replacing/inserting a sub-string in a specific location.

Negative start_pos values are calculated backwards, -1 == end of String.

When overwrite_len is zero, the function will insert the data at start_pos, pushing existing data until after the inserted data.

If overwrite_len is non-zero, than overwrite_len bytes will be overwritten (or deleted).

If len == 0 than src will be ignored and the data marked for replacement will be erased.

Symbol type: function

#fio_string_write2

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

Writes a group of objects (strings, numbers, etc') to dest.

dest and reallocate are similar to fio_string_write.

src is an array of fio_string_write_s structs, ending with a struct that's all set to 0.

Use the fio_string_write2 macro for ease, i.e.:

fio_str_info_s str = {0}; fio_string_write2(&str, my_reallocate, FIO_STRING_WRITE_STR1("The answer is: "), FIO_STRING_WRITE_NUM(42), FIO_STRING_WRITE_STR2("(0x", 3), FIO_STRING_WRITE_HEX(42), FIO_STRING_WRITE_STR2(")", 1));

Note: this function might end up allocating more memory than absolutely required as it favors fast performance over memory savings. It performs only a single allocation (if any) and computes numeral string length only when writing the numbers to the string.

Symbol type: function

#fio_string_write2

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

Note: this may be a macro only / macro wrapper for a function.

Symbol type: macro

#fio_string_write_i

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

Symbol type: function

#fio_string_write_u

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

Symbol type: function

#fio_string_write_hex

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

Symbol type: function

#fio_string_write_bin

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

Symbol type: function

#fio_string_printf

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

Similar to fio_string_write, only using printf semantics.

Symbol type: function

#fio_string_vprintf

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)

Similar to fio_string_write, only using vprintf semantics.

Symbol type: function

#fio_string_write_escape

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

Writes data at the end of the String, escaping the data using JSON semantics.

The JSON semantic are common to many programming languages, promising a UTF-8 String while making it easy to read and copy the string during debugging.

Symbol type: function

#fio_string_write_unescape

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

Writes an escaped data into the string after un-escaping the data.

Symbol type: function

#fio_string_write_base32enc

int fio_string_write_base32enc(fio_str_info_s *dest, fio_string_realloc_fn reallocate, const void *raw, size_t raw_len)

Writes data to String using base64 encoding.

Symbol type: function

#fio_string_write_base32dec

int fio_string_write_base32dec(fio_str_info_s *dest, fio_string_realloc_fn reallocate, const void *encoded, size_t encoded_len)

Writes decoded base64 data to String.

Symbol type: function

#fio_string_write_base64enc

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)

Writes data to String using base64 encoding.

Symbol type: function

#fio_string_write_base64dec

int fio_string_write_base64dec(fio_str_info_s *dest, fio_string_realloc_fn reallocate, const void *encoded, size_t encoded_len)

Writes decoded base64 data to String.

Symbol type: function

#fio_string_write_url_enc

int fio_string_write_url_enc(fio_str_info_s *dest, fio_string_realloc_fn reallocate, const void *raw, size_t raw_len)

Writes data to String using URL encoding (a.k.a., percent encoding).

Symbol type: function

#fio_string_write_url_dec

int fio_string_write_url_dec(fio_str_info_s *dest, fio_string_realloc_fn reallocate, const void *encoded, size_t encoded_len)

Writes decoded URL data to String, decoding + to spaces.

Symbol type: function

#fio_string_write_path_dec

int fio_string_write_path_dec(fio_str_info_s *dest, fio_string_realloc_fn reallocate, const void *encoded, size_t encoded_len)

Writes decoded URL data to String, without decoding + to spaces.

Symbol type: function

#fio_string_write_html_escape

int fio_string_write_html_escape(fio_str_info_s *dest, fio_string_realloc_fn reallocate, const void *raw, size_t raw_len)

Writes HTML escaped data to a String.

Symbol type: function

#fio_string_write_html_unescape

int fio_string_write_html_unescape(fio_str_info_s *dest, fio_string_realloc_fn reallocate, const void *enscaped, size_t enscaped_len)

Writes HTML un-escaped data to a String - incomplete and minimal.

Symbol type: function

#fio_string_readfd

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

Writes up to limit bytes from fd into dest, starting at start_at.

If limit is 0 (or less than 0) data will be written until EOF.

If start_at is negative, position will be calculated from the end of the file where -1 == EOF.

Note: this will fail unless used on actual files (not sockets, not pipes).

Symbol type: function

#fio_string_readfile

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 the file filename and pastes it's contents (or a slice ot it) at the end of the String. If limit == 0, than the data will be read until EOF.

If the file can't be located, opened or read, or if start_at is beyond the EOF position, NULL is returned in the state's data field.

Symbol type: function

#fio_string_getdelim_fd

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)

Writes up to limit bytes from fd into dest, starting at start_at and ending either at the first occurrence of delim or at EOF.

If limit is 0 (or less than 0) as much data as may be required will be written.

If start_at is negative, position will be calculated from the end of the file where -1 == EOF.

Note: this will fail unless used on actual seekable files (not sockets, not pipes).

Symbol type: function

#fio_string_getdelim_file

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)

Opens the file filename, calls fio_string_getdelim_fd and closes the file.

Symbol type: function

#fio_string_capa4len

inline size_t fio_string_capa4len(size_t new_len)

Symbol type: function

#fio_string_default_reallocate

int fio_string_default_reallocate(fio_str_info_s *dst, size_t len)

default reallocation callback implementation.

Symbol type: function

#fio_string_default_allocate_copy

int fio_string_default_allocate_copy(fio_str_info_s *dest, size_t new_capa)

default reallocation callback for memory that mustn't be freed.

Symbol type: function

#fio_string_default_free

void fio_string_default_free(void *)

frees memory that was allocated with the default callbacks.

Symbol type: function

#fio_string_default_free2

void fio_string_default_free2(fio_str_info_s str)

frees memory that was allocated with the default callbacks.

Symbol type: function

#fio_string_default_free_noop

void fio_string_default_free_noop(void *)

does nothing.

Symbol type: function

#fio_string_default_free_noop2

void fio_string_default_free_noop2(fio_str_info_s str)

does nothing.

Symbol type: function

#fio_string_default_key_alloc

void *fio_string_default_key_alloc(size_t len)

default allocator for the fio_keystr_s string data..

Symbol type: function

#fio_string_default_free_key

void fio_string_default_free_key(void *, size_t)

frees a fio_keystr_s memory that was allocated with the default callback.

Symbol type: function

#fio_string_utf8_valid

bool fio_string_utf8_valid(fio_str_info_s str)

Returns 1 if the String is UTF-8 valid and 0 if not.

Symbol type: function

#fio_string_utf8_len

size_t fio_string_utf8_len(fio_str_info_s str)

Returns the String's length in UTF-8 characters or 0 if invalid.

Symbol type: function

#fio_string_utf8_valid_code_point

size_t fio_string_utf8_valid_code_point(const void *u8c, size_t buf_len)

Returns 0 if non-UTF-8 or returns 1-4 (UTF-8 if a valid char).

Symbol type: function

#fio_string_utf8_select

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

Takes a UTF-8 character selection information (UTF-8 position and length) and updates the same variables so they reference the raw byte slice information.

If the String isn't UTF-8 valid up to the requested selection, than pos will be updated to -1 otherwise values are always positive.

The returned len value may be shorter than the original if there wasn't enough data left to accommodate the requested length. When a len value of 0 is returned, this means that pos marks the end of the String.

Returns -1 on error and 0 on success.

Symbol type: function

#fio_string_is_greater_buf

int fio_string_is_greater_buf(fio_buf_info_s a, fio_buf_info_s b)

Compares two fio_buf_info_s, returning 1 if data in a is bigger than b.

Note: returns 0 if data in b is bigger than or equal(!).

Symbol type: function

#fio_string_is_greater

inline int fio_string_is_greater(fio_str_info_s a, fio_str_info_s b)

Compares two strings, returning 1 if string a is bigger than string b.

Note: returns 0 if string b is bigger than string a or if strings are equal.

Symbol type: function

#fio_bstr_reserve

inline char *fio_bstr_reserve(char *bstr, size_t len)

Reserves len for future write operations (used to minimize realloc).

Symbol type: function

#fio_bstr_copy

inline char *fio_bstr_copy(char *bstr)

Copies a fio_bstr using "copy on write".

Symbol type: function

#fio_bstr_free

inline void fio_bstr_free(char *bstr)

Frees a binary string allocated by a fio_bstr function. Returns NULL.

Symbol type: function

#fio_bstr_info

inline fio_str_info_s fio_bstr_info(const char *bstr)

Returns information about the fio_bstr.

Symbol type: function

#fio_bstr_buf

inline fio_buf_info_s fio_bstr_buf(const char *bstr)

Returns information about the fio_bstr.

Symbol type: function

#fio_bstr_len

inline size_t fio_bstr_len(const char *bstr)

Gets the length of the fio_bstr. bstr MUST NOT be NULL.

Symbol type: function

#fio_bstr_len_set

inline char *fio_bstr_len_set(char *bstr, size_t len)

Sets the length of the fio_bstr. bstr MUST NOT be NULL.

Symbol type: function

#fio_bstr_is_greater

FIO_SFUNC int fio_bstr_is_greater(const char *a, const char *b)

Compares to see if fio_bstr a is greater than fio_bstr b (for FIO_SORT).

Symbol type: function

#fio_bstr_is_eq

FIO_SFUNC int fio_bstr_is_eq(const char *a, const char *b)

Compares to see if fio_bstr a is equal to another fio_bstr.

Symbol type: function

#fio_bstr_is_eq2info

FIO_SFUNC int fio_bstr_is_eq2info(const char *a_, fio_str_info_s b)

Compares to see if fio_bstr a is equal to another String.

Symbol type: function

#fio_bstr_is_eq2buf

FIO_SFUNC int fio_bstr_is_eq2buf(const char *a_, fio_buf_info_s b)

Compares to see if fio_bstr a is equal to another String.

Symbol type: function

#fio_bstr_write

inline char *fio_bstr_write(char *bstr, const void *restrict src, size_t len)

Writes data to a fio_bstr, returning the address of the new fio_bstr. Returns existing string on reallocation error (true for all fio_bstr_write).

Symbol type: function

#fio_bstr_replace

inline char *fio_bstr_replace(char *bstr, intptr_t start_pos, size_t overwrite_len, const void *src, size_t len)

Replaces data in a fio_bstr, returning the address of the new fio_bstr.

Symbol type: function

#fio_bstr_write2

inline char *fio_bstr_write2(char *bstr, const fio_string_write_s srcs[])

Writes data to a fio_bstr, returning the address of the new fio_bstr.

Symbol type: function

#fio_bstr_write2

#define fio_bstr_write2(bstr, ...)   \
  fio_bstr_write2(bstr, (fio_string_write_s[]){__VA_ARGS__, {0}})

Writes data to a fio_bstr, returning the address of the new fio_bstr.

Note: this may be a macro only / macro wrapper for a function.

Symbol type: macro

#fio_bstr_write_i

inline char *fio_bstr_write_i(char *bstr, int64_t num)

Writes number to a fio_bstr, returning the address of the new fio_bstr.

Symbol type: function

#fio_bstr_write_u

inline char *fio_bstr_write_u(char *bstr, uint64_t num)

Writes number to a fio_bstr, returning the address of the new fio_bstr.

Symbol type: function

#fio_bstr_write_hex

inline char *fio_bstr_write_hex(char *bstr, uint64_t num)

Writes number to a fio_bstr, returning the address of the new fio_bstr.

Symbol type: function

#fio_bstr_write_bin

inline char *fio_bstr_write_bin(char *bstr, uint64_t num)

Writes number to a fio_bstr, returning the address of the new fio_bstr.

Symbol type: function

#fio_bstr_write_escape

inline char *fio_bstr_write_escape(char *bstr, const void *src, size_t len)

Writes escaped data to a fio_bstr, returning its new address.

Symbol type: function

#fio_bstr_write_unescape

inline char *fio_bstr_write_unescape(char *bstr, const void *src, size_t len)

Un-escapes and writes data to a fio_bstr, returning its new address.

Symbol type: function

#fio_bstr_write_base64enc

inline char *fio_bstr_write_base64enc(char *bstr, const void *src, size_t len, uint8_t url_encoded)

Writes base64 encoded data to a fio_bstr, returning its new address.

Symbol type: function

#fio_bstr_write_base64dec

inline char *fio_bstr_write_base64dec(char *bstr, const void *src, size_t len)

Decodes base64 data and writes to a fio_bstr, returning its new address.

Symbol type: function

#fio_bstr_write_url_enc

inline char *fio_bstr_write_url_enc(char *bstr, const void *data, size_t len)

Writes data to String using URL encoding (a.k.a., percent encoding).

Symbol type: function

#fio_bstr_write_url_dec

inline char *fio_bstr_write_url_dec(char *bstr, const void *encoded, size_t len)

Writes decoded URL data to String.

Symbol type: function

#fio_bstr_write_html_escape

inline char *fio_bstr_write_html_escape(char *bstr, const void *raw, size_t len)

Writes HTML escaped data to a String.

Symbol type: function

#fio_bstr_write_html_unescape

inline char *fio_bstr_write_html_unescape(char *bstr, const void *escaped, size_t len)

Writes HTML un-escaped data to a String - incomplete and minimal.

Symbol type: function

#fio_bstr_readfd

inline char *fio_bstr_readfd(char *bstr, int fd, intptr_t start_at, intptr_t limit)

Writes to the String from a regular file fd.

Symbol type: function

#fio_bstr_readfile

inline char *fio_bstr_readfile(char *bstr, const char *filename, intptr_t start_at, intptr_t limit)

Writes to the String from a regular file named filename.

Symbol type: function

#fio_bstr_getdelim_file

inline char *fio_bstr_getdelim_file(char *bstr, const char *filename, intptr_t start_at, char delim, size_t limit)

Writes to the String from a regular file named filename.

Symbol type: function

#fio_bstr_getdelim_fd

inline char *fio_bstr_getdelim_fd(char *bstr, int fd, intptr_t start_at, char delim, size_t limit)

Writes to the String from a regular file fd.

Symbol type: function

#fio_bstr_printf

inline FIO___PRINTF_STYLE(2, 0) char *fio_bstr_printf(char *bstr, const char *format, ...)

Writes a fio_bstr in printf style.

Symbol type: function

#fio_bstr_reallocate

int fio_bstr_reallocate(fio_str_info_s *dest, size_t len)

default reallocation callback implementation - mostly for internal use.

Symbol type: function

#fio_keystr_buf

inline fio_buf_info_s fio_keystr_buf(fio_keystr_s *str)

returns the Key String. NOTE: Key Strings are NOT NUL TERMINATED!

Symbol type: function

#fio_keystr_info

inline fio_str_info_s fio_keystr_info(fio_keystr_s *str)

returns the Key String. NOTE: Key Strings are NOT NUL TERMINATED!

Symbol type: function

#fio_keystr_tmp

inline fio_keystr_s fio_keystr_tmp(const char *buf, uint32_t len)

Returns a TEMPORARY fio_keystr_s.

Symbol type: function

#fio_keystr_init

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

Returns an initialized fio_keystr_s containing a copy of str.

Symbol type: function

#fio_keystr_destroy

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

Destroys an initialized fio_keystr_s.

Symbol type: function

#fio_keystr_is_eq

inline int fio_keystr_is_eq(fio_keystr_s a, fio_keystr_s b)

Compares two Key Strings.

Symbol type: function

#fio_keystr_is_eq2

inline int fio_keystr_is_eq2(fio_keystr_s a_, fio_str_info_s b)

Compares a Key String to any String - used internally by the hash map.

Symbol type: function

#fio_keystr_is_eq3

inline int fio_keystr_is_eq3(fio_keystr_s a_, fio_buf_info_s b)

Compares a Key String to any String - used internally by the hash map.

Symbol type: function

#fio_keystr_hash

inline uint64_t fio_keystr_hash(fio_keystr_s a)

Returns a good-enough fio_keystr_s risky hash.

Symbol type: function