View source for Sort and SortNew (Stringlist methods)

{{Template:Stringlist:Sort and SortNew subtitle}}
<var>Sort</var> replaces the current contents of the method <var>Stringlist</var> with the sorted items. Since it does not return anything, this means that <var>Sort</var> is a subroutine.

<var>SortNew</var> creates a new <var>Stringlist</var> that contains the sorted items. Since it returns a reference to the <var>Stringlist</var> with the sorted items, this means that <var>SortNew</var> is a function.

==Syntax==
{{Template:Stringlist:Sort syntax}}
{{Template:Stringlist:SortNew syntax}}
===Syntax terms===
<table class="syntaxTable">
<tr><th>sl</th>
<td>A <var>Stringlist</var> object.</td></tr>

<tr><th>sortOrder</th>
<td>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 <code>A</code> for ascending or <code>D</code> for descending (see below for note about sorting using an implied <var>[[CENTSPAN parameter|CENTSPAN]]</var> of 1975). The quadruplets are made up of a start column, length, format, and a letter <code>A</code> for ascending or <code>D</code> for descending (see below for note about sorting using an implied <var>CENTSPAN</var> of 1975). The format in the quadruplets may be:
<table>
<tr><th><var>CH</var></th><td>Character format. The default.</td></tr>
<tr><th><var>FI</var></th><td>Fixed point format. Must have length 1, 2, 3, or 4.</td></tr>
<tr><th><var>FL</var></th><td>Floating point format. Must have length 4, 8, or 16.</td></tr>
<tr><th><var>PD</var></th><td>Packed decimal format. Must have length between 1 and 16, inclusive.</td></tr>
<tr><th><var>ZD</var></th><td>Zoned decimal format. Must have length between 1 and 16, inclusive.</td></tr>
</table>
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 <code>1,10,A 18,4,FI,D</code> would result in a <var>Stringlist</var> 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 <var>Stringlists</var> that are already associated with an image via <var>[[BindImage (Stringlist function)|BindImage]]</var>, 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 <var class="product">User Language</var> was written in mixed case, with automatic upper-casing in effect (see [[Mixed-case SOUL]]}, 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 <var>[[InvalidSortSpecification class|InvalidSortSpecification]]</var> exception is thrown.</td></tr>
<tr><th>pad</th>
<td>A string that specifies the pad character to be used to extend (for comparison purposes only) any <var class="term">sl</var> list items that are shorter than the end of a sort column range. </td></tr>

<tr><th>%outList</th>
<td>A reference to the newly created, sorted <var>Stringlist</var>.</td></tr>
</table>

==Usage notes==
<ul><li>All errors in <var>Sort</var> and <var>SortNew</var> result in request cancellation.<li>For <var>Sort</var>, the method discards the original contents of the <var>Stringlist</var> after the sort is completed.  So, in the following example, the results of the first sort are lost since the same <var>Stringlist</var> is immediately sorted to a different order.
<p class="output">%list:sort('1,24,A')
%list:sort('1,24,D')
</p>

<li>If you are sorting 2-digit year dates, you can use a <var>[[CENTSPAN parameter|CENTSPAN]]</var> of 1975 to sort the dates by appending the letter <code>C</code> to the third item (<code>A</code> or <code>D</code>) in the sort field specification.<li><var>SortNew</var> and <var>Sort</var> use any specified <var>Image</var> item's format for comparison. For example, if the <var>Image</var> item <code>Weight</code> is specified as part of the sort criteria, and <code>Weight</code> is defined as a <var>Float</var> type image item, a floating point comparison of the values is performed. Type-specific comparison is done for <var>Float</var>, <var>Binary</var>, <var>Packed</var>, and <var>Zoned</var> image items. Generally, the type-specific comparisons produce the same results as a character comparison unless some of the values are negative.

<li>If the method <var>Stringlist</var> was associated with an <var>Image</var>, by either the <var>BindImage</var> or <var>[[New (Stringlist constructor)|New]]</var> method, the <var>SortNew</var> output <var>Stringlist</var> is associated with the same image, as if a <var>BindImage</var> method had been invoked on the result of the <var>SortNew</var> method.
</ul>

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

<p class="code">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')
</p>

==See also==
{{Template:Stringlist:Sort and SortNew footer}}