Sorting

The sort method

The IMu::Module class sort method is used to order a set of matching records once the search of a module has been run.

Arguments

This sort method takes two arguments:

columns
The columns argument is used to specify the columns by which to sort the result set. The value of the argument can be either a string or a reference to an array of strings. Each string can be a simple column name or a set of column names, separated by semi-colons or commas.

Each column name can be preceded by a + (plus) or - (minus or dash). A leading + indicates that the records should be sorted in ascending order. A leading - indicates that the records should be sorted in descending order.

Note: If a sort order ("+" or "-") is not given, the sort order defaults to ascending.
flags
The flags argument is used to pass one or more flags to control the way the sort is carried out. As with the columns argument, the flags argument can be a string or a reference to an array of strings. Each string can be a single flag or a set of flags separated by semi-colons or commas.

The following flags control the type of comparisons used when sorting:
- word-based
  Sort disregards all punctuation and white spaces (more than the one space between words). For example:
```
Traveler's        Inn
```
  will be sorted as
```
Travelers Inn
```
- full-text
  Sort includes all punctuation and white spaces. For example:
```
Traveler's        Inn
```
  will be sorted as
```
Traveler's        Inn
```
  and will therefore differ from:
```
Traveler's Inn
```
- compress-spaces
  Sort includes punctuation but disregards all white space (with the exception of a single space between words). For example:
```
Traveler's        Inn
```
  will be sorted as
```
Traveler's Inn
```
  Note: If none of these flags is included, the comparison defaults to word-based.
The following flags modify the sorting behaviour:
- case-sensitive
  Sort is sensitive to upper and lower case. For example:
```
Melbourne gallery
```
  will be sorted separately to
```
Melbourne Gallery
```
- order-insensitive
  Values in a multi-value field will be sorted alphabetically regardless of the order in which they display. For example, a record which has the following values in the NamRoles_tab column in this order:
```
1. Collection Manager
2. Curator
3. Internet Administrator
```
  and another record which has the values in this order:
```
1. Internet Administrator
2. Collection Manager
3. Curator
```
  will be sorted the same.
- null-low
  Records with empty columns will be placed at the start of the result set rather than at the end.
- extended-sort
  Values that include diacritics will be sorted separately to those that do not. For example:
```
entrée
```
  will be sorted separately to
```
entree
```
The following flags can be used when generating a summary of the sorted records:
- report
  A summary of the sort is generated. The summary report is a hierarchically structured object that summarises the number of unique values contained in the sort columns. See Return Value and Example for a description and illustration of the returned structure.
- table-as-text
  All data from multi-valued columns will be treated as a single value (joined by line break characters) in the summary results array. For example, for a record which has the following values in the NamRoles_tab column:
  
  Collection Manager, Curator, Internet Administrator
  
  the summary will include statistics for a single value:
  
  Collection Manager
  Curator
  Internet Administrator
  
  Thus the number of values in the summary results display will match the number of records.
  
  If this option is not included, each value in a multi-valued column will be treated as a distinct value in the summary. Thus there may be many more values in the summary results than there are records.

For example:

Sort parties by first name (ascending):

my $parties = IMu::Module->new('eparties', $session);
my $search = IMu::Terms->new();
$search->add('NamLast', 'Smith');
my $hits = $parties->findTerms($search);

$parties->sort('NamFirst');

Sort parties by title (ascending) and then first name (descending):

# ⋯
my $sort =
[
    'NamTitle',
    '-NamFirst'
];
$parties->sort($sort);

Run a case-sensitive sort of parties by title (ascending) and then first name (descending):

# ⋯my $sort =
[
    'NamTitle',
    '-NamFirst'
];
my $flags =
[
    'case-sensitive'
];
$parties->sort($sort, $flags);

Example

This example shows a three-level sort by title, last name (descending) and first name on a set of Parties records:

my $parties = IMu::Module->new('eparties', $session);

my $terms = IMu::Terms->new('or');
$terms->add('NamLast', 'Smith');
$terms->add('NamLast', 'Wood');

my $hits = $parties->findTerms($terms);

my $sort =
[
    'NamTitle',
    '-NamLast',
    'NamFirst'
];
my $flags =
[
    'full-text',
    'report'
];
my $report = $parties->sort($sort, $flags);
showSummary($report, 0);
exit(0);

sub showSummary
{
    my $report = shift;
    my $indent = shift;

    if (! defined($report))
    {
        return;
    }
    my $prefix = '  ' x $indent;

    foreach my $term (@$report)
    {
        my $value = $term->{'value'};
        my $count = $term->{'count'};
        printf("%s%s (%d)\n", $prefix, $value, $count);

        my $list = $term->{'list'};
        showSummary($list, $indent + 1);
    }
}

This displays the distinct terms (and their counts) for the primary sort key (title). Nested under each primary key is the set of distinct terms and counts for the secondary key (last name) and nested under each secondary key is the set of distinct terms and counts for the tertiary key (first name):

Mr (2)

Wood (1)

  Gerard (1)

SMITH (1)

  Ian (1)

Ms (1)

ECCLES-SMITH (1)

  Kate (1)

Sir (1)

Wood (1)

  Henry (1)

(3)

Wood (1)

  Grant (1)

Smith (2)

Sophia (1)

William (1)

If another sort key was specified its terms would be nested under the tertiary key and so on.

Note: In the example above some of the records do not have a value for the primary sort key (title). By default these values are sorted after any other values. They can be sorted before other values using the null-low flag.