Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_sort_charvec_rank (m01dc)

## Purpose

nag_sort_charvec_rank (m01dc) ranks a vector of character data in ASCII or reverse ASCII order of a specified substring.

## Syntax

[irank, ifail] = m01dc(ch, m1, l1, l2, order, 'm2', m2)
[irank, ifail] = nag_sort_charvec_rank(ch, m1, l1, l2, order, 'm2', m2)

## Description

nag_sort_charvec_rank (m01dc) uses a variant of list-merging, as described on pages 165–166 in Knuth (1973). The function 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$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.

## References

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

## Parameters

### Compulsory Input Parameters

1:     ch(m2) – cell array of strings
m2, the dimension of the array, must satisfy the constraint m2m1${\mathbf{m2}}\ge {\mathbf{m1}}$.
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$255$.
2:     m1 – int64int32nag_int scalar
The index of the first element of ch to be ranked.
Constraint: m1 > 0${\mathbf{m1}}>0$.
3:     l1 – int64int32nag_int scalar
4:     l2 – int64int32nag_int scalar
Only the substring (l1:l2) of each element of ch is to be used in determining the rank order.
Constraint: 0 < l1l2LEN(ch(1))$0<{\mathbf{l1}}\le {\mathbf{l2}}\le \mathrm{LEN}\left({\mathbf{ch}}\left(1\right)\right)$.
5:     order – string (length ≥ 1)
If order = 'A'${\mathbf{order}}=\text{'A'}$, the values will be ranked in ASCII order.
If order = 'R'${\mathbf{order}}=\text{'R'}$, in reverse ASCII order.
Constraint: order = 'A'${\mathbf{order}}=\text{'A'}$ or 'R'$\text{'R'}$.

### Optional Input Parameters

1:     m2 – int64int32nag_int scalar
Default: The dimension of the array ch.
The index of the last element of ch to be ranked.
Constraint: m2m1${\mathbf{m2}}\ge {\mathbf{m1}}$.

None.

### Output Parameters

1:     irank(m2) – int64int32nag_int array
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)${\mathbf{ch}}\left(i\right)$ is the first element in the rank order, irank(i)${\mathbf{irank}}\left(i\right)$ is set to m1.
2:     ifail – int64int32nag_int scalar
${\mathrm{ifail}}={\mathbf{0}}$ unless the function detects an error (see [Error Indicators and Warnings]).

## Error Indicators and Warnings

Errors or warnings detected by the function:
ifail = 1${\mathbf{ifail}}=1$
 On entry, m2 < 1${\mathbf{m2}}<1$, or m1 < 1${\mathbf{m1}}<1$, or m1 > m2${\mathbf{m1}}>{\mathbf{m2}}$, or l2 < 1${\mathbf{l2}}<1$, or l1 < 1${\mathbf{l1}}<1$, or l1 > l2${\mathbf{l1}}>{\mathbf{l2}}$, or l2 > LEN(ch(1))${\mathbf{l2}}>\mathrm{LEN}\left({\mathbf{ch}}\left(1\right)\right)$.
ifail = 2${\mathbf{ifail}}=2$
 On entry, order is not 'A' or 'R'.
ifail = 3${\mathbf{ifail}}=3$
 On entry, the length of each element of ch exceeds 255$255$.

## Accuracy

Not applicable.

The average time taken by the function is approximately proportional to n × log(n)$n×\mathrm{log}\left(n\right)$, where n = m2m1 + 1$n={\mathbf{m2}}-{\mathbf{m1}}+1$.
The function relies on the Fortran intrinsic functions LLT and LGT to order characters according to the ASCII collating sequence.

## Example

```function nag_sort_charvec_rank_example
ch = {'A02AAF   289'; ...
'A02ABF   523'; ...
'A02ACF   531'; ...
'C02AEF   599'; ...
'C05AGF   240'; ...
'C05AJF   136'; ...
'C05AVF   211'; ...
'C05AXF   183'; ...
'C05AZF  2181'};
m1 = int64(1);
l1 = int64(7);
l2 = int64(12);
order = 'Reverse ASCII';
[irank, ifail] = nag_sort_charvec_rank(ch, m1, l1, l2, order)
```
```

irank =

6
5
4
10
3
2
7
11
8
9
1

ifail =

0

```
```function m01dc_example
ch = {'A02AAF   289'; ...
'A02ABF   523'; ...
'A02ACF   531'; ...
'C02AEF   599'; ...
'C05AGF   240'; ...
'C05AJF   136'; ...
'C05AVF   211'; ...
'C05AXF   183'; ...
'C05AZF  2181'};
m1 = int64(1);
l1 = int64(7);
l2 = int64(12);
order = 'Reverse ASCII';
[irank, ifail] = m01dc(ch, m1, l1, l2, order)
```
```

irank =

6
5
4
10
3
2
7
11
8
9
1

ifail =

0

```