# Function Reference

# _ArrayBinarySearch

Uses the binary search algorithm to search through a 1D or 2D array

#include <Array.au3>
_ArrayBinarySearch ( Const ByRef $aArray, $vValue [, $iStart = 0 [, $iEnd = 0 [, $iColumn = 0]]] )

## Parameters

$aArray | Array to search
$vValue | Value to find
$iStart | [optional] Index of array to start searching at
$iEnd | [optional] Index of array to stop searching at
$iColumn | [optional] Column of array to search

## Return Value

Success: | the index that value was found at.
Failure: | -1 and sets the @error flag to non-zero.
@error: | 1 - $aArray is not an array 2 - $vValue outside of array min/max values 3 - $vValue was not found in array 4 - $iStart is greater than $iEnd 5 - $aArray is not a 1D or 2D array 6 - $aArray is empty 7 - $iColumn outside array bounds

## Remarks

When performing a binary search on an array of items, the array (specified column if 2D) MUST be sorted in ASCENDING order before the search is done. Otherwise undefined results will be returned.

## Related

_ArrayFindAll, _ArraySearch

## Example

### Example 1

    #include <Array.au3>
    #include <MsgBoxConstants.au3>

    Local $iIndex

    Local $aArray[5][2]
    For $i = 0 To 4
        For $j = 0 To 1
            $aArray[$i][$j] = "#" & $i & $j
        Next
    Next
    _ArrayDisplay($aArray, "Array")

    ; Search col 0
    $iIndex = _ArrayBinarySearch($aArray, "#10", 0, 0, 0)
    MsgBox($MB_SYSTEMMODAL, "Index", $iIndex)

    ; Search col 1
    $iIndex = _ArrayBinarySearch($aArray, "#31", 0, 0, 1)
    MsgBox($MB_SYSTEMMODAL, "Index", $iIndex)

### Example 2

    ; using an array returned by StringSplit()

    #include <Array.au3>
    #include <MsgBoxConstants.au3>

    Local $avArray = StringSplit("a,b,d,c,e,f,g,h,i", ",")

    ; sort the array to be able to do a binary search
    _ArraySort($avArray, 0, 1) ; start at index 1 to skip $avArray[0]

    ; display sorted array
    _ArrayDisplay($avArray, "$avArray AFTER _ArraySort()")

    ; start at index 1 to skip $avArray[0]
    Local $iKeyIndex = _ArrayBinarySearch($avArray, "c", 1)
    If Not @error Then
        MsgBox($MB_SYSTEMMODAL, 'Entry found', ' Index: ' & $iKeyIndex)
    Else
        MsgBox($MB_SYSTEMMODAL, 'Entry Not found', ' Error: ' & @error)
    EndIf