Skip to main content
Version: Next

objectCopy

objectCopy ( object : object ) : object
objectCopy ( object : object , option : integer ) : object
objectCopy ( object : object , option : integer , groupWith : object ) : object
objectCopy ( object : object , option : integer , groupWith : collection ) : object

ParameterTypeDescription
objectobjectObject to copy
optionintegerkShared: return a shared object
groupWithobjectShared object to be grouped with the resulting object
groupWithcollectionShared collection to be grouped with the resulting object
ResultobjectDeep copy of object

Description

The objectCopy command returns an object containing a complete (deep) copy of the properties, sub-objects and values for the object.

By default, objectCopy returns a regular (not shared) object, even if the command is applied to a shared object. Pass the kShared constant in the option parameter to create a shared object. In this case, you can use the groupWith parameter to associate the shared object with another collection or object.

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

Notes
  • objectCopy can be used with an entity selection object. By default if kShared is omitted, a non-shareable entity selection is returned. If kShared is passed, a shareable entity selection is returned. In this context, the groupWith option is useless since an entity selection does not have a locking identifier.
  • The same principle applies to entity selections stored inside properties of object. However, the command is optimized when kShared is passed and a nested entity selection is shareable: the same entity selection reference is returned in the resulting object.
  • Datastore, dataclass, and entity objects are not copiable. If objectCopy command is called with them, a null value is returned

Example 1

This example illustrates the deep copy of an object containing a sub-object:

var ob1, ob2, ob3 : object

ob1 = {info: {a: 20; b: 30}}
//ob1: {"info":{"a":20,"b":30}}
ob2 = ob1 //another reference to the same object
//ob2: {"info":{"a":20,"b":30}}
ob3 = objectCopy(ob1) //deep copy of the object
//ob3: {"info":{"a":20,"b":30}}

ob1.info.b = 1000 //modify ob1 and thus ob2
ob3.info.a = 5000 //modify the deep copy
//ob1: {"info":{"a":20,"b":1000}}
//ob2: {"info":{"a":20,"b":1000}}
//ob3: {"info":{"a":5000,"b":30}}

Example 2

We want to copy the regular (non shared) person object into the sharedPerson shared object. To do this, we must create a shared copy of the object (sharedPerson).

 var person, copy, sharedPerson : object
var text : string

text = documentToString(file("/SOURCES/person.txt")
person = jsonParse(text) //person is a standard object
sharedPerson = newSharedObject()
copy = objectCopy(person,kShared) //copy is a shared object

//So it can be put in sharedPerson
use(sharedObject)
sharedObject.person = copy
end

Example 3

We want to copy sharedObj in sharedColl but since they belong to different shared groups, a direct copy would result in an error. We must make a copy of sharedObj and designate sharedColl* as shared group for the copy.

 var sharedObj, objCopy : object
var sharedColl : collection

//sharedObj belongs to a shared group
sharedObj = newSharedObject("lastname","Smith","address",newSharedObject("city","New York"))
//sharedColl belongs to another shared group
sharedColl = newSharedCollection(newSharedObject("lastname","Brown"))

objCopy = objectCopy(sharedObj,kShared,sharedColl)
//objCopy is now in the same shared group as sharedColl

//So objCopy can be put in sharedColl without error
use(sharedColl)
sharedColl.push(objCopy)
end