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_sort (m01cc)

## Purpose

nag_sort_charvec_sort (m01cc) rearranges a vector of character data so that a specified substring is in ASCII or reverse ASCII order.

## Syntax

[ch, ifail] = m01cc(ch, m1, l1, l2, order, 'm2', m2)
[ch, ifail] = nag_sort_charvec_sort(ch, m1, l1, l2, order, 'm2', m2)

## Description

nag_sort_charvec_sort (m01cc) is based on Singleton's implementation of the ‘median-of-three’ Quicksort algorithm (see Singleton (1969)), but with two additional modifications. First, small subfiles are sorted by an insertion sort on a separate final pass (see Sedgewick (1978)) Second, if a subfile is partitioned into two very unbalanced subfiles, the larger of them is flagged for special treatment: before it is partitioned, its end points are swapped with two random points within it; this makes the worst case behaviour extremely unlikely.
Only the substring (l1:l2) of each element of the array ch is used to determine the sorted order, but the entire elements are rearranged into sorted order.

## References

Sedgewick R (1978) Implementing Quicksort programs Comm. ACM 21 847–857
Singleton R C (1969) An efficient algorithm for sorting with minimal storage: Algorithm 347 Comm. ACM 12 185–187

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{ch}\left({\mathbf{m2}}\right)$ – cell array of strings
Elements m1 to m2 of ch must contain character data to be sorted.
Constraint: the length of each element of ch must not exceed $255$.
2:     $\mathrm{m1}$int64int32nag_int scalar
The index of the first element of ch to be sorted.
Constraint: ${\mathbf{m1}}>0$.
3:     $\mathrm{l1}$int64int32nag_int scalar
4:     $\mathrm{l2}$int64int32nag_int scalar
Only the substring (l1:l2) of each element of ch is to be used in determining the sorted order.
Constraint: $0<{\mathbf{l1}}\le {\mathbf{l2}}\le \mathrm{LEN}\left({\mathbf{ch}}\left(1\right)\right)$.
5:     $\mathrm{order}$ – string (length ≥ 1)
If ${\mathbf{order}}=\text{'A'}$, the values will be sorted into ASCII order.
If ${\mathbf{order}}=\text{'R'}$, into reverse ASCII order.
Constraint: ${\mathbf{order}}=\text{'A'}$ or $\text{'R'}$.

### Optional Input Parameters

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

### Output Parameters

1:     $\mathrm{ch}\left({\mathbf{m2}}\right)$ – cell array of strings
These values are rearranged into sorted order.
2:     $\mathrm{ifail}$int64int32nag_int scalar
${\mathbf{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:
${\mathbf{ifail}}=1$
 On entry, ${\mathbf{m2}}<1$, or ${\mathbf{m1}}<1$, or ${\mathbf{m1}}>{\mathbf{m2}}$, or ${\mathbf{l2}}<1$, or ${\mathbf{l1}}<1$, or ${\mathbf{l1}}>{\mathbf{l2}}$, or ${\mathbf{l2}}>\mathrm{LEN}\left({\mathbf{ch}}\left(1\right)\right)$.
${\mathbf{ifail}}=2$
 On entry, order is not 'A' or 'R'.
${\mathbf{ifail}}=3$
 On entry, the length of each element of ch exceeds $255$.
${\mathbf{ifail}}=-99$
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

## Accuracy

Not applicable.

The average time taken by the function is approximately proportional to $n×\mathrm{log}\left(n\right)$, where $n={\mathbf{m2}}-{\mathbf{m1}}+1$. The worst case time is proportional to ${n}^{2}$, but this is extremely unlikely to occur.
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 sorts them into reverse ASCII order on characters $7$ to $12$.
```function m01cc_example

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

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';
[ch, ifail] = m01cc(ch, m1, l1, l2, order);

fprintf('Records sorted on columns %2d to %2d:\n\n',l1,l2);
for j=1:numel(ch)
fprintf('%s\n',char(ch{j}));
end

```
```m01cc example results

Records sorted on columns  7 to 12:

C05AZF  2181
C02AEF   599
A02ACF   531
A02ABF   523
A02AAF   289
C05AGF   240
C05AVF   211
C05AXF   183