# facil.io - FIOBJ String API

See the core FIOBJ functions for accessing the String data (`fiobj_obj2cstr`) and freeing the String object (`fiobj_free`).

### FIOBJ String Initialization

#### `fiobj_str_new`

    FIOBJ fiobj_str_new(const char *str, size_t len);

Creates a String object. Remember to use `fiobj_free`.

#### `fiobj_str_buf`

    FIOBJ fiobj_str_buf(size_t capa);

Creates a String object with pre-allocation for Strings up to `capa` long.

If `capa` is zero, a whole memory page will be allocated.

Remember to use `fiobj_free`.

#### `fiobj_str_copy`

    static inline FIOBJ fiobj_str_copy(FIOBJ src);

Creates a copy from an existing String. Remember to use `fiobj_free`.

Implemented as:

    static inline FIOBJ fiobj_str_copy(FIOBJ src) {
      fio_str_info_s s = fiobj_obj2cstr(src);
      return fiobj_str_new(s.data, s.len);
    }

#### `fiobj_str_move`

    FIOBJ fiobj_str_move(char *str, size_t len, size_t capacity);

Creates a String object. Remember to use `fiobj_free`.

It's possible to wrap a previosly allocated memory block in a FIOBJ String object, as long as it was allocated using `fio_malloc`.

The ownership of the memory indicated by `str` will "move" to the object and will be freed (using `fio_free`) once the object's reference count drops to zero.

Note: The original memory MUST be allocated using `fio_malloc` (NOT the system's `malloc`) and it will be freed using `fio_free`.

#### `fiobj_str_tmp`

    FIOBJ fiobj_str_tmp(void);

Returns a thread-static temporary string. Avoid calling `fiobj_dup` or `fiobj_free`.

## String Manipulation and Data

#### `fiobj_str_freeze`

    void fiobj_str_freeze(FIOBJ str);

Prevents the String object from being changed.

When a String is used as a key for a Hash, it is automatically frozen to prevent the Hash from becoming broken.

#### `fiobj_str_capa_assert`

    size_t fiobj_str_capa_assert(FIOBJ str, size_t size);

Confirms the requested capacity is available and allocates as required.

Returns updated capacity.

#### `fiobj_str_capa`

    size_t fiobj_str_capa(FIOBJ str);

Returns a String's capacity, if any. This should include the NUL byte.

#### `fiobj_str_resize`

    void fiobj_str_resize(FIOBJ str, size_t size);

Resizes a String object, allocating more memory if required.

#### `fiobj_str_compact`

    void fiobj_str_compact(FIOBJ str);

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.

#### `fiobj_str_compact`

    #define fiobj_str_minimize(str) fiobj_str_compact((str))

Alias for `fiobj_str_compact`.

#### `fiobj_str_clear`

    void fiobj_str_clear(FIOBJ str);

Empties a String's data, but keeps the memory used for that data available.

#### `fiobj_str_write`

    size_t fiobj_str_write(FIOBJ dest, const char *data, size_t len);

Writes data at the end of the string, resizing the string as required.

Returns the new length of the String.

#### `fiobj_str_write_i`

    size_t fiobj_str_write_i(FIOBJ dest, int64_t num)

Writes a number at the end of the String using normal base 10 notation.

Returns the new length of the String

#### `fiobj_str_printf`

    size_t fiobj_str_printf(FIOBJ dest, const char *format, ...);

Writes data at the end of the string using a `printf` like interface, resizing the string as required.

Returns the new length of the String

#### `fiobj_str_vprintf`

    size_t fiobj_str_vprintf(FIOBJ dest, const char *format, va_list argv);

Writes data at the end of the string using a `vprintf` like interface, resizing the string as required.

Returns the new length of the String.

#### `fiobj_str_concat`

    size_t fiobj_str_concat(FIOBJ dest, FIOBJ source);

Writes data at the end of the string, resizing the string as required.

Remember to call `fiobj_free` to free the source (when done with it).

Returns the new length of the String.

#### `fiobj_str_join`

    #define fiobj_str_join(dest, src) fiobj_str_concat((dest), (src))

Alias for `fiobj_str_concat`.

#### `fiobj_str_readfile`

    size_t fiobj_str_readfile(FIOBJ dest, const char *filename, intptr_t start_at,
                              intptr_t limit);

Dumps the contents of `filename` 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 out of bounds (i.e., beyond the EOF position), FIOBJ_INVALID is returned.

If `start_at` is negative, it will be computed from the end of the file.

Remember to use `fiobj_free`.

NOTE: Requires a POSIX system, or might silently fail.

### Hashing

#### `fiobj_str_hash`

    uint64_t fiobj_str_hash(FIOBJ o);

Calculates a String's hash value for possible use as a Hash Map key.

Hash values use the default hashing function defined at compile time. This is usually SipHash 1-3, but could be set to a different hashing function (such as RiskyHash).

Note:

Since FIOBJ hashes are impervious to hash flooding attacks by design and don't require a strong hashing function. However, objects often contain network (external) information, and it would be better to use a strong hashing function.

X