From RAD Studio API Documentation
Jump to: navigation, search


procedure FindNearest(const KeyValues: array of const);


void __fastcall FindNearest(const System::TVarRec *KeyValues, const int KeyValues_High);


Type Visibility Source Unit Parent
Bde.DBTables TTable


Moves the cursor to the record that most closely matches a specified set of key values.

Call FindNearest to move the cursor to a specific record in a dataset or to the first record in the dataset that is greater than the values specified in the KeyValues parameter. KeyValues contains a comma-delimited array of field values, called a key. Each value in the key can be a literal, a variable, or nil (Delphi) or NULL (C++). If the number of values passed in KeyValues is less than the number of columns in the index used for the search, the missing values are assumed to be null. KeyValues_Size specifies the index of the last value in KeyValues (one less than the total number of values supplied). In the statement below, the FindKey method is used to find the table row with the value "'Princess Island SCUBA" in the index field.

Table1.FindNearest(['Princess Island SCUBA']);

TVarRec vr = ("Princess Island SCUBA");
Table1->FindNearest(&vr, 0);

Note: In C++ code, the search values can be passed to FindNearest using either a TVarRec (as above) or an ARRAYOFCONST construct. The example below performs the same search as the preceding example, but using ARRAYOFCONST.

Table1->FindNearest(ARRAYOFCONST(("Princess Island SCUBA")));

For Paradox and dBASE tables, the key must always be an index, which can be specified in the IndexName property. If IndexName is empty, FindNearest uses the primary index of the table. Note that FindKey does not work with dBASE expression indexes. Use the GotoKey or GotoNearest method instead.

For SQL tables, the key may correspond to a specified index in IndexName, or to a list of field names in the IndexFieldNames property.

FindNearest positions the cursor either on a record that exactly matches the search criteria, or on the first record whose values are greater than those specified in the search criteria. If there are no records that match or exceed the specified criteria, FindNearest positions the cursor on the last record in the table. KeyExclusive affects the boundary conditions of ranges and will affect the record selected by FindNearest.

See Also