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

Required. 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.

Start

Required. 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. { Mode 1 }
  • 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.

Examples:

  If 1 NextState;
  [
    Simple  = New(0, 0, 0)  { Creates a simple value        };
    Array1 = 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 };
    Array2    = New(2, Start[0], Length[0]); 
     { Creates a 2-dimensional array } 
  ]

The above script allocates memory for 3 variables:

Simple is a simple value

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

Array2 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.

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

    Array1 = New(10);

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

    Array2 = 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;