Array.BinarySearch Method

Array.BinarySearch Method

---

Class

System.Array

Syntax

     Dim result As Integer = Array.BinarySearch(array, value[, comparer]) 

or:

     Dim result As Integer = Array.BinarySearch(array, index, _        length, value[, comparer]) 

array (required; any array)

The one-dimensional array to be searched

value (required in syntax 1; any)

The value to search for in array

index (required in syntax 2; Integer)

The array element at which the search is to start

length (required in syntax 2; Integer)

The number of array elements to be searched

comparer (optional; IComparer interface)

A class implementing the IComparer interface that determines how two items are compared for equality

Description

The BinarySearch method returns the zero-based ordinal position of the first element that matches value in array. The dimension or range being searched must already be sorted. This method uses a binary search algorithm.

If nameSet is an array of names in alphabetical order, then the code:

     Array.BinarySearch(nameSet, "steve") 

returns the position of the first element with the name "steve." If no match is found, BinarySearch returns the negative number whose bitwise complement is the index of the first element that is larger than "steve."

Usage at a Glance

• The array must be a one-dimensional array sorted in ascending order.

• If value is not found in the array, the method returns a negative number, which is the bitwise complement of the index of the first element that is larger than value. To change this negative value into an index you can use, use the Not operator, as in the following code fragment:

       position = Array.BinarySearch(someArray, valueToFind)     If (position >= 0) Then        MsgBox(position)     Else        MsgBox(position & vbCrLf & Not position)     End If 

  
  

• If an array contains Boolean values, the method fails to correctly identify the position of the first False value in the array.

• By default, the System.Collections.Comparer class is used to compare value with the members of array. It performs case-sensitive comparisons.

• In addition to the Comparer class, you can also pass an instance of the System.Collections.CaseInsensitiveComparer class as the comparer argument. It provides for case-insensitive comparisons. For example:

       Dim someStates(  ) As String = {"Alaska", "ALASKA", _        "Michigan", "MICHIGAN", "New York", "NEW YORK"}     Dim searchState As String     Dim position As Integer     Dim toCompare As New CaseInsensitiveComparer     searchState = "MICHIGAN"     position = Array.BinarySearch(someStates, searchState, toCompare) 

  
  

  The value of position will be 2.

See Also

Array Class, Array.IndexOf Method, Array.LastIndexOf Method, Array.Sort Method