Next: EnumInstanceMembers - AurieFramework/YYToolkit GitHub Wiki

Enumerates the members for a given GameMaker struct / instance pointer.

AurieStatus EnumInstanceMembers(
    [in] RValue             Instance,
    [in] std::function<...> EnumFunction
);

An object-typed RValue, containing the pointer to the instance the members of which will be enumerated. Given that RValues can be implicitely constructed from a CInstance*, it is possible for callers to pass a CInstance* directly. Note that this method operates only on CInstance* or on GameMaker structs, not on other data structures like DSMaps or DSLists. To access members of those data structures, callers should consider using GameMaker built-in functions, such as ds_map_find_value or ds_list_find_value.

A pointer to a caller-defined callback function. This function is called for every member of the Instance provided. The function should be of the following prototype:

bool ExampleFunction(
    [in]      const char* MemberName,
    [in, out] RValue*     Value
);

If the callback function returns true, the enumeration is stopped, and EnumInstanceMembers returns AURIE_SUCCESS. If the callback returns false, enumeration continues. If at no point during enumeration the callback function returned true, the function returns AURIE_OBJECT_NOT_FOUND. It is safe to provide a lambda, as the std::function wrapper is used. The callback function may modify the RValue pointed-to by the Value pointer, which will cause the respective member to change in the enumerated instance.

The function returns AURIE_SUCCESS on success, otherwise returns a matching error code. If the internal runner function needed for accessing variables, the AURIE_MODULE_INTERNAL_ERROR status code is returned. If an invalid kind of RValue is specified, the function returns AURIE_INVALID_PARAMETER. If at no point during enumeration the callback function returned true, the function returns AURIE_OBJECT_NOT_FOUND.

This function should be used with caution, given that some instances contain thousands of members (eg. the global instance), which means the callback function may be called hundreds or thousands of times per a single call to EnumInstanceMembers. The time required to loop over all elements in the instance increases with at best with O(n), and at worst with O(n log(n)).