facil.io
API Reference

#./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