| Description |
The current ArrayList 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 | Array
|
|
| Microsoft MSDN Links |
System.Collections
System.Collections.ArrayList
|
|
|
| A simple example of found and not found elements |
program Project1;
{$APPTYPE CONSOLE}
uses
System.Collections;
var
List : System.Collections.ArrayList;
index : Integer;
begin
// Create our array list object
List := ArrayList.Create;
// Fill it
List.Add('ABC');
List.Add('DEF');
List.Add('GHI');
List.Add('JKL');
List.Add('MNO');
// Try to find 'GHI'
index := List.BinarySearch('GHI');
Console.WriteLine('The index of ''GHI'' is {0}', index.ToString);
// Try to find 'GHZ'
index := List.BinarySearch('GHZ');
Console.WriteLine('The index of ''GHZ'' is {0}', index.ToString);
// Try to find 'ZZZ'
index := List.BinarySearch('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
| | | Using a custom Comparer for the search | program Project1;
{$APPTYPE CONSOLE}
uses
System.Collections;
type
// Define our data class
MyData = Class
private
daAge : Integer;
published
property Age : Integer
read daAge;
constructor Create(Age : Integer);
end;
// Define our comparer class
MyComparer = Class(TObject, System.Collections.IComparer)
published
function Compare(Object1 : System.Object;
Object2 : System.Object) : Integer;
end;
// Data class constructor
constructor MyData.Create(Age: Integer);
begin
Inherited Create;
daAge := Age;
end;
// Compare method of our comparer class
function MyComparer.Compare(Object1 : System.Object;
Object2 : System.Object) : Integer;
var
Data1, Data2 : MyData;
begin
// Protect our comparison in case of non-integer objects
try
// We cast the Object parameters to our Data type
Data1 := MyData(Object1);
Data2 := MyData(Object2);
// And compare : Return <1, 0 or >1 as appropriate
Result := Data1.Age - Data2.Age;
except
Result := 0;
end;
end;
// Main code
// ----------------------------------------------------------
var
List : System.Collections.ArrayList;
Comparer : MyComparer;
i : Integer;
index : Integer;
begin
// Create our array list object
List := ArrayList.Create;
// Fill it in sotred sequence
List.Add(MyData.Create(2));
List.Add(MyData.Create(23));
List.Add(MyData.Create(74));
List.Add(MyData.Create(112));
List.Add(MyData.Create(243));
List.Add(MyData.Create(559));
// Display List contents : note the 0 indexing
for i := 0 to List.Count-1 do
Console.WriteLine(MyData(List.Item[i]).Age.ToString);
// Create our comparer object
Comparer := MyComparer.Create;
// Search for some values using our comparator
Console.WriteLine;
index := List.BinarySearch(MyData.Create(74), Comparer);
Console.WriteLine('74 position = {0}', index.ToString);
// Search for some values using our comparator
Console.WriteLine;
index := List.BinarySearch(MyData.Create(111), Comparer);
Console.WriteLine('111 position = {0}', index.ToString);
Console.Readline;
end.
| | Show full unit code | 2
23
74
112
243
559
74 position = 2
111 position = -4
|
| |
|
|
|