Difference between revisions of "Foreach"
→See Also
imported>Odessa (clarified and added external links) |
imported>Odessa |
||
| (4 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 <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. | 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> | |||
ref Item | |||
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> | <pre> | ||
array_var Entry | array_var Entry | ||
array_var Collection | |||
foreach Entry <- | foreach Entry:array <- Collection:array | ||
; Entry["key"] is the key (index) of each entry (0, 1, 2... for lists) | ; 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 | ; 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> | ||
==Example== | ==Example== | ||
<pre> | |||
ref rItem | |||
ref rActor | |||
foreach rItem <- rActor | |||
if rItem.IsEquipped | |||
rItem.UnequipMe | |||
endif | |||
loop | |||
; Will unequip all equipped items from rActor | |||
</pre> | |||
<pre> | <pre> | ||
array_var Beatles | array_var Beatles | ||
| Line 79: | Line 97: | ||
</pre> | </pre> | ||
You can also use the [[Ar_Range]] command to approximate the traditional 'C' style for loop. The code below | 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> | <pre> | ||
foreach | foreach Entry <- (Ar_Range 0, 10) | ||
Print $ | Print $Entry["value"] | ||
loop | 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== | ||
| Line 92: | Line 111: | ||
*[[Eval]] | *[[Eval]] | ||
*[[Label]]/[[Goto]] | *[[Label]]/[[Goto]] | ||
*[[GetListForms]] (converts a form list to an array, so you can use foreach with it) | |||
*[[NVSE Expressions]] | |||
==External Links== | ==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://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] | *[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]] | ||