facil.io
API Reference

#./fio-stl/250 fiobj.h

66 public symbols.

#Macros

#FIOBJ_MAX_NESTING

c
#define FIOBJ_MAX_NESTING 512

Sets the limit on nesting level transversal by recursive functions.

This effects JSON output / input and the fiobj_each2 function since they are recursive.

HOWEVER: this value will NOT effect the recursive fiobj_free which could (potentially) expload the stack if given melformed input such as cyclic data structures.

Values should be less than 32K.

Symbol type: macro

#FIOBJ_JSON_APPEND

c
#define FIOBJ_JSON_APPEND 1

Symbol type: macro

#FIOBJ_MARK_MEMORY_ALLOC

c
#define FIOBJ_MARK_MEMORY_ALLOC()   \
  fio_atomic_add(&FIOBJ_MARK_MEMORY_ALLOC_COUNTER, 1)

Symbol type: macro

#FIOBJ_MARK_MEMORY_FREE

c
#define FIOBJ_MARK_MEMORY_FREE()   \
  fio_atomic_add(&FIOBJ_MARK_MEMORY_FREE_COUNTER, 1)

Symbol type: macro

#FIOBJ_MARK_MEMORY_PRINT

c
#define FIOBJ_MARK_MEMORY_PRINT()   \
  FIO___LOG_PRINT_LEVEL(   \
      ((FIOBJ_MARK_MEMORY_ALLOC_COUNTER == FIOBJ_MARK_MEMORY_FREE_COUNTER)   \
           ? 4 /* FIO_LOG_LEVEL_INFO */   \
           : 3 /* FIO_LOG_LEVEL_WARNING */),   \
      ((FIOBJ_MARK_MEMORY_ALLOC_COUNTER == FIOBJ_MARK_MEMORY_FREE_COUNTER)   \
           ? "INFO: total remaining FIOBJ allocations: %zu (%zu - %zu)"   \
           : "WARNING: LEAKED! FIOBJ allocations: %zu (%zu - %zu)"),   \
      FIOBJ_MARK_MEMORY_ALLOC_COUNTER - FIOBJ_MARK_MEMORY_FREE_COUNTER,   \
      FIOBJ_MARK_MEMORY_ALLOC_COUNTER,   \
      FIOBJ_MARK_MEMORY_FREE_COUNTER)

Symbol type: macro

#FIOBJ_MARK_MEMORY_ENABLED

c
#define FIOBJ_MARK_MEMORY_ENABLED 1

If true, FIOBJ memory allocation counting is enabled.

Symbol type: macro

#FIOBJ_MARK_MEMORY_ALLOC_COUNTER

c
#define FIOBJ_MARK_MEMORY_ALLOC_COUNTER 0 /* when testing unmarked FIOBJ */

Symbol type: macro

#FIOBJ_MARK_MEMORY_FREE_COUNTER

c
#define FIOBJ_MARK_MEMORY_FREE_COUNTER  0 /* when testing unmarked FIOBJ */

Symbol type: macro

#FIOBJ_T_NULL

c
#define FIOBJ_T_NULL  2  /* 0b010 a lonely second bit signifies a primitive */

Symbol type: macro

#FIOBJ_T_TRUE

c
#define FIOBJ_T_TRUE  18 /* 0b010 010 - primitive value */

Symbol type: macro

#FIOBJ_T_FALSE

c
#define FIOBJ_T_FALSE 34 /* 0b100 010 - primitive value */

Symbol type: macro

#FIOBJ_TYPE

c
#define FIOBJ_TYPE(o) fiobj_type(o)

Use the macros to avoid future API changes.

Symbol type: macro

#FIOBJ_TYPE_IS

c
#define FIOBJ_TYPE_IS(o, type) (fiobj_type(o) == type)

Use the macros to avoid future API changes.

Symbol type: macro

#FIOBJ_T_INVALID

c
#define FIOBJ_T_INVALID 0

Identifies an invalid type identifier (returned from FIOBJ_TYPE(o)

Symbol type: macro

#FIOBJ_INVALID

c
#define FIOBJ_INVALID 0

Identifies an invalid object

Symbol type: macro

#FIOBJ_IS_INVALID

c
#define FIOBJ_IS_INVALID(o)     (((uintptr_t)(o)&7UL) == 0)

Tests if the object is (probably) a valid FIOBJ

Symbol type: macro

#FIOBJ_IS_NULL

c
#define FIOBJ_IS_NULL(o)        (FIOBJ_IS_INVALID(o) || ((o) == FIOBJ_T_NULL))

Symbol type: macro

#FIOBJ_TYPE_CLASS

c
#define FIOBJ_TYPE_CLASS(o)     ((fiobj_class_en)(((uintptr_t)(o)) & 7UL))

Symbol type: macro

#FIOBJ_PTR_TAG

c
#define FIOBJ_PTR_TAG(o, klass) ((uintptr_t)(((uintptr_t)(o)) | (klass)))

Symbol type: macro

#FIOBJ_PTR_UNTAG

c
#define FIOBJ_PTR_UNTAG(o)      ((uintptr_t)(((uintptr_t)(o)) & (~7ULL)))

Symbol type: macro

#FIOBJ_STR_TEMP_VAR

c
#define FIOBJ_STR_TEMP_VAR(str_name)   \
  struct {   \
    uint64_t i1;   \
    uint64_t i2;   \
    FIO_NAME(FIO_NAME(fiobj, FIOBJ___NAME_STRING), s) s;   \
  } FIO_NAME(str_name, __auto_mem_tmp) = {0x7f7f7f7f7f7f7f7fULL,   \
                                          0x7f7f7f7f7f7f7f7fULL,   \
                                          FIO_STR_INIT};   \
  FIOBJ str_name =   \
      (FIOBJ)(((uintptr_t) & (FIO_NAME(str_name, __auto_mem_tmp).s)) |   \
              FIOBJ_T_STRING);

Creates a temporary FIOBJ String object on the stack.

String data might be allocated dynamically.

Symbol type: macro

#FIOBJ_STR_TEMP_VAR_STATIC

c
#define FIOBJ_STR_TEMP_VAR_STATIC(str_name, buf_, len_)   \
  struct {   \
    uint64_t i1;   \
    uint64_t i2;   \
    FIO_NAME(FIO_NAME(fiobj, FIOBJ___NAME_STRING), s) s;   \
  } FIO_NAME(str_name,   \
             __auto_mem_tmp) = {0x7f7f7f7f7f7f7f7fULL,   \
                                0x7f7f7f7f7f7f7f7fULL,   \
                                FIO_STR_INIT_STATIC2((buf_), (len_))};   \
  FIOBJ str_name =   \
      (FIOBJ)(((uintptr_t) & (FIO_NAME(str_name, __auto_mem_tmp).s)) |   \
              FIOBJ_T_STRING);

Creates a temporary FIOBJ String object on the stack, initialized with a static string.

String data might be allocated dynamically.

Symbol type: macro

#FIOBJ_STR_TEMP_VAR_EXISTING

c
#define FIOBJ_STR_TEMP_VAR_EXISTING(str_name, buf_, len_, capa_)   \
  struct {   \
    uint64_t i1;   \
    uint64_t i2;   \
    FIO_NAME(FIO_NAME(fiobj, FIOBJ___NAME_STRING), s) s;   \
  } FIO_NAME(str_name, __auto_mem_tmp) = {   \
      0x7f7f7f7f7f7f7f7fULL,   \
      0x7f7f7f7f7f7f7f7fULL,   \
      FIO_STR_INIT_EXISTING((buf_), (len_), (capa_))};   \
  FIOBJ str_name =   \
      (FIOBJ)(((uintptr_t) & (FIO_NAME(str_name, __auto_mem_tmp).s)) |   \
              FIOBJ_T_STRING);

Creates a temporary FIOBJ String object on the stack, initialized with a static string.

String data might be allocated dynamically.

Symbol type: macro

#FIOBJ_STR_TEMP_DESTROY

c
#define FIOBJ_STR_TEMP_DESTROY(str_name)   \
  FIO_NAME(FIO_NAME(fiobj, FIOBJ___NAME_STRING), destroy)(str_name);

Resets a temporary FIOBJ String, freeing and any resources allocated.

Symbol type: macro

#Types

#fiobj_class_en

c
typedef enum {
FIOBJ_T_NUMBER = 0x01, /* 0b001 3 bits taken for small numbers */
FIOBJ_T_PRIMITIVE = 2, /* 0b010 a lonely second bit signifies a primitive */
FIOBJ_T_STRING = 3, /* 0b011 */
FIOBJ_T_ARRAY = 4, /* 0b100 */
FIOBJ_T_HASH = 5, /* 0b101 */
FIOBJ_T_FLOAT = 6, /* 0b110 */
FIOBJ_T_OTHER = 7, /* 0b111 dynamic type - test content */
} fiobj_class_en

FIOBJ type enum for common / primitive types.

Symbol type: type

#fiobj_each_s

c
struct fiobj_each_s {
/** The being iterated. Once set, cannot be safely changed. */
FIOBJ const parent;
/** The index to start at / the current object's index */
uint64_t index;
/** The callback / task called for each index, may be updated mid-cycle. */
int (*task)(struct fiobj_each_s *info);
/** The argument passed along to the task. */
void *udata;
/** The value of the current object in the Array or Hash Map */
FIOBJ value;
/* The key, if a Hash Map */
FIOBJ key;
}

Iteration information structure passed to the callback.

Symbol type: type

#Functions

#fiobj_type

c
inline size_t fiobj_type(FIOBJ o)

Returns an objects type. This isn't limited to known types.

Symbol type: function

#fiobj_dup

c
inline FIOBJ fiobj_dup(FIOBJ o)

Increases an object's reference count (or copies) and returns it.

Symbol type: function

#fiobj_free

c
inline void fiobj_free(FIOBJ o)

Decreases an object's reference count or frees it.

Symbol type: function

#fiobj_is_eq

c
inline unsigned char fiobj_is_eq(FIOBJ a, FIOBJ b)

Compares two objects.

Symbol type: function

#fiobj2cstr

c
inline fio_str_info_s fiobj2cstr(FIOBJ o)

Returns a temporary String representation for any FIOBJ object.

Symbol type: function

#fiobj2i

c
inline intptr_t fiobj2i(FIOBJ o)

Returns an integer representation for any FIOBJ object.

Symbol type: function

#fiobj2f

c
inline double fiobj2f(FIOBJ o)

Returns a float (double) representation for any FIOBJ object.

Symbol type: function

#fiobj2hash

c
inline uint64_t fiobj2hash(FIOBJ object_key)

Calculates an object's hash value for a specific hash map object.

Symbol type: function

#fiobj_each1

c
FIO_SFUNC uint32_t fiobj_each1(FIOBJ o, int (*task)(fiobj_each_s *info), void *udata, int32_t start_at)

Performs a task for each element held by the FIOBJ object.

If task returns -1, the each loop will break (stop).

Returns the "stop" position - the number of elements processed + start_at.

Symbol type: function

#fiobj_each2

c
uint32_t fiobj_each2(FIOBJ o, int (*task)(fiobj_each_s *info), void *udata)

Performs a task for the object itself and each element held by the FIOBJ object or any of it's elements (a deep task).

The order of performance is by order of appearance, as if all nesting levels were flattened.

If task returns -1, the each loop will break (stop).

Returns the number of elements processed.

Symbol type: function

#fiobj_true

c
inline FIOBJ fiobj_true(void)

Returns the true primitive.

Symbol type: function

#fiobj_false

c
inline FIOBJ fiobj_false(void)

Returns the false primitive.

Symbol type: function

#fiobj_null

c
inline FIOBJ fiobj_null(void)

Returns the nil / null primitive.

Symbol type: function

#fiobj_num_new

c
inline FIOBJ FIO_NAME(fiobj_num_new, new)(intptr_t i)

Creates a new Number object.

Symbol type: function

#fiobj_num2i

c
inline intptr_t FIO_NAME2(fiobj_num2i, i)(FIOBJ i)

Reads the number from a FIOBJ Number.

Symbol type: function

#fiobj_num2f

c
inline double FIO_NAME2(fiobj_num2f, f)(FIOBJ i)

Reads the number from a FIOBJ Number, fitting it in a double.

Symbol type: function

#fiobj_num2cstr

c
fio_str_info_s FIO_NAME2(fiobj_num2cstr, cstr)(FIOBJ i)

Returns a String representation of the number (in base 10).

Symbol type: function

#fiobj_num_free

c
inline void FIO_NAME(fiobj_num_free, free)(FIOBJ i)

Frees a FIOBJ number.

Symbol type: function

#fiobj_float_new

c
inline FIOBJ FIO_NAME(fiobj_float_new, new)(double i)

Creates a new Float (double) object.

Symbol type: function

#fiobj_float2i

c
inline intptr_t FIO_NAME2(fiobj_float2i, i)(FIOBJ i)

Reads the number from a FIOBJ Float rounding it to an integer.

Symbol type: function

#fiobj_float2f

c
inline double FIO_NAME2(fiobj_float2f, f)(FIOBJ i)

Reads the value from a FIOBJ Float, as a double.

Symbol type: function

#fiobj_float2cstr

c
fio_str_info_s FIO_NAME2(fiobj_float2cstr, cstr)(FIOBJ i)

Returns a String representation of the float.

Symbol type: function

#fiobj_float_free

c
inline void FIO_NAME(fiobj_float_free, free)(FIOBJ i)

Frees a FIOBJ Float.

Symbol type: function

#fiobj_str_new_cstr

c
inline FIOBJ FIO_NAME(fiobj_str_new_cstr, new_cstr)(const char *ptr, size_t len)

Symbol type: function

#fiobj_str_new_buf

c
inline FIOBJ FIO_NAME(fiobj_str_new_buf, new_buf)(size_t capa)

Symbol type: function

#fiobj_str_new_copy

c
inline FIOBJ FIO_NAME(fiobj_str_new_copy, new_copy)(FIOBJ original)

Symbol type: function

#fiobj_str2cstr

c
inline fio_str_info_s FIO_NAME2(fiobj_str2cstr, cstr)(FIOBJ s)

Returns information about the string. Same as fiobj_str_info().

Symbol type: function

#fiobj_hash_set2

c
inline FIOBJ FIO_NAME(fiobj_hash_set2, set2)(FIOBJ hash, const char *key, size_t len, FIOBJ value)

Sets a value in a hash map, allocating the key String and automatically calculating the hash value.

Symbol type: function

#fiobj_hash_get2

c
inline FIOBJ FIO_NAME(fiobj_hash_get2, get2)(FIOBJ hash, const char *buf, size_t len)

Finds a value in the hash map, using a temporary String and automatically calculating the hash value.

Symbol type: function

#fiobj_hash_remove2

c
inline int FIO_NAME(fiobj_hash_remove2, remove2)(FIOBJ hash, const char *buf, size_t len, FIOBJ *old)

Removes a value in a hash map, using a temporary String and automatically calculating the hash value.

Symbol type: function

#fiobj2json

c
inline FIOBJ fiobj2json(FIOBJ dest, FIOBJ o, uint8_t beautify)

Returns a JSON valid FIOBJ String, representing the object.

If dest is an existing String, the formatted JSON data will be appended to the existing string.

Symbol type: function

#fiobj_hash_update_json

c
size_t FIO_NAME(fiobj_hash_update_json, update_json)(FIOBJ hash, fio_str_info_s str)

Updates a Hash using JSON data.

Parsing errors and non-dictionary object JSON data are silently ignored, attempting to update the Hash as much as possible before any errors encountered.

Conflicting Hash data is overwritten (preferring the new over the old).

Returns the number of bytes consumed. On Error, 0 is returned and no data is consumed.

Symbol type: function

#fiobj_hash_update_json2

c
inline size_t FIO_NAME(fiobj_hash_update_json2, update_json2)(FIOBJ hash, char *ptr, size_t len)

Helper function, calls fiobj_hash_update_json with string information

Symbol type: function

#fiobj_json_parse

c
FIOBJ fiobj_json_parse(fio_str_info_s str, size_t *consumed)

Parses a C string for JSON data. If consumed is not NULL, the size_t variable will contain the number of bytes consumed before the parser stopped (due to either error or end of a valid JSON data segment).

Returns a FIOBJ object matching the JSON valid C string str.

If the parsing failed (no complete valid JSON data) FIOBJ_INVALID is returned.

Symbol type: function

#fiobj_json_parse2

c
#define fiobj_json_parse2(data_, len_, consumed)   \
  fiobj_json_parse(FIO_STR_INFO2(data_, len_), consumed)

Helper macro, calls fiobj_json_parse with string information

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

Symbol type: macro

#fiobj_json_find

c
FIOBJ fiobj_json_find(FIOBJ object, fio_str_info_s notation)

Uses JavaScript style notation to find data in an object structure.

For example, "[0].name" will return the "name" property of the first object in an array object.

Returns a temporary reference to the object or FIOBJ_INVALID on an error.

Use fiobj_dup to collect an actual reference to the returned object.

Symbol type: function

#fiobj_json_find2

c
#define fiobj_json_find2(object, str, length)   \
  fiobj_json_find(object, FIO_STR_INFO2(str, length))

Uses JavaScript style notation to find data in an object structure.

For example, "[0].name" will return the "name" property of the first object in an array object.

Returns a temporary reference to the object or FIOBJ_INVALID on an error.

Use fiobj_dup to collect an actual reference to the returned object.

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

Symbol type: macro

#fiobj_mustache_build

c
inline FIOBJ fiobj_mustache_build(fio_mustache_s *m, FIOBJ ctx)

Builds a Mustache template using a FIOBJ context (usually a Hash).

Returns a FIOBJ String with the rendered template. May return FIOBJ_INVALID if nothing was written.

Symbol type: function

#fiobj_mustache_build2

c
inline FIOBJ fiobj_mustache_build2(fio_mustache_s *m, FIOBJ dest, FIOBJ ctx)

Builds a Mustache template using a FIOBJ context (usually a Hash).

Writes output to dest string (may be FIOBJ_INVALID / NULL).

Returns dest (or a new String). May return FIOBJ_INVALID if nothing was written and dest was empty.

Symbol type: function

#fiobj_hash_update

c
inline void FIO_NAME(fiobj_hash_update, update)(FIOBJ dest, FIOBJ src)

Updates a hash using information from another Hash.

Symbol type: function