For Each...Next

Repeats a group of statements for each element in an array or collection.

Synopsis

For Each element In group
    [statements]
    [Exit For]
    [statements]
Next [element]

Arguments

The For Each...Next statement syntax has these parts:

element	Variable used to iterate through the elements of the collection or array. For collections, element can only be a Variant variable, a generic Object variable, or any specific object variable. For arrays, element can only be a Variant variable.
group	Name of an object collection or array.
statement	One or more statements that are executed on each item in group.

Description

The For Each block is entered if there is at least one element in group. Once the loop has been entered, all the statements in the loop are executed for the first element in group. As long as there are more elements in group, the statements in the loop continue to execute for each element. When there are no more elements in group, the loop is exited and execution continues with the statement following the Next statement.

The Exit For can only be used within a For Each...Next or For...Next control structure to provide an alternate way to exit. Any number of Exit For statements may be placed anywhere in the loop. The Exit For is often used with the evaluation of some condition (for example, If...Then), and transfers control to the statement immediately following Next.

You can nest For Each...Next loops by placing one For Each...Next loop within another. However, each loop element must be unique.

For Each and the Split Function

A Split function cannot be directly used as the group argument of a For Each...Next statement. You must first assign the Split return value to an array variable. You can then specify this array variable as the group argument of the For Each...Next statement.

Examples

The following example illustrates use of the For Each...Next statement:

Erase ^RandomData
 
' Generate some random nodes
For i =  65 to 90
  If Rnd(i) > .5 Then
    ^RandomData(Chr(i),"subnode")="data"
  Else
    ^RandomData(Chr(i))="data"
  End If
Next
 
PrintLn "Traverse forwards"
 
For each k1 in ^RandomData
  PrintLn k1
  For each k2 in ^RandomData(k1)
    Print k1,vbTAB,k2
    If Exists(^RandomData(k1,k2)) and vbHasValue Then
      Print " = ",^RandomData(k1,k2)
    End If
    PrintLn
  Next
Next

Notes

If you omit element in a Next statement, execution continues as if you had included it. If a Next statement is encountered before its corresponding For statement, an error occurs.