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

. 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: 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$ – int64int32nag_int scalar: The index of the first element of ch to be ranked.

Constraint: $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 < l1 \leq l2 \leq LEN (ch (1))$ .
5: $order$ – string (length ≥ 1): If $order ='A'$ , the values will be ranked in ASCII order.
If $order ='R'$ , in reverse ASCII order.

Constraint: $order ='A'$ or $'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: $m2 \geq m1$ .

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)$ is the first element in the rank order, $irank (i)$ is set to m1.
2: $ifail$ – int64int32nag_int scalar: $ifail = 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$

On entry,	$m2 < 1$ ,
or	$m1 < 1$ ,
or	$m1 > m2$ ,
or	$l2 < 1$ ,
or	$l1 < 1$ ,
or	$l1 > l2$ ,
or	$l2 > LEN (ch (1))$ .

$ifail = 2$

On entry,

order is not 'A' or 'R'.

$ifail = 3$

On entry,

the length of each element of ch exceeds

255

$ifail = - 99$: An unexpected error has been triggered by this routine. Please contact NAG.

$ifail = - 399$: Your licence key may have expired or may not have been installed correctly.

$ifail = - 999$: Dynamic memory allocation failed.

Accuracy

Not applicable.

Further Comments

The average time taken by the function is approximately proportional to

n \times \log (n)

, where

n = m2 - m1 + 1

The function relies on the Fortran intrinsic functions LLT and LGT to order characters according to the ASCII collating sequence.

Example

This example reads a file of

12

-character records, and ranks them in reverse ASCII order on characters

7

12

Open in the MATLAB editor: m01dc_example

function m01dc_example


fprintf('m01dc example results\n\n');

ch = {'A02AAF   289'; ...
      'A02ABF   523'; ...
      'A02ACF   531'; ...
      'C02ADF   169'; ...
      'C02AEF   599'; ...
      'C05ADF  1351'; ...
      '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);

fprintf('Records ranked on columns %2d to %2d\n\n',l1,l2);
fprintf('   Data         Ranks\n\n');
for i = 1:numel(ch)
  fprintf('%s%7d\n',char(ch{i}),irank(i));
end

m01dc example results

Records ranked on columns  7 to 12

   Data         Ranks

A02AAF   289      6
A02ABF   523      5
A02ACF   531      4
C02ADF   169     10
C02AEF   599      3
C05ADF  1351      2
C05AGF   240      7
C05AJF   136     11
C05AVF   211      8
C05AXF   183      9
C05AZF  2181      1

PDF version (NAG web site, 64-bit version, 64-bit version)

Chapter Contents

Chapter Introduction

NAG Toolbox