# `./fio-stl/201 string.h` 47 public symbols. ### Macros #### `FIO_STR_OPTIMIZE_EMBEDDED` ```c #define FIO_STR_OPTIMIZE_EMBEDDED 0 ``` For each unit (0 by default), adds `sizeof(char *)` bytes to the type size, increasing the amount of strings that could be embedded within the type without additional memory allocation. For example, when using a reference counter wrapper on a 64bit system, it would make sense to set this value to 1 - allowing the type size to fully utilize a 16 byte memory allocation alignment. _Symbol type:_ `macro` #### `FIO_STR_OPTIMIZE4IMMUTABILITY` ```c #define FIO_STR_OPTIMIZE4IMMUTABILITY 0 ``` Minimizes the struct size, storing only string length and pointer. By avoiding extra (mutable related) data, such as the allocated memory's capacity, strings require less memory. However, this does introduce a performance penalty when editing the string data. _Symbol type:_ `macro` #### `FIO_STR_INIT` ```c #define FIO_STR_INIT \ { .special = 0 } ``` This value should be used for initialization. For example: // on the stack fio_str_s str = FIO_STR_INIT; // or on the heap fio_str_s *str = malloc(sizeof(*str)); *str = FIO_STR_INIT; Remember to cleanup: // on the stack fio_str_destroy(&str); // or on the heap fio_str_free(str); free(str); _Symbol type:_ `macro` #### `FIO_STR_INIT_EXISTING` ```c #define FIO_STR_INIT_EXISTING(buffer, length, capacity) \ { .capa = (capacity), .len = (length), .buf = (buffer) } ``` This macro allows the container to be initialized with existing data, as long as it's memory was allocated with the same allocator (`malloc` / `fio_malloc`). The `capacity` value should exclude the NUL character (if exists). NOTE: This macro isn't valid for FIO_STR_SMALL (or strings with the FIO_STR_OPTIMIZE4IMMUTABILITY optimization) _Symbol type:_ `macro` #### `FIO_STR_INIT_STATIC` ```c #define FIO_STR_INIT_STATIC(buffer) \ { \ .special = 4, .capa = FIO_STRLEN((buffer)), .len = FIO_STRLEN((buffer)), \ .buf = (char *)(buffer) \ } ``` This macro allows the container to be initialized with existing static data, that shouldn't be freed. NOTE: This macro isn't valid for FIO_STR_SMALL (or strings with the FIO_STR_OPTIMIZE4IMMUTABILITY optimization) _Symbol type:_ `macro` #### `FIO_STR_INIT_STATIC2` ```c #define FIO_STR_INIT_STATIC2(buffer, length) \ { .special = 4, .capa = (length), .len = (length), .buf = (char *)(buffer) } ``` This macro allows the container to be initialized with existing static data, that shouldn't be freed. NOTE: This macro isn't valid for FIO_STR_SMALL (or strings with the FIO_STR_OPTIMIZE4IMMUTABILITY optimization) _Symbol type:_ `macro` #### `FIO_STR_WRITE2` ```c #define FIO_STR_WRITE2(str_name, dest, ...) \ FIO_NAME(str_name, __write2)(dest, (fio_string_write_s[]){__VA_ARGS__, {0}}) ``` _Symbol type:_ `macro` ### Types #### `fiobj_str_s` ```c typedef struct { /* String flags: * * bit 1: small string. * bit 2: frozen string. * bit 3: static (non allocated) string (big strings only). * bit 3-8: small string length (up to 64 bytes). */ uint8_t special; uint8_t reserved[(sizeof(void *) * (1 + FIO_STR_OPTIMIZE_EMBEDDED)) - (sizeof(uint8_t))]; /* padding length */ #if !FIO_STR_OPTIMIZE4IMMUTABILITY size_t capa; /* known capacity for longer Strings */ size_t len; /* String length for longer Strings */ #endif /* FIO_STR_OPTIMIZE4IMMUTABILITY */ char *buf; /* pointer for longer Strings */ } fiobj_str_s ``` The `fio_str_s` type should be considered opaque. The type's attributes should be accessed ONLY through the accessor functions: `fio_str2cstr`, `fio_str_len`, `fio_str2ptr`, `fio_str_capa`, etc'. Note: when the `small` flag is present, the structure is ignored and used as raw memory for a small String (no additional allocation). This changes the String's behavior drastically and requires that the accessor functions be used. _Symbol type:_ `type` ### Functions #### `fiobj_str_init_const` ```c inline fio_str_info_s fiobj_str_init_const(FIO_STR_PTR s, const char *str, size_t len) ``` Initializes the container with the provided static / constant string. The string will be copied to the container **only** if it will fit in the container itself. Otherwise, the supplied pointer will be used as is and it should remain valid until the string is destroyed. The final string can be safely be destroyed (using the `destroy` function). _Symbol type:_ `function` #### `fiobj_str_init_copy` ```c inline fio_str_info_s fiobj_str_init_copy(FIO_STR_PTR s, const char *str, size_t len) ``` Initializes the container with a copy of the provided dynamic string. The string is always copied and the final string must be destroyed (using the `destroy` function). _Symbol type:_ `function` #### `fiobj_str_init_copy2` ```c inline fio_str_info_s fiobj_str_init_copy2(FIO_STR_PTR dest, FIO_STR_PTR src) ``` Initializes the container with a copy of an existing String object. The string is always copied and the final string must be destroyed (using the `destroy` function). _Symbol type:_ `function` #### `fiobj_str_destroy` ```c inline void fiobj_str_destroy(FIO_STR_PTR s) ``` Frees the String's resources and re-initializes the container. Note: if the container isn't allocated on the stack, it should be freed separately using the appropriate `free` function. _Symbol type:_ `function` #### `fiobj_str_detach` ```c inline char *fiobj_str_detach(FIO_STR_PTR s) ``` Returns a C string with the existing data, re-initializing the String. Note: the String data is removed from the container, but the container isn't freed. Returns NULL if there's no String data. NOTE: Returned string is ALWAYS dynamically allocated. Remember to free. _Symbol type:_ `function` #### `fiobj_str_dealloc` ```c inline void fiobj_str_dealloc(void *ptr) ``` Frees the pointer returned by `detach`. _Symbol type:_ `function` #### `fiobj_str_info` ```c inline fio_str_info_s fiobj_str_info(const FIO_STR_PTR s) ``` Returns the String's complete state (capacity, length and pointer). _Symbol type:_ `function` #### `fiobj_str_buf` ```c inline fio_buf_info_s fiobj_str_buf(const FIO_STR_PTR s) ``` Returns the String's partial state (length and pointer). _Symbol type:_ `function` #### `fiobj_str_ptr` ```c inline char *fiobj_str_ptr(FIO_STR_PTR s) ``` Returns a pointer (`char *`) to the String's content. _Symbol type:_ `function` #### `fiobj_str_len` ```c inline size_t fiobj_str_len(FIO_STR_PTR s) ``` Returns the String's length in bytes. _Symbol type:_ `function` #### `fiobj_str_capa` ```c inline size_t fiobj_str_capa(FIO_STR_PTR s) ``` Returns the String's existing capacity (total used & available memory). _Symbol type:_ `function` #### `fiobj_str_freeze` ```c inline void fiobj_str_freeze(FIO_STR_PTR s) ``` Prevents further manipulations to the String's content. _Symbol type:_ `function` #### `fiobj_str_is_frozen` ```c inline uint8_t fiobj_str_is_frozen(FIO_STR_PTR s) ``` Returns true if the string is frozen. _Symbol type:_ `function` #### `fiobj_str_is_allocated` ```c inline int fiobj_str_is_allocated(const FIO_STR_PTR s) ``` Returns 1 if memory was allocated (and the String must be destroyed). _Symbol type:_ `function` #### `fiobj_str_is_eq` ```c inline int fiobj_str_is_eq(const FIO_STR_PTR str1, const FIO_STR_PTR str2) ``` Binary comparison returns `1` if both strings are equal and `0` if not. _Symbol type:_ `function` #### `fiobj_str_hash` ```c inline uint64_t fiobj_str_hash(const FIO_STR_PTR s, uint64_t seed) ``` Returns the string's Risky Hash value. Note: Hash algorithm might change without notice. _Symbol type:_ `function` #### `fiobj_str_resize` ```c inline fio_str_info_s fiobj_str_resize(FIO_STR_PTR s, size_t size) ``` Sets the new String size without reallocating any memory (limited by existing capacity). Returns the updated state of the String. Note: When shrinking, any existing data beyond the new size may be corrupted. _Symbol type:_ `function` #### `fiobj_str_compact` ```c inline void fiobj_str_compact(FIO_STR_PTR s) ``` Performs a best attempt at minimizing memory consumption. Actual effects depend on the underlying memory allocator and it's implementation. Not all allocators will free any memory. _Symbol type:_ `function` #### `fiobj_str_reserve` ```c fio_str_info_s fiobj_str_reserve(FIO_STR_PTR s, size_t amount) ``` Reserves (at least) `amount` of bytes for the string's data. `amount` is in addition to existing String length. Make sure to call `resize` with the updated information once the editing is done. Returns the updated state of the String. _Symbol type:_ `function` #### `fiobj_str_utf8_valid` ```c size_t fiobj_str_utf8_valid(FIO_STR_PTR s) ``` Returns 1 if the String is UTF-8 valid and 0 if not. _Symbol type:_ `function` #### `fiobj_str_utf8_len` ```c size_t fiobj_str_utf8_len(FIO_STR_PTR s) ``` Returns the String's length in UTF-8 characters. _Symbol type:_ `function` #### `fiobj_str_utf8_select` ```c int fiobj_str_utf8_select(FIO_STR_PTR s, 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` #### `fiobj_str_write` ```c inline fio_str_info_s fiobj_str_write(FIO_STR_PTR s, const void *src, size_t src_len) ``` Writes data at the end of the String. _Symbol type:_ `function` #### `fiobj_str_concat` ```c fio_str_info_s fiobj_str_concat(FIO_STR_PTR dest, FIO_STR_PTR const src) ``` Appends the `src` String to the end of the `dest` String. If `dest` is empty, the resulting Strings will be equal. _Symbol type:_ `function` #### `fiobj_str_join` ```c inline fio_str_info_s fiobj_str_join(FIO_STR_PTR dest, FIO_STR_PTR const src) ``` Alias for fio_str_concat _Symbol type:_ `function` #### `fiobj_str_replace` ```c fio_str_info_s fiobj_str_replace(FIO_STR_PTR s, intptr_t start_pos, size_t old_len, const void *src, size_t src_len) ``` Replaces the data in the String - replacing `old_len` bytes starting at `start_pos`, with the data at `src` (`src_len` bytes long). Negative `start_pos` values are calculated backwards, `-1` == end of String. When `old_len` is zero, the function will insert the data at `start_pos`. If `src_len == 0` than `src` will be ignored and the data marked for replacement will be erased. _Symbol type:_ `function` #### `fiobj_str_write_i` ```c fio_str_info_s fiobj_str_write_i(FIO_STR_PTR s, int64_t num) ``` Writes a number at the end of the String using normal base 10 notation. _Symbol type:_ `function` #### `fiobj_str_write_hex` ```c fio_str_info_s fiobj_str_write_hex(FIO_STR_PTR s, int64_t num) ``` Writes a number at the end of the String using Hex (base 16) notation. _Symbol type:_ `function` #### `fiobj_str_write_bin` ```c fio_str_info_s fiobj_str_write_bin(FIO_STR_PTR s, int64_t num) ``` _Symbol type:_ `function` #### `fiobj_str_vprintf` ```c fio_str_info_s fiobj_str_vprintf(FIO_STR_PTR s, const char *format, va_list argv) ``` Writes to the String using a vprintf like interface. Data is written to the end of the String. _Symbol type:_ `function` #### `fiobj_str_printf` ```c fio_str_info_s fiobj_str_printf(FIO_STR_PTR s, const char *format, ...) ``` Writes to the String using a printf like interface. Data is written to the end of the String. _Symbol type:_ `function` #### `fiobj_str_write_escape` ```c fio_str_info_s fiobj_str_write_escape(FIO_STR_PTR s, const void *data, size_t data_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` #### `fiobj_str_write_unescape` ```c fio_str_info_s fiobj_str_write_unescape(FIO_STR_PTR s, const void *escaped, size_t len) ``` Writes an escaped data into the string after unescaping the data. _Symbol type:_ `function` #### `fiobj_str_write_base64enc` ```c fio_str_info_s fiobj_str_write_base64enc(FIO_STR_PTR s, const void *data, size_t data_len, uint8_t url_encoded) ``` Writes data at the end of the String, encoding the data as Base64 encoded data. _Symbol type:_ `function` #### `fiobj_str_write_base64dec` ```c fio_str_info_s fiobj_str_write_base64dec(FIO_STR_PTR s, const void *encoded, size_t encoded_len) ``` Writes decoded base64 data to the end of the String. _Symbol type:_ `function` #### `fiobj_str_write_html_escape` ```c fio_str_info_s fiobj_str_write_html_escape(FIO_STR_PTR s, const void *raw, size_t len) ``` Writes HTML escaped data to a String. _Symbol type:_ `function` #### `fiobj_str_write_html_unescape` ```c fio_str_info_s fiobj_str_write_html_unescape(FIO_STR_PTR s, const void *escaped, size_t len) ``` Writes HTML un-escaped data to a String - incomplete and minimal. _Symbol type:_ `function` #### `fiobj_str_readfd` ```c fio_str_info_s fiobj_str_readfd(FIO_STR_PTR s, int fd, intptr_t start_at, intptr_t limit) ``` Reads data from a file descriptor `fd` at offset `start_at` and pastes it's contents (or a slice of it) at the end of the String. If `limit == 0`, than the data will be read until EOF. The file should be a regular file or the operation might fail (can't be used for sockets). The file descriptor will remain open and should be closed manually. _Symbol type:_ `function` #### `fiobj_str_readfile` ```c fio_str_info_s fiobj_str_readfile(FIO_STR_PTR s, const char *filename, intptr_t start_at, intptr_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` -----------------------------------------------------