====EACH====

===Parameters===

^Order^Name^Type^Desc^
|1|list|any|The list to iterate through|
|2|func|[[function|function]]|The function to execute for every item in the list|

===Returns===

The stacks returned from calling //func// on each item in the list , followed by a single [[const|const]] with the number of items added.

===Description===

This command runs the //func// function for every item in the //list// array. 

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 [[fFOR]], except this function iterates through a //list// rather than through the stack.

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 //each// 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//.

===Simple Example===

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

We have several machines that all share the same type - 'Pump House'.

We want to know what's inside them - but we want to know which assets belong to which pump-house.

Using **EACH**, we can do this.

First, we get all of the pump houses with the [[foftype|oftype]] function.

**'Pump House' [[fOFTYPE]]**

Next, we want to get a list of all of the assets //located// inside //each// of these pump houses.

We write the query we'd use to get the children of **one** of these items...

**'Location' [[fRELATIONSHIP]] 'downi' [[fRELATED]]**

...and then enclose it in square brackets, followed by the call to 'each'.

**'Pump House' [[fOFTYPE]] [ 'Location' [[fRELATIONSHIP]] 'downi' [[fRELATED]] ] EACH**

This will return a list containing **sublists** - one for each pump house.

===Complex Example===

**('Alpha', 'Beta', '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 each asset. But we need to know each of the asset names before-hand, and it would be painful for large lists.

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

To walk through the process...

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

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

Now, 'Each' 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]] ] EACH**

===See Also===

[[fFOR]]
[[fNAME]]