7 Expressions [expr]

7.6 Compound expressions [expr.compound]

7.6.2 Unary expressions [expr.unary]

7.6.2.8 New [expr.new]

1
#
The new-expression attempts to create an object of the type-id or new-type-id ([dcl.name]) to which it is applied.
The type of that object is the allocated type.
This type shall be a complete object type ([basic.types.general]), but not an abstract class type ([class.abstract]) or array thereof ([intro.object]).
[Note 1: 
Because references are not objects, references cannot be created by new-expressions.
— end note]
[Note 2: 
The type-id can be a cv-qualified type, in which case the object created by the new-expression has a cv-qualified type.
— end note]
2
#
If a placeholder type or a placeholder for a deduced class type ([dcl.type.class.deduct]) appears in the type-specifier-seq of a new-type-id or type-id of a new-expression, the allocated type is deduced as follows: Let init be the new-initializer, if any, and T be the new-type-id or type-id of the new-expression, then the allocated type is the type deduced for the variable x in the invented declaration ([dcl.spec.auto]): T x init ;
[Example 1: new auto(1); // allocated type is int auto x = new auto('a'); // allocated type is char, x is of type char* template<class T> struct A { A(T, T); }; auto y = new A{1, 2}; // allocated type is A<int> — end example]
3
#
The new-type-id in a new-expression is the longest possible sequence of new-declarators.
[Note 3: 
This prevents ambiguities between the declarator operators &, &&, *, and [] and their expression counterparts.
— end note]
[Example 2: new int * i; // syntax error: parsed as (new int*) i, not as (new int)*i
The * is the pointer declarator and not the multiplication operator.
— end example]
4
#
[Note 4: 
Parentheses in a new-type-id of a new-expression can have surprising effects.
[Example 3: 
new int(*[10])(); // error is ill-formed because the binding is (new int) (*[10])(); // error
Instead, the explicitly parenthesized version of the new operator can be used to create objects of compound types ([basic.compound]):
new (int (*[10])()); allocates an array of 10 pointers to functions (taking no argument and returning int).
— end example]
— end note]
5
#
The attribute-specifier-seq in a noptr-new-declarator appertains to the associated array type.
6
#
Every constant-expression in a noptr-new-declarator shall be a converted constant expression ([expr.const]) of type std​::​size_t and its value shall be greater than zero.
[Example 4: 
Given the definition int n = 42, new float[n][5] is well-formed (because n is the expression of a noptr-new-declarator), but new float[5][n] is ill-formed (because n is not a constant expression).
— end example]
7
#
If the type-id or new-type-id denotes an array type of unknown bound ([dcl.array]), the new-initializer shall not be omitted; the allocated object is an array with n elements, where n is determined from the number of initial elements supplied in the new-initializer ([dcl.init.aggr], [dcl.init.string]).
8
#
If the expression in a noptr-new-declarator is present, it is implicitly converted to std​::​size_t.
The expression is erroneous if:
  • (8.1)
    the expression is of non-class type and its value before converting to std​::​size_t is less than zero;
  • (8.2)
    the expression is of class type and its value before application of the second standard conversion ([over.ics.user])62 is less than zero;
  • (8.3)
    its value is such that the size of the allocated object would exceed the implementation-defined limit; or
  • (8.4)
    the new-initializer is a braced-init-list and the number of array elements for which initializers are provided (including the terminating '\0' in a string-literal ([lex.string])) exceeds the number of elements to initialize.
If the expression is erroneous after converting to std​::​size_t:
When the value of the expression is zero, the allocation function is called to allocate an array with no elements.
9
#
If the allocated type is an array, the new-initializer is a braced-init-list, and the expression is potentially-evaluated and not a core constant expression, the semantic constraints of copy-initializing a hypothetical element of the array from an empty initializer list are checked ([dcl.init.list]).
[Note 5: 
The array can contain more elements than there are elements in the braced-init-list, requiring initialization of the remainder of the array elements from an empty initializer list.
— end note]
10
#
Objects created by a new-expression have dynamic storage duration ([basic.stc.dynamic]).
[Note 6: 
The lifetime of such an object is not necessarily restricted to the scope in which it is created.
— end note]
11
#
When the allocated type is “array of N T” (that is, the noptr-new-declarator syntax is used or the new-type-id or type-id denotes an array type), the new-expression yields a prvalue of type “pointer to T” that points to the initial element (if any) of the array.
Otherwise, let T be the allocated type; the new-expression is a prvalue of type “pointer to T” that points to the object created.
[Note 7: 
Both new int and new int[10] have type int* and the type of new int[i][10] is int (*)[10].
— end note]
12
#
A new-expression may obtain storage for the object by calling an allocation function ([basic.stc.dynamic.allocation]).
If the new-expression terminates by throwing an exception, it may release storage by calling a deallocation function.
If the allocated type is a non-array type, the allocation function's name is operator new and the deallocation function's name is operator delete.
If the allocated type is an array type, the allocation function's name is operator new[] and the deallocation function's name is operator delete[].
[Note 8: 
An implementation is expected to provide default definitions for the global allocation functions ([basic.stc.dynamic], [new.delete.single], [new.delete.array]).
A C++ program can provide alternative definitions of these functions ([replacement.functions]) and/or class-specific versions ([class.free]).
The set of allocation and deallocation functions that can be called by a new-expression can include functions that do not perform allocation or deallocation; for example, see [new.delete.placement].
— end note]
13
#
If the new-expression does not begin with a unary ​::​ operator and the allocated type is a class type T or array thereof, a search is performed for the allocation function's name in the scope of T ([class.member.lookup]).
Otherwise, or if nothing is found, the allocation function's name is looked up by searching for it in the global scope.
14
#
An implementation is allowed to omit a call to a replaceable global allocation function ([new.delete.single], [new.delete.array]).
When it does so, the storage is instead provided by the implementation or provided by extending the allocation of another new-expression.
15
#
During an evaluation of a constant expression, a call to an allocation function is always omitted.
[Note 9: 
Only new-expressions that would otherwise result in a call to a replaceable global allocation function can be evaluated in constant expressions ([expr.const]).
— end note]
16
#
The implementation may extend the allocation of a new-expression e1 to provide storage for a new-expression e2 if the following would be true were the allocation not extended:
  • (16.1)
    the evaluation of e1 is sequenced before the evaluation of e2, and
  • (16.2)
    e2 is evaluated whenever e1 obtains storage, and
  • (16.3)
    both e1 and e2 invoke the same replaceable global allocation function, and
  • (16.4)
    if the allocation function invoked by e1 and e2 is throwing, any exceptions thrown in the evaluation of either e1 or e2 would be first caught in the same handler, and
  • (16.5)
    the pointer values produced by e1 and e2 are operands to evaluated delete-expressions, and
  • (16.6)
    the evaluation of e2 is sequenced before the evaluation of the delete-expression whose operand is the pointer value produced by e1.
[Example 5: void can_merge(int x) { // These allocations are safe for merging: std::unique_ptr<char[]> a{new (std::nothrow) char[8]}; std::unique_ptr<char[]> b{new (std::nothrow) char[8]}; std::unique_ptr<char[]> c{new (std::nothrow) char[x]}; g(a.get(), b.get(), c.get()); } void cannot_merge(int x) { std::unique_ptr<char[]> a{new char[8]}; try { // Merging this allocation would change its catch handler. std::unique_ptr<char[]> b{new char[x]}; } catch (const std::bad_alloc& e) { std::cerr << "Allocation failed: " << e.what() << std::endl; throw; } } — end example]
17
#
When a new-expression calls an allocation function and that allocation has not been extended, the new-expression passes the amount of space requested to the allocation function as the first argument of type std​::​size_t.
That argument shall be no less than the size of the object being created; it may be greater than the size of the object being created only if the object is an array and the allocation function is not a non-allocating form ([new.delete.placement]).
For arrays of char, unsigned char, and std​::​byte, the difference between the result of the new-expression and the address returned by the allocation function shall be an integral multiple of the strictest fundamental alignment requirement of any object type whose size is no greater than the size of the array being created.
[Note 10: 
Because allocation functions are assumed to return pointers to storage that is appropriately aligned for objects of any type with fundamental alignment, this constraint on array allocation overhead permits the common idiom of allocating character arrays into which objects of other types will later be placed.
— end note]
18
#
When a new-expression calls an allocation function and that allocation has been extended, the size argument to the allocation call shall be no greater than the sum of the sizes for the omitted calls as specified above, plus the size for the extended call had it not been extended, plus any padding necessary to align the allocated objects within the allocated memory.
19
#
The new-placement syntax is used to supply additional arguments to an allocation function; such an expression is called a placement new-expression.
20
#
Overload resolution is performed on a function call created by assembling an argument list.
The first argument is the amount of space requested, and has type std​::​size_t.
If the type of the allocated object has new-extended alignment, the next argument is the type's alignment, and has type std​::​align_val_t.
If the new-placement syntax is used, the initializer-clauses in its expression-list are the succeeding arguments.
If no matching function is found then
  • (20.1)
    if the allocated object type has new-extended alignment, the alignment argument is removed from the argument list;
  • (20.2)
    otherwise, an argument that is the type's alignment and has type std​::​align_val_t is added into the argument list immediately after the first argument;
and then overload resolution is performed again.
21
#
[Example 6: 
  • (21.1)
    new T results in one of the following calls: operator new(sizeof(T)) operator new(sizeof(T), std::align_val_t(alignof(T)))
  • (21.2)
    new(2,f) T results in one of the following calls: operator new(sizeof(T), 2, f) operator new(sizeof(T), std::align_val_t(alignof(T)), 2, f)
  • (21.3)
    new T[5] results in one of the following calls: operator new[](sizeof(T) * 5 + x) operator new[](sizeof(T) * 5 + x, std::align_val_t(alignof(T)))
  • (21.4)
    new(2,f) T[5] results in one of the following calls: operator new[](sizeof(T) * 5 + x, 2, f) operator new[](sizeof(T) * 5 + x, std::align_val_t(alignof(T)), 2, f)
Here, each instance of x is a non-negative unspecified value representing array allocation overhead; the result of the new-expression will be offset by this amount from the value returned by operator new[].
This overhead may be applied in all array new-expressions, including those referencing a placement allocation function, except when referencing the library function operator new[](std​::​size_t, void*).
The amount of overhead may vary from one invocation of new to another.
— end example]
22
#
[Note 11: 
Unless an allocation function has a non-throwing exception specification, it indicates failure to allocate storage by throwing a std​::​bad_alloc exception ([basic.stc.dynamic.allocation], [except], [bad.alloc]); it returns a non-null pointer otherwise.
If the allocation function has a non-throwing exception specification, it returns null to indicate failure to allocate storage and a non-null pointer otherwise.
— end note]
If the allocation function is a non-allocating form ([new.delete.placement]) that returns null, the behavior is undefined.
Otherwise, if the allocation function returns null, initialization shall not be done, the deallocation function shall not be called, and the value of the new-expression shall be null.
23
#
[Note 12: 
When the allocation function returns a value other than null, it must be a pointer to a block of storage in which space for the object has been reserved.
The block of storage is assumed to be appropriately aligned ([basic.align]) and of the requested size.
The address of the created object will not necessarily be the same as that of the block if the object is an array.
— end note]
24
#
A new-expression that creates an object of type T initializes that object as follows:
25
#
The invocation of the allocation function is sequenced before the evaluations of expressions in the new-initializer.
Initialization of the allocated object is sequenced before the value computation of the new-expression.
26
#
If the new-expression creates an array of objects of class type, the destructor is potentially invoked ([class.dtor]).
27
#
If any part of the object initialization described above63 terminates by throwing an exception and a suitable deallocation function can be found, the deallocation function is called to free the memory in which the object was being constructed, after which 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.
[Note 14: 
This is appropriate when the called allocation function does not allocate memory; otherwise, it is likely to result in a memory leak.
— end note]
28
#
If the new-expression does not begin with a unary ​::​ operator and the allocated type is a class type T or an array thereof, a search is performed for the deallocation function's name in the scope of T.
Otherwise, or if nothing is found, the deallocation function's name is looked up by searching for it in the global scope.
29
#
A declaration of a placement deallocation function matches the declaration of a placement allocation function if it has the same number of parameters and, after parameter transformations ([dcl.fct]), all parameter types except the first are identical.
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 usual 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.
For a non-placement allocation function, the normal deallocation function lookup is used to find the matching deallocation function ([expr.delete]).
In any case, the matching deallocation function (if any) shall be non-deleted and accessible from the point where the new-expression appears.
[Example 7: struct S { // Placement allocation function: static void* operator new(std::size_t, std::size_t); // Usual (non-placement) deallocation function: static void operator delete(void*, std::size_t); }; S* p = new (0) S; // error: non-placement deallocation function matches // placement allocation function — end example]
30
#
If a new-expression calls a deallocation function, it passes the value returned from the allocation function call as the first argument of type void*.
If a placement deallocation function is called, it is passed the same additional arguments as were passed to the placement allocation function, that is, the same arguments as those specified with the new-placement syntax.
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.
62)62)
If the conversion function returns a signed integer type, the second standard conversion converts to the unsigned type std​::​size_t and thus thwarts any attempt to detect a negative value afterwards.
63)63)
This can include evaluating a new-initializer and/or calling a constructor.