NAG FL Interface
m01dcf (charvec_​rank)

Settings help

FL Name Style:


FL Specification Language:


1 Purpose

m01dcf ranks a vector of character data in ASCII or reverse ASCII order of a specified substring.

2 Specification

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

3 Description

m01dcf 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.
Only the substring (l1:l2) of each element of the array ch is used to determine the rank order.

4 References

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

5 Arguments

1: ch(m2) Character(*) array Input
On entry: elements m1 to m2 of ch must contain character data to be ranked.
Constraint: the length of each element of ch must not exceed 255.
2: m1 Integer Input
On entry: the index of the first element of ch to be ranked.
Constraint: m1>0.
3: m2 Integer Input
On entry: the index of the last element of ch to be ranked.
Constraint: m2m1.
4: l1 Integer Input
5: l2 Integer Input
On entry: only the substring (l1:l2) of each element of ch is to be used in determining the rank order.
Constraint: 0<l1l2len(ch(1)).
6: order Character(1) Input
On entry: if order='A', the values will be ranked in ASCII order.
If order='R', in reverse ASCII order.
Constraint: order='A' or 'R'.
7: irank(m2) Integer array Output
On exit: elements m1 to m2 of irank contain the ranks of the corresponding elements of ch. Note that the ranks are in the range m1 to m2: thus, if ch(i) is the first element in the rank order, irank(i) is set to m1.
8: 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, l1=value.
Constraint: l11.
On entry, l1=value and l2=value.
Constraint: l1l2.
On entry, l2=value.
Constraint: l21.
On entry, l2=value and len(ch(1))=value.
Constraint: l2len(ch(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=3
On entry, len(ch(1))=value.
Constraint: len(ch(1))255.
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

m01dcf 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.
The routine relies on the Fortran intrinsic functions LLT and LGT to order characters according to the ASCII collating sequence.

10 Example

This example reads a file of 12-character records, and ranks them in reverse ASCII order on characters 7 to 12.

10.1 Program Text

Program Text (m01dcfe.f90)

10.2 Program Data

Program Data (m01dcfe.d)

10.3 Program Results

Program Results (m01dcfe.r)