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