REPY_FOREACH - Python Object Iteration Macros

Macros
#define	REPY_FOREACH_FNAC(iter_identifier, py_object)
	Iterate through a Python object, the way Python's for loops do.
#define	REPY_FOREACH(iter_identifier, py_object, auto_self_destuct)
	Iterate through a Python object, the way Python's for loops do.
#define	REPY_FOREACH_CLEANUP_NOW(iter_identifier)
	Manually clean up the REPY_IteratorHelper for a REPY_FOREACH loop.
#define	REPY_FOREACH_BREAK(iter_identifier)
	Manually clean up the REPY_IteratorHelper for a REPY_FOREACH loop, and immediately break.
#define	REPY_FOREACH_RETURN(iter_identifier, retType, retVal)
	Manually clean up the REPY_IteratorHelper for a REPY_FOREACH loop, and immediately return.

Detailed Description

A convienient way to iterate through a Python object in your C mod code.

Macro Definition Documentation

REPY_FOREACH

#define REPY_FOREACH	(		iter_identifier,
			py_object,
			auto_self_destuct )

Value:

for (REPY_IteratorHelper* iter_identifier = REPY_IteratorHelper_Create(py_object, REPY_NO_OBJECT, NULL, auto_self_destuct); REPY_IteratorHelper_Update(iter_identifier);)

Iterate through a Python object, the way Python's for loops do.

A REPY_IteratorHelper object is created to manage the iteration process. The current object of the loop can be accessed via REPY_IteratorHelper_BorrowCurrent, and the index of that object can be accessed via REPY_IteratorHelper_GetIndex. See the REPY_IteratorHelper documentation for more information.

REPY_IteratorHelper copies the py_object handle you pass in, so it's safe to release it of have it be Single-Use.

In this macro, REPY_IteratorHelper_Update is set to clean up the REPY_IteratorHelper automatically, once the iteration ends. Ergo, you only have to clean up if you end the loop early, such as through a break or a return. The macros REPY_FOREACH_CLEANUP_NOW, REPY_FOREACH_BREAK, and REPY_FOREACH_RETURN are provided to facillitate that. Failure to manually clean up the REPY_IteratorHelper when exiting the loop early will result in a memory leak.

Because this macro can be used outside of a REPY_FN scope, this macro cannot automatically add it to the auto-cleanup handler.

Parameters

iter_identifier	the variable name for the REPY_IteratorHelper pointer.
py_object	a REPY_Handle for the Python object to iterate through.
auto_self_destuct	whether or not this helper should destroy itself on the last REPY_IteratorHelper_Update call.

REPY_FOREACH_BREAK

#define REPY_FOREACH_BREAK

(

iter_identifier

)

Value:

REPY_FOREACH_CLEANUP_NOW(iter_identifier); break

Manually clean up the REPY_IteratorHelper for a REPY_FOREACH loop, and immediately break.

Parameters

iter_identifier

the REPY_IteratorHelper pointer.

REPY_FOREACH_CLEANUP_NOW

#define REPY_FOREACH_CLEANUP_NOW

(

iter_identifier

)

Value:

REPY_IteratorHelper_Destroy(iter_identifier)

Manually clean up the REPY_IteratorHelper for a REPY_FOREACH loop.

Once this had been called, you'll have a crash if you attempt another pass of the loop.

Parameters

iter_identifier

the REPY_IteratorHelper pointer.

REPY_FOREACH_FNAC

#define REPY_FOREACH_FNAC	(		iter_identifier,
			py_object )

Value:

for (REPY_IteratorHelper* iter_identifier = \
    REPY_DeferredCleanupHelper_AddIteratorHelper(REPY_FN_AUTO_CLEANUP, REPY_IteratorHelper_Create(py_object, REPY_NO_OBJECT, NULL, false)); \
    REPY_IteratorHelper_Update(iter_identifier); \
) \

Iterate through a Python object, the way Python's for loops do.

A REPY_IteratorHelper object is created to manage the iteration process. The current object of the loop can be accessed via REPY_IteratorHelper_BorrowCurrent, and the index of that object can be accessed via REPY_IteratorHelper_GetIndex. See the REPY_IteratorHelper documentation for more information.

REPY_IteratorHelper copies the py_object REPY_Handle you pass in, so it's safe to release it of have it be Single-Use.

Unlike REPY_FOREACH, this macro assumes that it's being called inside a REPY_FN scope, and therefore will use the scope's auto cleanup. That way, you don't need to worry about doing it yourself with the other macros in this section.

Parameters

iter_identifier	the variable name for the REPY_IteratorHelper pointer.
py_object	a REPY_Handle for the Python object to iterate through.

REPY_FOREACH_RETURN

#define REPY_FOREACH_RETURN	(		iter_identifier,
			retType,
			retVal )

Value:

retType __repy_retVal = retVal; \
REPY_FOREACH_CLEANUP_NOW(iter_identifier); \
return __repy_retVal

Manually clean up the REPY_IteratorHelper for a REPY_FOREACH loop, and immediately return.

Supports returning a value.

Parameters

iter_identifier

the REPY_IteratorHelper pointer.