Defined in header
Replaceable allocation functions
void*operatornew(std::size_tcount); (1)void*operatornew[](std::size_tcount); (2)void*operatornew(std::size_tcount,std::align_val_tal); (3)(since C++17)void*operatornew[](std::size_tcount,std::align_val_tal); (4)(since C++17)Replaceable non-throwing allocation functions
void*operatornew(std::size_tcount,conststd::nothrow_t&tag); (5)(noexcept since C++11)void*operatornew[](std::size_tcount,conststd::nothrow_t&tag); (6)(noexcept since C++11)void*operatornew(std::size_tcount,std::align_val_tal,conststd::nothrow_t&tag)noexcept; (7)(since C++17)void*operatornew[](std::size_tcount,std::align_val_tal,conststd::nothrow_t&tag)noexcept; (8)(since C++17)Non-allocating placement allocation functions
void*operatornew(std::size_tcount,void*ptr); (9)(noexcept since C++11)
(constexpr since C++26)void*operatornew[](std::size_tcount,void*ptr); (10)(noexcept since C++11)
(constexpr since C++26)User-defined placement allocation functions
void*operatornew(std::size_tcount,/* args... */); (11)void*operatornew[](std::size_tcount,/* args... */); (12)void*operatornew(std::size_tcount,std::align_val_tal,/* args... */); (13)(since C++17)void*operatornew[](std::size_tcount,std::align_val_tal,/* args... */); (14)(since C++17)Class-specific allocation functions
void*T::operatornew(std::size_tcount); (15)void*T::operatornew[](std::size_tcount); (16)void*T::operatornew(std::size_tcount,std::align_val_tal); (17)(since C++17)void*T::operatornew[](std::size_tcount,std::align_val_tal); (18)(since C++17)Class-specific placement allocation functions
void*T::operatornew(std::size_tcount,/* args... */); (19)void*T::operatornew[](std::size_tcount,/* args... */); (20)void*T::operatornew(std::size_tcount,std::align_val_tal,/* args... */); (21)(since C++17)void*T::operatornew[](std::size_tcount,std::align_val_tal,/* args... */); (22)(since C++17)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
to allocate memory in which new object would then be initialized. They may also be called using regular function call syntax.
1-8)
allocation functions. The standard library provides default implementations for these functions, for the effects of the default implementations, see
.
9,10) Called by the standard
. Performs no action and returns ptr unmodified.
If this function is called through placement new and ptr is a null pointer, the behavior is undefined.
11-22) User-defined allocation functions called by new expressions.
Overloads (
) are implicitly declared in each translation unit even if the
header is not included.
See
for the criteria of selecting overload.
Parameters
count - number of bytes to allocate ptr - pointer to a memory area to initialize the object at tag - disambiguation tag used to select non-throwing overloads al - alignment to use, invalid value leads to undefined behavior Return value
1-4) If the allocation succeeds, a non-null pointer p0 which points to suitably aligned memory of size at least size and is different from any previously returned value p1, unless that value p1 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)ptr
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
on failure to allocate memory.
11-22) Same as (
) if the function does not return on allocation failure, otherwise same as (
).
Global replacements
Overloads (
) are
. The effects of the default versions are:
1) Attempts to allocate the requested storage. Whether the attempt involves a call to
or
is unspecified.
If the attempt is successful, returns a pointer to the allocated storage, the storage is aligned to the fundamental alignment(until C++17)the storage is aligned to __STDCPP_DEFAULT_NEW_ALIGNMENT__(since C++17).
Otherwise, if currently no
is installed, throws
.
Otherwise, calls the currently installed new-handler. If the new-handler returns, starts another allocation attempt.
Otherwise, exits the current invocation.
2) Returns operatornew(count).
3) Same as (1), except that the returned storage is aligned to al.
4) Returns operatornew(count,al).
5-8) Calls (1-4) respectively with the same arguments except for tag.
If the call returns normally, returns the result of that call.
Otherwise, returns a null pointer.
On
, it is implementation-defined whether the default versions of (
) satisfy the behaviors required above. Freestanding implementations are recommended that if any of these default versions meet the requirements of a hosted implementation, they all should.
(since C++26)Global operators new/delete replacement:
Run this code
#include<cstdio>#include<cstdlib>#include<new>// no inline, required by [replacement.functions]/3void*operatornew(std::size_tsz){std::printf("1) new(size_t), size = %zu\n",sz);if(sz==0)++sz;// avoid std::malloc(0) which may return nullptr on successif(void*ptr=std::malloc(sz))returnptr;throwstd::bad_alloc{};// required by [new.delete.single]/3}// no inline, required by [replacement.functions]/3void*operatornew[](std::size_tsz){std::printf("2) new[](size_t), size = %zu\n",sz);if(sz==0)++sz;// avoid std::malloc(0) which may return nullptr on successif(void*ptr=std::malloc(sz))returnptr;throwstd::bad_alloc{};// required by [new.delete.single]/3}voidoperatordelete(void*ptr)noexcept{std::puts("3) delete(void*)");std::free(ptr);}voidoperatordelete(void*ptr,std::size_tsize)noexcept{std::printf("4) delete(void*, size_t), size = %zu\n",size);std::free(ptr);}voidoperatordelete[](void*ptr)noexcept{std::puts("5) delete[](void* ptr)");std::free(ptr);}voidoperatordelete[](void*ptr,std::size_tsize)noexcept{std::printf("6) delete[](void*, size_t), size = %zu\n",size);std::free(ptr);}intmain(){int*p1=newint;deletep1;int*p2=newint[10];// guaranteed to call the replacement in C++11delete[]p2;}Possible output:
// Compiled with GCC-5 in C++17 mode to obtain the following: 1) op new(size_t), size = 4 4) op delete(void*, size_t), size = 4 2) op new[](size_t), size = 40 5) op delete[](void* ptr) Overloads of operator new and operator new[] with additional user-defined parameters ("placement forms", versions (
)) may be declared at global scope as usual, and are called by the matching
of new expressions.
The standard library's non-allocating placement forms of operator new(
) cannot be replaced and can only be customized if the placement new expression did not use the ::new syntax, by providing a class-specific placement new(
) with matching signature: void*T::operatornew(std::size_t,void*) or void*T::operatornew[](std::size_t,void*).
The placement form void*operatornew(std::size_t,std::size_t) is not allowed because the matching signature of the deallocation function, voidoperatordelete(void*,std::size_t), is a usual (not placement) deallocation function.
(since C++14)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 ::new 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
, any allocation functions declared in class scope hides all global allocation functions for the new expressions that attempt to allocate objects of this class.
When allocating objects and arrays of objects whose alignment exceeds __STDCPP_DEFAULT_NEW_ALIGNMENT__, overload resolution is performed twice: first, for alignment-aware function signatures, then for alignment-unaware function signatures. This means that if a class with
has an alignment-unaware class-specific allocation function, it is the function that will be called, not the global alignment-aware allocation function. This is intentional: the class member is expected to know best how to handle that class.
(since C++17)When allocating objects and arrays of objects whose alignment does not exceed __STDCPP_DEFAULT_NEW_ALIGNMENT__, overload resolution is performed twice: first, for alignment-unaware function signatures, then for alignment-aware function signatures.
(since C++20)Run this code
#include<cstddef>#include<iostream>// class-specific allocation functionsstructX{staticvoid*operatornew(std::size_tcount){std::cout<<"custom new for size "<<count<<'\n';return::operatornew(count);}staticvoid*operatornew[](std::size_tcount){std::cout<<"custom new[] for size "<<count<<'\n';return::operatornew[](count);}};intmain(){X*p1=newX;deletep1;X*p2=newX[10];delete[]p2;}Possible output:
custom new for size 1 custom new[] for size 10 Overloads of operator new and operator new[] 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.
When allocating objects and arrays of objects whose alignment exceeds __STDCPP_DEFAULT_NEW_ALIGNMENT__, overload resolution for placement forms is performed twice just as for regular forms: first, for alignment-aware function signatures, then for alignment-unaware function signatures.
(since C++17)When allocating objects and arrays of objects whose alignment does not exceed __STDCPP_DEFAULT_NEW_ALIGNMENT__, overload resolution for placement forms is performed twice just as for regular forms: first, for alignment-unaware function signatures, then for alignment-aware function signatures.
(since C++20)Run this code
#include<cstddef>#include<iostream>#include<stdexcept>structX{X(){throwstd::runtime_error("");}// custom placement newstaticvoid*operatornew(std::size_tcount,boolb){std::cout<<"custom placement new called, b = "<<b<<'\n';return::operatornew(count);}// custom placement deletestaticvoidoperatordelete(void*ptr,boolb){std::cout<<"custom placement delete called, b = "<<b<<'\n';::operatordelete(ptr);}};intmain(){try{[[maybe_unused]]X*p1=new(true)X;}catch(conststd::exception&){}}Output:
custom placement new called, b = 1 custom placement delete called, b = 1 If class-level operator new is a template function, it must have the return type of void*, the first argument
, and it must have two or more parameters. In other words, only placement forms can be templates.
Notes
Even though the non-allocating placement new(
) cannot be replaced, a function with the same signature may be defined at class scope as described above. In addition, global overloads that look like placement new but take a non-void pointer type as the second argument are allowed, so the code that wants to ensure that the true placement new is called (e.g.
), must use ::new and also cast the pointer to void*.
If the behavior of a deallocation function does not satisfy the default constraints, the behavior is undefined.
It is unspecified whether library versions of operator new make any calls to
or
(since C++17).
For loading a large file, file mapping via OS-specific functions, e.g.,
on POSIX or CreateFileMapping(
/
) along with
on Windows, is preferable to allocating a buffer for file reading.
macro ValueStdFeature
__cpp_lib_freestanding_operator_new
(C++26)freestanding support for replaceable operatornew
(C++26)no freestanding support
(C++26)constexpr placement new and new[]
Formally, this macro expands to 202306L if all the default versions of the replaceable global allocation functions meet the requirements of a hosted implementation.
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 any class derived from
could be thrown,
even if the
base is ambiguous or inaccessible the exception thrown should match
a handler of type
C++98 multiple calls for allocating zero
bytes could yield the same pointer only allowed if all such previously
yielded pointers have been
passed to deallocation functions
C++98 replacing the replaceable allocation functions did
not affect the default behaviors of the corresponding
replaceable non-throwing allocation functions the default behaviors
change accordingly
C++98 replacements of the replaceable allocation
functions could be declared inlineprohibited, no diagnostic required References
C++23 standard (ISO/IEC 14882:2024):
17.7 Dynamic memory management [support.dynamic]
C++20 standard (ISO/IEC 14882:2020):
17.6 Dynamic memory management [support.dynamic]
C++17 standard (ISO/IEC 14882:2017):
21.6 Dynamic memory management [support.dynamic]
C++14 standard (ISO/IEC 14882:2014):
18.6 Dynamic memory management [support.dynamic]
C++11 standard (ISO/IEC 14882:2011):
18.6 Dynamic memory management [support.dynamic]
C++03 standard (ISO/IEC 14882:2003):
18.4 Dynamic memory management [lib.support.dynamic]
C++98 standard (ISO/IEC 14882:1998):
18.4 Dynamic memory management [lib.support.dynamic]
See also
[static](C++23)
allocates memory using Allocator
(public static member function of std::generator<Ref,V,Allocator>::promise_type)
operator deleteoperator delete[]
deallocation functions
(function)
(C++11)
obtains the current new handler
(function)
registers a new handler
(function)
(deprecated in C++17)(removed in C++20)
obtains uninitialized storage
(function template)
allocates memory
(function)
(C++17)
allocates aligned memory
(function)