For Each…Next

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

Syntax:

For Each element [ As type ] In group
     [ statements ]
     [ Continue For | Exit For ]
     [ statements ]
Next [ element ]

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.
type: optional A type used to declare element.
When present it is equivalent to placing Dim element As type immediately before the For Each statement.
group: Name of an object collection or array (except an array of user-defined types (UDTs)).
statements: optional One or more statements that are executed on each item in group.
Continue For: optional Immediately skips remaining statements and begins next iteration, or exits the loop if no more iterations remain.
Continue For is often used after evaluating some condition, for example If…Then.
Exit For: optional Immediately exits the body of the loop.
Exit For is often used after evaluating some condition, for example If…Then, and transfers control to the statement immediately following Next.

The For…Each block is entered if there is at least one element in group. After the loop has been entered, all the statements in the loop are executed for the first element in group. If 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.

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

Note

When element is omitted in a Next statement, execution continues as if element is included. If a Next statement is encountered before its corresponding For statement, an error occurs.

The For…Each…Next statement cannot be used with an array of user-defined types because a Variant can’t contain a user-defined type.

An object of a class can be the group when the class has a member marked [Enumerator] that supplies an enumerator. See Custom Enumerators for how to write one.

Warning

In BETA 1005, a For Each that cannot get an enumerator from group never ends when it runs under On Error Resume Next, or under an error handler that ends with Resume Next. That happens when group is Nothing, an object of a class with no [Enumerator] member, or an object whose [Enumerator] member returns Nothing or raises an error. The error resumes into the loop body, and Next raises error 91 and goes back to the body, again and again. Test group before the loop. VB6 runs the body once, then raises error 92 at Next, and the loop ends.

Example

This example uses the For Each…Next statement to search the Text property of all elements in a collection for the existence of the string “Hello”. In the example, MyObject is a text-related object and is an element of the collection MyCollection. Both are generic names used for illustration purposes only.

Dim Found, MyObject, MyCollection 
Found = False         ' Initialize variable. 
For Each MyObject In MyCollection    ' Iterate through each element.  
  If MyObject.Text = "Hello" Then    ' If Text equals "Hello". 
    Found = True      ' Set Found to True. 
    Exit For          ' Exit loop. 
  End If 
Next