Ascending and Descending (SortOrder functions): Difference between revisions

From m204wiki
Jump to navigation Jump to search
 
(17 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{Template:SortOrder:Ascending and Descending subtitle}}
{{Template:SortOrder:Ascending and Descending subtitle}}


These shared methods create a new instance of the SortOrder class.
These [[Notation conventions for methods#Shared members|shared methods]] create a new instance of the <var>SortOrder</var> class. The ordering direction of the new instance is given by the method name:
The ordering direction of the new instance is given by the constructor name:
<var>Ascending</var> is low-to-high; <var>Descending</var> is high-to-low.
Ascending is low-to-high; Descending is high-to-low.


The sorting key of the new instance is specified by the input parameter
The sorting key of the new instance is specified by the input parameter
to the constructor.
to the method.
This parameter is a function that gets
This parameter is a function that gets
applied to each item in the collection that is being sorted, and it must be
applied to each item in the collection that is being sorted, and it must be
a method that operates on the item type and returns a User Language intrinsic
a method that operates on the item type and returns a <var class="product">User Language</var> intrinsic
datatype (Float, String, Longstring, or Unicode) value.
datatype (<var>Float</var>, <var>String</var>, <var>Longstring</var>, or <var>Unicode</var>) value.
===Ascending/Descending syntax===
 
==Ascending/Descending syntax==
{{Template:SortOrder:Ascending syntax}}
{{Template:SortOrder:Ascending syntax}}
{{Template:SortOrder:Descending syntax}}
{{Template:SortOrder:Descending syntax}}


  %sord = [%(sortorder for itemtype):] Ascending(function)
===Syntax terms===
<table class="syntaxTable">
<tr><th>%sortOrder</th>
<td>A <var>SortOrder</var> object variable to contain the new object instance. </td></tr>
<tr><th nowrap="true"><var>[%(SortOrder For </var>itemType<var>)]</var>
<td>This optional specification of the class in parentheses denotes a [[Notation conventions for methods#Constructors|virtual constructor]]. See [[#Usage notes|"Usage notes"]], below, for more information about invoking a <var>SortOrder</var> virtual constructor.  </td></tr>
<tr><th>itemFunction</th>
<td>A method value (a method name literal, a method variable, a class <var>Variable</var>, or even a method that returns a method value) for a method that operates on objects of the type specified on the declaration of the collection being sorted, and that returns a numeric or string value.
<p>
The default <var class="term">itemFunction</var> value as of <var class="product">Sirius Mods</var> version 7.6 is the special value <var>This</var>, described further in the "Usage Notes," below. </p></td></tr>
</table>


  %sord = [%(sortorder for itemtype):] Descending(function)
==Usage Notes==
===Syntax terms===
<ul>
<dl>
<li>As described in [[Object variables#Virtual Constructor methods|"Virtual Constructor methods"]], <var>Ascending</var> and <var>Descending</var> can be invoked with
<dt><i>%sord</i>
no method object, with an explicit class specification, or with an object variable of the class,
<dd>A SortOrder object variable to contain the new object instance.
even if that object is <var>Null</var>:
<dt><i>%(sortorder for itemtype)</i>
<p class="code">%sord = Descending(<i>itemFunction</i>)
<dd>This optional specification of the class and collection item type
in parentheses indicates
that the method is shared and does not operate on a specific instance.
<dt><i>function</i>
<dd>A method value (a method name literal, a method variable, a class Variable,
or even a method that returns a method value) for a method
that operates on objects of the type specified on the
declaration of the collection being sorted, and that returns a numeric or
string value.


The default ''function'' value as of ''Sirius Mods'' version 7.6
%sord = %(SortOrder for <i>itemType</i>):Descending(<i>itemFunction</i>)
is the special value <tt>This</tt>,
described further in the &ldquo;Usage Notes,&rdquo; below.


</dl>
%sord = %sord:Descending(<i>itemFunction</i>)
===Usage Notes===
</p>
<ul>
'''Note:'''
<li>For more information about the ''function'' parameter,
As shown in the second of these above, if you explicitly specify the
see [[SortOrder class#Specifying a SortOrder's sort key method|Specifying a SortOrder's sort key method]].
class name, you must include the item datatype of the collection to be sorted, just as on a <var>SortOrder</var> object variable's [[SortOrder class#Declaring a SortOrder object variable|declaration]].
<li>Ascending and Descending are constructors and as such can be called with
<li>For more information about the <var class="term">itemFunction</var> parameter,
no method object, with an explicit class name, or with an object variable,
see [[SortOrder class#Specifying a SortOrder's sort key method|"Specifying a SortOrder's sort key method"]].
even if that object is null:
The parameter is a method value, not a <var class="product">User Language</var> expression,
<pre>
    %sord = Descending(&'italic(function))
    %sord = %(sortorder for float):Descending(&'italic(function))
    %sord = %sord:Descending(&'italic(function))
</pre>
<li>The Ascending or Descending parameter is a method value, not a User Language expression,
and you may not specify a function that itself has an argument.
and you may not specify a function that itself has an argument.
In order to do this, see the [[SortOrder class#xmplocal|example using a Local function]], which shows a way to apply such a function
In order to do this, see the [[SortOrder class#xmplocal|example using a Local function]], which shows a way to apply such a function in a sort.
in a sort.
<li>As of <var class="product">Sirius Mods</var> version 7.6, the
<li>As of ''Sirius Mods'' version 7.6, the
default <var>SortOrder</var> <var class="term">itemFunction</var> value is <var>This</var>, a
default SortOrder ''function'' value is <tt>This</tt>, a
method value that is valid for <var class="product">User Language</var> [[Intrinsic classes#Two generic intrinsic classes: string and numeric|intrinsic]] method objects only.
method value that is valid for User Language intrinsic method objects only.
The identity method <var>This</var> returns the value of the
The identity method <tt>This</tt> returns the value of the
method object to which it is applied.
method object to which it is applied.


The following statements are therefore equivalent:
The following statements are therefore equivalent:
<pre>
<p class="code">%sortOrder = Descending(this)
    %sord = Descending(this)
%sortOrder = Descending
    %sord = Descending
</p>
</pre>
'''Note:'''
'''Note:'''
Using the default SortOrder above on a non-intrinsic method object
Using the default <var>SortOrder</var> above on a non-intrinsic method object
produces a compilation error.
produces a compilation error.
</ul>
</ul>


==See also==
{{Template:SortOrder:Ascending and Descending footer}}
{{Template:SortOrder:Ascending and Descending footer}}
[[Category:SortOrder methods]]

Latest revision as of 02:25, 3 April 2015

Create SortOrder object to sort in ascending or descending order (SortOrder class)


These shared methods create a new instance of the SortOrder class. The ordering direction of the new instance is given by the method name: Ascending is low-to-high; Descending is high-to-low.

The sorting key of the new instance is specified by the input parameter to the method. This parameter is a function that gets applied to each item in the collection that is being sorted, and it must be a method that operates on the item type and returns a User Language intrinsic datatype (Float, String, Longstring, or Unicode) value.

Ascending/Descending syntax

%sortOrder = [%(SortOrder For itemType):]Ascending[( [itemFunction])]

%sortOrder = [%(SortOrder For itemType):]Descending[( [itemFunction])]

Syntax terms

%sortOrder A SortOrder object variable to contain the new object instance.
[%(SortOrder For itemType)] This optional specification of the class in parentheses denotes a virtual constructor. See "Usage notes", below, for more information about invoking a SortOrder virtual constructor.
itemFunction A method value (a method name literal, a method variable, a class Variable, or even a method that returns a method value) for a method that operates on objects of the type specified on the declaration of the collection being sorted, and that returns a numeric or string value.

The default itemFunction value as of Sirius Mods version 7.6 is the special value This, described further in the "Usage Notes," below.

Usage Notes

  • As described in "Virtual Constructor methods", Ascending and Descending can be invoked with no method object, with an explicit class specification, or with an object variable of the class, even if that object is Null:

    %sord = Descending(itemFunction) %sord = %(SortOrder for itemType):Descending(itemFunction) %sord = %sord:Descending(itemFunction)

    Note: As shown in the second of these above, if you explicitly specify the class name, you must include the item datatype of the collection to be sorted, just as on a SortOrder object variable's declaration.

  • For more information about the itemFunction parameter, see "Specifying a SortOrder's sort key method". The parameter is a method value, not a User Language expression, and you may not specify a function that itself has an argument. In order to do this, see the example using a Local function, which shows a way to apply such a function in a sort.
  • As of Sirius Mods version 7.6, the default SortOrder itemFunction value is This, a method value that is valid for User Language intrinsic method objects only. The identity method This returns the value of the method object to which it is applied. The following statements are therefore equivalent:

    %sortOrder = Descending(this) %sortOrder = Descending

    Note: Using the default SortOrder above on a non-intrinsic method object produces a compilation error.

See also

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=Ascending_and_Descending_(SortOrder_functions)&oldid=76841"