operator new[]


function
<new> 
void* operator new[] (std::size_t size) throw (std::bad_alloc);
void* operator new[] (std::size_t size, const std::nothrow_t& nothrow_constant) throw();
void* operator new[] (std::size_t size, void* ptr) throw();

Allocate storage space for array

The first version allocates size bytes of storage space, aligned to represent an array object of that size (or less, if the implementation uses array overhead), and returns a non-null pointer to the first byte of this block. On failure, it throws a bad_alloc exception.

The second version is the nothrow version. It does the same as the first version, except that on failure it turns a null pointer instead of throwing an exception.

The third version is the placement version, that does not allocate memory - it simply returns ptr. Notice though that the constructor for the object will still be called.

Global dynamic storage operator functions are special in the standard library:
  • All three versions of operator new[] are declared in the global namespace, not in the std namespace.
  • The first and second versions are implicitly declared in every translation unit of a C++ program: The header <new> does not need to be included for them to be present.
  • The first and second versions are also replaceable: A program may provide its own definition, that replaces the default one, to produce the result described above.


If set_new_handler has been used to define a new_handler function, this new_handler function is called by the standard default definition of operator new[] if it cannot allocate the requested storage by its own.

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 new and an array type specifier is an operator new[] expression. This, first calls function operator new[] with the size of its array type specifier as first argument (plus any array overhead storage to keep track of the size, if any), and if this is successful, it then automatically initializes or constructs each of the objects in the array (if needed). The expression evaluates as a pointer to the appropriate type pointing to the first element of the array.

Parameters

size
Size in bytes of the requested memory block.
size_t is an integral type.
nothrow_constant
The constant nothrow.
This parameter is only used to distinguish it from the first 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 a memory block where the object is to be constructed


Return value

For the first and second versions, a pointer to the first element in 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
 
// operator new[] example
#include <iostream>
#include <memory>
#include <new>
using namespace std;

struct myclass {myclass() {cout <<"myclass constructed\n";}};

int main () {
  // uses first version:
  int * p1 = new int[5];

  // uses second version:
  int * p2 = new (nothrow) int[4];

  // uses third version:
  pair <myclass*,ptrdiff_t> p3 = get_temporary_buffer<myclass>(3);
  new (p3.first) myclass[3];   // calls constructors
  return_temporary_buffer(p3.first);

  return 0;
}


Output:

myclass constructed
myclass constructed
myclass constructed


See also

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