m01 Chapter Contents
m01 Chapter Introduction
NAG Library Manual

# NAG Library Function Documentnag_rank_sort (m01dsc)

## 1  Purpose

nag_rank_sort (m01dsc) ranks a vector of arbitrary data type objects in ascending or descending order.

## 2  Specification

 #include #include
void  nag_rank_sort (const Pointer vec, size_t n, ptrdiff_t stride,
 Integer (*compare)(const Nag_Pointer a, const Nag_Pointer b),
Nag_SortOrder order, size_t ranks[], NagError *fail)

## 3  Description

nag_rank_sort (m01dsc) ranks a set of $n$ data objects of arbitrary type, which are stored in the elements of an array at intervals of length stride. The ranks are in the range 0 to $n-1$.
Either ascending or descending ranking order may be specified.
nag_rank_sort (m01dsc) uses a variant of list merging as described by Knuth (1973).

## 4  References

Knuth D E (1973) The Art of Computer Programming (Volume 3) (2nd Edition) Addison–Wesley

## 5  Arguments

1:    $\mathbf{vec}\left[{\mathbf{n}}\right]$const Pointer Input
On entry: the array of objects to be ranked.
2:    $\mathbf{n}$size_tInput
On entry: the number $n$ of objects.
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.
3:    $\mathbf{stride}$ptrdiff_tInput
On entry: the increment between data items in vec to be ranked.
Note: if stride is positive, vec should point at the first data object; otherwise vec should point at the last data object.
Constraint: $0<\left|{\mathbf{stride}}\right|\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.
4:    $\mathbf{compare}$function, supplied by the userExternal Function
nag_rank_sort (m01dsc) 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.
5:    $\mathbf{order}$Nag_SortOrderInput
On entry: specifies whether the array is to be ranked into ascending or descending order.
Constraint: ${\mathbf{order}}=\mathrm{Nag_Ascending}$ or $\mathrm{Nag_Descending}$.
6:    $\mathbf{ranks}\left[{\mathbf{n}}\right]$size_tOutput
On exit: the ranks of the corresponding data elements in vec.
7:    $\mathbf{fail}$NagError *Input/Output
The NAG error argument (see Section 2.7 in How to Use the NAG Library and its Documentation).

## 6  Error Indicators and Warnings

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

## 8  Parallelism and Performance

nag_rank_sort (m01dsc) is not threaded in any implementation.

The time taken by nag_rank_sort (m01dsc) is approximately proportional to $n\mathrm{log}\left(n\right)$.

## 10  Example

The example program reads a list of real numbers and ranks them into ascending order.

### 10.1  Program Text

Program Text (m01dsce.c)

### 10.2  Program Data

Program Data (m01dsce.d)

### 10.3  Program Results

Program Results (m01dsce.r)