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

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.

SortOrder object variable declaration syntax

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

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)

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

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 a special method value, 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 (?? refid=localmd.) 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.