Combine and sort collections

4D v16 R6 opens a wide range of possibilities to manage collections. Merging two collections into one, cloning or just ordering a collection is as easy as calling a method. It saves valuable time, for example, when you need to concatenate two collections, keep only the distinct values, or sort it.

This article is part of a series demonstrating how to manipulate collections using the methods added in 4D v16 R6. To learn even more, download our database example, which includes 12 different examples to show what you can do with collection methods!

Database example: Manage collections

Copying A collection

Deep copy

The copy method, returns a deep copy of the collection instance. A deep copy means that all elements in the original collection are duplicated and don’t share any reference with the returned collection.

In the example below, performing a deep copy using the copy method adds a new element to $col2 (a copy of the first collection – $col). An additional element is added to $col2, however $col remains unchanged:

//create a collection
$col:=New collection("a";"b";"c";"d";"e") 
//make a deep copy of the first collection
$col2:=$col.copy($col)  
//add a new element to the copy of the first collection
$col2.push("f")  
// $col=["a","b","c","d,"e"]

// $col2=["a","b","c","d,"e","f"]

Shallow copy

When you make a shallow copy of a collection, the elements within the original collection share their references with the returned collection. For example, if you create a collection, make a typical shallow copy of it, and then add a new element to the copy ($col2), the original collection ($col) will also reflect the change because $col and $col2 share their reference:

//create a collection
$col:=New collection("a";"b";"c";"d";"e") 
//make a shallow copy of the first collection
$col2:=$col 
//add a new element to the copy of the first collection 
$col2.push("f")  
// $col2=$col=["a","b","c","d,"e","f"]

You can create a shallow copy of a part of a collection using the slice method:

//create a collection
$col:=New collection("a";"b";"c";"d";"e")
// Copy from index 2 and stop at end of collection -1
$col2:=$col.slice(2;-1)
//$col2=[c,d]

Combining collections

Concatenating two collections can be done using either the concat or combine methods.

The concat method returns a new collection with the concatenation of the two collections:

//create 2 collections
$col:=New collection("a";"b";"c")
$col2:=New collection(1;2;3)
//combine the 2 collections into a 3rd collection
$col3:=$col.concat($col2)
//$col3=["a","b","c",1,2,3]

The combine method adds each element of a collection (passed in parameter) to the end of the original collection:

//create 2 collections
$col:=New collection("a";"b";"c")
$col2:=New collection(1;2;3)
//add the 2nd collection to the end of the first collection
$col.combine($col2)
//$col=["a","b","c",1,2,3]

The distinct method creates a new collection containing only distinct (different) values from the original collection:

$col:=New collection("a";"b";"c";"a";"b";"c";"d";"e")
$col2:=$col.distinct()
//$col2=[a,b,c,d,e]

Sorting a collection

To sort a collection, you can use the sort or orderBy methods. The sort method modifies the original collection, whereas orderBy returns an entirely new (shallow copy), sorted collection, but doesn’t modify the original collection:

$col:=New collection("a";"b";"c";"a";"b";"c";"d";"e")
$col2:=$col.orderBy()
//$col2=["a","a","b","b","c","c","d","e"]

//$col=["a","b","c","a","b","c","d","e"]
$col.sort()
//$col=["a","a","b","b","c","c","d","e"]

You can also sort a collection using sort or orderByMethod, which requires a call back method:

$col:=New collection("Orange";"Apple";"Grape";"Pear";"Banana";"Fig";"Blackberry";"Passion fruit")
$col2:=$col.orderByMethod("WordLength")
//$col2=[Passion fruit,Blackberry,Orange,Banana,Apple,Grape,Pear,Fig]
$col.sort("WordLength")
//$col=[Passion fruit,Blackberry,Orange,Banana,Apple,Grape,Pear,Fig]

Where the WordLength callback method is one of your project methods:

$1.result:=Length(String($1.value))>Length(String($1.value2))

Finally, you can make a deep copy of a collection with all its elements in reverse order using reverse:

$col:=New collection(1;3;5;2;4;6)
$col2:=$col.reverse()
//$c2=[6,4,2,5,3,1]