carb::dictionary::IDictionary

Defined in carb/dictionary/IDictionary.h

struct IDictionary

DOM-style dictionary (keeps the whole structure in-memory).

In most functions, item is specified using the relative root index and path from the relative root. Path can be nullptr, meaning that baseItem will be considered a specified item.

In some cases, a read or write lock must be held across multiple function calls. An example of this would be a call to getItemChildCount() followed by one or more calls to getItemChildByIndex(). Since you would not want another thread to change the dictionary between the two calls, you must use a lock to keep the state consistent. In this case ScopedWrite and ScopedRead exist to maintain a lock across multiple calls.

Thread Safety: IDictionary functions are thread-safe unless otherwise indicated. Where possible, a shared (“read”) lock is held so that multiple threads may query data from a carb::dictionary::Item without blocking each other. Functions that contain Mutable in the name, and functions that exchange non-const carb::dictionary::Item pointers will hold an exclusive (“write”) lock, which will block any other threads attempting to perform read/write operations on the carb::dictionary::Item. These locks are held at the true-root level of the Item hierarchy which ensures safety across that root Item’s hierarchy (see IDictionary::createItem).

Ordering

Dictionary items of type ItemType::eDictionary can function as either an array type (sequential integer keys starting with 0), or a map type. For map types, dictionary attempts to order child items in the order that they were created, provided that the items were created by createItem(), update(), or duplicateItem() (the “creation functions”). This order is reflected when retrieving child items via getItemChildByIndex(). Performing one of the creation functions on a key that already exists will move it to the end of the order, but merely setting a value on an existing item will not change its order.

Subscriptions

Dictionary Item objects may have subscriptions for notification of changes, either for an individual Item (subscribeToNodeChangeEvents), or a sub-tree (subscribeToTreeChangeEvents). Subscriptions are called in the context of the thread that triggered the change, and only once that thread has fully released the lock for the dictionary hierarchy that contains the changed Item (since looks are at the true-root level). Subscription callbacks also follow the principles of Basic Callback Hygiene:

unsubscribeToChangeEvents may be called from within the callback to unregister the called subscription or any other subscription.
Unregistering the subscription ensures that it will never be called again, and any calls in process on another thread will complete before unsubscribeToChangeEvents returns.
The true-root level lock is not held while the callback is called, but may be temporarily taken for API calls within the callback.

Public Functions

inline int32_t getAsInt(const Item *item)

Attempts to get the supplied item as 32-bit integer, either directly or via a cast.

Warning

The value is truncated by casting to 32-bits. In debug builds, an assert occurs if the value read from the item would be truncated.

Parameters: item – [in] The item to retrieve the integer value from.
Returns: The 64 bit integer value of item. This will be converted from the existing type if this Item is not a 64 bit integer. The conversion semantics are the same as for getAsInt64(). Note that the string conversion behavior has the same clamping limits as getAsInt64(), which may result in unexpected wraparound behavior; you should use getAsInt64() instead if you may be reading string values.

inline void setInt(Item *item, int32_t value)

Sets the 32-bit integer value for the supplied item.

If an item was already present, changes its original type to eInt. If the present item is a eDictionary item, destroys all its children. If the item doesn’t exist, creates eInt item, and all the required items along the path if necessary.

Parameters

item – dictionary::Item
value – Integer value that will be set to the supplied item.

inline Item *makeInt64AtPath(Item *baseItem, const char *path, int64_t value)

Helper function that sets the value to an item at path.

Creates item at path if it doesn’t exist.

Parameters

baseItem – Base item to apply path from.
path – Path.
value – Integer value that will be set to the supplied item.

inline Item *makeIntAtPath(Item *baseItem, const char *path, int32_t value)

Helper function that sets the value to an item at path.

Creates item at path if it doesn’t exist.

Parameters

baseItem – Base item to apply path from.
path – Path.
value – Integer value that will be set to the supplied item.

inline float getAsFloat(const Item *item)

Attempts to get the supplied item as 32-bit float, either directly or via a cast.

Parameters: item – [in] The item to retrieve the floating point value from.
Returns: The 64 bit floating point value of item. This will be converted from the existing type if this Item is not a double. The conversion semantics are the same as with getAsFloat64().

inline void setFloat(Item *item, float value)

Sets the 32-bit floating point value for the supplied item.

If an item was already present, changes its original type to eFloat. If the present item is a eDictionary item, destroys all its children. If the item doesn’t exist, creates eFloat item, and all the required items along the path if necessary.

Parameters

item – dictionary::Item
value – Floating point value that will be set to the supplied item.

inline Item *makeFloat64AtPath(Item *baseItem, const char *path, double value)

Helper function that sets the value to an item at path.

Creates item at path if it doesn’t exist.

Parameters

baseItem – Base item to apply path from.
path – Path.
value – Float value that will be set to the supplied item.

inline Item *makeFloatAtPath(Item *baseItem, const char *path, float value)

Helper function that sets the value to an item at path.

Creates item at path if it doesn’t exist.

Parameters

baseItem – Base item to apply path from.
path – Path.
value – Float value that will be set to the supplied item.

inline Item *makeBoolAtPath(Item *baseItem, const char *path, bool value)

Helper function that sets the value to an item at path.

Creates item at path if it doesn’t exist.

Parameters

baseItem – Base item to apply path from.
path – Path.
value – Bool value that will be set to the supplied item.

inline const char *createStringBufferFromItemValue(const Item *item, size_t *pStringLen = nullptr) const

Attempts to create a new string buffer with a value, either the real string value or a string resulting from converting the item value to a string.

Note

Please use destroyStringBuffer() to free the created buffer.

Parameters

item – dictionary::Item
pStringLen – (optional) Receives the length of the string. This can be useful if the string contains NUL characters (i.e. byte data).

Returns

Pointer to the created string buffer if applicable, nullptr otherwise.

inline const char *getStringBuffer(const Item *item, size_t *pStringLen = nullptr)

Returns internal raw data pointer to the string value of an item.

Thus, doesn’t perform any conversions.

Warning

This function returns the internal string buffer. Another thread may change the setting value which can cause the string buffer to be destroyed. It is recommended to take a ScopedRead lock around calling this function and using the return value.

Parameters

item – dictionary::Item
pStringLen – (optional) Receives the length of the string. This can be useful if the string contains NUL characters (i.e. byte data).

Returns

Raw pointer to the internal string value if applicable, nullptr otherwise.

inline void setString(Item *item, const char *value, size_t stringLen = size_t(-1)) const

Sets a string value for the supplied item.

If item is not of type eString it is changed to be eString. Change notifications for subscriptions are queued. The given string is then set in the item at path. If value is nullptr, the string item will store an empty string.

Parameters

item – dictionary::Item
value – String value that will be set to the supplied item.
stringLen – (optional) The length of the string at value to copy. This can be useful if only a portion of the string should be copied, or if value contains NUL characters (i.e. byte data). The default value of size_t(-1) treats value as a NUL-terminated string.

inline Item *makeStringAtPath(Item *baseItem, const char *path, const char *value, size_t stringLen = size_t(-1))

Helper function that sets the value to an item at path.

Creates item at path if it doesn’t exist.

Parameters

baseItem – Base item to apply path from.
path – Path.
value – String value that will be set to the supplied item.
stringLen – (optional) The length of the string at value to copy. This can be useful if only a portion of the string should be copied, or if value contains NUL characters (i.e. byte data). The default value of size_t(-1) treats value as a NUL-terminated string.

Returns

The item at the given path

inline Item *makeDictionaryAtPath(Item *parentItem, const char *path)

Helper function that ensures the item at path is a dictionary.

Creates item at path if it doesn’t exist.

Parameters

parentItem – Base item to apply path from.
path – Path.

template<typename T> T get(const dictionary::Item *item)

Reads the value from an Item, converting if necessary.

Template Parameters: T – The type of item to read. Must be a supported type.
Parameters: item – The Item to read from.
Returns: The value read from the Item.

template<typename T> T get(const dictionary::Item *baseItem, const char *path)

Reads the value from an Item, converting if necessary.

Template Parameters

T – The type of item to read. Must be a supported type.

Parameters

baseItem – The base Item to read from. Must not be nullptr.
path – The path from baseItem to determine the child Item. May be an empty string.

Returns

The value read from the Item.

template<typename T> void makeAtPath(dictionary::Item *baseItem, const char *path, T value)

Constructs a new Item with the given value or changes an existing item to hold the given value.

Template Parameters

T – The type of the value stored. Must be a supported type.

Parameters

baseItem – The base Item to read from. Must not be nullptr.
path – The path from baseItem where the child Item will be constructed.
value – The value to assign to the new Item.

inline int32_t getAsIntAt(const Item *item, size_t index)

Attempts to read an array item as a 32-bit integer.

Attempts to get the child item as integer, either directly or via a cast, considering the item at path to be an array, and using the supplied index to access its child.

Warning

The value is truncated by casting to 32-bits. In debug builds, an assert occurs if the value read from the item would be truncated.

Parameters

item – dictionary::Item
index – Index of the element in array.

Returns

Integer value, either value directly or cast from the real item type. Zero is returned on conversion failure.

inline void setIntAt(Item *item, size_t index, int32_t value)

Set an integer value in an array item.

Sets the integer value for the supplied item. If item is not an eDictionary, item is changed to an eDictionary and notifications are queued. index is used as the name of the child item. If the child item already existed and matches type eInt it is updated with the new value, otherwise any previous child item is destroyed (along with any of its children) and a new child item is created of type eInt; finally the new value is set into this child item. Change notifications are queued for every change that occurs. Subscriptions are notified of changes when the calling thread no longer holds any locks on the true root of item.

Parameters

item – dictionary::Item
index – Index of the element in array.
value – Integer value that will be set to the supplied item.

inline float getAsFloatAt(const Item *item, size_t index)

Attempts to read an array item as a float.

Attempts to read the path and array index as a float, either directly or via a cast, considering the item at path to be an array, and using the supplied index to access its child. Default value (0.0f) is returned if item is nullptr, index doesn’t exist, or there is a conversion failure.

Warning

The value is truncated by casting to 32-bits.

Parameters

item – An Item
index – Index of the element in array

Returns

float value, either value directly or cast from the real item type.

inline void setFloatAt(Item *item, size_t index, float value)

Set a float value in an array item.

Sets the float value for the supplied item. If item is not an eDictionary, item is changed to an eDictionary and notifications are queued. index is used as the name of the child item. If the child item already existed and matches type eFloat it is updated with the new value, otherwise any previous child item is destroyed (along with any of its children) and a new child item is created of type eFloat; finally the new value is set into this child item. Change notifications are queued for every change that occurs. Subscriptions are notified of changes when the calling thread no longer holds any locks on the true root of item.

Parameters

item – dictionary::Item
index – Index of the element in array.
value – Floating point value that will be set to the supplied item.

inline const char *createStringBufferFromItemValueAt(const Item *item, size_t index, size_t *pStringLen = nullptr) const

Attempts to create new string buffer with a value, either the real string value or a string resulting from converting the item value to a string.

Considers the item to be an array, and using the supplied index to access its child.

Note

Please use destroyStringBuffer to free the created buffer.

Parameters

item – dictionary::Item
index – Index of the element in array.
pStringLen – (optional) Receives the length of the string. This can be useful if the string contains NUL characters (i.e. byte data). Undefined if the function returns nullptr.

Returns

Pointer to the created string buffer if applicable, nullptr otherwise.

inline const char *getStringBufferAt(const Item *item, size_t index, size_t *pStringLen = nullptr) const

Returns internal raw data pointer to the string value of an item.

Thus, doesn’t perform any conversions. Considers the item at path to be an array, and using the supplied index to access its child. Dangerous function which only guarantees safety of the data when dictionary is not changing.

Parameters

item – dictionary::Item
index – Index of the element in array.
pStringLen – (optional) Receives the length of the string. This can be useful if the string contains NUL characters (i.e. byte data). Undefined if the function returns nullptr.

Returns

Raw pointer to the internal string value if applicable, nullptr otherwise.

inline void setStringAt(Item *item, size_t index, const char *value, size_t stringLen = size_t(-1)) const

Sets a string value in the supplied array item.

Sets the string value for the supplied item. If item is not an eDictionary, item is changed to an eDictionary and notifications are queued. index is used as the name of the child item. If the child item already existed and matches type eString it is updated with the new value, otherwise any previous child item is destroyed (along with any of its children) and a new child item is created of type eString; finally the new value is set into this child item. Change notifications are queued for every change that occurs. Subscriptions are notified of changes when the calling thread no longer holds any locks on the true root of item.

Parameters

item – dictionary::Item
index – Index of the element in array.
value – String value that will be set to the supplied item. May be nullptr which is interpreted to be an empty string.
stringLen – (optional) The length of the string at value to copy. This can be useful if only a portion of the string should be copied, or if value contains NUL characters (i.e. byte data). The default value of size_t(-1) treats value as a NUL-terminated string, or ignored if value is nullptr.

template<typename ArrayElementType> void setArray(Item *item, const ArrayElementType *array, size_t arrayLength)

Updates an item to be an array of the given type with provided values.

This is a helper function that will call the appropriate API function based on ArrayElementType:

bool: setBoolArray
int32_t: setIntArray
int64_t: setInt64Array
float: setFloatArray
double: setFloat64Array
const char*: setStringArray

Note

Any existing children in item are removed.

Template Parameters

ArrayElementType – The type of elements to fill the array with.

Parameters

item – The Item that will be changed to an array type
array – An array that is used to fill item. The values are copied.
arrayLength – The length of array as a count of the items.

inline void deleteChildren(Item *item)

Delete all children of a specified item.

Parameters: item – dictionary::Item

inline void copyItemFlags(Item *dstItem, const Item *srcItem)

Copies all item flags from one Item to another.

Parameters

dstItem – The destination Item that will receive the flags.
srcItem – The source Item from which flags are copied.

inline Item *duplicateItem(const Item *item)

Duplicates a given item as a new root.

Parameters: item – The item to duplicate.
Returns: A new item that where item is to root.

inline Item *duplicateItem(const Item *item, Item *newParent, const char *newKey)

Duplicates a item where another item is the parent.

If the key already exists, the item will be overridden.

Parameters

item – The item to duplicate.
newParent – The parent item to own the duplicated item.
newKey – the key in the parent.

Returns

The newly duplicated item.

Public Members

const Item *(*getItem)(const Item *baseItem, const char *path)

Returns opaque pointer to read-only item.

Param baseItem: Base item to apply path from (required)
Param path: Child path, separated with forward slash (‘/’), can be nullptr
Return: Opaque item pointer if the item is valid and present, or nullptr otherwise

Item *(*getItemMutable)(Item *baseItem, const char *path)

Returns opaque pointer to mutable item.

Param baseItem: Base item to apply path from (required)
Param path: Child path, separated with forward slash (‘/’), can be nullptr
Return: Opaque item pointer if the item is valid and present, or nullptr otherwise

size_t (*getItemChildCount)(const Item *item)

Returns number of children that belong to the specified item, if this item is a dictionary.

Returns 0 if item is not a dictionary, or doesn’t exist.

Param item: Item to query number of children from.
Return: Number of children if applicable, 0 otherwise.

const Item *(*getItemChildByIndex)(const Item *item, size_t childIndex)

Returns opaque pointer to a read-only child item by its index.

Mostly for dynamic dictionary processing. This function is different from getItemAt function, in a sense that this function doesn’t work with the array view of the supplied item - for example if the item has children named “A”, “B”, “0”, this function will return all of them in an undefined succession. While getItemAt functions work only with items which has array-like names (e.g. “0”, “1”, “2”, etc.).

Param item: Item to query child from.
Param childIndex: Child index.
Return: Opaque const item pointer if the item and index are valid, or nullptr otherwise.

Item *(*getItemChildByIndexMutable)(Item *item, size_t childIndex)

Returns opaque pointer to a mutable child item by its index.

Mostly for dynamic dictionary processing. This function is different from getItemAtMutable function, in a sense that this function doesn’t work with the array view of the supplied item - for example if the item has children named “A”, “B”, “0”, this function will return all of them in an undefined succession. While getItemAt functions work only with items which has array-like names (e.g. “0”, “1”, “2”, etc.).

Param item: Item to query child from.
Param childIndex: Child index.
Return: Opaque item pointer if the item and index are valid, or nullptr otherwise.

const Item *(*getItemParent)(const Item *item)

Returns read-only parent item, or nullptr if the supplied item is true root item.

Param item: Item to get parent for.
Return: Opaque item pointer if the item is valid and has parent, or nullptr otherwise.

Item *(*getItemParentMutable)(Item *item)

Returns opaque pointer to a mutable parent item, or nullptr if the supplied item is true root item.

Param item: Item to get parent for.
Return: Opaque item pointer if the item is valid and has parent, or nullptr otherwise.

ItemType (*getItemType)(const Item *item)

Returns original item type.

If the item is not a valid item, returns eCount.

Param item: dictionary::Item
Return: Original item type if item is valid, eCount otherwise.

const char *(*createStringBufferFromItemName)(const Item *item)

Securely string buffer filled with the item name.

Note

Please use destroyStringBuffer() to free the created buffer.

Param item: dictionary::Item
Return: Pointer to the created item name buffer if applicable, nullptr otherwise.

const char *(*getItemName)(const Item *item)

Returns pointer to an item name, if the item is valid.

Dangerous function which only guarantees safety of the data when item is not changing.

Param item: dictionary::Item
Return: Pointer to an internal item name string if the item is valid, nullptr otherwise.

Item *(*createItem)(Item *baseItem, const char *path, ItemType itemType)

Creates item, and all the required items along the path if necessary.

If baseItem supplied is nullptr, the created item is created as a true root.

Param baseItem: Base Item to apply path from. Passing nullptr means that the created item will be a true root (i.e. has no parent Item).
Param path: Path to the new item.
Param itemType: ItemType of the Item to create.
Return: Opaque Item pointer if it was successfully created, or nullptr otherwise.

bool (*isAccessibleAs)(ItemType itemType, const Item *item)

Checks if the item could be accessible as the provided type, either directly, or via a cast.

Generally this means for a given ItemType to return true for item:

ItemType::eDictionary — item must be of type ItemType::eDictionary.
ItemType::eString — item must be of any type except ItemType::eDictionary.
ItemType::eInt — item must be of type ItemType::eInt, ItemType::eFloat, or ItemType::eBool, or ItemType::eString that contains only a string representation of an integer (in in decimal, hex or octal, as convertible by strtoll()) or a floating-point number (as convertible by strtod()).
ItemType::eFloat — item must be of type ItemType::eFloat, ItemType::eInt or ItemType::eBool, or ItemType::eString that contains only a string representation of a floating point number (as convertible by strtod()).
ItemType::eBool — item must be of type ItemType::eBool, ItemType::eInt, or ItemType::eFloat, or ItemType::eString that either contains only case-insensitive versions of "true" or "false" or only a string representation of a floating point number (as convertible by strtod()).

Param itemType: Item type to check for.
Param item: dictionary::Item
Return: true if accessible (see above); false otherwise.

int64_t (*getAsInt64)(const Item *item)

Attempts to get the supplied item as integer, either directly or via a cast.

Note

carb.dictionary.serializer-toml.plugin cannot handle integers that exceed INT64_MAX.

Note

When carb.dictionary.serializer-json.plugin reads integers exceeding UINT64_MAX, it will store the result as a double, so you may get unexpected 64 bit integer values. Unsigned 64 bit values are still retrievable with full precision though; they will just be wrapped around when returned from this function.

Param item: [in] The item to retrieve the integer value from.
Return: The 64 bit integer value of item. This will be converted from the existing type if this Item is not a 64 bit integer. For an Item of type int32_t, float or double, this conversion will be a direct cast. Note that overly large double values convert to INT64_MIN on x86_64. For an Item of string type, the string data will be interpreted as a number. If the string is not a valid number, 0 will be returned. If the string is a valid number, but exceeds the range of an int64_t, it will be parsed as a double and converted to an int64_t.

void (*setInt64)(Item *item, int64_t value)

Sets the integer value for the supplied item.

If an item was already present, changes its original type to eInt. If the present item is a eDictionary item, destroys all its children. If the item doesn’t exist, creates eInt item, and all the required items along the path if necessary.

Param item: dictionary::Item
Param value: Integer value that will be set to the supplied item.

double (*getAsFloat64)(const Item *item)

Attempts to get the supplied item as float, either directly or via a cast.

Param item: [in] The item to retrieve the floating point value from.
Return: The 64 bit floating point value of item. This will be converted from the existing type if this Item is not a double. For an Item of type int32_t, int64_t or float, this conversion will be a direct cast. For an Item of string type, the string data will be interpreted as a number. If the string is not a valid number, 0 will be returned. If the string is a valid number, but exceeds the range of a double INFINITY or -INFINITY will be returned. Some precision may be lost on overly precise strings.

void (*setFloat64)(Item *item, double value)

Sets the floating point value for the supplied item.

If an item was already present, changes its original type to eFloat. If the present item is a eDictionary item, destroys all its children. If the item doesn’t exist, creates eFloat item, and all the required items along the path if necessary.

Param item: dictionary::Item
Param value: Floating point value that will be set to the supplied item.

bool (*getAsBool)(const Item *item)

Attempts to get the supplied item as eBool, either directly or via a cast.

Param item: dictionary::Item
Return: Boolean value, either value directly or cast from the real item type.

void (*setBool)(Item *item, bool value)

Sets the boolean value for the supplied item.

If an item was already present, changes its original type to eBool. If the present item is a eDictionary item, destroys all its children. If the item doesn’t exist, creates eBool item, and all the required items along the path if necessary.

Param item: dictionary::Item
Param value: Boolean value that will be set to the supplied item.

bool (*isAccessibleAsArray)(const Item *item)

Checks if the item could be accessible as array.

Param item: dictionary::Item
Return: true if accessible, that is, all child items have names which are contiguous non-negative integers starting with zero; false otherwise or if item has no children (empty dictionary).

bool (*isAccessibleAsArrayOf)(ItemType itemType, const Item *item)

Checks if the item could be accessible as the array of items of provided type, either directly, or via a cast of all elements.

For this function to return true, isAccessibleAsArray must be satisfied, as well as each child item must satisfy isAccessibleAs for the given itemType. Empty dictionaries and non-dictionary types of item will always return false.

Param itemType: Item type to check for.
Param item: dictionary::Item
Return: True if a valid array and with all items accessible (see above), or false otherwise.

size_t (*getArrayLength)(const Item *item)

Checks if the all the children of the item have array-style indices.

If yes, returns the number of children (array elements).

Param item: dictionary::Item
Return: Non-zero number of array elements if applicable (implies isAccessibleAsArray), or 0 otherwise.

ItemType (*getPreferredArrayType)(const Item *item)

Runs through all the array elements and infers a type that is most suitable for the array.

The rules are thus:

Strings attempt to convert to float or bool if possible (see isAccessibleAs for possibilities).
The converted type of the first element is the initial type.
If the initial type is a ItemType::eBool and later elements can be converted to ItemType::eBool without losing precision, ItemType::eBool is kept. (String variants of “true”/”false”, or values exactly equal to 0/1)
Elements of type ItemType::eFloat can convert to ItemType::eInt if they don’t lose precision.

Param item: dictionary::Item
Return: Item type that is most suitable for the array, or ItemType::eCount on failure.

int64_t (*getAsInt64At)(const Item *item, size_t index)

Attempts to read an array item as a 64-bit integer.

Attempts to get the child item as integer, either directly or via a cast, considering the item at path to be an array, and using the supplied index to access its child.

Param item: dictionary::Item
Param index: Index of the element in array.
Return: Integer value, either value directly or cast from the real item type. Zero is returned on conversion failure.

void (*setInt64At)(Item *item, size_t index, int64_t value)

Set an integer value in an array item.

Sets the integer value for the supplied item. If item is not an eDictionary, item is changed to an eDictionary and notifications are queued. index is used as the name of the child item. If the child item already existed and matches type eInt it is updated with the new value, otherwise any previous child item is destroyed (along with any of its children) and a new child item is created of type eInt; finally the new value is set into this child item. Change notifications are queued for every change that occurs. Subscriptions are notified of changes when the calling thread no longer holds any locks on the true root of item.

Param item: dictionary::Item
Param index: Index of the element in array.
Param value: Integer value that will be set to the supplied item.

void (*getAsInt64Array)(const Item *item, int64_t *arrayOut, size_t arrayBufferLength)

Fills the given buffer with the array values from the given path.

If the provided item is not an array item, arrayOut is not modified. If the array item contains more items than arrayBufferLength, a warning message is logged and items past the end are ignored.

Warning

Dictionary items that are not arrays will only have child keys which are convertible to array indices written to arrayOut. For example, if item is a dictionary item with keys ‘5’ and ‘10’, only those items will be written into arrayOut; the other indices will not be written. It is highly recommended to take a ScopedRead lock around calling this function, and only if isAccessibleAsArray or isAccessibleAsArrayOf return true.

Param item: dictionary::Item
Param arrayOut: Array buffer to fill with integer values.
Param arrayBufferLength: Size of the supplied array buffer.

void (*setInt64Array)(Item *item, const int64_t *array, size_t arrayLength)

Creates or updates an item to be an integer array.

item is changed to eDictionary, or if it already was, has all child items cleared (change notifications will will be queued for any child items that are destroyed). New child items will be created for all elements of the given array.

Param item: dictionary::Item
Param array: Integer array to copy values from.
Param arrayLength: Array length.

void (*getAsIntArray)(const Item *item, int32_t *arrayOut, size_t arrayBufferLength)

Fills the given buffer with the array values from the given path.

If the provided item is not a dictionary item, arrayOut is not modified. If the array item contains more items than arrayBufferLength, a warning message is logged and items past the end are ignored.

Warning

Dictionary items that are not arrays will only have child keys which are convertible to array indices written to arrayOut. For example, if item is a dictionary item with keys ‘5’ and ‘10’, only those items will be written into arrayOut; the other indices will not be written. It is highly recommended to take a ScopedRead lock around calling this function, and call only if isAccessibleAsArray or isAccessibleAsArrayOf return true.

Warning

Any integer element that does not fit within int32_t is truncated by casting.

Param item: dictionary::Item
Param arrayOut: Array buffer to fill with integer values.
Param arrayBufferLength: Size of the supplied array buffer.

void (*setIntArray)(Item *item, const int32_t *array, size_t arrayLength)

Creates or updates an item to be an integer array.

item is changed to eDictionary, or if it already was, has all child items cleared (change notifications will will be queued for any child items that are destroyed). New child items will be created for all elements of the given array.

Param item: dictionary::Item
Param array: Integer array to copy values from.
Param arrayLength: Array length.

double (*getAsFloat64At)(const Item *item, size_t index)

Attempts to read an array item as a double.

Attempts to read the path and array index as a double, either directly or via a cast, considering the item at path to be an array, and using the supplied index to access its child. Default value (0.0) is returned if item is nullptr, index doesn’t exist, or there is a conversion failure.

Param item: dictionary::Item
Param index: Index of the element in array.
Return: double value, either value directly or cast from the real item type.

void (*setFloat64At)(Item *item, size_t index, double value)

Set a double value in an array item.

Sets the double value for the supplied item. If item is not an eDictionary, item is changed to an eDictionary and notifications are queued. index is used as the name of the child item. If the child item already existed and matches type eFloat it is updated with the new value, otherwise any previous child item is destroyed (along with any of its children) and a new child item is created of type eFloat; finally the new value is set into this child item. Change notifications are queued for every change that occurs. Subscriptions are notified of changes when the calling thread no longer holds any locks on the true root of item.

Param item: dictionary::Item
Param index: Index of the element in array.
Param value: double value that will be set to the supplied item.

void (*getAsFloat64Array)(const Item *item, double *arrayOut, size_t arrayBufferLength)

Fills the given buffer with the array values from the given path.

If the provided item is not a dictionary item, arrayOut is not modified. If the array item contains more items than arrayBufferLength, a warning message is logged and items past the end are ignored.

Warning

Dictionary items that are not arrays will only have child keys which are convertible to array indices written to arrayOut. For example, if item is a dictionary item with keys ‘5’ and ‘10’, only those items will be written into arrayOut; the other indices will not be written. It is highly recommended to take a ScopedRead lock around calling this function, and call only if isAccessibleAsArray or isAccessibleAsArrayOf return true.

Param item: dictionary::Item
Param arrayOut: Array buffer to fill with floating point values.
Param arrayBufferLength: Size of the supplied array buffer.

void (*setFloat64Array)(Item *item, const double *array, size_t arrayLength)

Creates or updates an item to be a double array.

item is changed to eDictionary, or if it already was, has all child items cleared (change notifications will will be queued for any child items that are destroyed). New child items will be created for all elements of the given array.

Param item: dictionary::Item
Param array: Floating point array to copy values from.
Param arrayLength: Array length.

void (*getAsFloatArray)(const Item *item, float *arrayOut, size_t arrayBufferLength)

Fills the given buffer with the array values from the given path.

If the provided item is not a dictionary item, arrayOut is not modified. If the array item contains more items than arrayBufferLength, a warning message is logged and items past the end are ignored.

Warning

Dictionary items that are not arrays will only have child keys which are convertible to array indices written to arrayOut. For example, if item is a dictionary item with keys ‘5’ and ‘10’, only those items will be written into arrayOut; the other indices will not be written. It is highly recommended to take a ScopedRead lock around calling this function, and call only if isAccessibleAsArray or isAccessibleAsArrayOf return true.

Warning

Any element that does not fit within float is truncated by casting.

Param item: dictionary::Item
Param arrayOut: Array buffer to fill with floating point values.
Param arrayBufferLength: Size of the supplied array buffer.

void (*setFloatArray)(Item *item, const float *array, size_t arrayLength)

Creates or updates an item to be a float array.

item is changed to eDictionary, or if it already was, has all child items cleared (change notifications will will be queued for any child items that are destroyed). New child items will be created for all elements of the given array.

Param item: dictionary::Item
Param array: Floating point array to copy values from.
Param arrayLength: Array length.

bool (*getAsBoolAt)(const Item *item, size_t index)

Attempts to read an array item as a bool.

Attempts to read the path and array index as a bool, either directly or via a cast, considering the item at path to be an array, and using the supplied index to access its child. Default value (false) is returned if item is nullptr, index doesn’t exist, or there is a conversion failure.

Param item: dictionary::Item
Param index: Index of the element in array.
Return: Boolean value, either value directly or cast from the real item type.

void (*setBoolAt)(Item *item, size_t index, bool value)

Set a bool value in an array item.

Sets the bool value for the supplied item. If item is not an eDictionary, item is changed to an eDictionary and notifications are queued. index is used as the name of the child item. If the child item already existed and matches type eBool it is updated with the new value, otherwise any previous child item is destroyed (along with any of its children) and a new child item is created of type eBool; finally the new value is set into this child item. Change notifications are queued for every change that occurs. Subscriptions are notified of changes when the calling thread no longer holds any locks on the true root of item.

Param item: dictionary::Item
Param index: Index of the element in array.
Param value: Boolean value that will be set to the supplied item.

void (*getAsBoolArray)(const Item *item, bool *arrayOut, size_t arrayBufferLength)

Fills the given buffer with the array values from the given path.

If the provided item is not a dictionary item, arrayOut is not modified. If the array item contains more items than arrayBufferLength, a warning message is logged and items past the end are ignored.

Warning

Dictionary items that are not arrays will only have child keys which are convertible to array indices written to arrayOut. For example, if item is a dictionary item with keys ‘5’ and ‘10’, only those items will be written into arrayOut; the other indices will not be written. It is highly recommended to take a ScopedRead lock around calling this function, and call only if isAccessibleAsArray or isAccessibleAsArrayOf return true.

Param item: dictionary::Item
Param arrayOut: Array buffer to fill with boolean values.
Param arrayBufferLength: Size of the supplied array buffer.

void (*setBoolArray)(Item *item, const bool *array, size_t arrayLength)

Creates or updates an item to be a bool array.

item is changed to eDictionary, or if it already was, has all child items cleared (change notifications will will be queued for any child items that are destroyed). New child items will be created for all elements of the given array.

Param item: dictionary::Item
Param array: Boolean array to copy values from.
Param arrayLength: Array length.

void (*getStringBufferArray)(const Item *item, const char **arrayOut, size_t arrayBufferLength)

Returns internal raw data pointers to the string value of all child items of an array.

Thus, doesn’t perform any conversions.

If the provided item is not a dictionary item, arrayOut is not modified. If the array item contains more items than arrayBufferLength, a warning message is logged and items past the end are ignored.

Warning

This function returns the internal string buffer(s) for several items. Another thread may change the setting value which can cause the string buffer to be destroyed. It is recommended to take a ScopedRead lock around calling this function and use of the filled items in arrayOut.

Warning

Dictionary items that are not arrays will only have child keys which are convertible to array indices written to arrayOut. For example, if item is a dictionary item with keys ‘5’ and ‘10’, only those items will be written into arrayOut; the other indices will not be written. It is highly recommended to take a ScopedRead lock around calling this function, and call only if isAccessibleAsArray or isAccessibleAsArrayOf return true.

Param item: dictionary::Item
Param arrayOut: Array buffer to fill with integer values.
Param arrayBufferLength: Size of the supplied array buffer.

void (*setStringArray)(Item *item, const char *const *array, size_t arrayLength)

Creates or updates an item to be a string array.

item is changed to eDictionary, or if it already was, has all child items cleared (change notifications will will be queued for any child items that are destroyed). New child items will be created for all elements of the given array.

Param item: dictionary::Item
Param array: String array to copy values from.
Param arrayLength: Array length.

const Item *(*getItemAt)(const Item *item, size_t index)

Returns opaque pointer to a read-only child item by its index.

Mostly for dynamic dictionary processing. This function is designed for array view access, if you just want to enumerate all children, use getItemChildCount and getItemChildByIndex instead.

Param item: dictionary::Item
Return: Opaque const item pointer if the item and index are valid, or nullptr otherwise.

Item *(*getItemAtMutable)(Item *item, size_t index)

Returns opaque pointer to a mutable item by its index.

Mostly for dynamic dictionary processing. This function is designed for array view access, if you just want to enumerate all children, use getItemChildCount and getItemChildByIndex instead.

Param item: dictionary::Item
Return: Opaque item pointer if the item and index are valid, or nullptr otherwise.

void (*getItemArray)(const Item *item, const Item **arrayOut, size_t arrayBufferLength)

Attempts to securely fill the supplied arrayOut buffer with read-only opaque pointers to the items that are array elements.

arrayBufferLength is used as a buffer overflow detection. This function should not be used for simple dynamic processing purposes, use getItemChildCount and getItemChildByIndex instead.

Param item: The Item.
Param arrayOut: Array buffer to fill with opaque item pointers.
Param arrayBufferLength: Size of the supplied array buffer.

void (*update)(Item *dstBaseItem, const char *dstPath, const Item *srcBaseItem, const char *srcPath, OnUpdateItemFn onUpdateItemFn, void *userData)

Merges the source item into a destination item.

Destination path may be non-existing, then missing items in the path will be created as new dictionary items.

Param dstBaseItem: Destination base item to apply path from.
Param dstPath: Destination Child path, separated with forward slash (‘/’), can be nullptr.
Param srcBaseItem: Source base item to apply path from.
Param srcPath: Source Child path, separated with forward slash (‘/’), can be nullptr.
Param onUpdateItemFn: Function that will tell whether the update should overwrite the destination item with the source item. See carb::dictionary::keepOriginal(), carb::dictionary::overwriteOriginal(), or carb::dictionary::overwriteOriginalWithArrayHandling().
Param userData: User data pointer that will be passed into the onUpdateItemFn.

void (*destroyItem)(Item *item)

Destroys given item, and all of its children, if any.

Change notifications are queued.

Param item: dictionary::Item

void (*destroyStringBuffer)(const char *stringBuffer)

Frees a string buffer.

The string buffers are created by createStringBufferFromItemValue(), createStringBufferFromItemName or createStringBufferFromItemValueAt().

Param stringBuffer: String buffer to destroy. Undefined behavior results if this is not a value returned from one of the functions listed above.

bool (*getItemFlag)(const Item *item, ItemFlag flag)

Retrieves the value of an item flag.

Param item: dictionary::Item
Param flag: ItemFlag.
Return: Original item type if item is valid, eCount otherwise.

void (*setItemFlag)(Item *item, ItemFlag flag, bool flagValue)

Sets the value of an item flag.

Param item: dictionary::Item
Param flag: ItemFlag.
Return: Original item type if item is valid, eCount otherwise.

SubscriptionId *(*subscribeToNodeChangeEvents)(Item *baseItem, const char *path, OnNodeChangeEventFn onChangeEventFn, void *userData)

Subscribes to change events about a specific item.

When finished with the subscription, call unsubscribeToChangeEvents.

Param baseItem: An item
Param path: The subpath from baseItem or nullptr
Param onChangeEventFn: The function to call when a change event occurs
Param userData: User-specific data that will be provided to onChangeEventFn
Return: A subscription handle that can be used with unsubscribeToChangeEvents

SubscriptionId *(*subscribeToTreeChangeEvents)(Item *baseItem, const char *path, OnTreeChangeEventFn onChangeEventFn, void *userData)

Subscribes to change events for all items in a subtree.

All items under <baseItem>/<path> will trigger change notifications.

When finished with the subscription, call unsubscribeToChangeEvents.

Param baseItem: An item
Param path: The subpath from baseItem or nullptr
Param onChangeEventFn: The function to call when a change event occurs
Param userData: User-specific data that will be provided to onChangeEventFn
Return: A subscription handle that can be used with unsubscribeToChangeEvents()

void (*unsubscribeToChangeEvents)(SubscriptionId *subscriptionId)

Unsubscribes from change events.

Param subscriptionId: The subscription handle from subscribeToNodeChangeEvents or subscribeToTreeChangeEvents

void (*unsubscribeItemFromNodeChangeEvents)(Item *item)

Unsubscribes all node change handles for a specific Item.

Param item: An item

void (*unsubscribeItemFromTreeChangeEvents)(Item *item)

Unsubscribes all subtree change handles for a specific Item.

Param item: An item

void (*readLock)(const Item *item)

Locks an Item for reading.

Mutex-locks item for reading. This is only necessary if you are doing multiple read operations and require thread-safe consistency across the multiple operations. May be called multiple times within a thread, but unlock() must be called for each readLock() call, once the read lock is no longer needed.