Difference between revisions of "Foreach"
→See Also
imported>Odessa (entries are 'stringmap' not 'map' artays) |
imported>Odessa |
||
(5 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
Added by NVSE 4. Used to repeat a script block for each entry in a collection. The collection may be either a container, [[Array Variable|array]] or [[String Variable|string]]. This can be a good alternative to using [[while]] or [[goto]] because it avoids infinite loop crash mistakes. However, be wary altering the size of the collection within the loop, as this may result in unexpected behavior. | |||
Within foreach loops, the command | Within foreach loops, the command <b>continue</b> may be used to skip any remaining loop code for that entry, and move on to the next. In the same context, the command <b>break</b> may be used to end the loop immediately, ignoring any remaining code and entries. | ||
==Syntax and Usage== | |||
In the case of a container, an entry is a temporary reference to an item in its inventory. This means it may be used as a [[calling reference]], but becomes invalid once the loop ends. (See also: [[GetInvRefsForItem]], [[CopyIR]], [[RemoveMeIR]], [[IsEquipped]]). | |||
<pre> | <pre> | ||
array_var | ref Item | ||
array_var | ref Container | ||
foreach Item:tempref <- Container:ref | |||
; Item is a temporary reference to an item in the container | |||
loop | |||
</pre> | |||
For an [[Array Variable|array]], each entry is a stringmap with two fields, <b>"key"</b> and <b>"value"</b>. The key is the index of the entry in the collection (0, 1, 2... for regular list arrays). (Note: you can replace 'entry["value"]' with the shorthand '*entry', see [[NVSE Expressions]]) | |||
<pre> | |||
array_var Entry | |||
array_var Collection | |||
foreach | foreach Entry:array <- Collection:array | ||
; | ; Entry["key"] is the key (index) of each entry (0, 1, 2... for lists) | ||
; | ; Entry["value"] is the value of each entry in the array | ||
loop | |||
</pre> | |||
For a string, each entry is a string containing a single character. | |||
<pre> | |||
string_var Char | |||
string_var Source | |||
foreach Char:string <- Source:string | |||
; Char is a single character in String | |||
loop | loop | ||
</pre> | </pre> | ||
Line 31: | Line 36: | ||
==Example== | ==Example== | ||
<pre> | <pre> | ||
ref rItem | |||
ref rActor | |||
foreach rItem <- rActor | |||
if rItem.IsEquipped | |||
rItem.UnequipMe | |||
endif | |||
loop | |||
array_var | ; Will unequip all equipped items from rActor | ||
array_var | </pre> | ||
<pre> | |||
array_var Beatles | |||
array_var Entry | |||
ref rMusician | ref rMusician | ||
int iPosition | int iPosition | ||
let | let Beatles := ar_List JohnREF, PaulREF, GeorgeREF, RingoREF | ||
foreach | foreach Entry <- Beatles | ||
let iPosition := | let iPosition := Entry["key"] | ||
let rMusician := | let rMusician := Entry["value"] | ||
Print "Entry #" + $iPosition + " is " + $rMusician | |||
loop | loop | ||
; Will print in game: | ; Will print in game: | ||
; Entry 0 is John Lennon | ; Entry #0 is John Lennon | ||
; Entry 1 is Paul McCartney | ; Entry #1 is Paul McCartney | ||
; Entry 2 is George Harrison | ; Entry #2 is George Harrison | ||
; Entry 3 is Ringo Starr | ; Entry #3 is Ringo Starr | ||
</pre> | </pre> | ||
Using <b>continue</b>: | |||
<pre> | <pre> | ||
foreach Entry <- Beatles | |||
let rMusician := Entry["value"] | |||
foreach | |||
let rMusician := | |||
if rMusician.GetDead | if rMusician.GetDead | ||
continue ; * Go direct to next entry: we ignore dead members | continue ; * Go direct to next entry: we ignore dead members | ||
endif | endif | ||
rMusician.AddItem Beer 1 | rMusician.AddItem Beer, 1 | ||
loop | loop | ||
; Every living member of the Beatles is given a beer | ; Every living member of the Beatles is given a beer | ||
</pre> | </pre> | ||
Using <b>break</b>: | |||
<pre> | <pre> | ||
foreach Entry <- Beatles | |||
let rMusician := Entry["value"] | |||
foreach | if rMusician.GetInWorldSpace Liverpool | ||
let rMusician := | rMusician.AddItem Beer, 1 | ||
if rMusician.GetInWorldSpace Liverpool | else | ||
break ; * End Loop immediately if we find a member is not in Liverpool | break ; * End Loop immediately if we find a member is not in Liverpool | ||
endif | endif | ||
loop | loop | ||
; Give a beer to each member of the Beatles until one is found not to be in Liverpool- assume that all Beatles except Paul are in Liverpool; since Paul is the second entry of the array, only John, the first, gets a beer. | ; Give a beer to each member of the Beatles until one is found not to be in Liverpool- assume that all Beatles except Paul are in Liverpool; since Paul is the second entry of the array, only John, the first, gets a beer. | ||
</pre> | |||
You can also use the [[Ar_Range]] command to approximate the traditional 'C' style for loop. The code below prints the numbers 0-10: | |||
<pre> | |||
foreach Entry <- (Ar_Range 0, 10) | |||
Print $Entry["value"] | |||
loop | |||
</pre> | </pre> | ||
Note that above we reference <b>Entry["value"]</b> in the [[Print]] function directly, rather than use an intermediary variable (<b>let SomeVar := Entry["value"]..</b>). This is only possible when using NVSE aware functions or the [[Script Compiler Override]]. | |||
= | |||
==See Also== | ==See Also== | ||
*[[While]] | |||
*[[Array Variables]] | *[[Array Variables]] | ||
*[[Let]] | *[[Let]] | ||
*[[Eval]] | *[[Eval]] | ||
*[[Label]] | *[[Label]]/[[Goto]] | ||
*[[ | *[[GetListForms]] (converts a form list to an array, so you can use foreach with it) | ||
*[[NVSE Expressions]] | |||
==External Links== | |||
*[http://obse.silverlock.org/obse_command_doc.html#OBSE_Expressions List of supported expression found in OBSE, these are equivalent in NVSE] | |||
*[http://fallout.bethsoft.com/eng/links/privacyredirect.php?site=http://www.loverslab.com/topic/26749-tutorial-nvse4-part-1-syntax-and-expressions/ Tutorial on syntax and expressions in NVSE 4] (this link requires pre-setting user details for this site) | |||
[[Category:Functions_(NVSE)]] | [[Category:Functions_(NVSE)]] | ||
[[Category:Commands]] | [[Category:Commands]] | ||
[[Category:Scripting]] | [[Category:Scripting]] |