SortOrder class: Difference between revisions

From m204wiki
Jump to navigation Jump to search
 
(18 intermediate revisions by 4 users not shown)
Line 1: Line 1:
Objects in the SortOrder class are used primarily as input to the
Objects in the <var>SortOrder</var> class are used primarily as input to the
collection class sorting methods (SortNew in the Arraylist and NamedArraylist
[[Collections|collection class]] sorting methods (<var>[[SortNew (Arraylist function)|SortNew]]</var> in the <var>Arraylist</var> and <var>NamedArraylist</var>
classes and Sort in the Arraylist class).
classes and <var>[[Sort (Arraylist subroutine)|Sort]]</var> in the <var>Arraylist</var> class).
The SortNew and Sort methods take a SortOrder object as a parameter which provides
The <var>SortNew</var> and <var>Sort</var> methods take a <var>SortOrder</var> object as a parameter which provides
sorting criteria for the sort.
sorting criteria for the sort.
The <var>SortOrder</var> class is new as of <var class="product">Sirius Mods</var> version 7.3.
   
   
A SortOrder object consists of two kinds of information:
==Overview==
A <var>SortOrder</var> object consists of two kinds of information:
<ul>
<ul>
<li>A sort ordering direction (ascending or descending)
<li>A sort ordering direction (Ascending or Descending)
<li>A sort key (function on the items in the list being sorted)
<li>A sort key (function on the items in the list being sorted)
</ul>
</ul>
   
   
For a sort in ascending order by price for the items in a <tt>%orders</tt>
For a sort in ascending order by price for the items in a <code>%orders</code>
Arraylist, you might specify:
<var>Arraylist</var>, you might specify:
<pre>
<p class="code">%orders = %orders:SortNew(ascending(price))
    %orders = %orders:SortNew(ascending(price))
</p>
</pre>
   
   
where [[Ascending and Descending (SortOrder constructors)|<tt>ascending</tt>]] is a SortOrder constructor with parameter <tt>price</tt>, a method defined
where <var>[[Ascending and Descending (SortOrder functions)|Ascending]]</var> is a <var>SortOrder</var> constructor with parameter <code>price</code>, a method defined
to operate on the items in %orders.
to operate on the items in <code>%orders</code>.
   
   
The Price method above is applied to each of the items in %orders, and the resulting
The <code>price</code> method above is applied to each of the items in <code>%orders</code>, and the resulting
values are sorted in ascending order, alphabetically or numerically according to
values are sorted in ascending order, alphabetically or numerically according to
the Price return value type.
the <code>price</code> return value type.
Price must return an intrinsic (number, string, unicode) value.
<code>price</code> must return an [[Intrinsic classes|intrinsic]] (number, string, unicode) value.
For more about the method in a SortOrder, see "[[#Specifying a SortOrder's sort key method|Specifying a SortOrder's sort key method]]" below..
For more about the method in a <var>SortOrder</var>, see [[#Specifying a SortOrder's sort key method|"Specifying a SortOrder's sort key method"]] below.
   
   
If <tt>%sord</tt> is a SortOrder instance returned by the Ascending constructor
If <code>%sord</code> is a <var>SortOrder</var> instance returned by the <var>Ascending</var> constructor
with the <tt>price</tt> method as argument:
with the <code>price</code> method as argument:
<pre>
<p class="code">%sord = Ascending(price)
    %sord = Ascending(price)
</p>
</pre>
   
   
Then the SortNew statement above is equivalent to the following:
Then the <var>SortNew</var> statement above is equivalent to the following:
<pre>
<p class="code">%orders = %orders:SortNew(%sord)
    %orders = %orders:SortNew(%sord)
</p>
</pre>
   
   
To provide multiple sort criteria for a sort,
To provide multiple sort criteria for a sort,
a SortOrder object may be a collection of multiple SortOrders.
a <var>SortOrder</var> object may be a collection of multiple <var>SortOrder</var>s.
However, to construct such a SortOrder collection,
However, to construct such a <var>SortOrder</var> collection,
you must use the SortOrder class [[List (SortOrder constructor)|List constructor ]].
you must use the <var>SortOrder</var> class <var>[[List (SortOrder function)|List]]</var> constructor.
List takes SortOrders as inputs and returns a SortOrder object that contains them.
<var>List</var> takes <var>SortOrder</var>s as inputs and returns a <var>SortOrder</var> object that contains them.
   
   
For example, to sort in ascending order by quantity and price for <tt>%orders</tt>:
For example, to sort in ascending order by quantity and price for <code>%orders</code>:
<pre>
<p class="code">%sord = List(ascending(quantity), descending(price))
    %sord = List(ascending(quantity), descending(price))
%orders = %orders:SortNew(%sord)
    %orders = %orders:SortNew(%sord)
</p>
</pre>
   
   
The SortOrder object in the preceding example contains two sort criteria;
The <var>SortOrder</var> object in the preceding example contains two sort criteria;
you may specify as many as seven.
you may specify as many as seven.
 
===SortOrder object variable declaration syntax===
==Declaring a SortOrder object variable==
  <objvar> Is Object SortOrder For <itemtype>
The syntax for declaring a <var>SortOrder</var> object variable is:
<p class="syntax"><span class="term">objvar</span> <span class="literal">Is Object SortOrder For</span> <span class="term">itemtype</span></p>
   
   
Where:
Where:
<dl>
<table class="syntaxTable">
<dt><objvar>
<tr><th>objvar</th>
<dd>The name of the SortOrder object variable.
<td>The name of the <var>SortOrder</var> object variable. </td></tr>
<dt><itemtype>
 
<dd>The datatype of the items in the collection to be sorted.
<tr><th>itemtype</th>
</dl>
<td>The datatype of the items in the collection to be sorted. </td></tr>
</table>
   
   
SortOrders are immutable objects.
==Assigning a SortOrder object variable==
You can assign a sort order to a SortOrder object:
<var>SortOrder</var>s are immutable objects.
<pre>
You can assign a sort order to a <var>SortOrder</var> object:
    %myOrder is object sortOrder for longstring
<p class="code">%myOrder is object sortOrder for longstring
    ...
...
    %myorder = ascending(length)
%myorder = ascending(length)
</pre>
</p>
   
   
But thereafter you cannot modify the object &mdash;
But thereafter you cannot modify the object &mdash;
although, you may assign a different value to a SortOrder object variable:
although, you may assign a different value to a <var>SortOrder</var> object variable:
<pre>
<p class="code">%myorder = ascending(length)
    %myorder = ascending(length)
...
    ...
%myorder = descending(reverse)
    %myorder = descending(reverse)
</p>
</pre>
 
==Specifying a SortOrder's sort key method==
The SortOrder class is new as of ''Sirius Mods'' version 7.3.
The following examples show different method types, actually "method values,"
====Specifying a SortOrder's sort key method====
as the sort key in a <var>SortOrder</var>.
The following examples show different method types, actually &ldquo;method values,&rdquo;
as the sort key in a SortOrder.
A method value is a value assigned to a [[Method variables|method variable]].
A method value is a value assigned to a [[Method variables|method variable]].
And for a SortOrder, the method variable's implicit declaration is:
And for a <var>SortOrder</var>, the method variable's implicit declaration is:
<pre>
<p class="syntax"><span class="literal">Is Function</span> (<span class="term">itemtype</span>):<span class="term">methname</span> <span class="literal">Is</span> <span class="term">intrinType</span>
    Is Function (<itemtype>):<methname> Is <intrinType>
</p>
</pre>
Where:
Where:
<dl>
<table class="syntaxTable">
<dt><itemtype>
<tr><th>itemtype</th>
<dd>The class of the items in the collection to be sorted.
<td>The class of the items in the collection to be sorted. </td></tr>
<dt><methname>
<tr><th>methname</th>
<dd>A method name, but merely a placeholder in an actual declaration.
<td>A method name, but merely a placeholder in an actual declaration.
Any method (system or user), class
Any method (system or user), class Variable or Property, local method, or method variable that fits the declaration can be used in the <var>SortOrder</var>. </td></tr>
Variable or Property, local method, or method variable that fits the
<tr><th>intrinType</th>
declaration can be used in the SortOrder.
<td>A <var class="product">User Language</var> [[Intrinsic classes#Intrinsic methods in User Language|intrinsic class]] type returned by the function. </td></tr>
<dt><intrinType>
</table>
<dd>A User Language [[Intrinsic Classes#Intrinsic methods in User Language|intrinsic class]] type returned by the function.
</dl>
   
   
In the examples below, the method values are respectively a class Variable,
In the examples below, the method values are respectively a class variable,
a method variable, a local method, and a special method value, all of which
a method variable, a local method, and the special method value <var>This</var>, all of which
satisfy the Function template described above.
satisfy the <var>Function</var> template described above.
<ol>
<ol>
<li>The sortorder in the following example specifies a class Variable
<li>The <var>SortOrder</var> in the following example specifies a class variable
as the sort key:
as the sort key:
<pre>
<p class="code">class info
    class info
  public
      public
      variable name  is string len 32
          variable name  is string len 32
      variable rank  is float
          variable rank  is float
      variable serialnumber is string len 8
          variable serialnumber is string len 8
  end public
      end public
end class
    end class
...
    ...
%order  is object sortOrder for object info
    %order  is object sortOrder for info
...
    ...
%order = ascending(name)
    %order = ascending(name)
</p>
</pre>
 
<li>The following example outlines the use of a method variable
<li>The following example outlines the use of a method variable
as a SortOrder sort key.
as a <var>SortOrder</var> sort key.
Hypothetical user class <tt>Order</tt> has two Variables to sort its data by,
Hypothetical user class <code>Order</code> has two <var>Variables</var> to sort its data by,
and they are conditionally assigned to method variable <tt>%sortMethod</tt>.
and they are conditionally assigned to method variable <code>%sortMethod</code>.
<pre>
<p class="code"> ...
    ...
%sortMethod  is function (order):number is float
    %sortMethod  is function (order):number is float
...
    ...
If ..
    If ..
  %sortMethod = totalprice
      %sortMethod = totalprice
End if
    End if
If ..
    If ..
  %sortMethod = totalProductionCost
      %sortMethod = totalProductionCost
End if
    End if
...
    ...
%orders = %orders:sortnew(descending(%sortMethod))
    %orders = %orders:sortnew(descending(%sortMethod))
</p>
</pre>
 
<li>In this example, a Local method ([[??]] refid=localmd.) is used
<li><div id="xmplocal"></div>In this example, a [[Local and Common entities#Defining and invoking a local method|local method]] is used to accommodate a <var>SortOrder</var> function that requires a parameter.
to accommodate a SortOrder function that requires a parameter.
The <var>SortOrder</var> syntax does not provide for specifying a parameter for the
The SortOrder syntax does not provide for specifying a parameter for the
method parameter.
method parameter.
   
   
Say the <tt>totalPrice</tt> method is a function that
Say the <code>totalPrice</code> method is a function that
accepts a parameter ("clientRating")
accepts a parameter ("clientRating")
which is used in its calculation of the total price.
which is used in its calculation of the total price.
You can define a local method (<tt>tprice</tt>)
You can define a local method (<code>tprice</code>)
to be used in the SortOrder instead of totalPrice:
to be used in the <var>SortOrder</var> instead of <code>totalPrice</code>:
<pre>
<p class="code">%clientRating  is float
    %clientRating  is float
   
   
    local function tprice is float expose
local function (order):tprice is float expose
      return %this:totalprice(%clientRating)
  return %this:totalprice(%clientRating)
    end function
end function
   
   
    %orders = %orders:sortnew(descending(tprice))
%orders = %orders:sortnew(descending(tprice))
</pre>
</p>
   
   
If ClientRating was already a member of the Order class, you would specify:
If <code>ClientRating</code> was already a member of the Order class, you would specify:
<pre>
<p class="code">
    local function tprice is float
local function (order):tprice is float
      return %this:totalprice(%this:clientRating)
  return %this:totalprice(%this:clientRating)
    end function
end function
   
   
    %orders = %orders:sortnew(descending(tprice))
%orders = %orders:sortnew(descending(tprice))
</pre>
</p>
   
   
If <tt>tprice</tt> was used in many places, you could move it
If <code>tprice</code> was used in many places, you could move it
into the Order class without changing the Sort calls.
into the Order class without changing the <var>Sort</var> calls.
<li>The SortOrder in the following fragment uses the special method
 
value <tt>This</tt> as the sort key.
<li>The <var>SortOrder</var> in the following fragment uses the special method
Valid only when applied to User Language intrinsic method objects, <tt>This</tt>
value <var>This</var> as the sort key.
simply returns the value of the method object.
Valid only when applied to <var class="product">User Language</var> [[Intrinsic classes#Two generic intrinsic classes: string and numeric|intrinsic]] method objects, <var>This</var> simply returns the value of the method object.
<pre>
<p class="code"> ...
    ...
%foo  is arraylist of longstring
    %foo  is arraylist of longstring
%foosrt is arraylist of longstring
    %foosrt is arraylist of longstring
...
    ...
%foosrt = %foo:sortNew(ascending(this))
    %foosrt = %foo:sortNew(ascending(this))
...
    ...
%foo:sort(descending(this))
    %foo:sort(descending(this))
...
    ...
</p>
</pre>
   
   
<tt>This</tt> is the default method value as of ''Sirius Mods'' version 7.6.
<var>This</var> is the default method value as of <var class="product">Sirius Mods</var> version 7.6.
</ol>
</ol>
==List of SortOrder methods==
The [[List of SortOrder methods|"List of SortOrder methods"]] shows all the class methods.
[[Category:System classes]]
[[Category:System classes]]

Latest revision as of 15:35, 14 January 2016

Objects in the SortOrder class are used primarily as input to the collection class sorting methods (SortNew in the Arraylist and NamedArraylist classes and Sort in the Arraylist class). The SortNew and Sort methods take a SortOrder object as a parameter which provides sorting criteria for the sort.

The SortOrder class is new as of Sirius Mods version 7.3.

Overview

A SortOrder object consists of two kinds of information:

  • A sort ordering direction (Ascending or Descending)
  • A sort key (function on the items in the list being sorted)

For a sort in ascending order by price for the items in a %orders Arraylist, you might specify:

%orders = %orders:SortNew(ascending(price))

where Ascending is a SortOrder constructor with parameter price, a method defined to operate on the items in %orders.

The price method above is applied to each of the items in %orders, and the resulting values are sorted in ascending order, alphabetically or numerically according to the price return value type. price must return an intrinsic (number, string, unicode) value. For more about the method in a SortOrder, see "Specifying a SortOrder's sort key method" below.

If %sord is a SortOrder instance returned by the Ascending constructor with the price method as argument:

%sord = Ascending(price)

Then the SortNew statement above is equivalent to the following:

%orders = %orders:SortNew(%sord)

To provide multiple sort criteria for a sort, a SortOrder object may be a collection of multiple SortOrders. However, to construct such a SortOrder collection, you must use the SortOrder class List constructor. List takes SortOrders as inputs and returns a SortOrder object that contains them.

For example, to sort in ascending order by quantity and price for %orders:

%sord = List(ascending(quantity), descending(price)) %orders = %orders:SortNew(%sord)

The SortOrder object in the preceding example contains two sort criteria; you may specify as many as seven.

Declaring a SortOrder object variable

The syntax for declaring a SortOrder object variable is:

objvar Is Object SortOrder For itemtype

Where:

objvar The name of the SortOrder object variable.
itemtype The datatype of the items in the collection to be sorted.

Assigning a SortOrder object variable

SortOrders are immutable objects. You can assign a sort order to a SortOrder object:

%myOrder is object sortOrder for longstring ... %myorder = ascending(length)

But thereafter you cannot modify the object — although, you may assign a different value to a SortOrder object variable:

%myorder = ascending(length) ... %myorder = descending(reverse)

Specifying a SortOrder's sort key method

The following examples show different method types, actually "method values," as the sort key in a SortOrder. A method value is a value assigned to a method variable. And for a SortOrder, the method variable's implicit declaration is:

Is Function (itemtype):methname Is intrinType

Where:

itemtype The class of the items in the collection to be sorted.
methname A method name, but merely a placeholder in an actual declaration. Any method (system or user), class Variable or Property, local method, or method variable that fits the declaration can be used in the SortOrder.
intrinType A User Language intrinsic class type returned by the function.

In the examples below, the method values are respectively a class variable, a method variable, a local method, and the special method value This, all of which satisfy the Function template described above.

  1. The SortOrder in the following example specifies a class variable as the sort key:

    class info public variable name is string len 32 variable rank is float variable serialnumber is string len 8 end public end class ... %order is object sortOrder for object info ... %order = ascending(name)

  2. The following example outlines the use of a method variable as a SortOrder sort key. Hypothetical user class Order has two Variables to sort its data by, and they are conditionally assigned to method variable %sortMethod.

    ... %sortMethod is function (order):number is float ... If .. %sortMethod = totalprice End if If .. %sortMethod = totalProductionCost End if ... %orders = %orders:sortnew(descending(%sortMethod))

  3. In this example, a local method is used to accommodate a SortOrder function that requires a parameter.

    The SortOrder syntax does not provide for specifying a parameter for the method parameter.

    Say the totalPrice method is a function that accepts a parameter ("clientRating") which is used in its calculation of the total price. You can define a local method (tprice) to be used in the SortOrder instead of totalPrice:

    %clientRating is float local function (order):tprice is float expose return %this:totalprice(%clientRating) end function %orders = %orders:sortnew(descending(tprice))

    If ClientRating was already a member of the Order class, you would specify:

    local function (order):tprice is float return %this:totalprice(%this:clientRating) end function %orders = %orders:sortnew(descending(tprice))

    If tprice was used in many places, you could move it into the Order class without changing the Sort calls.

  4. The SortOrder in the following fragment uses the special method value This as the sort key. Valid only when applied to User Language intrinsic method objects, This simply returns the value of the method object.

    ... %foo is arraylist of longstring %foosrt is arraylist of longstring ... %foosrt = %foo:sortNew(ascending(this)) ... %foo:sort(descending(this)) ...

    This is the default method value as of Sirius Mods version 7.6.

List of SortOrder methods

The "List of SortOrder methods" shows all the class methods.