New

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([Dimensions, Start], Size)  { Mode 1 } Or New(FirstDimension, SecondDimension)  { Mode 2 }

Parameters

{ Mode 1 }

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. 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. 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 2 }

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

The New function is limited to a maximum of 2,000,000 elements for each dimension.

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;