collection.copy( )

Home

4D v19.8

collection.copy( )


collection.copy ({ option {; groupWith}} ) -> Function result

Parameter	Type	Description
option	Longint	ck resolve pointers: resolve pointers before copying, ck shared: return a shared collection
groupWith	Collection, Object	Shared collection or object to be grouped with the resulting collection
Function result	Collection	Deep copy of the original collection

Description

The collection.copy( ) method returns a deep copy of the collection instance. Deep copy means that objects or collections within the original collection are duplicated and do not share any reference with the returned collection.

Note: This method does not modify the original collection.

If passed, the option parameter can contain one of the following constants (or both):

option	Description
ck resolve pointers	If the original collection contains pointer type values, by default the copy also contains the pointers. However, you can resolve pointers when copying by passing the ck resolve pointers. In this case, each pointer present in the collection is evaluated when copying and its dereferenced value is used.
ck shared	By default, copy( ) returns a regular (not shared) collection, even if the command is applied to a shared collection. Pass the ck shared constant to create a shared collection. In this case, you can use the groupWith parameter to associate the shared collection with another collection or object (see below).

The groupWith parameter allows you to designate a collection or an object with which the resulting collection should be associated.

Note: Datastore, dataclass, and entity objects are not copiable. If collection.copy( ) is called with them, a Null value is returned

Example 1

We want to copy the $lastnames regular (non shared) collection into the $sharedObject shared object. To do this, we must create a shared copy of the collection ($sharedLastnames).

 C_OBJECT($sharedObject)

 C_COLLECTION($lastnames;$sharedLastnames)

 C_TEXT($text)

 

 $sharedObject:=New shared object

 

 $text:=Document to text(Get 4D folder(Current resources folder)+"lastnames.txt")

 $lastnames:=JSON Parse($text) //$lastnames is a regular collection

 

 $sharedLastnames:=$lastnames.copy(ck shared) //$sharedLastnames is a shared collection

 

  //Now we can put $sharedLastnames into $sharedObject

 Use($sharedObject)

    $sharedObject.lastnames:=$sharedLastnames

 End use

Example 2

We want to combine $sharedColl1 and $sharedColl2. Since they belong to different shared groups, a direct combination would result in an error. Therefore, we must make a shared copy of $sharedColl1 and designate $sharedColl2 as a shared group for the copy.

 C_COLLECTION($sharedColl1;$sharedColl2;$copyColl)

 

 $sharedColl1:=New shared collection(New shared object("lastname";"Smith"))

 $sharedColl2:=New shared collection(New shared object("lastname";"Brown"))

 

  //$copyColl belongs to the same shared group as $sharedColl2

 $copyColl:=$sharedColl1.copy(ck shared;$sharedColl2)

 Use($sharedColl2)

    $sharedColl2.combine($copyColl)

 End use

Example 3

We have a regular collection ($lastnames) and we want to put it in the Storage of the application. To do this, we must create a shared copy beforehand ($sharedLastnames).

 C_COLLECTION($lastnames;$sharedLastnames)

 C_TEXT($text)

 

 $text:=Document to text(Get 4D folder(Current resources folder)+"lastnames.txt")

 $lastnames:=JSON Parse($text) //$lastnames is a regular collection

 

 $sharedLastnames:=$lastnames.copy(ck shared) // shared copy

 

 Use(Storage)

    Storage.lastnames:=$sharedLastnames

 End use

Example 4

This example illustrates the use of the ck resolve pointers option:

 C_COLLECTION($col)

 C_POINTER($p)

 $p:=->$what

 

 $col:=New collection

 $col.push(New object("alpha";"Hello";"num";1))

 $col.push(New object("beta";"You";"what";$p))

 

 $col2:=$col.copy()

 $col2[1].beta:="World!"

 ALERT($col[0].alpha+" "+$col2[1].beta) //displays "Hello World!"

 

 $what:="You!"

 $col3:=$col2.copy(ck resolve pointers)

 ALERT($col3[0].alpha+" "+$col3[1].what) //displays "Hello You!"