collection.orderBy( )

Home

4D v19.8


collection.orderBy ( {criteria} ) -> Function result

Parameter	Type	Description
criteria	Text, Collection, Longint	Text: property path(s) on which to order the collection Collection: collection of criteria objects Longint: ck ascending or ck descending (scalar values)
Function result	Collection	Ordered copy of the collection (shallow copy)

Description

The collection.orderBy( ) method returns a new collection containing all elements of the collection in the order specified by criteria.

This method returns a shallow copy, which means that objects or collections in both collections share the same reference. If the original collection is a shared collection, the returned collection is also a shared collection.

Note: This method does not modify the original collection.

If you omit the criteria parameter, the method orders scalar values in the collection in ascending order (other element types such as objects or collections are returned unordered). You can modify this automatic order by passing the ck ascending or ck descending constants in the criteria parameter (see below).

You can also pass a criteria parameter to define how the collection elements must be sorted. Three syntaxes are supported for this parameter:

criteria is of text type (formula): "propertyPath1 {desc or asc}, propertyPath2 {desc or asc},..." (default order: asc)
In this case, criteria contains a formula made of 1 to x property paths and (optionally) sort orders, separated by commas. The order in which the properties are passed determines the sorting priority of the collection elements.
By default, properties are sorted in ascending order. You can set the sort order of a property in the criteria string, separated from the property path by a single space: pass "asc" to sort in ascending order or "desc" in descending order.

criteria is of collection type: in this case, each element of the collection contains an object structured in the following way:
{"propertyPath": string,
"descending": boolean}
By default, properties are sorted in ascending order ("descending" is false).
You can add as many objects in the criteria collection as necessary.

criteria is of longint type: in this case, you pass one of the following constants from the Objects and collections theme:

Constant	Type	Value	Comment
ck ascending	Longint	0	Elements are ordered in ascending order (default)
ck descending	Longint	1	Elements are ordered in descending order

This syntax orders scalar values in the collection only (other element types such as objects or collections are returned unordered).

If the collection contains elements of different types, they are first grouped by type and sorted afterwards. Types are returned in the following order:

null
booleans
strings
numbers
objects
collections
dates

Example 1

Ordering a collection of numbers in ascending and descending order:

 C_COLLECTION($c;$c2;$3)

 $c:=New collection

 For($vCounter;1;10)

    $c.push(Random)

 End for

 $c2:=$c.orderBy(ck ascending)

 $c3:=$c.orderBy(ck descending)

Example 2

Ordering a collection of objects based on a text formula with property names:

 C_COLLECTION($c)

 $c:=New collection

 For($vCounter;1;10)

    $c.push(New object("id";$vCounter;"value";Random))

 End for

 $c2:=$c.orderBy("value desc")

 $c2:=$c.orderBy("value desc, id")

 $c2:=$c.orderBy("value desc, id asc")

Ordering a collection of objects with a property path:

 C_COLLECTION($c)

 $c:=New collection

 $c.push(New object("name";"Cleveland";"phones";New object("p1";"01";"p2";"02")))

 $c.push(New object("name";"Blountsville";"phones";New object("p1";"00";"p2";"03")))

 $c2:=$c.orderBy("phones.p1 asc")

Example 3

Ordering a collection of objects using a collection of criteria objects:

 C_COLLECTION($crit;$c)

 $crit:=New collection

 $c:=New collection

 For($vCounter;1;10)

    $c.push(New object("id";$vCounter;"value";Random))

 End for

 $crit.push(New object("propertyPath";"value";"descending";True))

 $crit.push(New object("propertyPath";"id";"descending";False))

 $c2:=$c.orderBy($crit)

Ordering with a property path:

 C_COLLECTION($crit;$c)

 $c:=New collection

 $c.push(New object("name";"Cleveland";"phones";New object("p1";"01";"p2";"02")))

 $c.push(New object("name";"Blountsville";"phones";New object("p1";"00";"p2";"03")))

 $crit:=New collection(New object("propertyPath";"phones.p2";"descending";True))

 $c2:=$c.orderBy($crit)