Except where otherwise specified, the provisions of ([basic.stc.dynamic]) apply to the library versions of operator new and operator delete.
void* operator new(std::size_t size);
Effects: The allocation function ([basic.stc.dynamic.allocation]) called by a new-expression ([expr.new]) to allocate size bytes of storage suitably aligned to represent any object of that size.
Replaceable: a C++ program may define a function with this function signature that displaces the default version defined by the C++ standard library.
Required behavior: Return a non-null pointer to suitably aligned storage ([basic.stc.dynamic]), or else throw a bad_alloc exception. This requirement is binding on a replacement version of this function.
Default behavior:
Executes a loop: Within the loop, the function first attempts to allocate the requested storage. Whether the attempt involves a call to the Standard C library function malloc is unspecified.
Returns a pointer to the allocated storage if the attempt is successful. Otherwise, if the current new_handler ([get.new.handler]) is a null pointer value, throws bad_alloc.
Otherwise, the function calls the current new_handler function ([new.handler]). If the called function returns, the loop repeats.
The loop terminates when an attempt to allocate the requested storage is successful or when a called new_handler function does not return.
void* operator new(std::size_t size, const std::nothrow_t&) noexcept;
Effects: Same as above, except that it is called by a placement version of a new-expression when a C++ program prefers a null pointer result as an error indication, instead of a bad_alloc exception.
Replaceable: a C++ program may define a function with this function signature that displaces the default version defined by the C++ standard library.
Required behavior: Return a non-null pointer to suitably aligned storage ([basic.stc.dynamic]), or else return a null pointer. This nothrow version of operator new returns a pointer obtained as if acquired from the (possibly replaced) ordinary version. This requirement is binding on a replacement version of this function.
Default behavior: Calls operator new(size). If the call returns normally, returns the result of that call. Otherwise, returns a null pointer.
[ Example:
T* p1 = new T; // throws bad_alloc if it fails T* p2 = new(nothrow) T; // returns nullptr if it fails
— end example ]
void operator delete(void* ptr) noexcept;
void operator delete(void* ptr, std::size_t size) noexcept;
Effects: The deallocation function ([basic.stc.dynamic.deallocation]) called by a delete-expression to render the value of ptr invalid.
Replaceable: a C++ program may define a function with signature void operator delete(void* ptr) noexcept that displaces the default version defined by the C++ standard library. If this function (without size parameter) is defined, the program should also define void operator delete(void* ptr, std::size_t size) noexcept. If this function with size parameter is defined, the program shall also define the version without the size parameter. [ Note: The default behavior below may change in the future, which will require replacing both deallocation functions when replacing the allocation function. — end note ]
Requires: ptr shall be a null pointer or its value shall be a value returned by an earlier call to the (possibly replaced) operator new(std::size_t) or operator new(std::size_t,const std::nothrow_t&) which has not been invalidated by an intervening call to operator delete(void*).
Requires: If an implementation has strict pointer safety ([basic.stc.dynamic.safety]) then ptr shall be a safely-derived pointer.
Requires: If present, the std::size_t size argument shall equal the size argument passed to the allocation function that returned ptr.
Required behavior: Calls to operator delete(void* ptr, std::size_t size) may be changed to calls to operator delete(void* ptr) without affecting memory allocation. [ Note: A conforming implementation is for operator delete(void* ptr, std::size_t size) to simply call operator delete(ptr). — end note ]
Default behavior: the function operator delete(void* ptr, std::size_t size) calls operator delete(ptr). [ Note: See the note in the above Replaceable paragraph. — end note ]
Default behavior: If ptr is null, does nothing. Otherwise, reclaims the storage allocated by the earlier call to operator new.
void operator delete(void* ptr, const std::nothrow_t&) noexcept;
void operator delete(void* ptr, std::size_t size, const std::nothrow_t&) noexcept;
Effects: The deallocation function ([basic.stc.dynamic.deallocation]) called by the implementation to render the value of ptr invalid when the constructor invoked from a nothrow placement version of the new-expression throws an exception.
Replaceable: a C++ program may define a function with signature void operator delete(void* ptr, const std::nothrow_t&) noexcept that displaces the default version defined by the C++ standard library. If this function (without size parameter) is defined, the program should also define void operator delete(void* ptr, std::size_t size, const std::nothrow_t&) noexcept. If this function with size parameter is defined, the program shall also define the version without the size parameter. [ Note: The default behavior below may change in the future, which will require replacing both deallocation functions when replacing the allocation function. — end note ]
Requires: If an implementation has strict pointer safety ([basic.stc.dynamic.safety]) then ptr shall be a safely-derived pointer.
Requires: If present, the std::size_t size argument must equal the size argument passed to the allocation function that returned ptr.
Required behavior: Calls to operator delete(void* ptr, std::size_t size, const std::nothrow_t&) may be changed to calls to operator delete(void* ptr, const std::nothrow_t&) without affecting memory allocation. [ Note: A conforming implementation is for operator delete(void* ptr, std::size_t size, const std::nothrow_t&) to simply call operator delete(void* ptr, const std::nothrow_t&). — end note ]
Default behavior: operator delete(void* ptr, std::size_t size, const std::nothrow_t&) calls operator delete(ptr, std::nothrow), and operator delete(void* ptr, const std::nothrow_t&) calls operator delete(ptr).
void* operator new[](std::size_t size);
Effects: The allocation function ([basic.stc.dynamic.allocation]) called by the array form of a new-expression ([expr.new]) to allocate size bytes of storage suitably aligned to represent any array object of that size or smaller.227
Replaceable: a C++ program can define a function with this function signature that displaces the default version defined by the C++ standard library.
Required behavior: Same as for operator new(std::size_t). This requirement is binding on a replacement version of this function.
Default behavior: Returns operator new(size).
void* operator new[](std::size_t size, const std::nothrow_t&) noexcept;
Effects: Same as above, except that it is called by a placement version of a new-expression when a C++ program prefers a null pointer result as an error indication, instead of a bad_alloc exception.
Replaceable: a C++ program can define a function with this function signature that displaces the default version defined by the C++ standard library.
Required behavior: Return a non-null pointer to suitably aligned storage ([basic.stc.dynamic]), or return a null pointer. This requirement is binding on a replacement version of this function.
Default behavior: Calls operator new[](size). If the call returns normally, returns the result of that call. Otherwise, returns a null pointer.
void operator delete[](void* ptr) noexcept;
void operator delete[](void* ptr, std::size_t size) noexcept;
Effects: The deallocation function ([basic.stc.dynamic.deallocation]) called by the array form of a delete-expression to render the value of ptr invalid.
Replaceable: a C++ program can define a function with signature void operator delete[](void* ptr) noexcept that displaces the default version defined by the C++ standard library. If this function (without size parameter) is defined, the program should also define void operator delete[](void* ptr, std::size_t size) noexcept. If this function with size parameter is defined, the program shall also define the version without the size parameter. [ Note: The default behavior below may change in the future, which will require replacing both deallocation functions when replacing the allocation function. — end note ]
Requires: ptr shall be a null pointer or its value shall be the value returned by an earlier call to operator new[](std::size_t) or operator new[](std::size_t,const std::nothrow_t&) which has not been invalidated by an intervening call to operator delete[](void*).
Requires: If present, the std::size_t size argument must equal the size argument passed to the allocation function that returned ptr.
Required behavior: Calls to operator delete[](void* ptr, std::size_t size) may be changed to calls to operator delete[](void* ptr) without affecting memory allocation. [ Note: A conforming implementation is for operator delete[](void* ptr, std::size_t size) to simply call operator delete[](void* ptr). — end note ]
Requires: If an implementation has strict pointer safety ([basic.stc.dynamic.safety]) then ptr shall be a safely-derived pointer.
Default behavior: operator delete[](void* ptr, std::size_t size) calls operator delete[](ptr), and operator delete[](void* ptr) calls operator delete(ptr).
void operator delete[](void* ptr, const std::nothrow_t&) noexcept;
void operator delete[](void* ptr, std::size_t size, const std::nothrow_t&) noexcept;
Effects: The deallocation function ([basic.stc.dynamic.deallocation]) called by the implementation to render the value of ptr invalid when the constructor invoked from a nothrow placement version of the array new-expression throws an exception.
Replaceable: a C++ program may define a function with signature void operator delete[](void* ptr, const std::nothrow_t&) noexcept that displaces the default version defined by the C++ standard library. If this function (without size parameter) is defined, the program should also define void operator delete[](void* ptr, std::size_t size, const std::nothrow_t&) noexcept. If this function with size parameter is defined, the program shall also define the version without the size parameter. [ Note: The default behavior below may change in the future, which will require replacing both deallocation functions when replacing the allocation function. — end note ]
Requires: If an implementation has strict pointer safety ([basic.stc.dynamic.safety]) then ptr shall be a safely-derived pointer.
Requires: If present, the std::size_t size argument must equal the size argument passed to the allocation function that returned ptr.
Required behavior: Calls to operator delete[](void* ptr, std::size_t size, const std::nothrow_t&) may be changed to calls to operator delete[](void* ptr, const std::nothrow_t&) without affecting memory allocation. [ Note: A conforming implementation is for operator delete[](void* ptr, std::size_t size, const std::nothrow_t&) to simply call operator delete[](void* ptr, const std::nothrow_t&). — end note ]
Default behavior: operator delete[](void* ptr, std::size_t size, const std::nothrow_t&) calls operator delete[](ptr, std::nothrow), and operator delete[](void* ptr, const std::nothrow_t&) calls operator delete[](ptr).
It is not the direct responsibility of operator new[](std::size_t) or operator delete[](void*) to note the repetition count or element size of the array. Those operations are performed elsewhere in the array new and delete expressions. The array new expression, may, however, increase the size argument to operator new[](std::size_t) to obtain space to store supplemental information.
These functions are reserved, a C++ program may not define functions that displace the versions in the Standard C++ library ([constraints]). The provisions of ([basic.stc.dynamic]) do not apply to these reserved placement forms of operator new and operator delete.
Returns: ptr.
Remarks: Intentionally performs no other action.
[ Example: This can be useful for constructing an object at a known address:
void* place = operator new(sizeof(Something)); Something* p = new (place) Something();
— end example ]
void* operator new[](std::size_t size, void* ptr) noexcept;
Returns: ptr.
Remarks: Intentionally performs no other action.
void operator delete(void* ptr, void*) noexcept;
Effects: Intentionally performs no action.
Requires: If an implementation has strict pointer safety ([basic.stc.dynamic.safety]) then ptr shall be a safely-derived pointer.
Remarks: Default function called when any part of the initialization in a placement new expression that invokes the library's non-array placement operator new terminates by throwing an exception ([expr.new]).
void operator delete[](void* ptr, void*) noexcept;
Effects: Intentionally performs no action.
Requires: If an implementation has strict pointer safety ([basic.stc.dynamic.safety]) then ptr shall be a safely-derived pointer.
Remarks: Default function called when any part of the initialization in a placement new expression that invokes the library's array placement operator new terminates by throwing an exception ([expr.new]).
For purposes of determining the existence of data races, the library versions of operator new, user replacement versions of global operator new, the C standard library functions calloc and malloc, the library versions of operator delete, user replacement versions of operator delete, the C standard library function free, and the C standard library function realloc shall not introduce a data race ([res.on.data.races]). Calls to these functions that allocate or deallocate a particular unit of storage shall occur in a single total order, and each such deallocation call shall happen before ([intro.multithread]) the next allocation (if any) in this order.