hide long namesshow long names
hide short namesshow short names
Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

NAG Toolbox: nag_sort_charvec_rank (m01dc)

 Contents

    1  Purpose
    2  Syntax
    7  Accuracy
    9  Example

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. 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:     chm2 – 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<l1l2LENch1.
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: m2m1.

Output Parameters

1:     irankm2 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 chi is the first element in the rank order, iranki 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,
orm1<1,
orm1>m2,
orl2<1,
orl1<1,
orl1>l2,
orl2>LENch1.
   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×logn, 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 to 12.
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

© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2015