the Fallout3 GECK Wiki

Editing Foreach

Warning: You are not logged in. Your IP address will be publicly visible if you make any edits. If you log in or create an account, your edits will be attributed to your username, along with other benefits.

The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then publish the changes below to finish undoing the edit.

Latest revision Your text
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.
{{Function
|origin = NVSE
|summary = Added by NVSE V4. Used to repeat a script block for each entry in an array. Each entry is itself a [[Array Variables|stringmap array]] with two fields, "key" and "value".


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 'continue' may be used to skip any remaining loop code for that entry, and move on to the next. In the same context, the command 'break' may be used to end the loop immediately, ignoring any remaining code and entries.


==Syntax and Usage==
|name = Foreach
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]]).
|returnType = void
|arguments =
  {{FunctionArgument
  |Name = entry
  |Type = array{{FunctionArgument
  |Name = <-
  |Type =
  }}
  }}{{FunctionArgument
  |Name = set
  |Type = array
  }}
}}
<pre>
<pre>
ref Item
array_var aSomeArray
ref Container
array_var aEntry
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 Entry:array <- Collection:array
foreach aEntry <- aSomeArray
     ; Entry["key"] is the key (index) of each entry (0, 1, 2... for lists)
     ; aEntry["key"] is the key of each entry in the array (0, 1, 2... for lists)
     ; Entry["value"] is the value of each entry in the array
     ; aEntry["value"] is 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 36: Line 31:
==Example==
==Example==
<pre>
<pre>
ref rItem
ref rActor
foreach rItem <- rActor
  if rItem.IsEquipped
        rItem.UnequipMe
  endif
loop


; Will unequip all equipped items from rActor
array_var aBeatles
</pre>
array_var aEntry
 
<pre>
array_var Beatles
array_var Entry
ref rMusician
ref rMusician
int iPosition
int iPosition


let Beatles := ar_List JohnREF, PaulREF, GeorgeREF, RingoREF
let aBeatles := ar_List JohnREF, PaulREF, GeorgeREF, RingoREF


foreach Entry <- Beatles
foreach aEntry <- aBeatles
     let iPosition := Entry["key"]
     let iPosition := aEntry["key"]
     let rMusician := Entry["value"]
     let rMusician := aEntry["value"]
     Print "Entry #" + $iPosition + " is " + $rMusician
     PrintC "Entry %g is %n", iPosition, 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>
<pre>
; Using Continue


Using <b>continue</b>:
foreach aEntry <- aBeatles
<pre>
     let rMusician := aEntry["value"]
foreach Entry <- Beatles
     let rMusician := Entry["value"]
     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>
<pre>
; Using Break


Using <b>break</b>:
foreach aEntry <- aBeatles
<pre>
     let rMusician := aEntry["value"]
foreach Entry <- Beatles
     if rMusician.GetInWorldSpace Liverpool == 0
     let rMusician := Entry["value"]
     if rMusician.GetInWorldSpace Liverpool
        rMusician.AddItem Beer, 1
    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
    rMusician.AddItem Beer 1
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>
</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:
==Notes==
<pre>
*This page may not be comprehensive, refer to external documentation for further information.
foreach Entry <- (Ar_Range 0, 10)
    Print $Entry["value"]
loop
</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]]
*[[While]]
*[[Eval]]
*[[Eval]]
*[[Label]]/[[Goto]]
*[[Label]]
*[[GetListForms]] (converts a form list to an array, so you can use foreach with it)
*[[Goto]]
*[[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]]

Please note that all contributions to the Fallout3 GECK Wiki are considered to be released under the Creative Commons Attribution-ShareAlike (see GECK:Copyrights for details). If you do not want your writing to be edited mercilessly and redistributed at will, then do not submit it here.
You are also promising us that you wrote this yourself, or copied it from a public domain or similar free resource. Do not submit copyrighted work without permission!

Cancel Editing help (opens in new window)
Retrieved from "https://geck.uesp.net/wiki/Foreach"