cpp/language/new

Creates and initializes objects with dynamic, that is, objects whose lifetime is not necessarily limited by the scope in which they were created.

Syntax
@1@ Attempts to create an object of type, denoted by the, which may be array type. @2@ Same as (1), but cannot include parentheses:


 * In addition, is greedy: it will include every token that can be a part of a declarator:

@3@ Same as (1), but provides additional arguments to the allocation function, see. @4@ Same as (2), but provides additional arguments to the allocation function.

The is not optional if
 * or is an ,

Explanation
The 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.

If is an array type, all dimensions other than the first must be specified as positive, but (only when using un-parenthesized syntaxes   and ) the first dimension may be. This is the only way to directly create an array with size defined at runtime, such arrays are often referred to as dynamic arrays:

The first dimension of zero is acceptable, and the allocation function is called.

Note: std offers similar functionality for one-dimensional dynamic arrays.

Allocation
The new-expression allocates storage by calling the appropriate allocation function. If is a non-array type, the name of the function is. If is an array type, the name of the function is.

As described in allocation function, the C++ program may provide global and class-specific replacements for these functions. If the new-expression begins with the optional operator, as in  or, class-specific replacements will be ignored (the function is  in global ). Otherwise, if is a class type, lookup begins in the class scope of.

When calling the allocation function, the new-expression passes the number of bytes requested as the first argument, of type, which is exactly for non-array.

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, , 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.

Placement new
If 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, which simply returns its second argument unchanged. This is used to construct objects in allocated storage:

Note: this functionality is encapsulated by the member functions of the classes.

If a non-throwing allocation function (e.g. the one selected by ) 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.

Construction
The object created by a new-expression is initialized according to the following rules:
 * For non-array, the single object is constructed in the acquired memory area.
 * If is absent, the object is.
 * If is a parenthesized list of arguments, the object is.


 * If or  is an array type, an array of objects is initialized.
 * If is absent, each element is.
 * If is an empty pair of parentheses, each element is.

If initialization terminates by throwing an exception (e.g. from the constructor), if new-expression allocated any storage, it calls the appropriate deallocation function: for non-array,  for array. The deallocation function is looked up in global scope if the new-expression used the syntax, otherwise it is looked up in the scope of, if  is a class type. If the failed allocation function was usual (non-placement), lookup for the deallocation function follows the rules described in. For a failed placement new, all parameter types, except the first, of the matching deallocation function must be identical to the parameters of the placement new. The call to the deallocation function is made the value obtained earlier from the allocation function passed as the first argument, and, if any, passed as the additional placement arguments. If no deallocation function is found, memory is not deallocated.

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:

or if the pointer goes out of scope:

or due to exception:

To simplify management of dynamically-allocated objects, the result of a new-expression is often stored in a smart pointer:. These pointers guarantee that the delete expression is executed in the situations shown above.