Sort and SortNew (Stringlist methods)

From m204wiki
Jump to navigation Jump to search

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.
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:
CHCharacter format. The default.
FIFixed point format. Must have length 1, 2, 3, or 4.
FLFloating point format. Must have length 4, 8, or 16.
PDPacked decimal format. Must have length between 1 and 16, inclusive.
ZDZoned 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 already associated with an image via BindImage, 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.

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.
%outList A reference to the newly created, sorted Stringlist.

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')

See also