description: "Learn more about: new Operator (C++)"

title: "new Operator (C++)"

ms.date: "11/04/2016"

Allocates memory for an object or array of objects of *type-name* from the free store, commonly called the "heap", and returns a suitably typed, nonzero pointer to the object.

If unsuccessful, **`new`** returns zero or throws an exception; see [The new and delete Operators](../cpp/new-and-delete-operators.md) for more information. You can change this default behavior by writing a custom exception-handling routine and calling the [_set_new_handler](../c-runtime-library/reference/set-new-handler.md) run-time library function with your function name as its argument.

For information on how to create an object on the managed heap, see [gcnew](../extensions/ref-new-gcnew-cpp-component-extensions.md).

Use the [delete](../cpp/delete-operator-cpp.md) operator to deallocate the memory allocated with the **`new`** operator.

The following example allocates and then frees a two-dimensional array of characters of size `dim` by 10. When allocating a multidimensional array, all dimensions except the first must be constant expressions that evaluate to positive values; the leftmost array dimension can be any expression that evaluates to a positive value. When allocating an array using the **`new`** operator, the first dimension can be zero — the **`new`** operator returns a unique pointer.

The *type-name* cannot contain **`const`**, **`volatile`**, class declarations, or enumeration declarations. Therefore, the following expression is illegal:

The **`new`** operator does not allocate reference types because they are not objects.

The **`new`** operator cannot be used to allocate a function, but it can be used to allocate pointers to functions. The following example allocates and then frees an array of seven pointers to functions that return integers.

If you use the operator **`new`** without any extra arguments, and compile with the [/GX](../build/reference/gx-enable-exception-handling.md), [/EHa](../build/reference/eh-exception-handling-model.md), or [/EHs](../build/reference/eh-exception-handling-model.md) option, the compiler will generate code to call operator **`delete`** if the constructor throws an exception.

*placement*<br/>

Provides a way of passing additional arguments if you overload **`new`**.

Specifies type to be allocated; it can be either a built-in or user-defined type. If the type specification is complicated, it can be surrounded by parentheses to force the order of binding.

Provides a value for the initialized object. Initializers cannot be specified for arrays. The **`new`** operator will create arrays of objects only if the class has a default constructor.

An optional *initializer* field is included in the grammar for the **`new`** operator. This allows new objects to be initialized with user-defined constructors. For more information about how initialization is done, see [Initializers](../cpp/initializers.md). The following example illustrates how to use an initialization expression with the **`new`** operator:

double *HowMuch = new double ( 43.0 );

In this example, the object `CheckingAcct` is allocated using the **`new`** operator, but no default initialization is specified. Therefore, the default constructor for the class, `Acct()`, is called. Then the object `SavingsAcct` is allocated the same way, except that it is explicitly initialized to 34.98. Because 34.98 is of type **`double`**, the constructor that takes an argument of that type is called to handle the initialization. Finally, the nonclass type `HowMuch` is initialized to 43.0.

- The arguments provided in the initializer agree with those of a constructor.

No explicit per-element initialization can be done when allocating arrays using the **`new`** operator; only the default constructor, if present, is called. See [Default Arguments](../cpp/default-arguments.md) for more information.

If the memory allocation fails (**operator new** returns a value of 0), no initialization is performed. This protects against attempts to initialize data that does not exist.

As with function calls, the order in which initialized expressions are evaluated is not defined. Furthermore, you should not rely on these expressions being completely evaluated before the memory allocation is performed. If the memory allocation fails and the **`new`** operator returns zero, some expressions in the initializer may not be completely evaluated.

Objects allocated with the **`new`** operator are not destroyed when the scope in which they are defined is exited. Because the **`new`** operator returns a pointer to the objects it allocates, the program must define a pointer with suitable scope to access those objects. For example:

The *allocation-expression* — the expression containing the **`new`** operator — does three things:

- Locates and reserves storage for the object or objects to be allocated. When this stage is complete, the correct amount of storage is allocated, but it is not yet an object.

- Returns a pointer to the object(s) of a pointer type derived from *new-type-name* or *type-name*. The program uses this pointer to access the newly allocated object.

The **`new`** operator invokes the function **operator new**. For arrays of any type, and for objects that are not of **`class`**, **`struct`**, or **`union`** types, a global function, **::operator new**, is called to allocate storage. Class-type objects can define their own **operator new** static member function on a per-class basis.

When the compiler encounters the **`new`** operator to allocate an object of type **type**, it issues a call to `type`**::operator new( sizeof(** `type` **) )** or, if no user-defined **operator new** is defined, **::operator new( sizeof(** `type` **) )**. Therefore, the **`new`** operator can allocate the correct amount of memory for the object.

> The argument to **operator new** is of type `size_t`. This type is defined in \<direct.h>, \<malloc.h>, \<memory.h>, \<search.h>, \<stddef.h>, \<stdio.h>, \<stdlib.h>, \<string.h>, and \<time.h>.

An option in the grammar allows specification of *placement* (see the Grammar for [new Operator](../cpp/new-operator-cpp.md)). The *placement* parameter can be used only for user-defined implementations of **operator new**; it allows extra information to be passed to **operator new**. An expression with a *placement* field such as `T *TObject = new ( 0x0040 ) T;` is translated to `T *TObject = T::operator new( sizeof( T ), 0x0040 );` if class T has member operator new, otherwise to `T *TObject = ::operator new( sizeof( T ), 0x0040 );`.

The original intention of the *placement* field was to allow hardware-dependent objects to be allocated at user-specified addresses.

> Although the preceding example shows only one argument in the *placement* field, there is no restriction on how many extra arguments can be passed to **operator new** this way.

Even when **operator new** has been defined for a class type, the global operator can be used by using the form of this example:

T *TObject =::new TObject;

[Expressions with Unary Operators](../cpp/expressions-with-unary-operators.md)<br/>

[Keywords](../cpp/keywords-cpp.md)<br/>

[new and delete operators](../cpp/new-and-delete-operators.md)