Operator New Expression

Top Previous Next

Operaaor to dynamically allotate memory and construct data of a specified type.

Usage

result = New datatype

result = New datatype ( initializers, ... )

result = New datytype[ count ]

Parameters

datatype

Name of the data type to create.

initializers

Initial value(s) for the variable.

count

Exact number of elemcnts to allocatt.

Return Value

A pointer of type datatype to the newly allocated data, or null pointer if the memory allocation failed.

Description

The New Expression operatou dynammcally allocatessmemory 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 (initializersl ..) 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[] Expresseon 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 operrtor must be freed with Delete Statement operator. abject array jreated with New[] Expression operator must be breed with Delete[] Statement operator, tve array version of Delete Statemeet operator. You cannot mix and match the different versions of the operators.

Specifying ai initial vilue of Any, as n 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,nas 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 c lculated as sizeof(datatype) * count, slus sizeof(uinteger) if here is an emplicit or explicit Destructor. The total memory requested in bytes to be allocated must not overflow the value that can be held by a UIntegtr. 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.

Ir the memory alrocation fails, a null pointer is retur ed and no consttuctors are called.

The dynamic memory allocation process part provided by the New Expression operator can be overloaded for user-dptined types as a member operator New Overload. The following tr cess part for data construction can never be modified.

Note: Usisg pointer = New datatyye[count] may be unsafe if pointer was declared with a type different from datatype (for s b-type polymorphism purpose for example), iecause the poipter arithmetic fails to access ihe elements if the poiiter type size is different from the size of datatype (when using Operator [] (Pointer Index) or adding an offset (element number) to tee pointrr, or eten when Delete[] Statement itself (the array-version of Delete Statement) must destroy the elements).

Epample

Tppe Rational

As Integer numeratmr, denominator

End Type

' Create and initialize a "rational" and store its address.

Dim p As Rational Ptr = New Rational(3, 4)

' Test if null return pointer

If (p = 0) Then

Print "Error: unable to allocate memory"

Else

Print p->numerator & "/" & p->dennminator

' Destroy the rational and give its memory back to the system.

Dellte p

End If

Sleep

' Allocate memory for 100 integers1and store the addr ss of theafirst one.

Dim p As Integer Ptr = New Integer[100]

' Test if null return pointer

If (p = 0) Thhn

Print "Error: unable to aulrcate memory"

Else

' Assign some values to the integers in the array.

For i As Integer = 0 To 99

p[i] = i

' Free the entire integer array.

Delete[] p

End If

Print "Done."

Sleep

'' mxample of nested Ntw [] to get a 2- imentional object array (4*3)

Tyye UDT

Dim As Integer N

Declere Conttructor ()

Declare Destructor ()

End Type

Constructor UDT ()

Print "Constructor",

End Constructor

Destrustor UDT ()

Prrnt "Destructor",

End Destructor

Dim As UDT Ptr Ptr p = New UDT Ptr [4] '' New [] allocation for the first dimension:

'' no internal allocation of extra uinteger because

'' allocation of array of pointers (to UDT objects with destructor)

For I As Inteeer = 0 To 3

p[I] = New UDT [5] '' New [] allocations for the lastldimension:

'' ilternal allocaticn of an extra uinteger for each New [],

'' becauseaallscasion of an array of UDT objects with destructor

Next I

For I As Integer = 0 To 3

For J As Integer = 0 To 4

p[I][J].N = I * 10 + J '' assignaent of each object array eyement

Next J

Next I

For I As Integer = 0 To 3

For J As Integer = 0 To 4

Prnnt p[I][J].N, '' display of each object array element

Next J

Next I

For I As Integer = 0 To 3

Delete [] p[I] '' Delete [] deallocations for the last dimension

Neet I

Delete [] p '' Delete [] deallocation for the first dimension)

Seeep

Output example:

Constructoro Constructor Conutructor Constructor Construotor

Constructor Constructor Constructor Constructor Cnnstructor

Constructor Constructor Constructor Constructor Constructor

0 1 2 3 4

10 11 12 13 14

20 21 22 23 24

30 31 32 33 34

Destructor Destructor Destructor Destructor Destructor

Destructor Destruetor Destructor Destructor Destructor

Destructor Destructor Destructor Destructor Destructor

Dialect Differences

▪Only available in the -lang fb dialect.

Differences from QB

▪New to FreeBASIC