New

(Engine-Level Function)

Description Allocates memory for an array from RAM and returns a pointer to that array.
Returns Pointer
Usage Script Only.
Function Groups Array,  Memory I/O
Related to: AddVariable | AdjustArray
Format:

New(Size) { Mode 1}

New([Dimensions, Start,] Size)  { Mode 2 }

New(FirstDimension, SecondDimension)  { Mode 3 }
Parameters  

{ Mode 1 }

Size

Required. A numeric value specifying the size of a one-dimensional array

{ Mode 2 }

Dimensions

An optional parameter that is any numeric expression giving the number of array dimensions to allocate.

  • To allocate a simple value, use 0, and for a one dimensional array, use 1.
  • If this parameter is omitted and the function has only 1 parameter, a single dimensional array is created.
  • If it is omitted and the function has 2 parameters (see FirstDimension and SecondDimension), a two dimensional array is created.
Start

An optional parameter that is either a numeric expression, or an array.

Specifying a start index other than zero for any dimension of an array is generally regarded as poor practice.

  • If Dimensions is omitted, this parameter must also be omitted.
  • If Dimensions is 0, this is ignored.
  • If Dimensions is 1, this is treated as a number, which is the index of the first element in the array allocated.
  • If Dimensions is greater than 1, this is must be the first element of an array of numbers, each element indicating the starting index for a dimension.
Size

Required. Either a numeric expression or an array.

  • If Dimensions and Start are omitted, a single value will define the number of elements in the single dimension array that is created. { Mode 1 }
  • If Dimensions is 0, this parameter is ignored.
  • If Dimensions is 1, this is treated as a number, which is the number of elements in the array allocated.
  • If Dimensions is greater than 1, this must be the first element of an array of numbers, each element indicating the number of elements in a dimension.

{ Mode 3 }

FirstDimension
Required. A numeric value that determines the number of elements in the first dimension of the two dimensional array that is created.
SecondDimension
Required. A numeric value that determines the number of elements in the second dimension of the two dimensional array that is created.
Comments  

Examples:

  If 1 NextState;
  [
    simple = New(0, 0, 0); { Creates a simple value } 
    array1Ptr = New(1, 0, 10);{ Creates a 1-dimensional array } 

    start[0] = 0; { Dimension 1 - Starting index } 
    start[1] = 0; { Dimension 2 - Starting index } 
    length[0] = 3; { Dimension 1 - Number of elements } 
    length[1] = 4; { Dimension 2 - Number of elements } 
    array2Ptr = New(2, start[0], length[0]); 
    { Creates a 2-dimensional array } 
  ]

The above script allocates memory for 3 variables:

simple is a simple value

array1Ptr is a 1-dimensional array with 10 elements, numbering from 0 to 9.

array2Ptr is a 2-dimensional array having 3 elements in its first dimension, numbering from 0 to 2, and 4 elements in its second dimension, numbering from 0 to 3.

array1Ptr could also have been created with the same attributes by using the following statement:

    array1Ptr = New(10);

array2Ptr could have been created with same number of rows and columns by using:

    array2Ptr = New(3, 4);

Multi-dimensional array:

    A = New(3, 0, 2);
    { A is an array of two elements, each of which is an array of two elements, which in turn are arrays of two elements }
    A[0][0][0] = 0;
    A[0][0][1] = 1;
    A[0][1][0] = 2;
    A[0][1][1] = 3;
    A[1][0][0] = 4;
    A[1][0][1] = 5;
    A[1][1][0] = 6;
    A[1][1][1] = 7;