operator new, operator new[]

 

C++

Language

Concepts

Utilities library

Strings library

Containers library

Algorithms library

Iterators library

Numerics library

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

 

Utilities library

Type support (basic types, RTTI, type traits)

Dynamic memory management

Error handling

Program utilities

Variadic functions

Date and time

Function objects

initializer_list (C++11)

bitset

hash (C++11)

Relational operators

rel_ops::operator!= rel_ops::operator> rel_ops::operator<= rel_ops::operator>=

Pairs and tuples

pair

tuple (C++11)

piecewise_construct_t (C++11)

piecewise_construct (C++11)

Swap, forward and move

swap

forward (C++11)

move (C++11)

move_if_noexcept (C++11)

declval (C++11)

 

Dynamic memory management

Low level memory management
Allocators
allocator
allocator_traits (C++11)
allocator_arg_t (C++11)
allocator_arg (C++11)
uses_allocator (C++11)
scoped_allocator_adaptor (C++11)
Uninitialized storage
uninitialized_copy
uninitialized_copy_n (C++11)
uninitialized_fill
uninitialized_fill_n
raw_storage_iterator
get_temporary_buffer
return_temporary_buffer
Smart pointers
unique_ptr (C++11)
shared_ptr (C++11)
weak_ptr (C++11)
auto_ptr (deprecated)
owner_less (C++11)
enable_shared_from_this (C++11)
bad_weak_ptr (C++11)
default_delete (C++11)
Garbage collection support
declare_reachable (C++11)
undeclare_reachable (C++11)
declare_no_pointers (C++11)
undeclare_no_pointers (C++11)
pointer_safety (C++11)
get_pointer_safety (C++11)
Miscellaneous
pointer_traits (C++11)
addressof (C++11)
align (C++11)
C Library
malloc calloc	realloc free

 

Low level memory management

Functions

operator new operator new[]

operator delete operator delete[]

get_new_handler (C++11)

set_new_handler

Classes

bad_alloc

bad_array_new_length (C++11)

nothrow_t

Types

new_handler

Objects

nothrow

 

Defined in header <new>
void* operator new  ( std::size_t count );	(1)
void* operator new[]( std::size_t count );	(2)
void* operator new  ( std::size_t count, const std::nothrow_t& );	(3)
void* operator new[]( std::size_t count, const std::nothrow_t& );	(4)
void* operator new  ( std::size_t, void* ptr );	(5)
void* operator new[]( std::size_t, void* ptr );	(6)

Allocates requested number of bytes. These allocation functions are called by new-expressions to allocate memory in which new object would then be initialized.

1-2) Allocates count bytes from free store. Calls the function pointer returned by std::get_new_handler on failure and repeats allocation attempts until new handler does not return or becomes a null pointer, at which time throws std::bad_alloc.

3-4) Same as 1-2, but returns a null pointer when 1-2 would throw std::bad_alloc

5-6) does nothing, returns ptr. These versions are called by new-expression which construct objects in previously allocated storage.

Replacing and overloading

The versions 1-4) are implicitly declared in each translation unit even if the <new> header is not included. These functions are replaceable: a user-provided non-member function with the same signature replaces the implicit version. At most one replacement may be provided for each of the four implicit allocation functions. Also, program can define class member versions of these functions or define allocation functions with different signatures (except that it is not permitted to replace (5-6) versions of the allocation function). The added signature should look like the following, where count is number of bytes to allocate and placement_params are the parameters supplied to the new expression:

void* operator new  (size_t count/*, placement_params*/);		for the new version
void* operator new[](size_t count/*, placement_params*/);		for the new[] version

The allocation function can be replaced/overloaded in two ways:

in the global scope: in order to call it, the signature of the overloaded allocation functions must be visible at the place of allocation, except for implicitly declared default allocation functions. This allocation function will be used for all allocations with corresponding parameters in the current program

in the local scope: the overloaded operator new must be static public member function of the class. This allocation function will be used only for allocations of that particular class.

During compilation, each new expression looks up for appropriate allocation function's name firstly in the class scope and after that in the global scope. It can be instructed to skip the first step by calling new as ::new. Note, that as per overloading rules, any allocation functions declared in class scope hides all global allocation functions. For more information see new expression. Note, that it is not possible to place allocation function in a namespace.

Parameters

count	-	number of bytes to allocate
ptr	-	pointer to a memory area to initialize the object at

Return value

1-4) pointer to allocated memory area

5-6) ptr

Exceptions

1-2) throws std::bad_alloc on failure to allocate memory

3-6)

noexcept specification:  

noexcept

  (since C++11)

See also

operator delete operator delete[]	deallocation functions (function)
get_new_handler (C++11)	obtains the current new handler (function)
set_new_handler	registers a new handler (function)
get_temporary_buffer	obtains uninitialized storage (function)
malloc	allocates memory (function)