Operator to dynamically allocate memory and construct data of a specified type.
The
New Expression operator dynamically allocates memory and constructs a specified data type.
For simple types, like integers, an initial value can be given. For types without constructors, initial values can be specified for each field (either with default initializer at data-field declaration, or with initializer list as in
New datatype (initializers, ..) if all type data-fields are numeric primitives only and without any default initializers). For types with at least one constructor, the initialize list (if any) must match an existing constructor. If no initializers are given, the default values for those types will be set.
New[] Expression operator is the (one-dimensional) array-version of the
New Expression operator and allocates enough memory for the specified number of objects. The default constructor for the type will be used to set the initial values for each item.
Objects created with
New Expression operator must be freed with
Delete Statement operator. Object array created with
New[] Expression operator must be freed with
Delete[] Statement operator, the array-version of
Delete Statement operator. You cannot mix and match the different versions of the operators.
Specifying an initial value of
Any, as in
New datatype (Any) will allocate memory for the type, but not initialize the data. This is only valid on data types that do not have constructors (otherwise for data types with constructors, syntax of simple memory allocation with pointer conversion, like
Cptr(datatype Ptr, Allocate(Sizeof(datatype))), can be substituted to the invalid use of New...Any).
Specifying an initial value of
Any, as in
New datatype[count] {Any} will allocate memory for the array, but not initialize the data. This is only valid on data types that do not have constructors (otherwise for data types with constructors, syntax of simple memory allocation with pointer conversion, like
Cptr(datatype Ptr, Allocate(count * Sizeof(datatype))), can be substituted to the invalid use of New...Any).
The total memory, in bytes, to be allocated with
New datatype[count] expression is calculated as
sizeof(datatype) * count, plus
sizeof(uinteger) if there is an implicit or explicit
Destructor. The total memory requested in bytes to be allocated must not overflow the value that can be held by a
UInteger. The extra
uinteger, if allocated, stores the number of elements as part of the allocation, so that
Delete Statement can determine the count of destructors to call.
If the memory allocation fails, a null pointer is returned and no constructors are called.
The dynamic memory allocation process part provided by the
New Expression operator can be overloaded for user-defined types as a member operator
New Overload. The following process part for data construction can never be modified.
Note: Using
pointer = New datatype[count] may be unsafe if
pointer was declared with a type different from
datatype (for sub-type polymorphism purpose for example), because the pointer arithmetic fails to access the elements if the pointer type size is different from the size of
datatype (when using
Operator [] (Pointer Index) or adding an offset (element number) to the pointer, or even when
Delete[] Statement itself (the array-version of
Delete Statement) must destroy the elements).