Sort and SortNew (Stringlist methods)

Sort and SortNew are a members of the Stringlist class.

Sort is a subroutine that replaces the current contents of the method Stringlist with the sorted items. SortNew is a function that creates a new Stringlist that contains the sorted items.

Sort and SortNew Syntax

sl:Sort( sortOrder, [pad]) Throws InvalidSortSpecification

%outList = sl:SortNew( sortOrder, [pad]) Throws InvalidSortSpecification

Syntax Terms

%sl

A Stringlist object.

%outlist

A reference to the newly created, sorted Stringlist.

sortorder

A string that specifies the sort order. The sort order is a character string that contains blank-separated triplets and/or quadruplets. The triplets are made up of a start column, length, and a letter "A" for ascending or "D" for descending (see below for note about sorting using an implied CENTSPAN of 1975). The quadruplets are made up of a start column, length, format, and a letter "A" for ascending or "D" for descending (see below for note about sorting using an implied CENTSPAN of 1975). The format in the quadruplets may be:

CH

Character format. The default.

FI

Fixed point format. Must have length 1, 2, 3, or 4.

FL

Floating point format. Must have length 4, 8, or 16.

PD

Packed decimal format. Must have length between 1 and 16, inclusive.

ZD

Zoned decimal format. Must have length between 1 and 16, inclusive.

While blanks separate consecutive triplets and quadruplets, the entities within a triplet or quadruplet must be separated by commas. For example, specifying a sort order of "1,10,A 18,4,FI,D" would result in a Stringlist being sorted in ascending order based on columns 1 through 10 and descending order based on a signed fixed point comparison of columns 18 through 21. For Stringlists that are associated with an image via BindImage (Stringlist function), the start column and length in any triplet and the start column, length, and format in any quadruplet can be replaced by the name of an image item in the associated image.

This argument is case sensitive. That is, in the likely event the User Language was written in mixed case, with automatic upper-casing in effect (see Mixed-case User Language}, any image names should be in uppercase. And, in any case, the sort formats and order must be in uppercase.

pad

A string that specifies the pad character to be used to extend (for comparison purposes only) any %sl list items that are shorter than the end of a sort column range.

Usage Notes

• All errors in Sort and SortNew result in request cancellation.
• For Sort, the method discards the original contents of the Stringlist after the sort is completed. So, in the following example, the results of the first sort are lost since the same Stringlist is immediately sorted to a different order.

  %list:sort('1,24,A')
  %list:sort('1,24,D')
  

• If you are sorting 2-digit year dates, you can use a CENTSPAN of 1975 to sort the dates by appending the letter "C" to the third item ("A" or "D") in the sort field specification.
• SortNew and Sort use any specified image item's format for comparison. For example, if the image item Weight is specified as part of the sort criteria, and Weight is defined as a Float type image item, a floating point comparison of the values is performed. Type-specific comparison is done for Float, Binary, Packed, and Zoned image items. Generally, the type-specific comparisons produce the same results as a character comparison unless some of the values are negative.
• If the method Stringlist was associated with an image, by either the BindImage or New method, the SortNew output Stringlist is associated with the same image, as if a BindImage method had been invoked on the result of the SortNew method.

Examples

The following is an example of using an image item name in a sort criterion.

image surgery
procedure is string len 16
dept is string len 5
code is string len 6
cost is binary
end image

prepare image surgery
%list = new('SURGERY')
...
%outlist = %list:sortNew('DEPT,A COST,D')