IDictionary#

Fully qualified name: carb::dictionary::IDictionary

Defined in carb/dictionary/detail/IDictionary2.h

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

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

Public Functions

virtual const Item *getItem( const Item *baseItem, cpp::string_view path, ) const = 0#

Returns opaque pointer to read-only item using a string_view for the path.

Parameters:

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

Returns:

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

virtual Item *getItem( Item *baseItem, cpp::string_view path, ) const = 0#

Returns opaque pointer to mutable item using a string_view for the path.

Parameters:

baseItem – Base item to apply path from (required).
path – Child path as a string_view, separated with forward slash (‘/’). The path should not start with a forward slash.

Returns:

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

virtual size_t getItemChildCount(const Item *item) const = 0#

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.

Parameters:: item – Item to query the number of children from. This may not be nullptr.
Returns:: The number of children if applicable, 0 otherwise.

virtual const Item *getItemChildByIndex( const Item *item, size_t childIndex, ) const = 0#

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

Parameters:

item – Item to query child from. This may not be nullptr.
childIndex – The 0-based index of the item to retrieve.

Returns:

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

virtual Item *getItemChildByIndex( Item *item, size_t childIndex, ) const = 0#

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

Mostly for dynamic dictionary processing. This function is different from the getItemAt() 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.).

Parameters:

item – Item to query child from. This may not be nullptr.
childIndex – The 0-based index of the item to retrieve.

Returns:

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

virtual const Item *getItemParent(const Item *item) const = 0#

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

Parameters:: item – Item to get parent for. This may not be nullptr.
Returns:: Opaque item pointer if the item is valid and has a parent, or nullptr otherwise.

virtual Item *getItemParent(Item *item) const = 0#

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

Parameters:: item – Item to get parent for. This may not be nullptr.
Returns:: Opaque item pointer if the item is valid and has a parent, or nullptr otherwise.

virtual ItemType getItemType(const Item *item) const = 0#

Returns an item’s type.

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

Parameters:: item – The item to retrieve the type for. This may not be nullptr.
Returns:: The item’s type if the item is valid or ItemType::eCount otherwise.

virtual cpp::optional<omni::string> createStringFromItemName( const Item *item, ) const = 0#

Returns a string filled with a copy of the item name.

Parameters:: item – The item to retrieve the name for. This may not be nullptr.
Returns:: An optional omni::string containing the item’s name if the item is valid. Returns carb::cpp::nullopt if the item is invalid.

virtual cpp::optional<cpp::zstring_view> getItemName( const Item *item, ) const = 0#

Returns a view of an item’s name if the item is valid.

Warning

As this function returns a view of an item, another thread may delete the item leaving the returned view as dangling memory. It is recommended to use ScopedRead around this function call and the use of the returned value.

Parameters:: item – The item to retrieve the name for. This may not be nullptr.
Returns:: Optional containing the internal item name string if the item is valid or nullopt otherwise.

virtual Item *createItem( Item *baseItem, cpp::string_view path, ItemType itemType, ) const = 0#

Creates a new item and all the required items along the given path if necessary, using a string_view for the path.

Parameters:

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).
path – Path to the new item relative to the base item baseItem, as a string_view. The path should not start with a forward slash.
itemType – The type of the new item to be created at the given path. This may not be ItemType::eCount.

Returns:

An opaque Item pointer if it was successfully created or nullptr otherwise.

virtual bool isAccessibleAs( ItemType itemType, const Item *item, ) const = 0#

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

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

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

Parameters:

itemType – The item type to check whether item is accessible as. This may not be ItemType::eCount.
item – The item to check the type accessibility for. This may not be nullptr.

Returns:

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

virtual int64_t getAsInt64(const Item *item) const = 0#

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.

Parameters:: item – [in] The item to retrieve the integer value from. This may not be nullptr.
Returns:: The 64 bit integer value of item. This will be converted from the existing type if this item is not a 64-bit integer 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).

virtual void setInt64(Item *item, int64_t value) const = 0#

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.

Parameters:

item – The item to set the integer value for. This may not be nullptr.
value – The integer value that will be set to the supplied item.

virtual double getAsFloat64(const Item *item) const = 0#

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

Parameters:: item – [in] The item to retrieve the floating point value from. This may not be nullptr.
Returns:: 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.

virtual void setFloat64(Item *item, double value) const = 0#

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.

Parameters:

item – The item to set the new 64-bit floating point value for. This may not be nullptr.
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.

virtual bool getAsBool(const Item *item) const = 0#

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

Parameters:: 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.
Returns:: 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.

virtual void setBool(Item *item, bool value) const = 0#

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.

Parameters:

item – The item to set a new boolean value for. This may not be nullptr.
value – The new boolean value that will be set to the supplied item.

virtual cpp::optional<omni::string> createStringFromItemValue( const Item *item, ) const = 0#

Attempts to create a string with a value, either a copy of 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.
Returns:: An optional omni::string if is successfully created, or carb::cpp::nullopt otherwise.

virtual cpp::optional<cpp::zstring_view> getStringView( const Item *item, ) const = 0#

Retrieves a view of the internal string for a given item.

Only valid for ItemType::eString Items.

This function provides direct access to the internal string of an item without any conversion.

Warning

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

Parameters:: item – The item to retrieve the string view for. This may not be nullptr.
Returns:: An optional containing a view on the internal string if the item has a string value, or nullopt otherwise. The size can be obtained from the zstring_view.

virtual cpp::optional<omni::string> getString( const Item *item, ) const = 0#

Returns a copy of the internal string for a given item.

Only valid for ItemType::eString items.

This function provides direct access to an item’s internal string without any conversion. To convert any item to a string value, use createStringFromItemValue.

Note

As the returned string is always a copy, this function does not have the same issues as getStringView.

Parameters:: item – The item to retrieve the string for. This may not be nullptr.
Returns:: An optional containing a omni::string copy of the internal string value if the item has a string value, or carb::cpp::nullopt otherwise.

virtual void setString(Item *item, cpp::string_view value) const = 0#

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.

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.

virtual bool isAccessibleAsArray(const Item *item) const = 0#

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

Parameters:: 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.
Returns:: 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.

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

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.

Parameters:

itemType – Item type to check for. This may not be ItemType::eCount.
item – The item to check whether it can be treated as an array of the requested type itemType. This may not be nullptr.

Returns:

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

virtual size_t getArrayLength(const Item *item) const = 0#

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

Parameters:: item – The item to test whether it is being treated purely as an array item. This may not be nullptr.
Returns:: Non-zero number of array elements if the item can be treated as an array (implies isAccessibleAsArray() also succeeds), or 0 otherwise.

virtual ItemType getPreferredArrayType(const Item *item) const = 0#

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:

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

Parameters:: 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.
Returns:: 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).

virtual int64_t getAsInt64At(const Item *item, size_t index) const = 0#

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.

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

virtual void setInt64At( Item *item, size_t index, int64_t value, ) const = 0#

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.

Parameters:

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.
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 64-bit integer value that will be set to the given index in the supplied array item.

virtual size_t getAsInt64Array( const Item *item, int64_t *arrayOut, size_t arrayBufferLength, ) const = 0#

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.

Parameters:

item – The array item to retrieve the 64-bit integer values from. This may not be nullptr.
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.
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.

Returns:

The number of values that were read into arrayOut. This may be less than arrayBufferLength if the array item contains fewer values than this.

virtual void setInt64Array( Item *item, const cpp::span<const int64_t> array, ) const = 0#

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.

Parameters:

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.
array – A span of new 64-bit integer values to use for the contents of the new array.

virtual size_t getAsIntArray( const Item *item, int32_t *arrayOut, size_t arrayBufferLength, ) const = 0#

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.

Parameters:

item – The array item to retrieve the 32-bit integer values from. This may not be nullptr.
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.
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.

Returns:

The number of values that were read into arrayOut. This may be less than arrayBufferLength if the array item contains fewer values than this.

virtual void setIntArray( Item *item, const cpp::span<const int32_t> array, ) const = 0#

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.

Parameters:

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.
array – A span of new 32-bit integer values to use for the contents of the new array.

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

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.

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

virtual void setFloat64At( Item *item, size_t index, double value, ) const = 0#

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.

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 64-bit floating point value that will be set to the given index in the supplied array item.

virtual size_t getAsFloat64Array( const Item *item, double *arrayOut, size_t arrayBufferLength, ) const = 0#

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.

Parameters:

item – The array item to retrieve the 64-bit floating point values from. This may not be nullptr.
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.
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.

Returns:

The number of values that were read into arrayOut. This may be less than arrayBufferLength if the array item contains fewer values than this.

virtual void setFloat64Array( Item *item, const cpp::span<const double> array, ) const = 0#

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.

Parameters:

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.
array – A span of new 64-bit floating point values to use for the contents of the new array.

virtual size_t getAsFloatArray( const Item *item, float *arrayOut, size_t arrayBufferLength, ) const = 0#

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.

Parameters:

item – The array item to retrieve the 32-bit floating point values from. This may not be nullptr.
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.
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.

Returns:

The number of values that were read into arrayOut. This may be less than arrayBufferLength if the array item contains fewer values than this.

virtual void setFloatArray( Item *item, const cpp::span<const float> array, ) const = 0#

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.

Parameters:

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.
array – A span of new 32-bit floating point values to use for the contents of the new array.

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

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.

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, false will be returned.

Returns:

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.

virtual void setBoolAt(Item *item, size_t index, bool value) const = 0#

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.

Parameters:

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.
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 boolean value that will be set to the given index in the supplied array item.

virtual size_t getAsBoolArray( const Item *item, bool *arrayOut, size_t arrayBufferLength, ) const = 0#

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.

Parameters:

item – The array item to retrieve the boolean values from. This may not be nullptr.
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.
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.

Returns:

The number of values that were read into arrayOut. This may be less than arrayBufferLength if the array item contains fewer values than this.

virtual void setBoolArray( Item *item, const cpp::span<const bool> array, ) const = 0#

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.

Parameters:

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.
array – A span of new boolean values to use for the contents of the new array.

virtual cpp::optional<omni::string> createStringFromItemValueAt( const Item *item, size_t index, ) const = 0#

Attempts to create a new string 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.

Returns:

An omni::string representing the string value of item at index if successful. Returns carb::cpp::nullopt if an error occurred, such as the index being out of range.

virtual cpp::optional<cpp::zstring_view> getStringViewAt( const Item *item, size_t index, ) const = 0#

Returns a view of the internal string for an indexed item.

Only valid for ItemType::eString Items.

This function provides direct access to the internal string of an item without any conversion. 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 view 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 view for. This must be in the range of the current size of the array.

Returns:

An optional containing a view on the internal string value if the requested indexed item is found, or nullopt otherwise. The size can be obtained from the zstring_view.

virtual void setStringAt( Item *item, size_t index, cpp::string_view value, ) const = 0#

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.

virtual size_t getStringArray( const Item *item, cpp::string_view *arrayOut, size_t arrayBufferLength, ) const = 0#

Fills a provided buffer with views 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 contain a non-empty value. Items that are not of type ItemType::eString will contain an emtpy cpp::string_view with nullptr data().

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 a view the internal string view(s) for several items. Another thread may change one of the values in the array which can cause the internal string for that item to be destroyed, rendering the view dangling. 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.

Parameters:

item – The array item to retrieve the internal string views 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.
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.
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.

Returns:

The number of values that were read into arrayOut. This may be less than arrayBufferLength if the array item contains fewer values than this.

virtual void setStringArray( Item *item, const cpp::span<const cpp::string_view> array, ) const = 0#

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.

Parameters:

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.
array – A span of string views to be set in each index of the new array item.

virtual const Item *getItemAt( const Item *item, size_t index, ) const = 0#

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.

Parameters:

item – The array item to retrieve a child item from. This may not be nullptr.
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.

Returns:

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.

virtual Item *getItemAt(Item *item, size_t index) const = 0#

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.

Parameters:

item – The array item to retrieve a child item from. This may not be nullptr.
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.

Returns:

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.

virtual size_t getItemArray(

const Item *item,

const Item **arrayOut,

size_t arrayBufferLength,

) const = 0#

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.

Parameters:

item – The array item to retrieve the child items for. This is expected to be an ItemType::eDictionary type item.
arrayOut – [out] Array buffer to fill with opaque item pointers.
arrayBufferLength – Size of the supplied array buffer.

Returns:

The number of values that were read into arrayOut. This may be less than arrayBufferLength if the array item contains fewer values than this.

virtual void update( Item *dstBaseItem, cpp::string_view dstPath, const Item *srcBaseItem, cpp::string_view srcPath, OnUpdateItemFn onUpdateItemFn, void *userData, ) const = 0#

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.

Parameters:

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.
dstPath – The item path relative to dstBaseItem where the merge operation will begin. This path may be 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.
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.
srcPath – The item path relative to srcBaseItem where the merge operation will begin. This path may be 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.
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:
- carb::dictionary::keepOriginal(): always keeps the item from the destination dictionary. This will essentially always leave the destination dictionary unmodified except for item paths that don’t already exist in it.
- carb::dictionary::overwriteOriginal(): always replaces the destination dictionary item with the matching source item at any given path. This will always favor the source item.
- carb::dictionary::overwriteOriginalWithArrayHandling(): same as above, but will handle items that have been marked as arrays even if they are empty.
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.

virtual void destroyItem(Item *item) const = 0#

Destroys the given item and all of its children.

Change notifications are queued for each item that is destroyed.

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

virtual bool getItemFlag(const Item *item, ItemFlag flag) const = 0#

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.

Parameters:

item – The item to check the given flag for. This may not be nullptr.
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.

Returns:

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

virtual void setItemFlag( Item *item, ItemFlag flag, bool flagValue, ) const = 0#

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.

Parameters:

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).
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.
flagValue – The new value to set for the flag. true indicates that the flag will become enabled while false indicates disabled.

virtual SubscriptionId *subscribeToNodeChangeEvents( Item *baseItem, cpp::string_view path, OnNodeChangeEventFn onChangeEventFn, void *userData, ) const = 0#

Subscribes to receive change events about a specific item, using a string_view for the path.

Parameters:

baseItem – The base item to watch for changes relative to. This may not be nullptr.
path – The subpath relative to baseItem that indicates the item to watch, as a string_view.
onChangeEventFn – The callback function to call when a change event occurs.
userData – An opaque data object that will be passed to the callback function.

Returns:

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

virtual SubscriptionId *subscribeToTreeChangeEvents( Item *baseItem, cpp::string_view path, OnTreeChangeEventFn onChangeEventFn, void *userData, ) const = 0#

Subscribes to change events for all items in a subtree, using a string_view for the path.

Parameters:

baseItem – The base item to watch for changes relative to. This may not be nullptr.
path – The subpath relative to baseItem that indicates the root of the subtree to watch, as a string_view.
onChangeEventFn – The callback function to call when a change event occurs.
userData – An opaque data object that will be passed to the callback function.

Returns:

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

virtual void unsubscribeFromChangeEvents( SubscriptionId *subscriptionId, ) const = 0#

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.

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

virtual void unsubscribeItemFromNodeChangeEvents(Item *item) const = 0#

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.

Parameters:: 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.

virtual void unsubscribeItemFromTreeChangeEvents(Item *item) const = 0#

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.

Parameters:: 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.

virtual void readLock(const Item *item) const = 0#

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.

Parameters:: 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.

virtual void writeLock(Item *item) const = 0#

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.

Parameters:: 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.

virtual void unlock(const Item *item) const = 0#

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.

Warning

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

Parameters:: 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.

virtual const extras::hash128_t getHash(const Item *item) const = 0#

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.

Parameters:: 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.
Returns:: 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.

virtual int lexicographicalCompare( const Item *itemA, const Item *itemB, ) const = 0#

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.

Parameters:

itemA – The first item to compare. This may not be nullptr.
itemB – The second item to compare. This may not be nullptr.

Returns:

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.

inline int32_t getAsInt(const Item *item) const#

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) const#

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, cpp::string_view path, int64_t value, ) const#

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, cpp::string_view path, int32_t value, ) const#

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) const#

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) const#

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, cpp::string_view path, double value, ) const#

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, cpp::string_view path, float value, ) const#

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, cpp::string_view path, bool value, ) const#

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 Item *makeStringAtPath( Item *baseItem, cpp::string_view path, cpp::string_view value, ) const#

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.

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, cpp::string_view path, ) const#

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 Item *item) const = delete#

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 zstring_view. 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 counterparts 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 getStringView() and has the same safety warnings.

template<typename T, typename U = T> T get( const Item *baseItem, cpp::string_view path, U &&defaultValue = T{}, ) const#

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. Must be the same as types supported by get(const Item*)const.
U – A type that can be passed to the constructor of T. Used for defaultValue.

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 an empty string to indicate that the value from baseItem should be retrieved instead.
defaultValue – A value used to construct the return value if baseItem and path do not describe a valid item.

Returns:

If baseItem and path reference an existing item, the return value will contain the result from get<T>(const Item*); otherwise a T constructed from defaultValue is returned.

template<typename T> cpp::optional<T> getOpt( const Item *baseItem, cpp::string_view path, ) const#

Optionally 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. Must be the same as types supported by get(const Item*)const.

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 an empty string to indicate that the value from baseItem should be retrieved instead.

Returns:

If baseItem and path reference an existing item, the return value will contain the result from get<T>(const Item*); otherwise carb::cpp::nullopt is returned.

template<typename T, std::enable_if_t<!carb::cpp::is_std_string_view_like_v<T>, bool> = true> Item *makeAtPath( Item *baseItem, cpp::string_view path, T value, ) const#

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().

Item *makeAtPath( Item *baseItem, cpp::string_view path, cpp::string_view value, ) const#

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) const#

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) const#

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) const#

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) const#

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.

template<typename ArrayElementType> void setArray( Item *item, const cpp::span<const ArrayElementType> array, ) const = delete#

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

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

bool: will call through to setBoolArray() for each child item.
int32_t: will call through to setIntArray() for each child item.
int64_t: will call through to setInt64Array() for each child item.
float: will call through to setFloatArray() for each child item.
double: will call through to setFloat64Array() for each child item.
const char*: will call through to setStringArray() for each child item.

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

void deleteChildren(Item *item) const#

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.

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

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) const#

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.

virtual Item *duplicateItem( const Item *item, Item *newParent, cpp::string_view newKey, ) const = 0#

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 empty unless newParent isnullptr.

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