|
|
| Line 1: |
Line 1: |
| <span style="font-size:120%; color:black"><b><section begin=dpl_desc/>Sort UnicodeNamedArraylist, return Arr<section end=dpl_desc/></b></span>
| | #REDIRECT [[SortNew (GenericNamedArraylist function)]] |
| [[Category:UnicodeNamedArraylist methods|SortNew function]]
| |
| <!--DPL?? Category:UnicodeNamedArraylist methods|SortNew function: Sort UnicodeNamedArraylist, return Arr-->
| |
| <p>
| |
| SortNew is a member of the [[UnicodeNamedArraylist class]].
| |
| </p>
| |
| | |
| This function sorts the method object UnicodeNamedArraylist and returns the sorted result
| |
| in a new Arraylist.
| |
| The sort is based on one or more sort criteria which consist of
| |
| a sorting direction (ascending or descending) paired with a sort key
| |
| (a function that gets applied to each UnicodeNamedArraylist item).
| |
| Each sort criterion pair is a [[SortOrder class|SortOrder]] object,
| |
| and multiple pairs are a SortOrder collection.
| |
| | |
| The sort key function that gets applied to each UnicodeNamedArraylist item, which
| |
| you identify in the SortNew parameter, must
| |
| operate on the item type and return a User Language intrinsic
| |
| datatype (Float, String, Longstring, or Unicode) value.
| |
| The values returned by the function are sorted into ascending or descending order
| |
| to determine the position of their associated item in the new Arraylist.
| |
| | |
| The system intrinsic classes are discussed in "[[Intrinsic classes]]".
| |
| ==Syntax==
| |
| %arlnew = %unamrayl:SortNew(sortCriteria)
| |
| ===Syntax Terms===
| |
| <dl>
| |
| <dt><i>%arlnew</i>
| |
| <dd>An Arraylist object to contain the sorted ''%unamrayl'' items.
| |
| <dt><i>%unamrayl</i>
| |
| <dd>The input UnicodeNamedArraylist object.
| |
| <dt><i>sortCriteria</i>
| |
| <dd>One or more SortOrder objects, which consist of an ordering direction for
| |
| the sort and a key to sort by, specified in the form: <tt>order(key)</tt>.
| |
| The order is either <tt>Ascending</tt> or <tt>Descending</tt>, and
| |
| the key is a function that is applied to each item in the Arraylist.
| |
| For example:
| |
| <pre style="xmp">
| |
| %alist = %unamray:sortnew(descending(length))
| |
| </pre>
| |
| | |
| The function is
| |
| a method value (a method or class member name literal, or a method variable)
| |
| for a method
| |
| that operates on objects of the type specified on the ''%unamrayl''
| |
| declaration and that returns a numeric or string value.
| |
| This is described further in "[[SortOrder class#Specifying a SortOrder's sort key method|Specifying a SortOrder's sort key method]]".
| |
| | |
| </dl>
| |
| ==Usage Notes==
| |
| <ul>
| |
| <li>If the function applied by SortNew returns string values, SortNew
| |
| uses the decimal-equivalent value of the character bytes to determine
| |
| the ascending or descending alphabetic order of the associated
| |
| UnicodeNamedArraylist items.
| |
| In ascending order,
| |
| the highest or last lowercase letter is “z”;
| |
| the highest or last uppercase letter is “Z”;
| |
| “z” ranks lower than all the uppercase letters;
| |
| and all letters rank lower than any number.
| |
| <li>If two or more UnicodeNamedArraylist items have equal values after all sort criteria
| |
| are applied, SortNew returns them in the same order in which they appear in the
| |
| input UnicodeNamedArraylist.
| |
| <li>The function in the parameter for SortNew is a method value, not a User Language expression.
| |
| That is, you cannot provide a function that itself has an argument
| |
| (say, <tt>Char(13)</tt>) as the SortNew parameter.
| |
| <li>As of ''Sirius Mods'' version 7.6, the default ''sortCriteria'' argument is
| |
| the SortOrder <tt>Ascending(This)</tt>,
| |
| where <tt>This</tt> is the identity function described further
| |
| in "[[Collections#Using the This function as the Maximum parameter|Using the This function as the Maximum parameter]]".
| |
| Therefore, <tt>%unamrayl:sortnew(ascending(this)</tt> can be
| |
| specified simply as <tt>%unamrayl:sortnew</tt>.
| |
| See the [[SortNew (Arraylist function)#Examples|SortNew example]].
| |
| </ul>
| |
| ==Examples==
| |
| <ul>
| |
| <li>For an example using the SortNew method, see [[UnicodeNamedArraylist class]].
| |
| </ul>
| |