SortOrder class

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 methods in this class are listed in "List of SortOrder methods".

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 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 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 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.