| Description |
TheArray is scanned for a match with the Needle object value.
The search does not look for the object instance - it merely performs a binary search, using the principle object value as the comparison value.
The returned value is the array index of the match, or negative if no match found. Unlike other search functions, the value of this negative number has a meaning :
| Value < 0th element | -1 is returned |
| Value < 1st element | -2 is returned |
| Value < 2nd element | -3 is returned |
| Value < nth element | -(n+1) is returned |
| Value > last element | -(last+2) is returned |
The search requires the array to be sorted into sequence.
The array is scanned from start to finish unless the optional Start and Count values are supplied.
You should code your own object Comparer for your own classes.
|
| | Notes | Important : the negative value value is relative to the whole array, even when the search works on a subset of the array.
A binary search starts with a comparison of the middle two elements. Either a match is found there and then, or the appropriate half is then searched. This process repeats on this half until a match is found or a subdivision is no longer possible. This is why the array must be pre-sorted into sequence.
|
| | References | IComparer
|
|
| Microsoft MSDN Links |
System
System.Array
|
|
|
| A simple example of found and not found elements |
program Project1;
{$APPTYPE CONSOLE}
var
strArray : System.Array;
index : Integer;
begin
// Create a 5 element single dimension array of Strings
strArray := System.Array.CreateInstance(TypeOf(String), 5);
// Fill out the array in sorted sequence
// (We could have used the static 'Sort' method to do the sort
strArray.SetValue('ABC', 0);
strArray.SetValue('DEF', 1);
strArray.SetValue('GHI', 2);
strArray.SetValue('JKL', 3);
strArray.SetValue('MNO', 4);
// Try to find 'GHI'
index := System.Array.BinarySearch(strArray, 'GHI');
Console.WriteLine('The index of ''GHI'' is {0}', index.ToString);
// Try to find 'GHZ'
index := System.Array.BinarySearch(strArray, 'GHZ');
Console.WriteLine('The index of ''GHZ'' is {0}', index.ToString);
// Try to find 'ZZZ'
index := System.Array.BinarySearch(strArray, 'ZZZ');
Console.WriteLine('The index of ''ZZZ'' is {0}', index.ToString);
Console.ReadLine;
end.
| | Show full unit code | The index of 'GHI' is 2
The index of 'GHZ' is -4
The index of 'ZZZ' is -6
| | | Limiting the search to a subset of the array | program Project1;
{$APPTYPE CONSOLE}
var
strArray : System.Array;
index : Integer;
begin
// Create an 8 element single dimension array of Strings
strArray := System.Array.CreateInstance(TypeOf(String), 8);
// Fill out the array in sorted sequence
// (We could have used the static 'Sort' method to do the sort
strArray.SetValue('ABC', 0);
strArray.SetValue('DEF', 1);
strArray.SetValue('GHI', 2);
strArray.SetValue('JKL', 3);
strArray.SetValue('MNO', 4);
strArray.SetValue('PQR', 5);
strArray.SetValue('STU', 6);
strArray.SetValue('VWX', 7);
// Try to find 'DEF' from index 0 to the end
index := System.Array.BinarySearch(strArray, 0, 8, 'DEF');
Console.WriteLine('The index of ''DEF'' from 0-6 is {0}', index.ToString);
// Try to find 'DEF' from index 2 to the end
index := System.Array.BinarySearch(strArray, 2, 6, 'DEF');
Console.WriteLine('The index of ''DEF'' from 2-6 is {0}', index.ToString);
Console.ReadLine;
end.
| | Show full unit code | The index of 'DEF' from 0-6 is 1
The index of 'DEF' from 2-6 is -3
|
| |
|
|
|