function
<new>

operator new

throwing (1)
void* operator new (std::size_t size) throw (std::bad_alloc);
nothrow (2)
void* operator new (std::size_t size, const std::nothrow_t& nothrow_value) throw();
placement (3)
void* operator new (std::size_t size, void* ptr) throw();
throwing (1)
void* operator new (std::size_t size);
nothrow (2)
void* operator new (std::size_t size, const std::nothrow_t& nothrow_value) noexcept;
placement (3)
void* operator new (std::size_t size, void* ptr) noexcept;
Allocate storage space
Default allocation functions (single-object form).

(1) throwing allocation
Allocates size bytes of storage, suitably aligned to represent any object of that size, and returns a non-null pointer to the first byte of this block.
On failure, it throws a bad_alloc exception.
(2) nothrow allocation
Same as above (1), except that on failure it returns a null pointer instead of throwing an exception.
If replaced, both the first and second versions shall return pointers with identical properties.
The default definition allocates memory by calling the the first version: ::operator new (size).
If replaced, both the first and second versions shall return pointers with identical properties.
(3) placement
Simply returns ptr (no storage is allocated).
Notice though that, if the function is called by a new-expression, the proper initialization will be performed (for class objects, this includes calling its default constructor).

The default allocation and deallocation functions are special components of the standard library; They have the following unique properties:
  • Global: All three versions of operator new are declared in the global namespace, not within the std namespace.
  • Implicit: The allocating versions ((1) and (2)) are implicitly declared in every translation unit of a C++ program, no matter whether header <new> is included or not.
  • Replaceable: The allocating versions ((1) and (2)) are also replaceable: A program may provide its own definition that replaces the one provided by default to produce the result described above, or can overload it for specific types.

If set_new_handler has been used to define a new_handler function, this new-handler function is called by the default definitions of the allocating versions ((1) and (2)) if they fail to allocate the requested storage.

operator new can be called explicitly as a regular function, but in C++, new is an operator with a very specific behavior: An expression with the new operator, first calls function operator new (i.e., this function) with the size of its type specifier as first argument, and if this is successful, it then automatically initializes or constructs the object (if needed). Finally, the expression evaluates as a pointer to the appropriate type.

Parameters

size
Size in bytes of the requested memory block.
This is the size of the type specifier in the new-expression when called automatically by such an expression.
If this argument is zero, the function still returns a distinct non-null pointer on success (although dereferencing this pointer leads to undefined behavior).
size_t is an integral type.
nothrow_value
The constant nothrow.
This parameter is only used to distinguish it from the first version with an overloaded version. When the nothrow constant is passed as second parameter to operator new, operator new returns a null-pointer on failure instead of throwing a bad_alloc exception.
nothrow_t is the type of constant nothrow.
ptr
A pointer to an already-allocated memory block of the proper size.
If called by a new-expression, the object is initialized (or constructed) at this location.

Return value

For the first and second versions, a pointer to the newly allocated storage space.
For the third version, ptr is returned.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
 
// operator new example
#include <iostream>     // std::cout
#include <new>          // ::operator new

struct MyClass {
  int data[100];
  MyClass() {std::cout << "constructed [" << this << "]\n";}
};

int main () {

  std::cout << "1: ";
  MyClass * p1 = new MyClass;
      // allocates memory by calling: operator new (sizeof(MyClass))
      // and then constructs an object at the newly allocated space

  std::cout << "2: ";
  MyClass * p2 = new (std::nothrow) MyClass;
      // allocates memory by calling: operator new (sizeof(MyClass),std::nothrow)
      // and then constructs an object at the newly allocated space

  std::cout << "3: ";
  new (p2) MyClass;
      // does not allocate memory -- calls: operator new (sizeof(MyClass),p2)
      // but constructs an object at p2

  // Notice though that calling this function directly does not construct an object:
  std::cout << "4: ";
  MyClass * p3 = (MyClass*) ::operator new (sizeof(MyClass));
      // allocates memory by calling: operator new (sizeof(MyClass))
      // but does not call MyClass's constructor

  delete p1;
  delete p2;
  delete p3;

  return 0;
}


Possible output:

1: constructed [0x8f0f70]
2: constructed [0x8f23a8]
3: constructed [0x8f23a8]
4:

Data races

Modifies the storage referenced by the returned value.
Calls to allocation and deallocation functions that reuse the same unit of storage shall occur in a single total order where each deallocation happens entirely before the next allocation.
This shall also apply to the observable behavior of custom replacements for this function.

Exception safety

The first version (1) throws bad_alloc if it fails to allocate storage.
Otherwise, it throws no exceptions (no-throw guarantee).

See also

operator new[]
Allocate storage space for array (function )
operator delete
Deallocate storage space (function )
nothrow
Nothrow constant (constant )
bad_alloc
Exception thrown on failure allocating memory (class )