NAG FL Interface
m01dbf (intvec_​rank)

Settings help

FL Name Style:


FL Specification Language:


1 Purpose

m01dbf ranks a vector of integer numbers in ascending or descending order.

2 Specification

Fortran Interface
Subroutine m01dbf ( iv, m1, m2, order, irank, ifail)
Integer, Intent (In) :: iv(m2), m1, m2
Integer, Intent (Inout) :: ifail
Integer, Intent (Out) :: irank(m2)
Character (1), Intent (In) :: order
C Header Interface
#include <nag.h>
void  m01dbf_ (const Integer iv[], const Integer *m1, const Integer *m2, const char *order, Integer irank[], Integer *ifail, const Charlen length_order)
The routine may be called by the names m01dbf or nagf_sort_intvec_rank.

3 Description

m01dbf uses a variant of list-merging, as described on pages 165–166 in Knuth (1973). The routine takes advantage of natural ordering in the data, and uses a simple list insertion in a preparatory pass to generate ordered lists of length at least 10. The ranking is stable: equal elements preserve their ordering in the input data.

4 References

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

5 Arguments

1: iv(m2) Integer array Input
On entry: elements m1 to m2 of iv must contain integer values to be ranked.
2: m1 Integer Input
On entry: the index of the first element of iv to be ranked.
Constraint: m1>0.
3: m2 Integer Input
On entry: m2 must specify the index of the last element of iv to be ranked.
Constraint: m2m1.
4: order Character(1) Input
On entry: if order='A', the values will be ranked in ascending (i.e., nondecreasing) order.
If order='D', into descending order.
Constraint: order='A' or 'D'.
5: irank(m2) Integer array Output
On exit: elements m1 to m2 of irank contain the ranks of the corresponding elements of iv. Note that the ranks are in the range m1 to m2: thus, if iv(i) is the first element in the rank order, irank(i) is set to m1.
6: ifail Integer Input/Output
On entry: ifail must be set to 0, −1 or 1 to set behaviour on detection of an error; these values have no effect when no error is detected.
A value of 0 causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of −1 means that an error message is printed while a value of 1 means that it is not.
If halting is not appropriate, the value −1 or 1 is recommended. If message printing is undesirable, then the value 1 is recommended. Otherwise, the value 0 is recommended. When the value -1 or 1 is used it is essential to test the value of ifail on exit.
On exit: ifail=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry ifail=0 or −1, explanatory error messages are output on the current error message unit (as defined by x04aaf).
Errors or warnings detected by the routine:
ifail=1
On entry, m1=value.
Constraint: m11.
On entry, m1=value and m2=value.
Constraint: m1m2.
On entry, m2=value.
Constraint: m21.
ifail=2
On entry, order has an illegal value: order=value.
ifail=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 7 in the Introduction to the NAG Library FL Interface for further information.
ifail=-399
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library FL Interface for further information.
ifail=-999
Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

Background information to multithreading can be found in the Multithreading documentation.
m01dbf is not threaded in any implementation.

9 Further Comments

The average time taken by the routine is approximately proportional to n×log(n), where n=m2-m1+1.

10 Example

This example reads a list of integers and ranks them in descending order.

10.1 Program Text

Program Text (m01dbfe.f90)

10.2 Program Data

Program Data (m01dbfe.d)

10.3 Program Results

Program Results (m01dbfe.r)