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.

Thread-safety: IDictionary functions are internally thread-safe. 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 root level of the Item hierarchy which ensures safety across the entire hierarchy.

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. However, uses of ScopedRead and ScopedWrite should be rare.

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.

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.

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 – 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 – 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 – 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. Dangerous function which only guarantees safety of the data when dictionary is not changing.

Parameters

• item – 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 the string value for the supplied item.

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

Parameters

• item – 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 get the child item as 32-bit 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.

Parameters

• item – Item.

• index – Index of the element in array.

Returns

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

inline void setIntAt(Item *item, size_t index, 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. Considering the item at path to be an array, and using the supplied index to access its child.

Parameters

• item – 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 get the child item as 32-bit 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.

Parameters

• item – An Item

• index – Index of the element in array

Returns

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

inline void setFloatAt(Item *item, size_t index, 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. Considering the item at path to be an array, and using the supplied index to access its child.

Parameters

• item – 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 – 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 – 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 the string value for the supplied item.

If an item was already present, changes its original type to eString. If the present item is a eDictionary item, destroys all its children. If the item doesn’t exist, creates eString item, and all the required items along the path if necessary. Considering the item at path to be an array, and using the supplied index to access its child.

Parameters

• item – Item.

• index – Index of the element in array.

• 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.

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

Changes an Item to be an array type (dictionary with keys as 0-based consecutive integers) with the given data.

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 – 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.

Param path

Child path, separated with forward slash (‘/’), can be nullptr.

Return

Opaque item pointer if the item is valid, or nullptr otherwise.

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

Returns opaque pointer to mutable item.

Param baseItem

Base item to apply path from.

Param path

Child path, separated with forward slash (‘/’), can be nullptr.

Return

Opaque item pointer if the item is valid, 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

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

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

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.

Param path

Path to the new item.

Param itemType

Item type 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.

Param itemType

Item type to check for.

Param item

Item.

Return

True if accessible, or 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

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

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

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

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, i.e.

all child items names are valid contiguous non-negative integers starting with zero.

Param item

Item.

Return

True if accessible, or false otherwise.

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.

Param itemType

Item type to check for.

Param item

Item.

Return

True if a valid array and with all items accessible, 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

Item.

Return

Number of array elements if applicable, 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.

Param item

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 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

Item.

Param index

Index of the element in array.

Return

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

void (*setInt64At)(Item *item, size_t index, 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. Considering the item at path to be an array, and using the supplied index to access its child.

Param item

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)

Attempts to securely fill the supplied arrayOut buffer with values, either raw values or via a cast of required item values to the integer type.

arrayBufferLength is used as a buffer overflow detection.

Param item

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)

Sets the integer array for the supplied item.

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

Param item

Item.

Param array

Integer array to copy values from.

Param arrayLength

Array length.

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

Attempts to securely fill the supplied arrayOut buffer with values, either raw values or via a cast of required item values to the 32-bit integer type.

arrayBufferLength is used as a buffer overflow detection.

Param item

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)

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

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

Param item

Item.

Param array

Integer array to copy values from.

Param arrayLength

Array length.

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

Attempts to get the child item as 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.

Param index

Index of the element in array.

Return

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

void (*setFloat64At)(Item *item, size_t index, 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. Considering the item at path to be an array, and using the supplied index to access its child.

Param item

Item.

Param index

Index of the element in array.

Param value

Floating point value that will be set to the supplied item.

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

Attempts to securely fill the supplied arrayOut buffer with values, either raw values or via a cast of required item values to the floating point type.

arrayBufferLength is used as a buffer overflow detection.

Param item

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)

Sets the floating point array for the supplied item.

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

Param item

Item.

Param array

Floating point array to copy values from.

Param arrayLength

Array length.

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

Attempts to securely fill the supplied arrayOut buffer with values, either raw values or via a cast of required item values to the 32-bit floating point type.

arrayBufferLength is used as a buffer overflow detection.

Param item

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)

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

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

Param item

Item.

Param array

Floating point array to copy values from.

Param arrayLength

Array length.

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

Attempts to get the child item as boolean, 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

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)

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. Considering the item at path to be an array, and using the supplied index to access its child.

Param item

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)

Attempts to securely fill the supplied arrayOut buffer with values, either raw values or via a cast of required item values to the boolean type.

arrayBufferLength is used as a buffer overflow detection.

Param item

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)

Sets the boolean array for the supplied item.

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

Param item

Item.

Param array

Boolean array to copy values from.

Param arrayLength

Array length.

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

Attempts to securely fill the supplied arrayOut buffer with values internal string raw pointers.

arrayBufferLength is used as a buffer overflow detection. Similarly to getStringBuffer - doesn’t support casts.

Param item

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)

Sets the string array for the supplied item.

If an item was already present, changes its original type to eDictionary. If the present item is a eDictionary item, destroys all its children.

Param item

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

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

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 dictionaries.

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.

Param userData

User data pointer that will be passed into the onUpdateItemFn.

void (*destroyItem)(Item *item)

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

Param item

Item.

void (*destroyStringBuffer)(const char *stringBuffer)

Frees buffer, created by “createBuffer*” functions.

Param stringBuffer

Buffer returned by one of the “createBuffer*” functions.

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

Retrieves the value of an item flag.

Param item

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

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.

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.

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

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. Do not use readLock() directly; prefer ScopedRead instead.

Param item

The item to read-lock. item’s entire hierarchy will be read-locked.

void (*writeLock)(Item *item)

Locks an Item for writing.

Mutex-locks item for writing (exclusive access). This is only necessary if you are doing multiple read/write 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 writeLock() call, once the write lock is no longer needed. Calling writeLock() when a readLock() is already held will release the lock and wait until exclusive write lock can be gained. Do not use writeLock() directly; prefer ScopedWrite instead.

Param item

The item to write-lock. item’s entire hierarchy will be write-locked.

void (*unlock)(const Item *item)

Releases a lock from a prior readLock() or writeLock().

Releases a held read- or write-lock. Must be called once for each read- or write-lock that is held. Must be called in the same thread that initiated the read- or write-lock. Do not use unlock() directly; prefer using ScopedWrite or ScopedRead instead.

Param item

The item to unlock. item’s entire hierarchy will be unlocked

const extras::hash128_t (*getHash)(const Item *item)

Returns a 128-bit hash representing the value.

This hash is invariant to the order of keys and values.

We guarantee that the hashing algorithm will not change unless the version number of the interface changes.

Param item

The item to take the hash of.

Return

The 128-bit hash of the item.

Item *(*duplicateItemInternal)(const Item *item, Item *newParent, const char *newKey)

Duplicates a dictionary.

Note

The function duplicateItem should be preferred to this internal function.

Param srcItem

The item to duplicate

Param newParent

The new parent of the dictionary, if nullptr, makes a new root.

Param newKey

If new parent is given, then newKey is new the key of that parent. If, the key already exists it is overwritten.

Return

The created item.

int (*lexicographicalCompare)(const Item *itemA, const Item *itemB)

Lexicographically compares two Items.

The items being compared do not need to be root items. If the items are a key of a parent object, that key is not included in the comparison.

The rules match https://en.cppreference.com/w/cpp/algorithm/lexicographical_compare, treating the key and values in the dictionary as an ordered set. The “type” is included in the comparison, however the rules of what types are ordered differently than others may change on a version change of this interface.

The function will return a negative, zero, or positive number. The magnitude of the number bears no importance, and shouldn’t be assumed to. A negative number means that itemA < itemB, zero itemA = itemB, and positive itemA > itemB.

Param itemA

The first item to compare.

Param itemB

The second item to compare.

Return

The result of a lexicographical compare of itemA and itemB.

Public Static Functions

static inline constexpr carb::InterfaceDesc getInterfaceDesc()

• Returns information about this interface. Auto-generated by CARB_PLUGIN_INTERFACE(). *

Returns

The carb::InterfaceDesc struct with information about this interface.