foreach - MethodScript

== foreach ==

Walks through array, setting ivar equal to each element in the array, then running code. In addition, foreach(1..4, @i, code()) is also valid, setting @i to 1, 2, 3, 4 each time. The same syntax is valid as in an array slice. If key is set (it must be an ivariable) then the index of each iteration will be set to that. See the examples for a demonstration.

=== Vital Info === {| style="width: 40%;" cellspacing="1" cellpadding="1" border="1" class="wikitable" |- ! scope="col" width="20%" | ! scope="col" width="80%" | |- ! scope="row" | Name | foreach |- ! scope="row" | Returns | void |- ! scope="row" | Usages | array, [key], ivar, code |- ! scope="row" | Throws | [[../objects/ms.lang.CastException|ms.lang.CastException]]
[[../objects/ms.lang.RangeException|ms.lang.RangeException]] |- ! scope="row" | Since | 3.0.1 |- ! scope="row" | Restricted |

|- ! scope="row" | Optimizations | None |}

Enhanced syntax may also be used in foreach, using the "in", "as" and "else" keywords. See the examples for examples of each structure. Using these keywords makes the structure of the foreach read much better. For instance, with foreach(@value in @array){ } the code very literally reads "for each value in array", making ascertaining the behavior of the loop easier. The "as" keyword reads less plainly, and so is not recommended for use, but is allowed. Note that the array and value are reversed with the "as" keyword. An "else" block may be used after the foreach, which will only run if the array provided is empty, that is, the loop code would never run. This provides a good way to provide "default" handling. Array modifications while iterating are supported, and are well defined. See [[Array_iteration|the page documenting array iterations]] for full details.

=== Usages ===

foreach(array, [key], ivar, code)

=== Examples === ====Example 1==== Using "in" keyword Given the following code:

@array = array(1, 2, 3);
foreach(@value in @array){
	msg(@value);
}
 Copy Code
1   @array = {{function|array}}(1, 2, 3);
2   {{keyword|foreach}}(@value {{keyword|in}} @array){
3     {{function|msg}}(@value);
4   }

The output would be:

1
2
3

====Example 2==== Using "in" keyword, with a key Given the following code:

@array = array(1, 2, 3);
foreach(@key: @value in @array){
	msg(@key . ': ' . @value);
}
 Copy Code
1   @array = {{function|array}}(1, 2, 3);
2   {{keyword|foreach}}(@key: @value {{keyword|in}} @array){
3     {{function|msg}}(@key . ': ' . @value);
4   }

The output would be:

0: 1
1: 2
2: 3

====Example 3==== Using "as" keyword Given the following code:

@array = array(1, 2, 3);
foreach(@array as @value){
	msg(@value);
}
 Copy Code
1   @array = {{function|array}}(1, 2, 3);
2   {{keyword|foreach}}(@array {{keyword|as}} @value){
3     {{function|msg}}(@value);
4   }

The output would be:

1
2
3

====Example 4==== With else clause Given the following code:

@array = array() # Note empty array
foreach(@value in @array){
	msg(@value);
} else {
	msg('No values were in the array');
}
 Copy Code
1   @array = {{function|array}}() # Note empty array
2   
3   {{keyword|foreach}}(@value {{keyword|in}} @array){
4     {{function|msg}}(@value);
5   } {{keyword|else}} {
6     {{function|msg}}('No values were in the array');
7   }

The output would be:

No values were in the array

====Example 5==== Basic functional usage Given the following code:

assign(@array, array(1, 2, 3))
foreach(@array, @i,
	msg(@i)
)
 Copy Code
1   {{function|assign}}(@array, {{function|array}}(1, 2, 3))
2   {{keyword|foreach}}(@array, @i,
3     {{function|msg}}(@i)
4   )

The output would be:

1
2
3

====Example 6==== With braces Given the following code:

assign(@array, array(1, 2, 3))
foreach(@array, @i){
	msg(@i)
}
 Copy Code
1   {{function|assign}}(@array, {{function|array}}(1, 2, 3))
2   {{keyword|foreach}}(@array, @i){
3     {{function|msg}}(@i)
4   }

The output would be:

1
2
3

====Example 7==== With a slice Given the following code:

foreach(1..3, @i){
	msg(@i)
}
 Copy Code
1   {{keyword|foreach}}(1..3, @i){
2     {{function|msg}}(@i)
3   }

The output would be:

1
2
3

====Example 8==== With a slice, counting down Given the following code:

foreach(3..1, @i){
	msg(@i)
}
 Copy Code
1   {{keyword|foreach}}(3..1, @i){
2     {{function|msg}}(@i)
3   }

The output would be:

3
2
1

====Example 9==== With array keys Given the following code:

@array = array('one': 1, 'two': 2)
foreach(@array, @key, @value){
	msg(@key.':'.@value)
}
 Copy Code
1   @array = {{function|array}}('one': 1, 'two': 2)
2   {{keyword|foreach}}(@array, @key, @value){
3     {{function|msg}}(@key.':'.@value)
4   }

The output would be:

one:1
two:2

===See Also=== [[Loops|Learning Trail: Loops]], [[Array_Iteration|Learning Trail: Array Iteration]]

Find a bug in this page? Edit this page yourself, then submit a pull request. (Note this page is automatically generated from the documentation in the source code.)