# NAG CL Interfacem01fsc (search_​vector)

Settings help

CL Name Style:

## 1Purpose

m01fsc searches a vector of arbitrary type data objects for the first or last match to a given value.

## 2Specification

 #include
Nag_Boolean  m01fsc (Pointer key, const Pointer vec, size_t n, ptrdiff_t stride,
 Integer (*compare)(const Nag_Pointer a, const Nag_Pointer b),
Nag_SortOrder order, Nag_SearchMatch final, Pointer *match, NagError *fail)
The function may be called by the names: m01fsc, nag_sort_search_vector or nag_search_vector.

## 3Description

m01fsc searches a sorted vector of $n$ 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 ${\mathbf{final}}=\mathrm{Nag_First}$, or the next earlier element, if ${\mathbf{final}}=\mathrm{Nag_Last}$.

None.

## 5Arguments

1: $\mathbf{key}$Pointer  Input
On entry: the object to search for.
2: $\mathbf{vec}\left[{\mathbf{n}}\right]$const Pointer  Input
On entry: the array of objects to be searched.
3: $\mathbf{n}$size_t Input
On entry: the number $n$ of objects to be searched.
Constraint: $0\le {\mathbf{n}}\le \mathrm{MAX_LENGTH}$, where $\mathrm{MAX_LENGTH}$ is an implementation-dependent value for the maximum size of an array.
4: $\mathbf{stride}$ptrdiff_t Input
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.
Constraint: $0<|{\mathbf{stride}}|\le p$, where $p$ is an implementation-dependent value for the maximum size_t size on the system, divided by n if n is positive.
5: $\mathbf{compare}$function, supplied by the user External Function
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:
 $-1$ if the first data field is less than the second, $\phantom{-}0$ if the first data field is equal to the second, $\phantom{-}1$ 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: $\mathbf{a}$const Nag_Pointer  Input
On entry: the first data field.
2: $\mathbf{b}$const Nag_Pointer  Input
On entry: the second data field.
6: $\mathbf{order}$Nag_SortOrder Input
On entry: specifies whether the array will be sorted into ascending or descending order.
Constraint: ${\mathbf{order}}=\mathrm{Nag_Ascending}$ or $\mathrm{Nag_Descending}$.
7: $\mathbf{final}$Nag_SearchMatch Input
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: ${\mathbf{final}}=\mathrm{Nag_First}$ or $\mathrm{Nag_Last}$.
8: $\mathbf{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 ${\mathbf{final}}=\mathrm{Nag_First}$ this is the next later element, otherwise the next earlier element.
9: $\mathbf{fail}$NagError * Input/Output
The NAG error argument (see Section 7 in the Introduction to the NAG Library CL Interface).

## 6Error Indicators and Warnings

On entry, argument final had an illegal value.
On entry, argument order had an illegal value.
NE_INT_ARG_EQ
On entry, ${\mathbf{stride}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{stride}}\ne 0$.
NE_INT_ARG_GT
On entry, ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{n}}\le ⟨\mathit{\text{value}}⟩$, an implementation-dependent size that is printed in the error message.
On entry, ${\mathbf{stride}}=⟨\mathit{\text{value}}⟩$.
Constraint: $|{\mathbf{stride}}|\le ⟨\mathit{\text{value}}⟩$, an implementation-dependent size that is printed in the error message.
NE_INT_ARG_LT
On entry, ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{n}}\ge 0$.

Not applicable.

## 8Parallelism and Performance

m01fsc is not threaded in any implementation.

The maximum time taken by the function is approximately proportional to ${\mathrm{log}}_{2}n$.

## 10Example

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.

### 10.1Program Text

Program Text (m01fsce.c)

### 10.2Program Data

Program Data (m01fsce.d)

### 10.3Program Results

Program Results (m01fsce.r)