====FOR====

===Parameters===

^Order^Name^Type^Desc^
|1|count|[[const|const]]|The number of items to read from the stack|
|2|func|[[function|function]]|The function to execute for every item in the list|

===Returns===

Copies the stack from every call to  //func// is run onto the stack, followed by a single [[const|const]] with the number of items added.

===Description===

This command runs the //func// function for the previous //count// lines on the stack. 

This command is mainly used if you want to return data that is broken up on a per-item basis rather than as a whole.

This command is very similar to [[fEACH]], except this function iterates through items on the //stack// rather than through a list.

When the //func// function is run, the **index** element (the item you're iterating into) is set as the 'index' variable, and is placed as the first element of the stack.

Note that the behaviour of [[fGET]] and [[fSET]] is slightly different when in the //FOR// loop. Calling **set** will only set a value for the nested function - you can't set values that will be accessible to the calling function.

However, //GET// can access information stored by //any function in the calling hierarchy//.

===Example===

To demonstrate the function, let's look at a simple example. 

**'Alpha' [[fASSET]] 'Beta' [[fASSET]] 'Gamma' [[fASSET]] [[fRELS]]** will return a single list of relationships that are present on //any// of the three assets. This might be useful in some scenarios, but we'd like to know which relationships are present in the individual assets.

We could do this by doing the same basic function three times...

**'Alpha' [[fASSET]] [[fRELS]] 'Beta' [[fASSET]] [[fRELS]] 'Gamma' [[fASSET]] [[fRELS]]** would do the job, as it would return three distinct lists, one for FOR asset. But we need to know FOR of the asset names before-hand, and it would be painful for large lists.

**'Alpha' [[fASSET]] 'Beta' [[fASSET]] 'Gamma' [[fASSET]] [[fSTACKCOUNT]] [ [[fRELS]] ] FOR** will run the function in the square brackets (RELS) for every item in the list returned by //ASSET//. 

To walk through the process...

When 'FOR' is called, the stack looks like this...

^Main Stack^Sub-Stack^
|[Asset List] Alpha - Beta - Gamma| | 
|[Function] RELS| |

Now, 'FOR' consumes the asset list and the function itself, resulting in an empty stack.

^Main Stack^Sub-Stack^
| | |

The //func// function has an independent stack, that initially contains the item from the list as the first item in the stack.

^Main Stack^Sub-Stack^
|[Empty]|[Asset List] Alpha|
| |[Command] RELS|

The [[fRELS]] command is executed, resulting in a list of relationships being added.

^Main Stack^Sub-Stack^
| |[Relationship List] Location, Profile, Water, 240VAC|

Now that the function is complete, the list is copied onto the **main** stack.

^Main Stack^
|[Relationship List] Location, Profile, Water, 240VAC|

This continues for all three items in the asset list, after which a constant is added that gives the total number of items processed (similar to the [[fCOUNT]] function).

^Main Stack^
|[Relationship List] Location, Profile, Water, 240VAC|
|[Relationship List] Location, Profile, 240VAC|
|[Relationship List] Location, Profile, Control, Hydraulic Pressure, 240VAC|
|[Const] 3|

To make your results clearer, you can use the [[fNAME]] function to apply names to your returned stack items.

**('Alpha', 'Beta', 'Gamma') [[fASSET]] [ [[fRELS]] 'index' [[fGET]] [[fNAME]] ] FOR**

===See Also===

[[fEACH]] \\
[[fNAME]] \\
[[fSTACKCOUNT]] \\