[Pawn] YSI Daily Tips

[Y_Less]

2021-05-21: Pass An Iterator As A Parameter



Sometimes you want to pass an iterator to a function.? Iterators are often global, but they don't have to be, and there are still times when you might want them as generic parameters.? There's no simple way to do this, it wasn't really a design consideration, but it is possible.



Under the hood an iterator is two variables - an array containing the data, and a single variable containing the count (the count is also an array for multi-iterators).? For the iterator Player these are called Iterator@Player and Iter_Count@Player (so you get vaguely readable warnings).? Thus, to receive an iterator in a function as use it within that function you need the following two parameters:

MyFunction(Iterator@iter[MAX_PLAYERS 1], Iter_Count@iter)

{

____foreach (new i : iter)

____{

____}

}

You can't use the `Iterator:` macro for this, because it also generates initialisation code, but you could create your own.? The size is %1 1 to hold some internal data.? This does mean you have to know what size of iterator you want to pass in advance, because currently foreach uses sizeof a lot internally.? This might be fixable, but isn't currently:

#define IterParam:%0<%1> Iterator@%0[%1 1], Iter_Count@%0



MyFunction(IterParam:iter<MAX_PLAYERS>)

{

____foreach (new i : iter)

____{

____}

}

With this code, PASSING the iterator is again fairly straightforward:

main()

{

____MyFunction(Iterator@Player, Iter_Count@Player);

}

But we've just changed one nice parameter in to two horrible parameters.? Fortunately the calling side of things is far better defined (since the y_iterate) API functions like Iter_Add already take plain iterators as parameters.? The functions might not be defined nicely, but they can be called nicely.? The macro for this is _ITER, which does all the work detecting which type of iterator was passed (normal or multi), the size and start, and calls an InternalA or InternalB version of another macro depending on normal- or multi-:

#define MyFunction _ITER<MyFunction>

#define Iter_MyFunction_InternalA(%0,%1)? ? MyFunction_(_:%1,%0)

#define Iter_MyFunction_InternalB(%0,%2,%1) MyFunction_(_:%1,%0)

This renames MyFunction to MyFunction_, then defines MyFunction as a macro that takes an iterator.? InternalA has two parameters given - the count and array.? InternalB has three parameters given - the count, the start, and the array.? If you want to pass the size of the iterator it's F@s(%1)-F@s(%0).? You can also just call your function? Iter_MyFunction_InternalA and you don't need the extra macros.? If your function takes more parameters after the iterator, they are all passed to the macros/functions in an additional %9 at the end of the parameter list.



Now the call is very simply:

main()

{

____MyFunction(Player);

}