Symisc Systems

Libcox C/C++ API Reference - Array Type Processing


Star Follow @symisc

Syntax

int libcox_array_walk(

      libcox_value *pArray,

      int (*xWalk)(libcox_value *pEntry,void *pUserData),

      void *pUserData

);


Iterate over the elements of a given array and invoke the supplied callback for each entry.

Description

This routine iterate over the elements of a given array and invokes the supplied walker callback for each entry. The first argument (pArray) must be of type array obtained by a prior successful call to libcox_context_new_array() or passed as parameter to the foreign command. Otherwise, this routine return immediately and the walk process could not be done.

The most interesting parameter is the walker callback (xWalk()) which is a user defined function that is invoked for each array entry. The callback must accept two arguments. The first argument is the entry value which could be any type even others arrays and the last argument is a copy of the third argument to this function which is forwarded verbatim by engine.

The callback must return LIBCOX_OK. Otherwise the walk process is aborted and this function return LIBCOX_ABORT.

The entry value could be extracted inside the callback using these interfaces:

libcox_value_to_int()
libcox_value_to_bool()
libcox_value_to_int64()
libcox_value_to_double()
libcox_value_to_string()


Note: This routine is not thread-safe.


Parameters

pArray

libcox_value to iterate over which must be of type array.

xWalk

Walker callback which is invoked for each array entry. If the callback wishes to abort the walk process, it must return a value different from LIBCOX_OK such as LIBCOX_ABORT.

pUserData

Arbitrary user pointer which is forwarded verbatim by the engine to the walker callback as its third argument.


Return value

LIBCOX_OK is returned on success. Any other return value typically (LIBCOX_ABORT) indicates failure.


See also

libcox_array_next_elem, libcox_array_insert, libcox_array_fetch.