I’m really impressed with .NET 2.0. We’ve all seen the big changes (ASP.NET WebParts, Improved DataGrids, Generics, etc.) I’m constantly finding a new improvement or little nugget of goodness when coding.
Help
Case in point. The MSDN help files. Everyone always makes jokes about how badly the MSDN .NET help are written. It seems that the help authors are listening. I was at a conference last summer and was surprised to find that one day in the ‘Mind meld with Microsoft’ session the room was filled with a team of help writers. There they were, probing the audience and asking serious questions about how we want the help engine to work.
This morning I was looking up a keyword in the help system and I started reading the For Each help page. Nicely done I thought. Below I’ve included the 1.1 and 2.0 versions of the For Each help page. See for yourself.
Help 1.1
Remarks
If element has not been declared outside this loop, you can declare it within the For Each statement. In this case, the scope of element is the body of the loop. However, you cannot declare element both outside and inside the loop.
The For Each…Next loop is entered if there is at least one element in group. Once the loop has been entered, the statements 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, the loop is terminated and execution continues with the statement following the Next statement.
Any number of Exit For statements may be placed anywhere in the loop as an alternative way to exit. Exit For is often used after evaluating some condition, for example with an If…Then…Else statement, and transfers control to the statement immediately following Next.
You can nest For Each…Next loops by placing one loop within another. Each loop must have a unique element variable.
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 As Boolean = False
Dim MyCollection As New Collection
For Each MyObject As Object In MyCollection ‘ Iterate through elements.
If CStr(MyObject.Text) = "Hello" Then ‘ If Text equals "Hello"
Found = True ‘ Set Found to True.
Exit For ‘ Exit loop.
End If
Next
Help 2.0
Remarks
For…Next Statements (Visual Basic) work well when you can associate each iteration of a loop with a control variable and determine that variable’s initial and final values. However, when you are dealing with a collection, the concept of initial and final values is not meaningful, and you do not necessarily know how many elements the collection has. In this case, a For Each…Next loop is a better choice.
When to Use For Each…Next
Use a For Each…Next loop when you want to repeat a set of statements for each element of a collection or array.
Rules
Data Types. The data type of element must be such that the data type of the elements of group can be converted to it.
The data type of group must be a reference type that refers to a collection or an array. This means that group must refer to an object that implements the IEnumerable interface of the System.Collections namespace or the Generic IEnumerable interface of the System.Collections.Generic namespace. IEnumerable defines the GetEnumerator method, which returns an enumerator object for the collection. The enumerator object implements the IEnumerator interface of the System.Collections namespace and exposes the Current property and the Reset and MoveNext methods. Visual Basic uses these to traverse the collection.
The elements of group are usually of type Object but can have any run-time data type.
Declaration. If element has not been declared outside this loop, you must declare it within the For Each statement. In this case, the scope of element is the body of the loop. However, you cannot declare element both outside and inside the loop.
Number of Iterations. Visual Basic evaluates the iteration values start, end, and step only once, before the loop begins. If your statement block changes end or step, these changes do not affect the iteration of the loop.
Nesting Loops. You can nest For Each loops by placing one loop within another. However, each loop must have a unique element variable.
You can also nest different kinds of control structures within one another. For more information, see Nested Control Structures.
Note:
If a Next statement of an outer nesting level is encountered before the Next of an inner level, the compiler signals an error.
Identifying the Control Variable. You can optionally specify element in the Next statement. This improves the readability of your program, especially if you have nested For Each loops. You must specify the same variable as the one that appears in the corresponding For Each statement.
Transferring Out of the Loop. The Exit Statement (Visual Basic) transfers control immediately to the statement following the Next statement. You might want to exit a loop if you detect a condition that makes it unnecessary or impossible to continue iterating, such as an erroneous value or a termination request. Also, if you catch an exception in a Try…Catch…Finally, you can use Exit For at the end of the Finally block.
You can place any number of Exit For statements anywhere in the For Each loop. Exit For is often used after evaluating some condition, for example in an If…Then…Else structure.
Endless Loops. One use of Exit For is to test for a condition that could cause an endless loop, which is a loop that could run an extremely 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).
Behavior
Entry into the Loop. When execution of the For Each…Next loop begins, Visual Basic verifies that group refers to a valid collection object. If not, it throws an exception. Otherwise, it calls the MoveNext method and the Current property of the enumerator object to return the first element. If MoveNext indicates there is no next element, that is, if the collection is empty, the For Each loop terminates and control passes to the statement following the Next statement. Otherwise, Visual Basic sets element to the first element and runs the statement block.
Iterations of the Loop. Each time Visual Basic encounters the Next statement, it returns to the For Each statement. Again it calls MoveNext and Current to return the next element, and again it either runs the block or terminates the loop depending on the result. This process continues until MoveNext indicates there is no next element or an Exit For statement is encountered.
Termination of the Loop. When all the elements in the collection have been successively assigned to element, the For Each loop terminates and control passes to the statement following the Next statement.
Changing Iteration Values. Changing the value of element while inside a loop can make it more difficult to read and debug your code. Changing the value of group does not affect the collection or its elements, which were determined when the loop was first entered.
Traversal Order. When you execute a For Each…Next loop, traversal of the collection is under the control of the enumerator object returned by the GetEnumerator method. The order of traversal is not determined by Visual Basic, but rather by the MoveNext method of the enumerator object. This means that you might not be able to predict which element of the collection is the first to be returned in element, or which is the next to be returned after a given element.
If your code depends on traversing a collection in a particular order, a For Each…Next loop is not the best choice unless you know the characteristics of the enumerator object the collection exposes. You might achieve more reliable results using a different loop structure, such as For…Next or Do…Loop.
Modifying the Collection. The enumerator object returned by GetEnumerator does not allow you to alter the collection by adding, deleting, replacing, or reordering any elements. If you alter the collection after you have initiated a For Each…Next loop, the enumerator object becomes invalid, and the next attempt to access an element results in an InvalidOperationException exception.
Modifying Collection Elements. The Current property of the enumerator object is ReadOnly (Visual Basic), and it returns a local copy of each collection element. This means that you cannot modify the elements themselves in a For Each…Next loop. Any modification you make affects only the local copy from Current and is not reflected back into the underlying collection. However, if an element is a reference type, you can modify the members of the instance to which it points. The following example illustrates this.
Sub lightBlueBackground(ByVal thisForm As System.Windows.Forms.Form)
For Each thisControl As System.Windows.Forms.Control In thisForm.Controls
thisControl.BackColor = System.Drawing.Color.LightBlue
Next thisControl
End Sub
The preceding example can modify the BackColor member of each thisControl element, although it cannot modify thisControl itself.
Traversing Arrays. Because the Array class implements the IEnumerable interface, all arrays expose the GetEnumerator method. This means you can iterate through an array with a For Each…Next loop. However, you can only read the array elements, not change them. For an illustration, see How to: Run Several Statements for Each Element in a Collection or Array.
