nag_search_vector (m01fsc) searches a vector of arbitrary type data objects for the first or last match to a given value.
nag_search_vector (m01fsc) searches a sorted vector of
arbitrary type data objects, which are stored in the elements of an array at intervals of length
stride.
vec must have previously been sorted into the specified order.
The function searches for the first or last match depending on the value of
final. It returns Nag_TRUE if an exact match is found and
match is set to point at that object. If there is no exact match then Nag_FALSE is returned and
match is set to point to either the next later element, if
, or the next earlier element, if
.
None.
- 1:
key – Pointer Input
-
On entry: the object to search for.
- 2:
vec[] – const Pointer Input
-
On entry: the array of objects to be searched.
- 3:
n – size_tInput
-
On entry: the number of objects to be searched.
Constraint:
.
- 4:
stride – ptrdiff_tInput
-
On entry: the increment between data items in
vec to be searched.
Note: if
stride is positive,
vec should point at the first data object; otherwise
vec should point at the last data object.
It should be noted that must be greater than or equal to size_of (data objects), for the search to be performed successfully. However, the code performs no check for violation of this constraint.
Constraint:
.
- 5:
compare – function, supplied by the userExternal Function
-
nag_search_vector (m01fsc) compares two data objects. If its arguments are pointers to a structure, this function must allow for the offset of the data field in the structure (if it is not the first).
The function must return:
|
if the first data field is less than the second, |
|
if the first data field is equal to the second, |
|
if the first data field is greater than the second. |
The specification of
compare is:
Integer |
compare (const Nag_Pointer a,
const Nag_Pointer b)
|
|
- 1:
a – const Nag_Pointer Input
-
On entry: the first data field.
- 2:
b – const Nag_Pointer Input
-
On entry: the second data field.
- 6:
order – Nag_SortOrderInput
On entry: specifies whether the array will be sorted into ascending or descending order.
Constraint:
or .
- 7:
final – Nag_SearchMatchInput
On entry: specifies whether to search for the first or last match. This also determines the pointer returned if an exact match cannot be found.
Constraint:
or .
- 8:
match – Pointer *Output
-
On exit: if an exact match is found this is a pointer to a pointer to the matching data object. If an exact match is not found this is set to point to the nearest object. If this is the next later element, otherwise the next earlier element.
- 9:
fail – NagError *Input/Output
-
The NAG error argument (see
Section 3.6 in the Essential Introduction).
Not applicable.
Not applicable.
The example program reads a key and a list of real numbers, which have been sorted into ascending order. It then searches the list for the first number which matches the key.