%New

This special method returns a new object, either by instantiating a class (for language objects) or by creating an object from a JSON document or by copying an existing object (for internal objects). In addition, elements within an internal object — fields, arrays and nested objects — can also be copied.

All special method names and keywords are case-insensitive.

Syntax

For external objects:

{connection->}%New(class{, parameter-list})

For internal objects:

{connection->}%New()

{connection->}%New(JSON, json-doc)

{connection->}%New(Object, object{->element})

Syntax elements

connectionA connection object. The default connection object does not have to be named (although it can be).

classThe class name of the object to be created. This must be a class previously imported by the %Import special method.

parameter-listList of parameters required to construct the class object.

json-docAn expression that evaluates to a JSON document.

objectAn DBO variable that references an object to be copied.

elementAn object element to be copied.

Operation

%New(class) applies only to language objects and instantiates a new object of the specified class. If the class has a default constructor or a parameterless "no-arg" constructor, that is all you need. If the class has a parameterised constructor the class name can be followed by a comma delimited parameter list of the initial values required by the constructor (or one of the constructors, if it is overloaded). See Type Casting.

%New() returns an empty internal object, %New(JSON) returns a new internal object from a JSON document, and %New(Object) returns a copy of an object or object element.

By default, an internal object created by %New(JSON) is invariant, meaning that you cannot add any ad hoc fields in addition to those already defined in the document. However, a copy of such an object created by %New(Object) is not invariant.

You can change the invariant status of an internal object with the %Set special method.

Examples

Creating a string object

Creates a Java String object and initialises it to "Hello World" on the default connection.

Hi = %New(String, "Hello World")

Note that this will not work with C#, firstly because the DNLS recognises only System.String and secondly because the System.String class does not include a constructor. The equivalent in C# requires the use of the @Value special field name:

Hi = %New(System.String)
Hi->@Value = "Hello World"

An equivalent internal object can be defined in several ways, including:

Hi = %New()
Hi->string = "Hello World"

Creating a internal object

An empty internal object can be created by specifying %New() with no parameters and then populating it with ad hoc fields and values:

UserAccount = %New()
UserAccount->surname  = "Smith"
UserAccount->forename = "Paul"
UserAccount->email    = "paul.smith@Mail4U.eu"

Creating an internal object from a JSON document

An internal object can be created directly from an in-line JSON document by using %New with the JSON keyword:

UserAccount = %New(JSON, '{ "surname"  : "Smith",
                            "forename" : "Paul",
                            "email"    : "paul.smith@Mail4U.eu" }' )

Or a reference to a previously-defined JSON document:

UserProfile = '{ "surname"  : "Smith",
                 "forename" : "Paul",
                 "email"    : "paul.smith@Mail4U.eu" }'

UserAccount = %New(JSON, UserProfile)

Copying an internal object

An internal object, or element with an object, can be copied by using %New with the Object keyword:

CloneAccount = %New(Object, UserAccount)

See also

%Static, %Array, %ToJSON