operator new

(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).

• 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.

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

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;
}

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

Data races

Exception safety

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)