nag_rank_sort (m01dsc) (PDF version)
m01 Chapter Contents
m01 Chapter Introduction
NAG Library Manual

NAG Library Function Document

nag_rank_sort (m01dsc)

+ Contents

    1  Purpose
    7  Accuracy

1  Purpose

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

2  Specification

#include <nag.h>
#include <nagm01.h>
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:     vec[n]const Pointer Input
On entry: the array of objects to be ranked.
2:     nsize_tInput
On entry: the number n  of objects.
Constraint: n0 .
3:     strideptrdiff_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. It should be noted that stride  must be greater than or equal to size_of (data objects), for correct ranks to be produced. However, the code performs no check for violation of this constraint.
Constraint: stride > 0 .
4:     comparefunction, 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,
-0 if the first data field is equal to the second,
-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:     aconst Nag_Pointer Input
On entry: the first data field.
2:     bconst Nag_Pointer Input
On entry: the second data field.
5:     orderNag_SortOrderInput
On entry: specifies whether the array is to be ranked into ascending or descending order.
Constraint: order=Nag_Ascending or Nag_Descending.
6:     ranks[n]size_tOutput
On exit: the ranks of the corresponding data elements in vec.
7:     failNagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

6  Error Indicators and Warnings

On entry, argument order had an illegal value.
On entry, stride=value.
Constraint: stride=0.
On entry, n=value.
Constraint: nvalue.
On entry, stride=value.
Constraint: stridevalue.
These arguments are limited to an implementation-dependent size which is printed in the error message.
On entry, n=value.
Constraint: n0.

7  Accuracy

Not applicable.

8  Parallelism and Performance

Not applicable.

9  Further Comments

The time taken by nag_rank_sort (m01dsc) is approximately proportional to n logn .

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)

nag_rank_sort (m01dsc) (PDF version)
m01 Chapter Contents
m01 Chapter Introduction
NAG Library Manual

© The Numerical Algorithms Group Ltd, Oxford, UK. 2014