cpp/memory/new/operator new

Attempts to allocate requested number of bytes, and the allocation request can fail (even if the requested number of bytes is zero). These allocation functions are called by new-expressions to allocate memory in which new object would then be initialized. They may also be called using regular function call syntax.

@1@ Called by non-array new-expressions to allocate storage required for a single object. The standard library implementation allocates bytes from free store. In case of failure, the standard library implementation calls the function pointer returned by std and repeats allocation attempts until new handler does not return or becomes a null pointer, at which time it throws std. This function is required to return a pointer suitably aligned to point to an object of the requested size. @2@ Called by the array form of new[]-expressions to allocate all storage required for an array (including possible new-expression overhead). The standard library implementation calls version. @3@ Called by non-array new-expressions to allocate storage required for a single object whose alignment requirement exceeds. @4@ Called by the array form of new[]-expressions to allocate all storage required for an array of objects whose alignment requirement exceeds. @5@ Called by the non-throwing non-array new-expressions. The standard library implementation calls the version and returns a null pointer on failure instead of propagating the exception. @6@ Called by the non-throwing array form of new[]-expressions. The standard library implementation calls the version and returns a null pointer on failure instead of propagating the exception. @7@ Called by the non-throwing non-array new-expressions when the object's alignment requirement exceeds. The standard library implementation calls the version and returns a null pointer on failure instead of propagating the exception. @8@ Called by the non-throwing array form of new[]-expressions when the alignment requirement of array elements exceeds. The standard library implementation calls the version and returns a null pointer on failure instead of propagating the exception.

@9@ Called by the standard single-object placement new expression. The standard library implementation performs no action and returns unmodified. The behavior is undefined if this function is called through a placement new expression and is a null pointer. @10@ Called by the standard array form placement new expression. The standard library implementation performs no action and returns unmodified. The behavior is undefined if this function is called through a placement new expression and is a null pointer.

@11@ If defined, called by the custom single-object placement new expression with the matching signature. If a class-specific version is defined, it is called in preference to. If neither nor  is provided by the user, the placement new expression is ill-formed. @12@ If defined, called by the custom array form placement new expression with the matching signature. If a class-specific version is defined, it is called in preference to. If neither nor  is provided by the user, the placement new expression is ill-formed. @13@ If defined, called by the custom single-object placement new expression with the matching signature if the object's alignment requirement exceeds. If a class-specific version is defined ( or ), it is called instead. If neither class-specific nor global alignment-aware (this one) placement form is provided, alignment-unaware placement form is looked up instead. @14@ If defined, called by the custom array form placement new expression with the matching signature if the element's alignment requirement exceeds. If a class-specific version ( or ) is defined, it is called instead. If neither class-specific nor global alignment-aware (this one) placement form is provided, alignment-unaware placement form is looked up instead.

@15@ If defined, called by the usual single-object new-expressions if allocating an object of type T. @16@ If defined, called by the usual array new[]-expressions if allocating an array of objects of type T. @17@ If defined, called by the usual single-object new-expressions if allocating an object of type T if its alignment requirement exceeds. If this overload is not provided, but alignment-unaware member form is, alignment-unaware member overload is called instead. @18@ If defined, called by the usual array new[]-expressions if allocating an array of objects of type T if its alignment requirement exceeds. If this overload is not provided, but alignment-unaware member form is, alignment-unaware member overload is called instead.

@19@ If defined, called by the custom single-object placement new expression with the matching signature if allocating an object of type T. @20@ If defined, called by the custom array form of placement new[] expression with the matching signature if allocating an array of objects of type T. @21@ If defined, called by the custom single-object placement new expression with the matching signature if allocating an object of type T if its alignment requirement exceeds. If this overload is not provided, but alignment-unaware member form is, alignment-unaware member overload is called instead. @22@ If defined, called by the custom array form of placement new[] expression with the matching signature if allocating an array of objects of type T if its alignment requirement exceeds. If this overload is not provided, but alignment-unaware member form is, alignment-unaware member overload is called instead.

Return value
@1-4@ If the allocation succeeds, a non-null pointer which points to suitably aligned memory of size at least  and is different from any previously returned value, unless that value  was subsequently passed to a replaceable ; if the allocation fails, does not return (an exception is thrown, see below). @5-8@ Same as, but returns a null pointer if the allocation fails. @9-10@ . @11-22@ Same as if the function does not return on allocation failure, otherwise same as.

Exceptions
@1-4@ Throws an exception of a type that would match a handler of type std on failure to allocate memory. @11-22@ Same as if the function does not return on allocation failure, otherwise same as.

Global replacements
The versions are implicitly declared in each translation unit even if the  header is not included. Versions are replaceable: a user-provided non-member function with the same signature defined anywhere in the program, in any source file, replaces the default version. Its declaration does not need to be visible.

The program is ill-formed, no diagnostic required if more than one replacement is provided in the program for any of the replaceable allocation function, or if a replacement is declared with the specifier. The program is ill-formed if a replacement is defined in namespace other than global namespace, or if it is defined as a static non-member function at global scope.

The standard library implementations of the nothrow versions directly calls the corresponding throwing versions. The standard library implementation of the throwing array versions directly calls the corresponding single-object version. Thus, replacing the throwing single object allocation functions is sufficient to handle all allocations.

Overloads of and  with additional user-defined parameters ("placement forms", versions ) may be declared at global scope as usual, and are called by the matching placement forms of new-expressions.

The standard library's non-allocating placement forms of  cannot be replaced and can only be customized if the placement new-expression did not use the  syntax, by providing a class-specific placement new  with matching signature:  or.

Class-specific overloads
Both single-object and array allocation functions may be defined as public static member functions of a class (versions ). If defined, these allocation functions are called by new-expressions to allocate memory for single objects and arrays of this class, unless the new expression used the form which bypasses class-scope lookup. The keyword is optional for these functions: whether used or not, the allocation function is a static member function.

The new expression looks for appropriate allocation function's name firstly in the class scope, and after that in the global scope. Note, that as per name lookup rules, any allocation functions declared in class scope hides all global allocation functions for the new-expressions that attempt to allocate objects of this class.

Overloads of and  with additional user-defined parameters ("placement forms"), may also be defined as class members ). When the placement new expression with the matching signature looks for the corresponding allocation function to call, it begins at class scope before examining the global scope, and if the class-specific placement new is provided, it is called.

If class-level is a template function, it must have the return type of, the first argument std, and it must have two or more parameters. In other words, only placement forms can be templates.