ForEach loop - Revision history

Wormbo: Undo revision 44119 by 82.73.101.51 (Talk) - That's actually how you log stuff in UE3

2010-11-14T20:53:24Z

Undo revision 44119 by 82.73.101.51 (Talk) - That's actually how you log stuff in UE3

82.73.101.51: /* Examples */

2010-11-14T12:54:06Z

‎Examples

Eliot: /* Examples */ Fixed example

2010-04-22T05:07:23Z

‎Examples: Fixed example

Wormbo: added pitfalls

2008-10-23T14:00:07Z

added pitfalls

Wormbo: New page: The '''ForEach''' loop in UnrealScript can be used to iterate over the output of iterator functions. Additionally, Unreal Engine 3 provides a special versio...

2008-10-11T13:41:14Z

New page: The '''ForEach''' loop in UnrealScript can be used to iterate over the output of iterator functions. Additionally, Unreal Engine 3 provides a special versio...

New page

The '''ForEach''' loop in [[UnrealScript]] can be used to iterate over the output of [[#Iterator functions|iterator functions]]. Additionally, [[Unreal Engine 3]] provides a special version of '''ForEach''' that iterates over the elements of a [[dynamic array]].

==Syntax==
The general syntax of the regular '''ForEach''' loop is:
'''ForEach''' ''iteratorfunction'''''('''''parameters''''') {'''
...
'''}'''
The first two parameters of iterator functions are always a parameter of a [[class limiter]] type and an ''out'' parameter of the same type as the first parameter's meta class, for example <code>class<Actor></code> and <code>Actor</code> respectively. Through special compiler "magic", the accepted type of variables for the second parameter is further limited if the first parameter specifies a subclass of the declared meta class. (see [[#Examples|examples]] below for details)

The special syntax for dynamic array in [[Unreal Engine 3]] is:
'''ForEach''' ''dynarray'''''('''''valuevariable''''') {'''
...
'''}'''
If the ''dynarray'' variable is of [[type]] <code>array<X></code>, the ''valuevariable'' must be declared as type <code>X</code>.

If you also need access the the array index corresponding to the current value, use:
'''ForEach''' ''dynarray'''''('''''valuevariable''''',''' ''indexvariable''''') {'''
...
'''}'''
The ''indexvariable'' must be declared as type [[int]].

==Iterator functions==
Iterator functions, or "iterators" for short, are native [[functions]] that have been declared with the special modifier ''iterator''. Iterators must be native and don't have a return value. They can only be called as part of a '''ForEach''' loop and usually have at least one ''out'' parameter.

A typical iterator function takes a class value as its first parameter and an object variable as its second parameter, which is defined with the modifier ''out''. Most iterator functions have more than two parameters, some of them also declared as ''out'', but most of them are optional.

A typical example is the VisibleCollidingActors function in the Actor class:
{{code|native(312) final iterator function '''VisibleCollidingActors'''(class<actor> '''BaseClass''', out actor '''Actor''', optional float '''Radius''', optional vector '''Loc''', optional bool '''bIgnoreHidden''');}}

==Examples==
A typical iterator function call might look like this example:
<uscript>
function PokeTriggersFor(Pawn Other)
local Trigger T;

if (Other == None)
return; // ForEach doesn't handle Accessed None gracefully!

foreach Other.RadiusActors(class'Trigger', T, 100.0) {
T.Touch(Other);
}
}
</uscript>
This example shows various features of using iterator functions in a '''ForEach''' loop:
* You can access iterators of other objects than the one containing the code. Just make sure you don't access the iterator function though ''None'' – before Unreal Engine 3 the game will crash mercilessly with a cryptic error message in that case! In this example an [[If statement]] performs a ''None'' check before the iterator is executed.
* If you specify a specific class as the first parameter, the second parameter must be of the same type. It would actually be a compiler error if the local [[variable]] ''T'' was declared as type <code>Actor</code>.

The array iterators of [[Unreal Engine 3]] are straight forward to use. The following example iterates over the [[UE3:Actor internal variables (UT3)#GeneratedEvents|GeneratedEvents]] array of the Actor containing this piece of code:
<uscript>
function IterateEvents()
{
local SequenceEvent E;

foreach GeneratedEvents(E) {
`log(E);
}
}
</uscript>
Like in the previous example, you can also iterate over dynamic arrays in other objects. Just remember to perform a check for ''None'' first to prevent log warnings.

{{navbox unrealscript}}

@@ Line 54: / Line 54: @@
    foreach GeneratedEvents(E) {
-     log(E);
+     `log(E);
+   }
+}

@@ Line 32: / Line 32: @@
 <uscript>
 function PokeTriggersFor(Pawn Other)
    local Trigger T;

@@ Line 58: / Line 58: @@
 </uscript>
 Like in the previous example, you can also iterate over dynamic arrays in other objects. Just remember to perform a check for ''None'' first to prevent log warnings.
 {{navbox unrealscript}}