dictionary#

Fully qualified name: carb::dictionary

namespace dictionary#: Namespace for carb::dictionary::IDictionary related interfaces and helpers.

Classes#

ScopedRead: A helper class for calling readLock() and unlock().
ScopedWrite: A helper class for calling writeLock() and unlock().

Enumerations#

ChangeEventType: Type of a change passed to a subscription callback.
ItemFlag: Item flags that can be specified by the user.
ItemType: Supported item types.
UpdateAction: Actions that may be returned by carb::dictionary::OnUpdateItemFn .
WalkerMode: Mode names for the ways to walk the requested dictionary.

Functions#

Item * createDictionaryFromFile(ISerializer *serializer, const char *filename): Attempts to read the contents of a file into a dictionary.
std::string dumpToString(const dictionary::Item *c, const char *serializerName=nullptr): Writes a dictionary to a string.
IDictionary * getCachedDictionaryInterface(): helper function to retrieve the IDictionary interface.
const Item * getChildByIndex(IDictionary *dict, const Item *item, size_t idx): Specialization for the getChildByIndex() callback that implements a simple retrieval of the requested child item using IDictionary::getItemChildByIndex() .
ItemPtrType * getChildByIndex(IDictionary *dict, ItemPtrType *item, size_t idx): Prototype for a callback function used to walk children in a dictionary.
std::string getItemFullPath(dictionary::IDictionary *dict, const carb::dictionary::Item *item, bool includeRoot=true): Retrieves the full path to dictionary item from its top-most ancestor.
std::vector< std::string > getStringArray(const IDictionary *dict, const Item *item): Attempts to retrieve an array of string values from a given dictionary path.
std::vector< std::string > getStringArray(const IDictionary *dict, const Item *baseItem, const char *path): Attempts to retrieve an array of string values from a given dictionary path.
std::string getStringFromItemName(const IDictionary *dict, const Item *baseItem, const char *path=nullptr): Attempts to retrieve the name of an item from a given path in a dictionary.
std::string getStringFromItemValue(const IDictionary *dict, const Item *baseItem, const char *path=nullptr): Attempts to retrieve the value of an item from a given path in a dictionary.
T getValueOrDefault(const Item *baseItem, const char *path, T defaultValue): Gets a child value from a given Item if present, otherwise returns the given default value.
UpdateAction keepOriginal(const Item *dstItem, ItemType dstItemType, const Item *srcItem, ItemType srcItemType, void *userData): Function that indicates that the merger should retain the existing destination item.
Item * makeStringArrayAtPath(Item *baseItem, const char *path, const std::vector< std::string > &arr): Set a string array at the given path with the given array (creating it if it doesn't yet exist).
UpdateAction overwriteOriginal(const Item *dstItem, ItemType dstItemType, const Item *srcItem, ItemType srcItemType, void *userData): Note that this function does not properly handle overwriting of arrays due to overwriting array being shorter, potentially leaving part of the older array in-place after the merge Use overwriteOriginalWithArrayHandling() if dictionaries are expected to contain array data.
UpdateAction overwriteOriginalWithArrayHandling(const Item *dstItem, ItemType dstItemType, const Item *srcItem, ItemType srcItemType, void *dictionaryInterface): Helper function for IDictionary::update() that ensures arrays are properly overwritten.
void saveFileFromDictionary(ISerializer *serializer, const dictionary::Item *dictionary, const char *filename, SerializerOptions serializerOptions): Writes the contents of a dictionary to a file.
void setDictionaryArrayElementFromStringValue(dictionary::IDictionary *dictionaryInterface, dictionary::Item *targetDictionary, const std::string &elementPath, const std::string &elementValue): Parses a string representation of an array and sets it relative to a dictionary path.
void setDictionaryElementAutoType(IDictionary *id, Item *dict, const std::string &path, const std::string &value): Attempts to set a value in a dictionary with an attempt to detect the value type.
void setDictionaryFromCmdLine(IDictionary *id, Item *dict, char **argv, int argc, const char *prefix="--/"): Parses a set of command line arguments for dictionary items arguments and sets them.
void setDictionaryFromStringMapping(IDictionary *id, Item *dict, const std::map< std::string, std::string > &mapping): Sets a series of values in a dictionary based on keys and values in a map object.
void setStringArray(IDictionary *dict, Item *item, const std::vector< std::string > &stringArray): Sets an array of values at a given path relative to a dictionary item.
void setStringArray(IDictionary *dict, Item *baseItem, const char *path, const std::vector< std::string > &stringArray): Sets an array of values at a given path relative to a dictionary item.
ItemType toItemType(): Helper function to convert a data type to a corresponding dictionary item type.
ItemType toItemType< bool >(): Specialization for an bool item value.
ItemType toItemType< char * >(): Specialization for an char* item value.
ItemType toItemType< const char * >(): Specialization for an const char* item value.
ItemType toItemType< double >(): Specialization for an double item value.
ItemType toItemType< float >(): Specialization for an float item value.
ItemType toItemType< int32_t >(): Specialization for an int32_t item value.
ItemType toItemType< int64_t >(): Specialization for an int64_t item value.
void unsubscribeTreeFromAllEvents(IDictionary *dict, Item *item): Unsubscribes all items in a dictionary tree from change notifications.
void walkDictionary(IDictionary *dict, WalkerMode walkerMode, ItemPtrType *root, ElementData rootElementData, OnItemFnType onItemFn, void *userData, GetChildByIndexFuncType getChildByIndexFunc=getChildByIndex< ItemPtrType >): Walk a dictionary item to enumerate all of its values.

Structs#

IDictionary: DOM-style dictionary (keeps the whole structure in-memory).
ISerializer: Interface intended to serialize dictionary objects to and from plain C strings.
Item: Structure used in opaque pointers to each dictionary node.
SubscriptionId: Opaque value representing a subscription.

Typedefs#

DeserializerOptions: Flags for deserializing a string (for ISerializer::createDictionaryFromStringBuffer() )
OnItemFn: Prototype for a callback function used to walk items in a dictionary.
OnNodeChangeEventFn: A callback that, once registered with IDictionary::subscribeToNodeChangeEvents() , receives notifications when an item at a specific path changes state or value.
OnTreeChangeEventFn: A callback that, once registered with IDictionary::subscribeToTreeChangeEvents() , receives notifications when Items in a given tree change state or value.
OnUpdateItemFn: Callback function that will tell whether and how the merger in IDictionary::update() operations should overwrite the destination item with the source item.
SerializerOptions: Base type for flags for the ISerializer::createStringBufferFromDictionary() function.

Variables#

constexpr DeserializerOptions fDeserializerOptionInSitu: Flag that indicates that the const char* string value can actually be considered as char* and treated destructively (allow in-situ modification by the deserializer).
constexpr SerializerOptions fSerializerOptionEmptyDictionaryIsArray: Flag to indicate that if an empty dictionary item is found while walking the dictionary that is being serialized, it should be represented by an empty array.
constexpr SerializerOptions fSerializerOptionIncludeCollectionName: Deprecated flag name for fSerializerOptionIncludeDictionaryName .
constexpr SerializerOptions fSerializerOptionIncludeDictionaryName: Flags to affect the behavior of the ISerializer::createStringBufferFromDictionary() function.
constexpr SerializerOptions fSerializerOptionMakePretty: Flag to indicate that the generated string should be formatted to be human readable and look 'pretty'.
constexpr SerializerOptions fSerializerOptionSerializeInfinityAsNull: Flag to indicate that the JSON serializer should write out infinity and NaN floating point values as a null object.
constexpr DeserializerOptions kDeserializerOptionNone: Default value for DeserializerOptions that specifies no options.
constexpr SerializerOptions kSerializerOptionEmptyDictionaryIsArray: Deprecated flag.
constexpr SerializerOptions kSerializerOptionIncludeCollectionName: Deprecated flag.
constexpr SerializerOptions kSerializerOptionIncludeDictionaryName: Deprecated serializer option flag names.
constexpr SerializerOptions kSerializerOptionMakePretty: Deprecated flag.
constexpr SerializerOptions kSerializerOptionSerializeInfinityAsNull: Deprecated flag.
constexpr OnUpdateItemFn kUpdateItemKeepOriginal: Alias for keepOriginal() .
constexpr OnUpdateItemFn kUpdateItemOverwriteOriginal: Alias for overwriteOriginal() .