carb::dictionary::walkDictionary

Defined in carb/dictionary/DictionaryUtils.h

template<typename ElementData, typename OnItemFnType, typename ItemPtrType = const Item, typename GetChildByIndexFuncType>
inline void carb::dictionary::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.

Remark

This walks a dictionary and enumerates all of its values of all types. This includes even ItemType::eDictionary items. Non-leaf items in the walk will be passed to the onItemFn callback before walking through its children. The getChildByIndexFunc callback function can be used to control the order in which the children of each level of the dictionary are enumerated. The default implementation simply enumerates the items in the order they are stored in (which is generally arbitrary). The dictionary’s full tree is walked in a depth first manner so sibling items are not guaranteed to be enumerated consecutively.

Thread Safety

This function is thread safe as long as nothing else is concurrently modifying the dictionary being walked. It is the caller’s responsibility to ensure that neither the dictionary nor any of its children will be modified until the walk is complete.

Template Parameters

  • ElementData – The data type for the per-item element data that is maintained during the walk. This can be used for example to track which level of the dictionary a given item is at by using an int type here.

  • OnItemFnType – The type for the onItemFn callback function.

  • ItemPtrType – The type used for the item type in the GetChildByIndexFuncType callback. This must either be const Item or Item. This defaults to const Item. If a non-const type is used here it is possible that items’ values could be modified during the walk. Using a non-const value is discouraged however since it can lead to unsafe use or undefined behavior.

  • GetChildByIndexFuncType – The type for the getChildByIndexFunc callback function.

Parameters

  • dict – [in] The IDictionary interface to use to access the items in the dictionary. This must not be nullptr. This must be the same interface that was originally used to create the dictionary root being walked.

  • walkerMode – [in] The mode to walk the given dictionary in.

  • root – [in] The root dictionary to walk. This must not be nullptr.

  • rootElementData – [in] The user specified element data value that is to be associated with the root element. This value can be changed during the walk by the onItemFn callback function.

  • onItemFn – [in] The callback function that is performed for each value in the given dictionary. The user specified element data value can be modified on each non-leaf item. This modified element data value is then passed to all further children of the given item. The element data value returned for leaf items is discarded. This must not be nullptr.

  • userData – [in] Opaque user data object that is passed to each onItemFn callback. The caller is responsible for knowing how to interpret and access this value.

  • getChildByIndexFunc – [in] Callback function to enumerate the children of a given item in the dictionary being walked. This must not be nullptr. This can be used to either control the order in which the child items are enumerated (ie: sort them before returning), or to return them as non-const objects so that the item’s value can be changed during enumeration. Attempting to insert or remove items by using a non-const child enumerator is unsafe and will generally result in undefined behavior.

Returns

No return value.