IDictionary#

Fully qualified name: 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:

  1. unsubscribeToChangeEvents may be called from within the callback to unregister the called subscription or any other subscription.

  2. Unregistering the subscription ensures that it will never be called again, and any calls in process on another thread will complete before unsubscribeToChangeEvents returns.

  3. 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’s value 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. This may not be nullptr.

Returns:

The 32-bit integer value of item. This will be converted from the existing type if this Item is not a 32-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 a value was already present in the item, the item’s type will be changed to ItemType::eInt. If the present item is a ItemType::eDictionary item, all of its children will be destroyed before setting the new value and changing the type.

Parameters:

  • item – The item to set an integer value for. This may not be nullptr.

  • value – The new integer value that will be set in the supplied item.

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

Helper function that sets the value of an item at a given path to a 64-bit integer.

The item at the requested path and all items leading up to it will be created if they do not exist.

Parameters:

  • baseItem – Base item to apply path from. This may be nullptr to create a new dictionary containing the new value at the requested path.

  • path – The path to the item to create or modify. If an item already exists at this path, its type will be changed to ItemType::eInt. If the original item was an ItemType::eDictionary, all of its children will be destroyed before setting the new integer value. If no item exists at the given path, a new one will be created containing the new value.

  • value – The new integer value that will be set to the supplied item.

Returns:

The created or modified item if the new value is successfully set or nullptr otherwise. The returned item only needs to be explicitly destroyed if it is created as a new root (ie: no parent items) or if it needs to be removed from the dictionary. The item can be destroyed with destroyItem().

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

Helper function that sets the value of an item at a given path to a 32-bit integer.

The item at the requested path and all items leading up to it will be created if they do not exist.

Parameters:

  • baseItem – Base item to apply path from. This may be nullptr to create a new dictionary containing the new value at the requested path.

  • path – The path to the item to create or modify. If an item already exists at this path, its type will be changed to ItemType::eInt. If the original item was an ItemType::eDictionary, all of its children will be destroyed before setting the new integer value. If no item exists at the given path, a new one will be created containing the new value.

  • value – The new integer value that will be set to the supplied item.

Returns:

The created or modified item if the new value is successfully set or nullptr otherwise. The returned item only needs to be explicitly destroyed if it is created as a new root (ie: no parent items) or if it needs to be removed from the dictionary. The item can be destroyed with destroyItem().

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 32-bit floating point value from. This may not be nullptr.

Returns:

The 32-bit floating point value of item. This will be converted from the existing type if this Item is not a float. 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 a value was already present, it will be changed to ItemType::eFloat. If the present item is a ItemType::eDictionary item, all of its children will be destroyed before settings the new value.

Parameters:

  • item – The item to set the new 32-bit floating point value for. This may not be nullptr.

  • value – The new 32-bit 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 of an item at a given path to a 64-bit floating point value.

The item at the requested path and all items leading up to it will be created if they do not exist.

Parameters:

  • baseItem – Base item to apply path from. This may be nullptr to create a new dictionary containing the new value at the requested path.

  • path – The path to the item to create or modify. If an item already exists at this path, its type will be changed to ItemType::eFloat. If the original item was an ItemType::eDictionary, all of its children will be destroyed before setting the new floating point value. If no item exists at the given path, a new one will be created containing the new value.

  • value – The new floating point value that will be set to the supplied item.

Returns:

The created or modified item if the new value is successfully set or nullptr otherwise. The returned item only needs to be explicitly destroyed if it is created as a new root (ie: no parent items) or if it needs to be removed from the dictionary. The item can be destroyed with destroyItem().

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

Helper function that sets the value of an item at a given path to a 32-bit floating point value.

The item at the requested path and all items leading up to it will be created if they do not exist.

Parameters:

  • baseItem – Base item to apply path from. This may be nullptr to create a new dictionary containing the new value at the requested path.

  • path – The path to the item to create or modify. If an item already exists at this path, its type will be changed to ItemType::eFloat. If the original item was an ItemType::eDictionary, all of its children will be destroyed before setting the new floating point value. If no item exists at the given path, a new one will be created containing the new value.

  • value – The new floating point value that will be set to the supplied item.

Returns:

The created or modified item if the new value is successfully set or nullptr otherwise. The returned item only needs to be explicitly destroyed if it is created as a new root (ie: no parent items) or if it needs to be removed from the dictionary. The item can be destroyed with destroyItem().

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

Helper function that sets the value of an item at a given path to a boolean value.

The item at the requested path and all items leading up to it will be created if they do not exist.

Parameters:

  • baseItem – Base item to apply path from. This may be nullptr to create a new dictionary containing the new value at the requested path.

  • path – The path to the item to create or modify. If an item already exists at this path, its type will be changed to ItemType::eBool. If the original item was an ItemType::eDictionary, all of its children will be destroyed before setting the new boolean value. If no item exists at the given path, a new one will be created containing the new value.

  • value – The new boolean value that will be set to the supplied item.

Returns:

The created or modified item if the new value is successfully set or nullptr otherwise. The returned item only needs to be explicitly destroyed if it is created as a new root (ie: no parent items) or if it needs to be removed from the dictionary. The item can be destroyed with destroyItem().

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.

Parameters:

  • item – The item to retrieve the value as a string from. This may not be nullptr.

  • pStringLen – [out] Receives the length of the string. This can be useful if the string contains null characters or just to be able to trivially know the string’s length after it has been retrieved. This may be nullptr if the length of the string is not needed. This parameter defaults to nullptr.

Returns:

A pointer to the created string buffer if if is successfully created, or nullptr otherwise. When this buffer is no longer needed, it must be destroyed using destroyStringBuffer().

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

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

No conversion will be performed on the value before returning. If the item’s type is not a string, nullptr will be returned.

Warning

This function returns the internal string buffer. Another thread may change the item’s value at any point which can cause the string buffer to be destroyed or overwritten unexpectedly. It is recommended to take a ScopedRead lock around calling this function and using the return value.

Parameters:

  • item – The item to retrieve the string buffer pointer for. This may not be nullptr.

  • pStringLen – [out] Receives the length of the string. This can be useful if the string contains null characters (i.e. byte data) or just to be able to trivially know the string’s length after its pointer has been retrieved. This may be nullptr if the length of the string is not needed. This parameter is optional and defaults to nullptr.

Returns:

The raw pointer to the internal string value if the item has a string value, or 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 the item item is not of type ItemType::eString it is changed to be ItemType::eString. If the item currently has the type ItemType::eDictionary, all of its children will be destroyed before setting the new string value. Change notifications for subscriptions are queued to be executed after the value (or type) change is complete. If value is nullptr, an empty string will be stored in the item.

Parameters:

  • item – The item to set a new string value in. This may not be nullptr.

  • value – The new string value that will be set in the supplied item. This may be nullptr to store an empty string in the item.

  • stringLen – The maximum number of characters in the string to copy. This can be useful if only a portion of the string should be copied, or if value contains null characters (i.e. byte data). If this value is larger than the number of characters in value, it is assumed that the caller knows that the length to copy. The copied bytes in that case will include any null characters that are encountered. If this value is set to size_t(-1), it is assumed that the string is null terminated and it is safe to access its full contents. This defaults to size_t(-1).

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

Helper function that sets the value of an item at a given path to a string value.

The item at the requested path and all items leading up to it will be created if they do not exist.

Parameters:

  • baseItem – Base item to apply path from. This may be nullptr to create a new dictionary containing the new value at the requested path.

  • path – The path to the item to create or modify. If an item already exists at this path, its type will be changed to ItemType::eString. If the original item was an ItemType::eDictionary, all of its children will be destroyed before setting the new string value. If no item exists at the given path, a new one will be created containing the new value.

  • value – The new string value that will be set to the supplied item. This string will be copied into the item.

  • stringLen – The maximum number of characters in the string to copy. This can be useful if only a portion of the string should be copied, or if value contains null characters (i.e. byte data). If this value is larger than the number of characters in value, it is assumed that the caller knows that the length to copy. The copied bytes in that case will include any null characters that are encountered. If this value is set to size_t(-1), it is assumed that the string is null terminated and it is safe to access its full contents. This defaults to size_t(-1).

Returns:

The created or modified item if the new value is successfully set or nullptr otherwise. The returned item only needs to be explicitly destroyed if it is created as a new root (ie: no parent items) or if it needs to be removed from the dictionary. The item can be destroyed with destroyItem().

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

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

If the item at the given path or any item leading up to its path does not exist, they will be created as needed.

Parameters:

  • parentItem – The base item to use the path path relative to. This may be nullptr to create a new dictionary root with the given path.

  • path – The path to the item to create or modify. If an item already at this path, its type will be changed to ItemType::eDictionary if it is not already that. If the item at this path is already a dictionary type, it will not be modified. No specific value will be added to the dictionary if it is created.

Returns:

The created or modified item if the new value is successfully set or nullptr otherwise. The returned item only needs to be explicitly destroyed if it is created as a new root (ie: no parent items) or if it needs to be removed from the dictionary. The item can be destroyed with destroyItem().

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

Reads the value from an item, converting it if necessary.

Template Parameters:

T – The type of the value to retrieve the value as from the given item. This must be one of the supported dictionary types. The supported types are int32_t, int64_t, bool, float, double, and const char*. Array dictionary values may also be retrieved with Int{2|3|4}, Uint{2|3|4}, Float{2|3|4}, or Double{2|3|4}. Unsigned numeric types are not supported and should be retrieved using their signed conterparts instead.

Parameters:

item – The item to retrieve the value from. This may not be nullptr.

Returns:

The value of the given item converted to the requested data type. Note that if a const char* value is returned, it is equivalent to calling getStringBuffer() and has the same safety warnings.

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

Reads the value from a path relative to a base item, converting if necessary.

Template Parameters:

T – The type of the value to retrieve the value as from the given item. This must be one of the supported dictionary types. The supported types are int32_t, int64_t, bool, float, double, and const char*. Array dictionary values may also be retrieved with Int{2|3|4}, Uint{2|3|4}, Float{2|3|4}, or Double{2|3|4}. Unsigned numeric types are not supported and should be retrieved using their signed conterparts instead.

Parameters:

  • baseItem – The base item that path is taken to be relative to. This may not be nullptr.

  • path – The path to the item relative to baseItem to retrieve the value from. This can be nullptr or an empty string to indicate that the value from baseItem should be retrieved instead.

Returns:

The value of the given item converted to the requested data type. Note that if a const char* value is returned, it is equivalent to calling getStringBuffer() and has the same safety warnings.

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

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

The item at the requested path and all items leading up to it will be created if they do not exist.

Template Parameters:

T – The type of the value to set in the given item path. This must be one of the supported dictionary types. The supported types are int32_t, int64_t, bool, float, double, const char*, std::string, carb::cpp::string_view, and omni::string. Array dictionary values may also be set with Int{2|3|4}, Uint{2|3|4}, Float{2|3|4}, or Double{2|3|4}. Unsigned numeric types in value must either be cast to their signed equivalents or an explicit template parameter must be provided to allow for an implicit cast.

Parameters:

  • baseItem – Base item to apply path from. This may be nullptr to create a new dictionary containing the new value at the requested path.

  • path – The path to the item to create or modify. If an item already exists at this path, its type will be changed to the ItemType that most most closely corresponds to the template parameter type. If the original item was an ItemType::eDictionary, all of its children will be destroyed before setting the new value. If no item exists at the given path, a new one will be created containing the new value.

  • value – The new value that will be set to the supplied item. If a string value is provided, the string will always be assumed to either be wrapped in an object such as std::string, omni::string, or carb::cpp::string_view, or that it will be null terminated. The string will be copied into the item’s value in full.

Returns:

The created or modified item if the new value is successfully set or nullptr otherwise. The returned item only needs to be explicitly destroyed if it is created as a new root (ie: no parent items) or if it needs to be removed from the dictionary. The item can be destroyed with destroyItem().

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 an integer, either directly or via a cast. This considers the item at the given path to be an array and uses the supplied index to access its child.

Parameters:

  • item – The array item to retrieve a value from. This may not be nullptr.

  • index – The 0-based index of the element in array. If this index is out of bounds of the array, 0 will be returned.

Returns:

The integer value of the given array element, either value directly or cast from the real item type. Zero is returned on conversion failure or if the index is out of bounds of the array’s size.

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

Set a 32-bit integer value in an array item.

Sets the integer value for the supplied item. If item is not an ItemType::eDictionary type, item is changed to an that type and item change notifications are queued. index is used as the name of the child item. If the child item already exists and is of the type ItemType::eInt, it is updated with the new value. Otherwise, that array element item and any of its children are destroyed and a new child item is created of type ItemType::eInt. Finally the new value is set into this new 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 – The array item to set a new 64-bit integer value in. This may not be nullptr. This must be of type ItemType::eDictionary. It does not need to already be treated as an array in order for this call to succeed. However, note that if it is not already seen as an array item (ie: the isAccessibleAsArray() function succeeds on it), its existing children (if any) will be destroyed and replaced with the new array item.

  • index – The 0-based index of the element in array to be set. Note that new array items should be created starting with index 0 and filling in consecutively numbered entries after that. If later entries are added first, the item may not be seen as an array by other functions until all other elements starting from index 0 are added.

  • value – The new 32-bit integer value that will be set to the given index in the supplied array item.

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

Attempts to read an array item as a 32-bit floating point number.

Attempts to get the child item as a 32-bit floating point number, either directly or via a cast. This considers the item at the given path to be an array and uses the supplied index to access its child.

Parameters:

  • item – The array item to retrieve a value from. This may not be nullptr.

  • index – The 0-based index of the element in array. If this index is out of bounds of the array, 0 will be returned.

Returns:

The 32-bit floating point value of the given array element, either directly or cast from the real item type. Zero is returned on conversion failure or if the index is out of bounds of the array’s size.

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

Set a 32-bit floating point value in an array item.

Sets the floating point value for the supplied item. If item is not an ItemType::eDictionary type, item is changed to an that type and item change notifications are queued. index is used as the name of the child item. If the child item already exists and is of the type ItemType::eFloat, it is updated with the new value. Otherwise, that array element item and any of its children are destroyed and a new child item is created of type ItemType::eFloat. Finally the new value is set into this new 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 – The array item to set a new 64-bit floating point value in. This may not be nullptr. It does not need to already be of type ItemType::eDictionary or need to already be treated as an array in order for this call to succeed. However, note that if it is not already seen as an array item (ie: the isAccessibleAsArray() function succeeds on it), its existing children (if any) will be destroyed and replaced with the new array item.

  • index – The 0-based index of the element in array to be set. Note that new array items should be created starting with index 0 and filling in consecutively numbered entries after that. If later entries are added first, the item may not be seen as an array by other functions until all other elements starting from index 0 are added.

  • value – The new 32-bit floating point value that will be set to the given index in the supplied array 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.

This considers the item to be an array using the supplied index to access the child in question.

Parameters:

  • item – The array item to retrieve one of the values from as a string. The value of one of its numbered children will be retrieved if the given index is in range of the array’s size. This item is assumed to be an ItemType::eDictionary type item. This may not be nullptr.

  • index – The 0-based index of the element in array to copy the value from. This must be in the range of the current size of the array.

  • pStringLen – [out] Receives the length of the string in characters. This can be useful if the string contains null characters (i.e. byte data). This value will be undefined if this function returns nullptr. This may be nullptr if the length of the string is not needed.

Returns:

A pointer to the created string buffer if successful. Once this buffer is no longer needed, it must be cleaned up using destroyStringBuffer(). Returns nullptr if an error occurred. Errors can include the index being out of range of the array or failing to allocate memory.

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

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

No conversion is performed on the item’s value. If the given item does not have an ItemType::eString value, nullptr will be returned. This considers the given item to be an array using the supplied index to access the requested child item.

Warning

This function is dangerous to use since it can only guarantee safety of the data when dictionary is not changing. Since any other thread can change the item at any other point, it is suggested that a ScopedRead or ScopedWrite lock be used around any access to the string buffer and its use.

Parameters:

  • item – The array item to access an indexed value from. The value of one of its numbered children will be retrieved if the given index is in range of the array’s size. This item is assumed to be an ItemType::eDictionary type item. This may not be nullptr.

  • index – The 0-based index of the element in the array to return the internal string buffer for. This must be in the range of the current sizez of the array.

  • pStringLen – [out] Receives the length of the string in characters. This can be useful if the string contains null characters (i.e. byte data). This value will be undefined if this function returns nullptr. This may be nullptr if the length of the string is not needed.

Returns:

The raw pointer to the internal string value if the requested indexed item is found. This buffer must not be destroyed or freed in any way. Its contents should also not be modified. Returns nullptr the requested array item does not contain a string buffer (ie: not a string value) or if an error occurs. Errors can include the index being out of range of the array.

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 given item. If item is not an ItemType::eDictionary, item is changed to an ItemType::eDictionary. Any applicable notifications are queued. index is used as the integer name of the child item to retrieve the value for. If the child item already existed and matches type ItemType::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 ItemType::eString. 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 – The array item to set a value in. The item will either have a child modified or added to it depending on whether a value at the given index already exists or not. This item is assumed to be an ItemType::eDictionary type item. This may not be nullptr.

  • index – The 0-based index of the element in the array to set the new string value for. A new child item will be added to the array if the requested index is not already present. Note though that this will not fill in any intermediate values in the array if the index is not contiguous with the rest of the array’s indices.

  • value – The new string value that will be set to the given item. This may be nullptr or an empty string to clear out the current value in the given array item.

  • stringLen – The maximum number of characters 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 null characters (i.e. byte data). The default value of size_t(-1) treats value as a null-terminated string. This value is 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:

Note

Any existing children in item are removed. Change notifications will be queued where applicable during this operation.

Template Parameters:

ArrayElementType – The type of elements to fill the array with. This must be a supported type listed above. Any other type must be able to be implicitly converted to a supported type. Any unsigned values should use their signed counterparts for this operation.

Parameters:

  • item – The item that will be changed to an array type and have its new children created. If this item is an ItemType::eDictionary, all of its existing children will be destroyed and new ones created from the given array of values. If this item is not already an ItemType::eDictionary, it will be converted to a dictionary item to be filled in. Any required change notifications will be queued as the operation proceeds. This may not be nullptr.

  • array – An array of values that will be used to fill the children of the new array item. The values are always copied into the new child items. This may not be nullptr.

  • arrayLength – The total number of entries in array. This is used as the size of the new array.

inline void deleteChildren(Item *item)#

Destroys all children of a specified item.

The item itself will not be destroyed. Change notifications will be queued for each item that is destroyed.

Parameters:

item – The item to destroy the subtree of. This may not be nullptr.

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

Copies all flags from one item to another.

Upon return, both items will have the same flags. The flags for the destination item dstItem will be overwritten instead of being merged.

Parameters:

  • dstItem – The destination item that will receive the new flags. Any existing flags state in this item will be overwritten. This may not be nullptr.

  • srcItem – The source item from which flags are copied. This item’s state will be left unmodified. This may not be nullptr.

inline Item *duplicateItem(const Item *item)#

Duplicates a given item as a new dictionary root.

The given item will have its entire subtree duplicated as well. The new item will not be attached to any other dictionary and can be treated as its own dictionary root. The caller is responsible for cleaning up the duplicated item when it is no longer needed.

Parameters:

item – The item to duplicate. This may not be nullptr. The entire subtree of this item will also be duplicated.

Returns:

The newly duplicated item if successful. This new item will be its own dictionary root and must be explicitly cleaned up with destroyItem() when it is no longer needed. Change notifications will not be triggered since the duplicated item will not have any existing subscriptions copied to it and the original item will not be modified. Returns nullptr if an error occurs.

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

Duplicates an item and places the new copy under a different parent item.

The given item will have its entire subtree duplicated as well. If the given key already exists on the new parent, it and all its children will be overwritten by the new duplicated item. Any applicable change events will be queued for the overwritten items.

Parameters:

  • item – The item to duplicate. This may not be nullptr. The entire subtree of this item will also be duplicated.

  • newParent – The new parent item to attach the duplicated item to. This may be nullptr to return the duplicated item as its own independent dictionary. If this item is returned without attaching it to a new parent, it is the caller’s responsibility to destroy the item with destroyItem() when it is no longer needed.

  • newKey – If a new parent item is given in newParent, this name specifies the key used to store the duplicated item in the parent. The new key name may not contain path separators (ie: ‘/’). This parameter is ignored if the newParent parameter is nullptr. This may not be nullptr unless newParent is also nullptr.

Returns:

The newly duplicated item if successful. If newParent was nullptr, this new item must be explicitly destroyed with destroyItem() when it is no longer needed. If newParent is not nullptr, the duplicated item will be owned by that new parent and will be automatically destroyed when that parent item is destroyed. Change notifications will have been triggered for the new item if a new parent was given or an existing item was overwritten. Existing subscriptions on any duplicated items will not be duplicated into the new item(s). Returns nullptr if an error occurs.

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. This may not be nullptr.

Param path:

Child path, separated with forward slash (‘/’). If provided, the path should not start with a forward slash. This can be nullptr or an empty string to simply return baseItem.

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. If provided, the path should not start with a forward slash.

Return:

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

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

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

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

Param item:

Item to query the number of children from. This may not be nullptr.

Return:

The number of children if applicable, 0 otherwise.

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

Returns an opaque pointer to a read-only child item by its index in the given base item.

This is mostly intended for dynamic dictionary processing. This function is different from the 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. Meanwhile the getItemAt() function works only with items which have array-like names (e.g. “0”, “1”, “2”, etc.).

Param item:

Item to query child from. This may not be nullptr.

Param childIndex:

The 0-based index of the item to retrieve.

Return:

Opaque const item pointer if the item and index are valid, or nullptr otherwise.

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

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

Mostly for dynamic dictionary processing. This function is different from the getItemAtMutable() function in the 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. Meanwhile getItemAt() functions work only with items which has array-like names (e.g. “0”, “1”, “2”, etc.).

Param item:

Item to query child from. This may not be nullptr.

Param childIndex:

The 0-based index of the item to retrieve.

Return:

Opaque item pointer if the item and index are valid, or nullptr otherwise.

const Item *(*getItemParent)(const Item *item)#

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

Param item:

Item to get parent for. This may not be nullptr.

Return:

Opaque item pointer if the item is valid and has a parent, or nullptr otherwise.

Item *(*getItemParentMutable)(Item *item)#

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

Param item:

Item to get parent for. This may not be nullptr.

Return:

Opaque item pointer if the item is valid and has a parent, or nullptr otherwise.

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

Returns an item’s type.

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

Param item:

The item to retrieve the type for. This may not be nullptr.

Return:

The item’s type if the item is valid or ItemType::eCount otherwise.

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

Creates and returns a string buffer filled with the item name.

The string buffer will be allocated in a thread safe manner.

Param item:

The item to retrieve the name for. This may not be nullptr.

Return:

A newly allocated buffer containing the item’s name if the item is valid. This buffer must be destroyed using destroyStringBuffer() when it is no longer needed. Returns nullptr if the item is invalid.

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

Returns a pointer to an item’s name if the item is valid.

Note that the returned buffer will be the internal name buffer for the item and will not be in a newly allocated buffer. This should only be used when the caller can guarantee safety around the access.

Param item:

The item to retrieve the name for. This may not be nullptr.

Return:

Pointer to an internal item name string if the item is valid or nullptr otherwise.

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

Creates a new item and all the required items along the given path if necessary.

If the baseItem item supplied is nullptr, the created item is created as a root dictionary (ie: the returned item does not have a parent item).

Param baseItem:

Base Item to create the new item(s) under. Passing nullptr means that the created item will be a true root (ie: has no parent Item).

Param path:

Path to the new item relative to the base item baseItem. This may not be nullptr.

Param itemType:

The type of the new item to be created at the given path. This may not be ItemType::eCount.

Return:

An opaque Item pointer if it was successfully created or nullptr otherwise. The returned item only needs to be explicitly destroyed if it is created as a root item or if the created item needs to be removed from the root dictionary. The item can be destroyed with destroyItem().

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:

Param itemType:

The item type to check whether item is accessible as. This may not be ItemType::eCount.

Param item:

The item to check the type accessibility for. This may not be nullptr.

Return:

true if accessible as the requested type (see above) or false otherwise.

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

Attempts to get the supplied item as a 64-bit 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 an unexpected 64-bit integer value when retrieved. 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. This may not be nullptr.

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 type. For an Item of type int32_t, float or double, this conversion will be a direct cast. Note that overly large double values will 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 (with the same potential limits as noted above).

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 ItemType::eInt. If the item is an ItemType::eDictionary item, this will destroy all of its children.

Param item:

The item to set the integer value for. This may not be nullptr.

Param value:

The integer value that will be set to the supplied item.

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

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

Param item:

[in] The item to retrieve the floating point value from. This may not be nullptr.

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 a value was already present, it will be changed to ItemType::eFloat. If the present item is of type ItemType::eDictionary item, all of its children will be destroyed before setting the new value.

Param item:

The item to set the new 64-bit floating point value for. This may not be nullptr.

Param value:

The new floating point value that will be set to the supplied item. The item’s data type will be changed to ItemType::eFloat if it already exists.

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

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

Param item:

The item to retrieve the boolean value from. If the item’s type is not ItemType::eBool, the value will attempt to be cast from other non dictionary types. For numeric item types, a zero value is considered to be false and any other value is considered to be true. For string item types, the value will first be checked if it is a numeric string, then it will check for values like true and false (case insensitive). If a numeric string is found, the value would be converted just as if it were an integer value. If the item is a dictionary type, false will always be assumed.

Return:

A boolean value, either directly from the item’s value or cast from the item’s type as explained above. If the item has the type ItemType::eDictionary or ItemType::eCount (ie: value not set yet on a newly created item), false is always returned.

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

Sets a boolean value for the supplied item.

If an item was already present, its type is changed to ItemType::eBool. If the present item has the type ItemType::eDictionary, all of the item’s children will be destroyed before setting the new value.

Param item:

The item to set a new boolean value for. This may not be nullptr.

Param value:

The new boolean value that will be set to the supplied item.

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

Checks if the given item could be accessible as an array.

Param item:

The item to check if it can be treated as an array dicitonary. An array dictionary has one or more children whose names are contiguous non-negative integers starting at zero. The dictionary could also have other children with non-integer or non-contiguous names as well, but those children will not be treated as part of the array.

Return:

true if the item is accessible as an array and false otherwise. If item has no children (ie: an empty dictionary) it is also considered to not be an array and false will be returned here.

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

Checks if the given 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 items will always return false.

Param itemType:

Item type to check for. This may not be ItemType::eCount.

Param item:

The item to check whether it can be treated as an array of the requested type itemType. This may not be nullptr.

Return:

true if the given item is a valid array where all child items are accessible as the requested type. Returns false otherwise.

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

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

This means that all of the names of all child items are consecutive integers starting with 0 or the item has been explicitly flagged as an array internally (ie: the various IDictionary::setArray() functions were used to create it). If yes, returns the number of children the item has (ie: array elements).

Param item:

The item to test whether it is being treated purely as an array item. This may not be nullptr.

Return:

Non-zero number of array elements if the item can be treated as an array (implies isAccessibleAsArray() also succeeds), or 0 otherwise.

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

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

Individual elements in the array may have different item types, but this tries to determine if there is one type that is either most common or can be converted to for each item.

The rules for determining the preferred type are thus:

Param item:

The array item to try to determine the preferred type for. This may not be nullptr. This item must be a ItemType::eDictionary item.

Return:

The item type that is most suitable for the array, or ItemType::eCount if a consistent preferred type could not be determined (ie: the item was not a dictionary or has no children).

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 an integer, either directly or via a cast. This considers the item at the given path to be an array and uses the supplied index to access its child.

Param item:

The array item to retrieve a value from. This may not be nullptr.

Param index:

The 0-based index of the element in array. If this index is out of bounds of the array, 0 will be returned.

Return:

The integer value of the given array element, either directly or cast from the real item type. Zero is returned on conversion failure or if the index is out of bounds of the array’s size.

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

Set a 64-bit integer value in an array item.

Sets the integer value for the supplied item. If item is not an ItemType::eDictionary type, item is changed to an that type and item change notifications are queued. index is used as the name of the child item. If the child item already exists and is of the type ItemType::eInt, it is updated with the new value. Otherwise, that array element item and any of its children are destroyed and a new child item is created of type ItemType::eInt. Finally the new value is set into this new 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:

The array item to set a new 64-bit integer value in. This may not be nullptr. It does not need to already be of type ItemType::eDictionary or need to already be treated as an array in order for this call to succeed. However, note that if it is not already seen as an array item (ie: the isAccessibleAsArray() function succeeds on it), its existing children (if any) will be destroyed and replaced with the new array item.

Param index:

The 0-based index of the element in array to be set. Note that new array items should be created starting with index 0 and filling in consecutively numbered entries after that. If later entries are added first, the item may not be seen as an array by other functions until all other elements starting from index 0 are added.

Param value:

The new 64-bit integer value that will be set to the given index in the supplied array item.

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

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

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.

Note

It is highly recommended to take a ScopedRead lock around calling this function. It should also only be called if isAccessibleAsArray() or isAccessibleAsArrayOf() return true.

Warning

Dictionary items that are not arrays will only have child items with names that are convertible to array indices (ie: 0-based consecutive integers) 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 modified.

Param item:

The array item to retrieve the 64-bit integer values from. This may not be nullptr.

Param arrayOut:

[out] Receives the values read from the array item. Note that only the entries in the array that correspond to the valid indices of the array item will be modified in this array. It is recommended to both verify the size of the array item and ensure it has a set of contiguous indices before attempting to parse the results.

Param arrayBufferLength:

The maximum number of values that can fit in arrayOut. If the array item contains more values than this, only the first arrayBufferLength values will be retrieved.

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

Modifies or updates an item to be a 64-bit integer array.

The given item is changed to have the type ItemType::eDictionary if it is not already. Any previous value in that item is lost. If it was already a dictionary, All of the item’s existing children will be destroyed (and any applicable change notifications will be queued for affected child items). New child items will be created for all elements of the given input array.

Param item:

The item to convert to an array and update the given values in. This may not be nullptr. This item does not need to already be a dictionary or array. However, if it was all previous children will be lost and replaced with the new array of values. The new child items will be given integer names starting from “0” up to one less than arrayLength.

Param array:

An array of new 64-bit integer values to use for the contents of the new array. Only the first arrayLength entries of this array will be used to fill in the new array item’s values.

Param arrayLength:

The total number of valid values in array that should be set in the given item as array elements.

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

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

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.

Note

It is highly recommended to take a ScopedRead lock around calling this function. It should also only be called if isAccessibleAsArray() or isAccessibleAsArrayOf() return true.

Warning

Dictionary items that are not arrays will only have child items with names that are convertible to array indices (ie: 0-based consecutive integers) 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 modified.

Param item:

The array item to retrieve the 32-bit integer values from. This may not be nullptr.

Param arrayOut:

[out] Receives the values read from the array item. Note that only the entries in the array that correspond to the valid indices of the array item will be modified in this array. It is recommended to both verify the size of the array item and ensure it has a set of contiguous indices before attempting to parse the results.

Param arrayBufferLength:

The maximum number of values that can fit in arrayOut. If the array item contains more values than this, only the first arrayBufferLength values will be retrieved.

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

Modifies or updates an item to be a 32-bit integer array.

The given item is changed to have the type ItemType::eDictionary if it is not already. Any previous value in that item is lost. If it was already a dictionary, All of the item’s existing children will be destroyed (and any applicable change notifications will be queued for affected child items). New child items will be created for all elements of the given input array.

Param item:

The item to convert to an array and update the given values in. This may not be nullptr. This item does not need to already be a dictionary or array. However, if it was all previous children will be lost and replaced with the new array of values. The new child items will be given integer names starting from “0” up to one less than arrayLength.

Param array:

An array of new 32-bit integer values to use for the contents of the new array. Only the first arrayLength entries of this array will be used to fill in the new array item’s values.

Param arrayLength:

The total number of valid values in array that should be set in the given item as array elements.

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

Attempts to read an array item as a 64-bit floating point number.

Attempts to get the child item as a 64-bit floating point number, either directly or via a cast. This considers the item at the given path to be an array and uses the supplied index to access its child.

Param item:

The array item to retrieve a value from. This may not be nullptr.

Param index:

The 0-based index of the element in array. If this index is out of bounds of the array, 0 will be returned.

Return:

The 64-bit floating point value of the given array element, either directly or cast from the real item type. Zero is returned on conversion failure or if the index is out of bounds of the array’s size.

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

Set a 64-bit floating point value in an array item.

Sets the floating point value for the supplied item. If item is not an ItemType::eDictionary type, item is changed to an that type and item change notifications are queued. index is used as the name of the child item. If the child item already exists and is of the type ItemType::eFloat, it is updated with the new value. Otherwise, that array element item and any of its children are destroyed and a new child item is created of type ItemType::eFloat. Finally the new value is set into this new 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:

The array item to set a new 64-bit floating point value in. This may not be nullptr. It does not need to already be of type ItemType::eDictionary or need to already be treated as an array in order for this call to succeed. However, note that if it is not already seen as an array item (ie: the isAccessibleAsArray() function succeeds on it), its existing children (if any) will be destroyed and replaced with the new array item.

Param index:

The 0-based index of the element in array to be set. Note that new array items should be created starting with index 0 and filling in consecutively numbered entries after that. If later entries are added first, the item may not be seen as an array by other functions until all other elements starting from index 0 are added.

Param value:

The new 64-bit floating point value that will be set to the given index in the supplied array item.

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

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

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.

Note

It is highly recommended to take a ScopedRead lock around calling this function. It should also only be called if isAccessibleAsArray() or isAccessibleAsArrayOf() return true.

Warning

Dictionary items that are not arrays will only have child items with names that are convertible to array indices (ie: 0-based consecutive integers) 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 modified.

Param item:

The array item to retrieve the 64-bit floating point values from. This may not be nullptr.

Param arrayOut:

[out] Receives the values read from the array item. Note that only the entries in the array that correspond to the valid indices of the array item will be modified in this array. It is recommended to both verify the size of the array item and ensure it has a set of contiguous indices before attempting to parse the results.

Param arrayBufferLength:

The maximum number of values that can fit in arrayOut. If the array item contains more values than this, only the first arrayBufferLength values will be retrieved.

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

Modifies or updates an item to be a 64-bit floating point array.

The given item is changed to have the type ItemType::eDictionary if it is not already. Any previous value in that item is lost. If it was already a dictionary, All of the item’s existing children will be destroyed (and any applicable change notifications will be queued for affected child items). New child items will be created for all elements of the given input array.

Param item:

The item to convert to an array and update the given values in. This may not be nullptr. This item does not need to already be a dictionary or array. However, if it was all previous children will be lost and replaced with the new array of values. The new child items will be given integer names starting from “0” up to one less than arrayLength.

Param array:

An array of new 64-bit floating point values to use for the contents of the new array. Only the first arrayLength entries of this array will be used to fill in the new array item’s values.

Param arrayLength:

The total number of valid values in array that should be set in the given item as array elements.

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

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

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.

Note

It is highly recommended to take a ScopedRead lock around calling this function. It should also only be called if isAccessibleAsArray() or isAccessibleAsArrayOf() return true.

Warning

Dictionary items that are not arrays will only have child items with names that are convertible to array indices (ie: 0-based consecutive integers) 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 modified.

Param item:

The array item to retrieve the 32-bit floating point values from. This may not be nullptr.

Param arrayOut:

[out] Receives the values read from the array item. Note that only the entries in the array that correspond to the valid indices of the array item will be modified in this array. It is recommended to both verify the size of the array item and ensure it has a set of contiguous indices before attempting to parse the results.

Param arrayBufferLength:

The maximum number of values that can fit in arrayOut. If the array item contains more values than this, only the first arrayBufferLength values will be retrieved.

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

Modifies or updates an item to be a 32-bit floating point array.

The given item is changed to have the type ItemType::eDictionary if it is not already. Any previous value in that item is lost. If it was already a dictionary, All of the item’s existing children will be destroyed (and any applicable change notifications will be queued for affected child items). New child items will be created for all elements of the given input array.

Param item:

The item to convert to an array and update the given values in. This may not be nullptr. This item does not need to already be a dictionary or array. However, if it was all previous children will be lost and replaced with the new array of values. The new child items will be given integer names starting from “0” up to one less than arrayLength.

Param array:

An array of new 32-bit floating point values to use for the contents of the new array. Only the first arrayLength entries of this array will be used to fill in the new array item’s values.

Param arrayLength:

The total number of valid values in array that should be set in the given item as array elements.

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

Attempts to read an array item as a boolean value.

Attempts to get the child item as a boolean value, either directly or via a cast. This considers the item at the given path to be an array and uses the supplied index to access its child.

Param item:

The array item to retrieve a value from. This may not be nullptr.

Param index:

The 0-based index of the element in array. If this index is out of bounds of the array, false will be returned.

Return:

The boolean value of the given array element, either value directly or cast from the real item type. false is returned on conversion failure or if the index is out of bounds of the array’s size.

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

Set a boolean value in an array item.

Sets the boolean value for the supplied item. If item is not an ItemType::eDictionary type, item is changed to an that type and item change notifications are queued. index is used as the name of the child item. If the child item already exists and is of the type ItemType::eBool, it is updated with the new value. Otherwise, that array element item and any of its children are destroyed and a new child item is created of type ItemType::eBool. Finally the new value is set into this new 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:

The array item to set a new boolean value in. This may not be nullptr. This must be of type ItemType::eDictionary. It does not need to already be treated as an array in order for this call to succeed. However, note that if it is not already seen as an array item (ie: the isAccessibleAsArray() function succeeds on it), its existing children (if any) will be destroyed and replaced with the new array item.

Param index:

The 0-based index of the element in array to be set. Note that new array items should be created starting with index 0 and filling in consecutively numbered entries after that. If later entries are added first, the item may not be seen as an array by other functions until all other elements starting from index 0 are added.

Param value:

The new boolean value that will be set to the given index in the supplied array item.

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

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

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.

Note

It is highly recommended to take a ScopedRead lock around calling this function. It should also only be called if isAccessibleAsArray() or isAccessibleAsArrayOf() return true.

Warning

Dictionary items that are not arrays will only have child items with names that are convertible to array indices (ie: 0-based consecutive integers) 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 modified.

Param item:

The array item to retrieve the boolean values from. This may not be nullptr.

Param arrayOut:

[out] Receives the values read from the array item. Note that only the entries in the array that correspond to the valid indices of the array item will be modified in this array. It is recommended to both verify the size of the array item and ensure it has a set of contiguous indices before attempting to parse the results.

Param arrayBufferLength:

The maximum number of values that can fit in arrayOut. If the array item contains more values than this, only the first arrayBufferLength values will be retrieved.

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

Modifies or updates an item to be a boolean array.

The given item is changed to have the type ItemType::eDictionary if it is not already. Any previous value in that item is lost. If it was already a dictionary, All of the item’s existing children will be destroyed (and any applicable change notifications will be queued for affected child items). New child items will be created for all elements of the given input array.

Param item:

The item to convert to an array and update the given values in. This may not be nullptr. This item does not need to already be a dictionary or array. However, if it was all previous children will be lost and replaced with the new array of values. The new child items will be given integer names starting from “0” up to one less than arrayLength.

Param array:

An array of new boolean values to use for the contents of the new array. Only the first arrayLength entries of this array will be used to fill in the new array item’s values.

Param arrayLength:

The total number of valid values in array that should be set in the given item as array elements.

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

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

No conversions are performed on the values, so only children of the array that are of ItemType::eString will return a non-nullptr value.

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 one of the values in the array which can cause the internal string buffer for that item 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:

The array item to retrieve the internal string buffer pointers from. All children that have keys that are convertible to array indices will have their values filled in arrayOut and only if those indices are within the range of zero through one one less than arrayBufferLength inclusive. This may not be nullptr.

Param arrayOut:

[out] Receives the internal data pointers for all array indexed children in the array. This array will be cleared to all nullptr before retrieving any values. Any entry that does not correspond to an ItemType::eString item in the array will receive nullptr. This may not be nullptr.

Param arrayBufferLength:

The maximum number of entries that can fit in arrayOut. No more than this many items will be written to the output array arrayOut.

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

Creates or updates an item to be a string array.

If item is already an ItemType::eDictionary type, all of its children will be destroyed and replaced by new items with values from array. Any applicable change notifications will be queued as a result of these operations. If the item is not already an ItemType::eDictionary, its subtree (if any) is destroyed and the item is converted to an ItemType::eDictionary that is treated as an array. New child items will be created for all elements of the given array.

Param item:

The array item to set new values for. The entire subtree of this item will be destroyed and replaced with the new array entries. This item will also be converted to an ItemType::eDictionary item. This may not be nullptr.

Param array:

An array of string values to be set in each index of the new array item. This may not be nullptr and must contain at least arrayLength entries. Individual entries may contain nullptr or an empty string to indicate that the new value at that index should be an empty string.

Param arrayLength:

The number of entries in array. Exactly this many new child items will be created as ItemType::eString items under the array. All new child items will have keys that match their index in array.

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

Returns a read-only child item by its index in an array item.

This is mostly intended for dynamic dictionary processing purposes. This function is designed for array view access. If you just want to enumerate all children, use getItemChildCount() and getItemChildByIndex() instead.

Param item:

The array item to retrieve a child item from. This may not be nullptr.

Param index:

The 0-based index of the child item in the array to rertieve. This must be within the range of 0 through one less than the current size of the array.

Return:

A read-only item pointer if the array item and index are valid. Since other threads could make changes to the dictionary that could cause the returned item to be destroyed, it is highly recommended that a ScopedRead lock be taken while working with the returned item. Returns nullptr if the given item is not an array or no item at the given index exists.

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

Returns a writable child item by its index in an array item.

This is mostly intended for dynamic dictionary processing purposes. This function is designed for array view access. If you just want to enumerate all children, use getItemChildCount() and getItemChildByIndex() instead.

Param item:

The array item to retrieve a child item from. This may not be nullptr.

Param index:

The 0-based index of the child item in the array to rertieve. This must be within the range of 0 through one less than the current size of the array.

Return:

A writable item pointer if the array item and index are valid. Since other threads could make changes to the dictionary that could cause the returned item to be destroyed, it is highly recommended that a ScopedRead or ScopedWrite lock be taken while working with the returned item. Returns nullptr if the given item is not an array or no item at the given index exists.

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.

No more than arrayBufferLength item objects will be retrieved. This function should not be used for simple dynamic processing purposes. Use getItemChildCount() and getItemChildByIndex() instead.

Param item:

The array item to retrieve the child items for. This is expected to be an ItemType::eDictionary type item.

Param arrayOut:

[out] 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.

If an entry exists in the source tree but not in the destination, new items will be created to fill them in if the callback requests that action. If an entry exists in the destination tree but not in the source tree, that item in the destination tree will be left unmodified. If an entry exists for any given path in both trees, a callback will be performed to decide how to proceed with the item merge.

Param dstBaseItem:

The root item that the item to merge the source item and its descendants into is taken to be relative to. The path dstPath is taken to be relative to this root item and determines where the merge operation starts. This may not be nullptr. This can be any item type and does not have to necessarily be a true root item in the dictionary. Note that depending on how the callback directs the merge, the type of the item identified by this plus the path dstPath may be modified.

Param dstPath:

The item path relative to dstBaseItem where the merge operation will begin. This path may be nullptr or an empty string to indicate that dstBaseItem itself should be used as the start of the merge. If the item at this path does not exist, a new item will be created at this path to use as the start of the merge.

Param srcBaseItem:

The root item of the source dictionary that will be merged into the destination. The real source item for the start of the merge operation is identified by both this parameter and the path srcPath. This may not be nullptr. This can be any item type and does not need to be a true root item in the dictionary.

Param srcPath:

The item path relative to srcBaseItem where the merge operation will begin. This path may be nullptr or an empty string to indicate that srcBaseItem itself should be used as the start of the merge. If the item at this path does not exist, the merge operation will simply fail immediately with no changes to the destination dictionary.

Param onUpdateItemFn:

Callback function that will direct how the merge operation occurs. This callback will be provided with every pair of items that could potentially be used in the merge. This includes items with paths that are present in both the source and destination, and items with paths that are only present in the source dictionary. If an item path only exists in the destination dictionary, this callback will not be performed as it is assumed that item will remain unmodified. This callback will return an action type that instructs the merger how to proceed for each item pair. This may not be nullptr. Some common callback implementations have been provided that can be used in this call as well:

Param userData:

Opaque user data pointer that will be passed into the callback function on each call. This value is not interpreted or accessed in any way internally, but simply passed unmodified to the callback function. It is the callback implementation’s responsibility to know how to properly interpret and access this value.

void (*destroyItem)(Item *item)#

Destroys the given item and all of its children.

Change notifications are queued for each item that is destroyed.

Param item:

The item to be destroyed. Its entire subtree will be destroyed as well. This may not be nullptr.

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

Frees a string buffer.

When a buffer returned from createStringBufferFromItemValue() or createStringBufferFromItemValueAt() is no longer needed, it must be explicitly destroyed with this function. Attempting to clean up these buffers in any other way will result in undefined behavior.

Param stringBuffer:

The 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’s flag.

Flags control how some item processing is handled.

See also

ItemFlag for more information on available flags and what behaviors each effects.

Param item:

The item to check the given flag for. This may not be nullptr.

Param flag:

The flag to check for in the given item. Only one flag may be specified at a time. Since ItemFlag is an enum and not a set of bit flags, combining multiple flags is not allowed.

Return:

true if the requested flag is enabled for the given item, and false otherwise.

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

Sets the new state of an item’s flag.

Flags control how some item processing is handled.

See also

ItemFlag for more information on available flags and what behaviors each effects.

Param item:

The item to modify the flags for. This may not be nullptr. This may be any type of item, but it is the caller’s responsibility to ensure the flags that do get set make useful sense for the given item’s type. Some flags may not have the desired effect if they are not fully handled for the given item type (ie: dictionary vs int/float/bool/string value).

Param flag:

The flag to set the new state for. Only one flag may be specified at a time. Since ItemFlag is an enum and not a set of bit flags, combining multiple flags is not allowed.

Param flagValue:

The new value to set for the flag. true indicates that the flag will become enabled while false indicates disabled.

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

Subscribes to receive change events about a specific item.

These notifications arrive in the form of a callback function with a specific change event type and item. Change notifications will only be queued for operations that directly effect the named item, not for any changes to ancestors in the dictionary. Multiple change notifications could be queued for a single operation.

When finished with the subscription, call unsubscribeToChangeEvents(). It is the caller’s responsibility to unsubscribe from all of its notifications before its module shuts down.

See also

ChangeEventType for more info on when each type of event is sent relative to the operationthat generated the notification), and the user data provided in userData. This may not be nullptr.

Param baseItem:

The base item to watch for changes relative to. This may not be nullptr. This item may be used as the item to watch for changes by passing nullptr or an empty string for path.

Param path:

The subpath relative to baseItem that indicates the item to watch. This may be nullptr or an empty string to allow the given item baseItem to be watched directly for changes.

Param onChangeEventFn:

The callback function to call when a change event occurs. This callback will provide the item object for reference, the type of change that either occurred or will occur (

Param userData:

An opaque data object that will be passed to the callback function onChangeEventFn any time it is called. This object will not be accessed or interpreted internally. It is the callback function implementation’s responsibility to know how to properly and safely interpret this value.

Return:

A subscription handle that can be used with unsubscribeToChangeEvents() if the subscription is successfully registered. Returns nullptr if an error occured.

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

Subscribes to change events for all items in a subtree.

These notifications arrive in the form of a callback function with a specific change event type and item. Change notifications will be queued for operations that directly affect the named item or for changes to any of its descendants in the dictionary. Multiple change notifications could be queued for any single operation.

When finished with the subscription, call unsubscribeToChangeEvents(). It is the caller’s responsibility to unsubscribe from all of its notifications before its module shuts down.

See also

ChangeEventType for more info on when each type of event is sent relative to the operationthat generated the notification), and the user data provided in userData. This may not be nullptr.

Param baseItem:

The base item to watch for changes relative to. This may not be nullptr. This item may be used as the root item to watch for changes on by passing nullptr or an empty string for path.

Param path:

The subpath relative to baseItem that indicates the root of the subtree to watch. This may be nullptr or an empty string to allow the given item baseItem to be used as the root of the subtree to watch for changes.

Param onChangeEventFn:

The callback function to call when a change event occurs for either the named item or its subtree. This callback will provide the item object for reference, the type of change that either occurred or will occur (

Param userData:

An opaque data object that will be passed to the callback function onChangeEventFn any time it is called. This object will not be accessed or interpreted internally. It is the callback function implementation’s responsibility to know how to properly and safely interpret this value.

Return:

A subscription handle that can be used with unsubscribeToChangeEvents() if the subscription is successfully registered. Returns nullptr if an error occured.

void (*unsubscribeToChangeEvents)(SubscriptionId *subscriptionId)#

Unsubscribes from change events.

This may be used to clean up the subscription object for both node change subscriptions returned from subscribeToNodeChangeEvents() and tree change subscriptions from subscribeToTreeChangeEvents(). This call may block temporarily if an affected change notification callback is still in progress. Upon return, it is guaranteed both that no more change notifications will arrive for the given subscription and that any pending change callbacks have finished executing.

Param subscriptionId:

The subscription handle from subscribeToNodeChangeEvents() or subscribeToTreeChangeEvents() to unsubscribe from. This may not be nullptr.

void (*unsubscribeItemFromNodeChangeEvents)(Item *item)#

Unsubscribes all node change handles for a specific Item.

This may be used to ensure that no more node change notifications will occur for a given item. Tree change notifications may still occur however if the given item is part of another watched subtree. This may block temporarily if an affected change notification callback is still in progress. Upon return, it is guaranteed both that no more node change notifications will arrive for the given item, and that any pending change callbacks have finished executing.

Param item:

The item to remove any pending node change notification subscriptions from. Only node subscriptions will be removed and unregistered. Tree change notifications could still occur on this item if another tree subscription is registered on an ancestor. This may not be nullptr.

void (*unsubscribeItemFromTreeChangeEvents)(Item *item)#

Unsubscribes all subtree change handles for a specific Item.

This may be used to ensure that all tree change notification subscriptions will be removed from the given item and unregistered. Only tree change subscriptions that were registered directly on the given item will be unregistered. If this item is in the subtree of another ancestor’s tree change subscription, those other higher subscriptions will not be removed. Upon return, it is guaranteed that both no more tree change notifications will arrive for subscriptsions that were watching the subtree of the given item, and that any pending change callbacks have finished executing.

Param item:

The item to remove any pending tree change notification subscriptions from. Only tree subscriptions will be removed and unregistered, and only subscriptions that were registered directly on the given item will be removed. Node change notifications could still occur on this item if they were also registered for it. This may not be nullptr.

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.

See also

unlock writeLock ScopedRead ScopedWrite

Warning

Do not use readLock() directly; prefer ScopedRead instead.

Warning

If a read lock is held and the same thread later takes a write lock, all locks will be released for a brief period of time, in which case another thread may be able to make changes.

Param item:

The item to read-lock. item’s entire hierarchy will be read-locked. This may not be nullptr since it may cause synchronization issues. item must not be destroyed while the read lock is held. The same item should be passed to unlock() to unlock this same item at a later point.

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.

See also

readLock unlock ScopedRead ScopedWrite

Warning

Do not use writeLock() directly; prefer ScopedWrite instead.

Param item:

The item to write-lock. item’s entire hierarchy will be write-locked. This may not be nullptr since it may cause synchronization issues. item must not be destroyed while the write lock is held. The same item should be passed to unlock() to unlock this same item at a later point.

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.

See also

readLock writeLock ScopedRead ScopedWrite

Warning

Do not use unlock() directly; prefer using ScopedWrite or ScopedRead instead.

Param item:

The item to unlock. item’s entire hierarchy will be unlocked. Another thread may only acquire this lock once all locks owned by the calling thread have been unlocked. This may not be nullptr.

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

Returns a 128-bit hash representing the value.

This hash uses the FNV128 algorithm. The hash will be invariant of the order of children in each item. Each item in the tree will use its key name, type, flags, and value (if any) to contribute to the hash. The hash can be used to compare two dictionaries for equality or to provide a way of including multiple dictionaries in a hash map container.

We guarantee that the hashing algorithm will not change unless the version number of the interface changes. These hashes should not be considered for persistent storage purposes for this reason.

Param item:

The item to take the hash of. This may not be nullptr. The item’s information as well as the information of each of its descendants will be included in the hash calculation.

Return:

The 128-bit hash of the item. This hash is guaranteed to be invariant for a given dictionary within the same process and interface version. The calculation of the hash may have a different result for a given dictionary in future interface versions however.

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. This may not be nullptr.

Param itemB:

The second item to compare. This may not be nullptr.

Return:

The result of a lexicographical compare of itemA and itemB. A negative value indicates that itemA should be ordered before itemB. A positive value indicates that itemA should be ordered after itemB. A zero value indicates that items itemA and itemB are equal.

Public Static Functions

static inline constexpr carb::InterfaceDesc getInterfaceDesc(
) noexcept#

Returns information about this interface.

Auto-generated by CARB_PLUGIN_INTERFACE() or CARB_PLUGIN_INTERFACE_EX.

Returns:

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

static inline constexpr carb::InterfaceDesc getLatestInterfaceDesc(
) noexcept#

Returns information about the latest version of this interface.

Auto-generated by CARB_PLUGIN_INTERFACE() or CARB_PLUGIN_INTERFACE_EX.

Returns:

The carb::InterfaceDesc struct with information about the latest version of this interface.

On this page