The For Each...Next Statement

Recall that collections are similar to arrays for storing one-dimensional sets of data items. An advantage of collections is that items can be indexed both by their locations in the collection -- collection.Item(n) -- and by special keys that are stored along with the data values -- collection.Item("key").

Using Collections for Look-ups

If your data fit the "value" and "key" format of a collection, then a table look-up can be most easily performed with this technique rather than by using arrays. Returning to a variation on an example presented earlier, the following collection contains state names (values) and state codes (keys). A state code is entered to look up the corresponding state name.

Sub Get_State (Src As Object, Args As EventArgs)

  Dim TheStates As New Collection
  TheStates.Add("Alabama","AL")
  TheStates.Add("Alaska","AK")
  TheStates.Add("Arizona","AZ")
  TheStates.Add("Arkansas","AR")
  TheStates.Add("California","CA")

  On Error Resume Next
  TheState.Text = TheStates.Item( UCase(Code.Text) )

End Sub

<asp:TextBox id="Code" Size="1" MaxLength="2" runat="server"/>
<asp:Button Text="Get State" OnClick="Get_State" runat="server"/>
<asp:Label id="TheState" EnableViewState="False" runat="server"/>

First, notice that there is no loop. The entered value (converted to lower case) is the key used to automatically find the associated state name in the collection.

TheStates.Item( UCase(Code.Text) )

Trapping for Errors

That's all there is to it, except for dealing with possible errors. If a value is entered for which there is no key match in the collection, an "index out of bounds" error occurs (the search extended beyond the boundaries of the collection). In order to trap for this error, an On Error Resume Next statement is added immediately before the search for UCase(Code.Text). As implied by the statement, if an error occurs while executing this search statement, simply go on to the next statement; do not stop and display an error message that embarasses the programmer.

Run-time errors cause the system to set properties of the Err object detailing information about the error, including a series of error numbers. Although you may not be interested in particular error numbers, you can use their setting as a way to react to any such errors. In the previous example nothing is done when an error occurs; the script just ends. However, you might want to indicate to the user that no match was found for the entered value.

To determine if an error occured, simply check for an error number not equal to 0. Then perform any processing deemed appropriate. You can, for example, add the following code to produce a "No match" message.

  On Error Resume Next
  TheState.Text = TheStates.Item( UCase(Code.Text) )
	
  If Err.Number <> 0 Then
    TheState.Text = "No match"
  End If

The For Each...Next Statement

Since collections contain related elements within which data are stored, they can also be iterated much like arrays. Rather than a For...Next statement, however, a For Each...Next statement is used.

For Each item In collection

   ...item

Next

The item is a programmer-supplied variable used as the loop's reference to elements in the collection; item must be declared as the same data type as values in the collection.

As the loop iterates, item points to each element, in turn, in the collection. Therefore, item can be used as a reference to the data values stored in the elements as they are iterated. An example should make this clear.

Below is repeated the code for the TheStates collection used in the previous example. The script has been changed by adding a For Each...Next loop to iterate the collection and display all the data values in the collection.

Sub Show_States (Src As Object, Args As EventArgs)

  Dim TheStates As New Collection
  TheStates.Add("Alabama","AL")
  TheStates.Add("Alaska","AK")
  TheStates.Add("Arizona","AZ")
  TheStates.Add("Arkansas","AR")
  TheStates.Add("California","CA")

  Dim Item As String
  For Each Item In TheStates
    StatesOut.Text &= Item & " "
  Next

End Sub

<asp:Button Text="Show States" OnClick="Show_States" runat="server"/>
<asp:Label id="StatesOut" EnableViewState="False" runat="server"/>

Here, variable Item is used as the index to the collection; it is declared as String because the data items in the collection are strings. The loop iterates through each element in the collection (Each Item In TheStates). Each element's contents (Item) is displayed by appending it to the accumulating list.

Notice that the TheStates collection seems to contain two data items in each element -- a state name and a state code. However, recall that the state code is the key to the element value; it is not the value of the element itself.

The For Each...Next statement has wide application for many different data structures in Visual Basic. There will be several occasions throughout these tutorials to enlist it for use.