findKeyNearest( )

Topic group Related topics

Finds the row with the nearest matching key value.

Syntax

<oRef>.findKeyNearest(<exp> | <exp list>)

<oRef>

The rowset in which to do the search.

<exp>

The value to search for.

<exp list>

One or more expressions, separated by commas, to search for in a simple or composite key index for non-DBF tables.

Property of

Rowset

Description

findKeyNearest( ) performs an indexed search in the rowset, using the index specified by the rowset’s indexName property. It looks for the first row in the index whose index key value matches <exp>, returning true or false to indicate if an exact match is found. If an exact match is not found, the row cursor is left at the nearest match; the row where the match would have been. For example, if "Smith" is followed by "Smythe" in the index, and the search expression is "Smothers", the search will fail and the row cursor will be left at "Smythe". "Smothers" comes after "Smith" and before "Smythe", so if it was in the index, it would be where "Smythe" is.

You can think of this exact, or nearest matching, as "equal, or the one after," as long as you remember that "after" depends on the index order. If the index is descending instead of ascending, then in the previous example, "Smythe" would be followed by "Smith", and a search for "Smothers" would end up on "Smith". The row cursor will end up on the end-of-set if the search value comes after the last value in the index.

findKeyNearest( ) is a navigation method; calling it fires the canNavigate event. If canNavigate returns false, findKeyNearest( ) does not attempt a search. onNavigate always fires after a search attempt. For more information on how navigation methods interact with navigation events and implicit saves, see next( ).

findKeyNearest( ) always performs a partial key match with strings. For example, findKeyNearest("Smi") will find "Smith". To perform a full key match, pad <exp> with enough extra spaces to match the length of the index key value.