Deallocates storage previously allocated by a matchingoperator new oroperator new[]. These deallocation functions are called bydelete anddelete[] expressions and byplacementnew expressions to deallocate memory after destructing (or failing to construct) objects with dynamic storage duration. They may also be called using regular function call syntax.

Ifptr is not a null pointer and one of the following conditions is satisfied, the behavior is undefined:

• Foroperator delete, the value ofptr does not represent the address of a block of memory allocated by an earlier call to (possibly replaced)operator new(std::size_t) (for overloads(1,5,9)) oroperator new(std::size_t,std::align_val_t) (for overloads(3,7,11)) which has not been invalidated by an intervening call tooperator delete.
• Foroperator delete[], the value ofptr does not represent the address of a block of memory allocated by an earlier call to (possibly replaced)operator new[](std::size_t) (for overloads(2,6,10)) oroperator new[](std::size_t,std::align_val_t) (for overloads(4,8,12)) which has not been invalidated by an intervening call tooperator delete[].

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

Seedelete expression for the criteria of selecting overload.

[edit]Parameters

[edit]Exceptions

If a deallocation function terminates by throwing an exception, the behavior is undefined, even if it is declared withnoexcept(false)(since C++11).

[edit]Global replacements

Overloads(1-12) 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} void operator delete(void* ptr)noexcept{std::puts("3) delete(void*)");std::free(ptr);} void operator delete(void* ptr,std::size_t size)noexcept{std::printf("4) delete(void*, size_t), size = %zu\n", size);std::free(ptr);} void operator delete[](void* ptr)noexcept{std::puts("5) delete[](void* ptr)");std::free(ptr);} void operator 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 delete andoperator delete[] with additional user-defined parameters ("placement forms",(15,16)) may be declared at global scope as usual, and are called by the matching placement forms ofnew expressions if a constructor of the object that is being allocated throws an exception.

The standard library placement forms ofoperator delete andoperator delete[](13,14) cannot be replaced and can only be customized if the placementnew expression did not use the::new syntax, by providing a class-specific placement delete(25,26) with matching signature:void T::operator delete(void*,void*) orvoid T::operator delete[](void*,void*).

[edit]Class-specific overloads

Deallocation functions(17-24) may be defined as static member functions of a class. These deallocation functions, if provided, are called bydelete expressions when deleting objects(17,19,21) and arrays(18,20,22) of this class, unless the delete expression used the form::delete which bypasses class-scope lookup. The keywordstatic is optional for these function declarations: whether the keyword is used or not, the deallocation function is always a static member function.

The delete expression looks for appropriate deallocation function's name starting from the class scope (array form looks in the scope of the array element class) and proceeds to the global scope if no members are found as usual. Note, that as pername lookup rules, any deallocation functions declared in class scope hides all global deallocation functions.

If the static type of the object that is being deleted differs from its dynamic type (such as when deleting apolymorphic object through a pointer to base), and if the destructor in the static type is virtual, the single object form of delete begins lookup of the deallocation function's name starting from the point of definition of the final overrider of its virtual destructor. Regardless of which deallocation function would be executed at run time, the statically visible version ofoperator delete must be accessible in order to compile. In other cases, when deleting an array through a pointer to base, or when deleting through pointer to base with non-virtual destructor, the behavior is undefined.

If the single-argument overload(17,18) is not provided, but the size-aware overload takingstd::size_t as the second parameter(21,22) is provided, the size-aware form is called for normal deallocation, and the C++ runtime passes the size of the object to be deallocated as the second argument. If both forms are defined, the size-unaware version is called.

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

custom delete for size 1custom delete for size 18

Overloads ofoperator delete andoperator delete[] with additional user-defined parameters ("placement forms",(25,26)) may also be defined as class members. When the failed placementnew expression looks for the corresponding placementdelete function to call, it begins lookup at class scope before examining the global scope, and looks for the function with the signature matching the placementnew:

#include <cstddef>#include <iostream>#include <stdexcept> struct X{    X(){throwstd::runtime_error("X(): std::runtime_error");} // custom placement newstaticvoid*operator new(std::size_t sz,bool b){std::cout<<"custom placement new called, b = "<< b<<'\n';return::operator new(sz);} // custom placement deletestaticvoid operator 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& ex){std::cout<< ex.what()<<'\n';}}

custom placement new called, b = 1custom placement delete called, b = 1X(): std::runtime_error

If class-leveloperator delete is a template function, it must have the return type ofvoid, the first argumentvoid*, and it must have two or more parameters. In other words, only placement forms can be templates. A template instance is never a usual deallocation function, regardless of its signature. The specialization of the template operator delete is chosen withtemplate argument deduction.

[edit]Notes

The call to the class-specificT::operator delete on a polymorphic class is the only case where a static member function is called through dynamic dispatch.

[edit]Defect reports

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

[edit]See also

• In other languages

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