Data Initialization

This article explains how to create a new instance of a Data Class or Primitive Type.

To initialize a simple (Primitive Type) or complex (Data Class) type, you can either:

  • Use the set of Functions NewObject(), NewIndexed(), and NewNamed()
  • Use the keyword new
Important: The general recommendation is to prefer Functions over keywords. See the dedicated section of Scripting Best Practices for more details.

Initialization Functions

To create a new instance of an element, use one of the following Functions, depending on whether the element contains single or multiple values:

  • NewObject() – Single value
  • NewIndexed() – Indexed collection (= array or list)
  • NewNamed() – Named collection (= map or associative array)

The Function NewObject() allows you to pass parameters to the initializer of a Data Class or the constructor of a Primitive Type. The first parameter is always the data type, followed by any parameters accepted by the constructor of the corresponding Data Class or Primitive Type. Some Data Classes and Primitive Types require mandatory parameters at initialization.

IMPORTANT! The Function NEW() was replaced by NewObject(). Although `NEW()` is still available to ensure backwards compatibility, use NewObject() instead for better code readability and consistency between single elements and collections.

Examples:

Copy 

Person $person := NewObject(Person);

Account $account := NewObject(Account, $accountNumber, $accountHolder);

ClusterFile $clusterFile := NewObject(ClusterFile, 'my-docs/my-document.pdf');

Indexed Date $dates := NewIndexed(Date);

Named Account $accounts := NewNamed(Account);

//

// Equivalent notations for collections:

//

Indexed Date $dates := []:Date;

Named Account $accounts := {}:Account;

For most Primitive Types such as String, Boolean, or number types, setting a value for a variable directly creates a new instance. You don't need to use the NewObject() Function.

Examples:

Copy 

// instead of... 

//

String $string := NewObject(String);

$string := 'Hi';

//

// write...

//

String $string := 'Hi';

//

// other examples of Primitive Types where a value can be set directly: 

//

Boolean $boolean :=true;

Integer $int := 1;

Double $double := 1.0;

Date $date := NOW();

Indexed String $ss := ['a', 'b']:String;

Named Integer $ints := {'a'=1, 'b'=2}:Integer;

Initialization Keyword

The keyword new is an alternative for creating a new instance of a Data Class or Primitive Type.

Note: We recommend to use the Functions described in the preceding section instead of the `new` keyword.

Add Indexed or Named after the new keyword if the new instance is a collection:

  • new – Single value
  • new Indexed – Indexed collection (= array, list)
  • new Named – Named collection (= map, associative array)

Examples:

Copy 

Person $person := new Person;

StringBuilder $sb := new StringBuilder;

Indexed Date $dates := new Indexed Date;

Named Account $accounts := new Named Account;

Data Class Function NEW()

To customize a Data Class constructor, define a function with the name NEW() on that Data Class. This allows you to initialize Data Class properties, e.g. set a default value.

Example of NEW() for the Data Class "Contact":

Copy 

/**

  Initialize a Contact

  @param $name contact person's name

  @param $statusActive optional contact status

*/

Function NEW(String $name, Boolean $statusActive := true) : Nothing Begin

   $this.firstName := $name;

   $this.statusActive := $statusActive;

   $this.addresses := NewIndexed(Address);

End

Summary

To sum up, here is a list of equivalent notations:

Copy 

// Initialize a single element

//

Person $person := NewObject(Person);

Person $person := new Person;

// Person $person := NEW(Person); --> deprecated

//

// Initialize an Indexed collection

//

Indexed Address $addresses := NewIndexed(Address);

Indexed Address $addresses := []:Address;

Indexed Address $addresses := new Indexed Address ;

//

// Initialize a Named collection

//

Named Integer $integers := NewNamed(Integer);

Named Integer $integers := {}:Integer;

Named Integer $integers := new Named Integer;