Sort and SortNew (Stringlist methods)
Sort the contents of a Stringlist (Stringlist class)
Sort replaces the current contents of the method Stringlist with the sorted items. Since it does not return anything, this means that Sort is a subroutine.
SortNew creates a new Stringlist that contains the sorted items. Since it returns a reference to the Stringlist with the sorted items, this means that SortNew is a function.
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:
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 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. If this argument is invalid, an InvalidSortSpecification exception is thrown. | ||||||||||
| 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
Cto the third item (AorD) 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')