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.
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
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
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
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.
%sord is a SortOrder instance returned by the Ascending constructor
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
%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
|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
|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.
- 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)
- The following example outlines the use of a method variable
as a SortOrder sort key.
Hypothetical user class
Orderhas two Variables to sort its data by, and they are conditionally assigned to method variable
... %sortMethod is function (order):number is float ... If .. %sortMethod = totalprice End if If .. %sortMethod = totalProductionCost End if ... %orders = %orders:sortnew(descending(%sortMethod))
- 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.
totalPricemethod 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
%clientRating is float local function (order):tprice is float expose return %this:totalprice(%clientRating) end function %orders = %orders:sortnew(descending(tprice))
ClientRatingwas 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))
tpricewas used in many places, you could move it into the Order class without changing the Sort calls.
- 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.