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 bynew expressions to allocate memory in which new object would then be initialized. They may also be called using regular function call syntax.

Overloads(1-4) are implicitly declared in each translation unit even if the<new> header is not included.

Seenew expression for the criteria of selecting overload.

[edit]Parameters

[edit]Return value

[edit]Exceptions

[edit]Global replacements

Overloads(1-8) arereplaceable. The effects of the default versions are:

#include <cstdio>#include <cstdlib>#include <new> // no inline, required by [replacement.functions]/3void* operator new(std::size_t sz){std::printf("1) new(size_t), size = %zu\n", sz);if(sz==0)++sz;// avoid std::malloc(0) which may return nullptr on success if(void*ptr=std::malloc(sz))return ptr; throwstd::bad_alloc{};// required by [new.delete.single]/3} // no inline, required by [replacement.functions]/3void* operator new[](std::size_t sz){std::printf("2) new[](size_t), size = %zu\n", sz);if(sz==0)++sz;// avoid std::malloc(0) which may return nullptr on success if(void*ptr=std::malloc(sz))return ptr; throwstd::bad_alloc{};// required by [new.delete.single]/3} voidoperator delete(void* ptr)noexcept{std::puts("3) delete(void*)");std::free(ptr);} voidoperator delete(void* ptr,std::size_t size)noexcept{std::printf("4) delete(void*, size_t), size = %zu\n", size);std::free(ptr);} voidoperator delete[](void* ptr)noexcept{std::puts("5) delete[](void* ptr)");std::free(ptr);} voidoperator delete[](void* ptr,std::size_t size)noexcept{std::printf("6) delete[](void*, size_t), size = %zu\n", size);std::free(ptr);} int main(){int* p1= newint;    delete p1; int* p2= newint[10];// guaranteed to call the replacement in C++11    delete[] p2;}

// Compiled with GCC-5 in C++17 mode to obtain the following:1) op new(size_t), size = 44) op delete(void*, size_t), size = 42) op new[](size_t), size = 405) op delete[](void* ptr)

Overloads ofoperator new andoperator new[] with additional user-defined parameters ("placement forms", versions(11-14)) may be declared at global scope as usual, and are called by the matchingplacement forms ofnew expressions.

The standard library's non-allocating placement forms ofoperator new(9,10) cannot be replaced and can only be customized if the placementnew expression did not use the::new syntax, by providing a class-specific placementnew(19,20) with matching signature:void* T::operator new(std::size_t,void*) orvoid* T::operator new[](std::size_t,void*).

[edit]Class-specific overloads

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

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

#include <cstddef>#include <iostream> // class-specific allocation functionsstruct X{staticvoid* operator new(std::size_t count){std::cout<<"custom new for size "<< count<<'\n';return::operator new(count);} staticvoid* operator new[](std::size_t count){std::cout<<"custom new[] for size "<< count<<'\n';return::operator new[](count);}}; int main(){    X* p1= new X;    delete p1;    X* p2= new X[10];    delete[] p2;}

custom new for size 1custom new[] for size 10

Overloads ofoperator new andoperator new[] with additional user-defined parameters ("placement forms"), may also be defined as class members(19-22)). When the placementnew 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 placementnew is provided, it is called.

#include <cstddef>#include <iostream>#include <stdexcept> struct X{    X(){throwstd::runtime_error("");} // custom placement newstaticvoid* operator new(std::size_t count,bool b){std::cout<<"custom placement new called, b = "<< b<<'\n';return::operator new(count);} // custom placement deletestaticvoidoperator delete(void* ptr,bool b){std::cout<<"custom placement delete called, b = "<< b<<'\n';::operator delete(ptr);}}; int main(){try{[[maybe_unused]] X* p1= new(true) X;}catch(conststd::exception&){}}

custom placement new called, b = 1custom placement delete called, b = 1

If class-leveloperator new is a template function, it must have the return type ofvoid*, the first argumentstd::size_t, and it must have two or more parameters. In other words, only placement forms can be templates.

[edit]Notes

Even though the non-allocating placementnew(9,10) 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 placementnew but take a non-void pointer type as the second argument are allowed, so the code that wants to ensure that the true placementnew is called (e.g.std::allocator::construct), must use::new and also cast the pointer tovoid*.

If the behavior of a deallocation function does not satisfy the default constraints, the behavior is undefined.

It is unspecified whether library versions ofoperator new make any calls tostd::malloc orstd::aligned_alloc(since C++17).

For loading a large file, file mapping via OS-specific functions, e.g.,mmap on POSIX orCreateFileMapping(A/W) along withMapViewOfFile on Windows, is preferable to allocating a buffer for file reading.

1. ↑Formally, this macro expands to202306L if all the default versions of the replaceable global allocation functions meet the requirements of a hosted implementation.

[edit]Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

[edit]References

[edit]See also

• In other languages

• Deutsch
• Español
• Français
• Italiano
• 日本語
• Português
• Русский
• 中文