NAG Library Function Document

nag_search_vector (m01fsc)

1  Purpose

2  Specification

3  Description

4  References

5  Arguments

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_tInput

On entry: the number $n$ of objects to be searched.

Constraint: $\mathbf{n}\ge 0$.

4:    $\mathbf{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 $\left|\mathbf{stride}\right|$ 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: $\left|\mathbf{stride}\right|>0$.

5:    $\mathbf{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:

$-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_SortOrderInput

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_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: $\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 3.6 in the Essential Introduction).

6  Error Indicators and Warnings

NE_BAD_PARAM

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}=0$.

NE_INT_ARG_GT

On entry, $\mathbf{n}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{n}\le 〈\mathit{\text{value}}〉$.

On entry, $\mathbf{stride}=〈\mathit{\text{value}}〉$.
Constraint: $\left|\mathbf{stride}\right|\le 〈\mathit{\text{value}}〉$.
These arguments are limited to an implementation-dependent size which is printed in the error message.

NE_INT_ARG_LT

On entry, $\mathbf{n}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{n}\ge 0$.

7  Accuracy

8  Parallelism and Performance

9  Further Comments

10  Example

10.1  Program Text

Program Text (m01fsce.c)

10.2  Program Data

Program Data (m01fsce.d)

10.3  Program Results

Program Results (m01fsce.r)