Creates and initializes objects with dynamic
, that is, objects whose lifetime is not necessarily limited by the scope in which they were created.
Syntax
::(optional)new(type)new-initializer(optional)(1) ::(optional)newtypenew-initializer(optional)(2) ::(optional)new(placement-args)(type)new-initializer(optional)(3) ::(optional)new(placement-args)typenew-initializer(optional)(4) 1,2) Attempts to create an object of type, denoted by the
type, which may be array type, and may include a
(since C++11), or include a class template name whose argument is to be deduced by
class template argument deduction
(since C++17).
3,4) Same as (1,2), but provides additional arguments to the allocation function, see
.
Explanation
type- the target type-id new-initializer- a parentheses-enclosed expression list or a
brace-enclosed initializer list
(since C++11)placement-args- additional placement arguments
The new expression attempts to allocate storage and then attempts to construct and initialize either a single unnamed object, or an unnamed array of objects in the allocated storage. The new expression returns a prvalue pointer to the constructed object or, if an array of objects was constructed, a pointer to the initial element of the array.
Syntax (1) or (3) is required if type includes parentheses:
newint(*[10])();// error: parsed as (new int) (*[10]) ()new(int(*[10])());// okay: allocates an array of 10 pointers to functionsIn addition, type is parsed greedily: it will be taken include every token that can be a part of a declarator:
newint+1;// okay: parsed as (new int) + 1, increments a pointer returned by new intnewint*1;// error: parsed as (new int*) (1)The new-initializer is not optional if
type is an
,
a
is used in type, that is, autoor decltype(auto)(since C++14), possibly combined with a
(since C++20),
(since C++11)a class template is used in type whose arguments need to be
.
(since C++17)double*p=newdouble[]{1,2,3};// creates an array of type double[3]autop=newauto('c');// creates a single object of type char. p is a char*autoq=newstd::integralauto(1);// OK: q is an int*autoq=newstd::floating_pointauto(true)// ERROR: type constraint not satisfiedautor=newstd::pair(1,true);// OK: r is a std::pair<int, bool>*autor=newstd::vector;// ERROR: element type can't be deducedDynamic arrays
If type is an array type, all dimensions other than the first must be specified as positive
(until C++14)
of type
(since C++14), but (only when using un-parenthesized syntaxes (2) and (4)) the first dimension may be an expression of integral type, enumeration type, or class type with a single non-explicit conversion function to integral or enumeration type(until C++14)any expression convertible to
(since C++14). This is the only way to directly create an array with size defined at runtime, such arrays are often referred to as dynamic arrays:
intn=42;doublea[n][5];// errorautop1=newdouble[n][5];// OKautop2=newdouble[5][n];// error: only the first dimension may be non-constantautop3=new(double[n][5]);// error: syntax (1) cannot be used for dynamic arraysThe behavior is undefined if the value in the first dimension (converted to integral or enumeration type if needed) is negative.
(until C++11)In the following cases the value of the expression specifying the first dimension is invalid:
the expression is of non-class type and its value before conversion to
is negative;
the expression is of class type and its value after user-defined conversion function and before the
is negative;
the value of the expression is larger than some implementation-defined limit;
the value is smaller than the number of array elements provided in the brace-enclosed initializer list (including the terminating '\0' on a
).
If the value in the first dimension is invalid for any of these reasons,
if, after conversion to
, the first dimension is a
and it is
, the program is ill-formed,
otherwise, if the allocation function that would have been called is non-throwing (including
overloads not declared noexcept), the new expression returns the null pointer of the required result type,
otherwise, the new expression does not call the allocation function, and instead throws an exception of a type that would match a
of type
.
(since C++11)The first dimension of zero is acceptable, and the allocation function is called.
Allocation
The new expression allocates storage by calling the appropriate
. If type is a non-array type, the name of the function is operatornew. If type is an array type, the name of the function is operatornew[].
As described in
, the C++ program may provide global and class-specific replacements for these functions. If the new expression begins with the optional :: operator, as in ::newT or ::newT[n], class-specific replacements will be ignored (the function is
in global
). Otherwise, if T is a class type, lookup begins in the class scope of T.
When calling the allocation function, the new expression passes the number of bytes requested as the first argument, of type
, which is exactly sizeof(T) for non-array T.
Array allocation may supply unspecified overhead, which may vary from one call to new to the next, unless the allocation function selected is the standard non-allocating form. The pointer returned by the new expression will be offset by that value from the pointer returned by the allocation function. Many implementations use the array overhead to store the number of objects in the array which is used by the
expression to call the correct number of destructors. In addition, if the new expression is used to allocate an array of char, unsignedchar, or
(since C++17), it may request additional memory from the allocation function if necessary to guarantee correct alignment of objects of all types no larger than the requested array size, if one is later placed into the allocated array.
new expressions are allowed to elide or combine allocations made through replaceable allocation functions. In case of elision, the storage may be provided by the compiler without making the call to an allocation function (this also permits optimizing out unused new expression). In case of combining, the allocation made by a new expression E1 may be extended to provide additional storage for another new expression E2 if all of the following is true:
1) The lifetime of the object allocated by E1 strictly contains the lifetime of the object allocated by E2.
2)E1 and E2 would invoke the same replaceable global allocation function.
3) For a throwing allocation function, exceptions in E1 and E2 would be first caught in the same handler.
Note that this optimization is only permitted when new expressions are used, not any other methods to call a replaceable allocation function: delete[]newint[10]; can be optimized out, but operatordelete(operatornew(10)); cannot.
(since C++14)During an evaluation of a
, a call to an allocation function is always omitted. Only new expressions that would otherwise result in a call to a replaceable global allocation function can be evaluated in constant expressions.
(since C++20)Placement new
If placement-args are provided, they are passed to the allocation function as additional arguments. Such allocation functions are known as "placement new", after the standard allocation function void*operatornew(std::size_t,void*), which simply returns its second argument unchanged. This is used to construct objects in allocated storage:
// within any block scope...{// Statically allocate the storage with automatic storage duration// which is large enough for any object of type “T”.alignas(T)unsignedcharbuf[sizeof(T)];T*tptr=new(buf)T;// Construct a “T” object, placing it directly into your // pre-allocated storage at memory address “buf”.tptr->~T();// You must **manually** call the object's destructor// if its side effects is depended by the program.}// Leaving this block scope automatically deallocates “buf”.Note: this functionality is encapsulated by the member functions of the
classes.
When allocating an object whose alignment requirement exceeds
__STDCPP_DEFAULT_NEW_ALIGNMENT__
or an array of such objects, the new expression passes the alignment requirement (wrapped in
) as the second argument for the allocation function (for placement forms, placement-arg appear after the alignment, as the third, fourth, etc arguments). If overload resolution fails (which happens when a class-specific allocation function is defined with a different signature, since it hides the globals), overload resolution is attempted a second time, without alignment in the argument list. This allows alignment-unaware class-specific allocation functions to take precedence over the global alignment-aware allocation functions.
(since C++17)newT;// calls operator new(sizeof(T))// (C++17) or operator new(sizeof(T), std::align_val_t(alignof(T))))newT[5];// calls operator new[](sizeof(T)*5 + overhead)// (C++17) or operator new(sizeof(T)*5+overhead, std::align_val_t(alignof(T))))new(2,f)T;// calls operator new(sizeof(T), 2, f)// (C++17) or operator new(sizeof(T), std::align_val_t(alignof(T)), 2, f)If a non-throwing allocation function (e.g. the one selected by new(std::nothrow)T) returns a null pointer because of an allocation failure, then the new expression returns immediately, it does not attempt to initialize an object or to call a deallocation function. If a null pointer is passed as the argument to a non-allocating placement new expression, which makes the selected standard non-allocating placement allocation function return a null pointer, the behavior is undefined.
Initialization
The object created by a new expression is initialized according to the following rules.
If type is not an array type, the single object is constructed in the acquired memory area:
If new-initializer is absent, the object is
.
If new-initializer is a parentheses-enclosed expression list, the object is
.
If new-initializer is a braced-enclosed initializer list, the object is
.
(since C++11)If type is an array type, an array of objects is initialized:
If new-initializer is absent, each element is
.
Even if the first dimension is zero, the semantic constraints of default-initializing a hypothetical element still need to be met.
If new-initializer is a pair of parentheses, each element is
.
Even if the first dimension is zero, the semantic constraints of value-initializing a hypothetical element still need to be met.
If new-initializer is a braced-enclosed initializer list, the array is
.
(since C++11)If new-initializer is a parentheses-enclosed non-empty expression list, the array is
.
(since C++20)Initialization failure
If initialization terminates by throwing an exception (e.g. from the constructor), the program looks up a matching deallocation function, then:
If a suitable deallocation function can be found, the deallocation function is called to free the memory in which the object was being constructed. After that, the exception continues to propagate in the context of the new expression.
If no unambiguous matching deallocation function can be found, propagating the exception does not cause the object’s memory to be freed. It is only appropriate if the called allocation function does not allocate memory, otherwise it is likely to result in a memory leak.
The scope of the
of the matching deallocation function is determined as follows:
If the new expression does not begin with ::, and the allocated type is either a class type T or an array of class type T, a search is performed for the deallocation function’s name in the class scope of T.
Otherwise, or if nothing is found in the T's class scope, the deallocation function’s name is looked up by searching for it in the
.
For a non-placement allocation function, the normal deallocation function lookup is used to find the matching deallocation function (see
).
For a placement allocation function, the matching deallocation function must have the same number of parameter, and each parameter type except the first is identical to the corresponding parameter type of the allocation function (after
).
If the lookup finds a single matching deallocation function, that function will be called; otherwise, no deallocation function will be called.
If the lookup finds a non-placement deallocation function and that function, considered as a placement deallocation function, would have been selected as a match for the allocation function, the program is ill-formed.
In any case, the matching deallocation function (if any) must be non-deleted and(since C++11) accessible from the point where the new expression appears.
structS{// Placement allocation function:staticvoid*operatornew(std::size_t,std::size_t);// Non-placement deallocation function:staticvoidoperatordelete(void*,std::size_t);};S*p=new(0)S;// error: non-placement deallocation function matches// placement allocation functionIf a deallocation function is called in a new expression (due to initialization failure), the arguments passed to that function are determined as follows:
The first argument is the value (of type void*) returned from the allocation function call.
Other arguments (only for placement deallocation functions) are the placement-args passed to the placement allocation function.
If the implementation is allowed to introduce a temporary object or make a copy of any argument as part of the call to the allocation function, it is unspecified whether the same object is used in the call to both the allocation and deallocation functions.
Memory leaks
The objects created by new expressions (objects with dynamic storage duration) persist until the pointer returned by the new expression is used in a matching
. If the original value of pointer is lost, the object becomes unreachable and cannot be deallocated: a memory leak occurs.
This may happen if the pointer is assigned to:
int*p=newint(7);// dynamically allocated int with value 7p=nullptr;// memory leakor if the pointer goes out of scope:
voidf(){int*p=newint(7);}// memory leakor due to exception:
voidf(){int*p=newint(7);g();// may throwdeletep;// okay if no exception}// memory leak if g() throwsTo simplify management of dynamically-allocated objects, the result of a new expression is often stored in a
:
(until C++17)
, or
(since C++11). These pointers guarantee that the delete expression is executed in the situations shown above.
Notes
requires that the array allocation overhead is zero if the element type of the created array is trivially destructible. So does MSVC.
Some implementations (e.g. MSVC before VS 2019 v16.7) require non-zero array allocation overhead on non-allocating placement array new if the element type is not trivially destructible, which is no longer conforming since
.
A non-allocating placement array new expression that creates an array of unsignedchar, or
(since C++17) can be used to
on given region of storage: it ends lifetime of objects overlapping with the array, and then implicitly creates objects of implicit-lifetime types in the array.
offers similar functionality for one-dimensional dynamic arrays.
Feature-test macro ValueStdFeature
(C++26)Constexpr
Keywords
Defect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
DR Applied to Behavior as published Correct behavior
C++98 value in the first dimension must have integral type enumeration types permitted
C++98 value in the first dimension must
have integral or enumeration type class types with a single
conversion function to integral
or enumeration type permitted
C++98 the behavior was unspecified when the
size of the allocated object would exceed
the implementation-defined limit no storage is obtained and an
exception is thrown in this case
C++98 non-allocating placement new need
to check if the argument is null undefined behavior for null argument
C++11 new(std::nothrow)int[N]
could throw
changed to return a null pointer
C++98 it was unclear whether default/value-initialization is
required to be well-formed when initializing empty arrays required
C++98 non-allocating placement array new
could require allocation overhead such allocation overhead disallowed
C++11 the program might be ill-formed even if the
first dimension is not potentially-evaluated well-formed in this case
C++11 the array bound could not be
deduced in a new expression deduction permitted See also