{{fbdoc item="title" value="Operator Placement New"}}----
Operator to construct an object at a specified memory address.

{{fbdoc item="syntax"}}##
	//result// = **New(//address//)** //[[DataType datatype]]//
		//or//
	//result// = **New(//address//)** //[[DataType datatype]]// ( //initializers//, ... )
		//or//
	//result// = **New(//address//)** //[[DataType datatype]]//**[** //count// **]**
##
{{fbdoc item="param"}}
	##//address//## 
		the location in memory to construct. the parenthesis are **not** optional.
	##//initializers//##
		Initial value(s) for the variable.
	##//datatype//##
		name of the data type to construct.
	##//count//##
		Number of elements to construct.

{{fbdoc item="ret"}}
	A pointer of type ##[[DataType datatype]]## to the newly constructed data.

{{fbdoc item="desc"}}
	The ##**Placement New**## operator constructs a specified data type at the specified memory location. 

	For simple types, like integers, an initial value can be given. For types without ##[[KeyPgConstructor constructor]]##s, initial values can be specified for each field. Types that have constructors can have their constructors called by ##**Placement New**## as well. If no initializers are given, the default values for those types will be set.

	Memory is **not** allocated when using the ##**Placement New**## operator. Instead, the memory at the specified ##//address//## is used.
	It is incorrect to call ##[[KeyPgOpDelete Delete]]## on the address. The proper way is to only call the destructor if one exists (implicitly or explicitly), with syntax as for a member method by using member access operator.
	See examples below for proper //placement new// usage.

	Specifying an initial value of ##[[KeyPgAny Any]]##, as in ##**New**(//address//)//datatype//(**Any**)## or ##**New**(//address//)//datatype//[//count//]{**Any**}## will 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 pointer conversion, like //Cptr(datatype Ptr, address)//, can be substituted to the invalid use of New...Any).

{{fbdoc item="ex"}}
{{fbdoc item="filename" value="examples/manual/operator/placement_new.bas"}}%%(freebasic)
'' "placement new" example

Type Rational
	As Integer    numerator, denominator
	Declare Constructor ( Byval n As Integer, Byval d As Integer )
	As String ratio = "/"
End Type

Constructor Rational ( Byval n As Integer, Byval d As Integer )
	This.numerator = n
	This.denominator = d
End Constructor

Scope
   
	'' allocate some memory to construct as a Rational
	Dim As Any Ptr ap = CAllocate(Len(Rational))
   
	'' make the placement new call
	Dim As Rational Ptr r = New (ap) Rational( 3, 4 )
   
	'' you can see, the addresses are the same, just having different types in the compiler
	Print ap, r
   
	'' confirm all is okay
	Print r->numerator & r->ratio & r->denominator
	
	'' delete must not be used with placement new
	'' destroying must be done explicitly if a destructor exists (implicitly or explicitly)
	''   (in this example, the var-string member induces an implicit destructor)
	r->destructor( )
	
	'' we explicitly allocated, so we explicitly deallocate
	Deallocate( ap )
	
End Scope
%%
{{fbdoc item="lang"}}
	- Only available in the //[[CompilerOptlang -lang fb]]// dialect.

{{fbdoc item="diff"}}
	- New to ""FreeBASIC""

{{fbdoc item="see"}}
	- ##[[KeyPgDestructor Destructor]]##
	- ##[[KeyPgOpNew New]]##

{{fbdoc item="back" value="CatPgOpMemory|Memory Operators"}}{{fbdoc item="back" value="CatPgOperators|Operators"}}