For...Next Statement (Visual Basic)
Repeats a group of statements a specified number of times.
For counter [ As datatype ] = start To end [ Step step ]
[ statements ]
[ Continue For ]
[ statements ]
[ Exit For ]
[ statements ]
Next [ counter ]
Parts
Part |
Description |
counter |
Required in the For statement. Numeric variable. The control variable for the loop. For more information, see Counter Argument later in this topic. |
datatype |
Optional. Data type of counter. For more information, see Counter Argument later in this topic. |
start |
Required. Numeric expression. The initial value of counter. |
end |
Required. Numeric expression. The final value of counter. |
step |
Optional. Numeric expression. The amount by which counter is incremented each time through the loop. |
statements |
Optional. One or more statements between For and Next that run the specified number of times. |
Continue For |
Optional. Transfers control to the next loop iteration. |
Exit For |
Optional. Transfers control out of the For loop. |
Next |
Required. Terminates the definition of the For loop. |
Note
The To keyword is used in this topic to specify the range for the counter. You can also use this keyword in the Select...Case Statement (Visual Basic) and in array declarations. For more information about array declarations, see Dim Statement (Visual Basic).
Simple Examples
You use a For...Next structure when you want to repeat a set of statements a set number of times.
In the following example, the index variable starts with a value of 1 and is incremented with each iteration of the loop, ending after the value of index reaches 5.
For index As Integer = 1 To 5
Debug.Write(index.ToString & " ")
Next
Debug.WriteLine("")
' Output: 1 2 3 4 5
In the following example, the number variable starts at 2 and is reduced by 0.25 on each iteration of the loop, ending after the value of number reaches 0. The Step argument of -.25 reduces the value by 0.25 on each iteration of the loop.
For number As Double = 2 To 0 Step -0.25
Debug.Write(number.ToString & " ")
Next
Debug.WriteLine("")
' Output: 2 1.75 1.5 1.25 1 0.75 0.5 0.25 0
Tip
A While...End While Statement (Visual Basic) or Do...Loop Statement (Visual Basic) works well when you don't know in advance how many times to run the statements in the loop. However, when you expect to run the loop a specific number of times, a For...Next loop is a better choice. You determine the number of iterations when you first enter the loop.
Nesting Loops
You can nest For loops by putting one loop within another. The following example demonstrates nested For...Next structures that have different step values. The outer loop creates a string for every iteration of the loop. The inner loop decrements a loop counter variable for every iteration of the loop.
For indexA = 1 To 3
' Create a new StringBuilder, which is used
' to efficiently build strings.
Dim sb As New System.Text.StringBuilder()
' Append to the StringBuilder every third number
' from 20 to 1 descending.
For indexB = 20 To 1 Step -3
sb.Append(indexB.ToString)
sb.Append(" ")
Next indexB
' Display the line.
Debug.WriteLine(sb.ToString)
Next indexA
' Output:
' 20 17 14 11 8 5 2
' 20 17 14 11 8 5 2
' 20 17 14 11 8 5 2
When nesting loops, each loop must have a unique counter variable.
You can also nest different kinds control structures within each other. For more information, see Nested Control Structures (Visual Basic).
Exit For and Continue For
The Exit For statement immediately exits the For…Next loop and transfers control to the statement that follows the Next statement.
The Continue For statement transfers control immediately to the next iteration of the loop. For more information, see Continue Statement (Visual Basic).
The following example illustrates the use of the Continue For and Exit For statements.
For index As Integer = 1 To 100000
' If index is between 5 and 7, continue
' with the next iteration.
If index >= 5 And index <= 8 Then
Continue For
End If
' Display the index.
Debug.Write(index.ToString & " ")
' If index is 10, exit the loop.
If index = 10 Then
Exit For
End If
Next
Debug.WriteLine("")
' Output: 1 2 3 4 9 10
You can put any number of Exit For statements in a For…Next loop. When used within nested For…Next loops, Exit For exits the innermost loop and transfers control to the next higher level of nesting.
Exit For is often used after you evaluate some condition (for example, in an If...Then...Else structure). You might want to use Exit For for the following conditions:
Continuing to iterate is unnecessary or impossible. An erroneous value or a termination request might create this condition.
A Try...Catch...Finally statement catches an exception. You might use Exit For at the end of the Finally block.
You have an endless loop, which is a loop that could run a large or even infinite number of times. If you detect such a condition, you can use Exit For to escape the loop. For more information, see Do...Loop Statement (Visual Basic).
Technical Implementation
When a For...Next loop starts, Visual Basic evaluates start, end, and step. Visual Basic evaluates these values only at this time and then assigns start to counter. Before the statement block runs, it compares counter to end. If counter is already larger than the end value (or smaller if step is negative), the For loop ends and control passes to the statement that follows the Next statement. Otherwise, the statement block runs.
Each time that Visual Basic encounters the Next statement, it increments counter by step and returns to the For statement. Again it compares counter to end, and again it either runs the block or exits the loop, depending on the result. This process continues until counter passes end or an Exit For statement is encountered.
The loop doesn't stop until counter has passed end. If counter is equal to end, the loop continues. The comparison that determines whether to run the block is counter <= end if step is positive and counter >= end if step is negative.
If you change the value of counter while inside a loop, your code might be more difficult to read and debug. Changing the value of start, end, or step doesn't affect the iteration values that were determined when the loop was first entered.
If you nest loops, the compiler signals an error if it encounters the Next statement of an outer nesting level before the Next statement of an inner level. However, the compiler can detect this overlapping error only if you specify counter in every Next statement.
Step Argument
The value of step can be either positive or negative. This parameter determines loop processing according to the following table:
Step value |
Loop executes if |
Positive or zero |
counter <= end |
Negative |
counter >= end |
The default value of step is 1.
Counter Argument
The following table indicates whether counter defines a new local variable that’s scoped to the entire For…Next loop. This determination depends on whether datatype is present and whether counter is already defined.
The datatype is present. |
A counter variable is already defined. |
Counter defines a new local variable that’s scoped to the entire For...Next loop. |
|---|---|---|
No |
Yes |
No. Counter is the variable that's already defined. If the scope of counter isn't local to the procedure, a compile-time warning occurs. |
No |
No |
Yes. The data type is inferred from the start, end, and step expressions. For information about type inference, see Option Infer Statement and Local Type Inference (Visual Basic). |
Yes |
Yes |
Yes, but only if the existing counter variable is defined outside the procedure. That separately defined counter variable remains as a separate variable. If the existing counter variable is defined local to the procedure, a compile-time error occurs. |
Yes |
No |
Yes. |
The data type of counter determines the type of the iteration, which must be one of the following types:
A Byte, SByte, UShort, Short, UInteger, Integer, ULong, Long, Decimal, Single, or Double.
An enumeration that you declare by using an Enum Statement (Visual Basic).
An Object.
A type T that has the following operators, where B is a type that can be used in a Boolean expression.
Public Shared Operator >= (op1 As T, op2 As T) As B
Public Shared Operator <= (op1 As T, op2 As T) As B
Public Shared Operator - (op1 As T, op2 As T) As T
Public Shared Operator + (op1 As T, op2 As T) As T
You can specify counter in the Next statement. This syntax improves the readability of your program, especially if you have nested For loops. You must specify the variable that appears in the corresponding For statement.
The start, end, and step expressions can evaluate to any data type that widens to the type of counter. If you use a user-defined type for counter, you might have to define the CType conversion operator to convert the types of start, end, or step to the type of counter.
Example
The following example removes all elements from a generic list. Instead of a For Each...Next Statement (Visual Basic), the example shows a For...Next statement that iterates in descending order. The example uses this technique because the removeAt method causes elements after the removed element to have a lower index value.
Dim lst As New List(Of Integer) From {10, 20, 30, 40}
For index As Integer = lst.Count - 1 To 0 Step -1
lst.RemoveAt(index)
Next
Debug.WriteLine(lst.Count.ToString)
' Output: 0
The following example iterates through an enumeration that's declared by using an Enum Statement (Visual Basic).
Public Enum Mammals
Buffalo
Gazelle
Mongoose
Rhinoceros
Whale
End Enum
Public Sub ListSomeMammals()
For mammal As Mammals = Mammals.Gazelle To Mammals.Rhinoceros
Debug.Write(mammal.ToString & " ")
Next
Debug.WriteLine("")
' Output: Gazelle Mongoose Rhinoceros
End Sub
In the following example, the statement parameters use a class that has operator overloads for the +, -, >=, and <= operators.
Private Class Distance
Public Property Number() As Double
Public Sub New(ByVal number As Double)
Me.Number = number
End Sub
' Define operator overloads to support For...Next statements.
Public Shared Operator +(ByVal op1 As Distance, ByVal op2 As Distance) As Distance
Return New Distance(op1.Number + op2.Number)
End Operator
Public Shared Operator -(ByVal op1 As Distance, ByVal op2 As Distance) As Distance
Return New Distance(op1.Number - op2.Number)
End Operator
Public Shared Operator >=(ByVal op1 As Distance, ByVal op2 As Distance) As Boolean
Return (op1.Number >= op2.Number)
End Operator
Public Shared Operator <=(ByVal op1 As Distance, ByVal op2 As Distance) As Boolean
Return (op1.Number <= op2.Number)
End Operator
End Class
Public Sub ListDistances()
Dim distFrom As New Distance(10)
Dim distTo As New Distance(25)
Dim distStep As New Distance(4)
For dist As Distance = distFrom To distTo Step distStep
Debug.Write(dist.Number.ToString & " ")
Next
Debug.WriteLine("")
' Output: 10 14 18 22
End Sub
See Also
Reference
While...End While Statement (Visual Basic)
Do...Loop Statement (Visual Basic)