View source for New and delete (C++)

{{short description|C++ programming keywords for dynamic memory allocation}}
{{lowercase|title=new (C++)}}
In the [[C++]] [[programming language]], {{mono|'''new'''}} and {{mono|'''delete'''}} are a pair of [[language construct]]s that perform [[dynamic memory allocation]], [[Constructor (object-oriented programming)|object construction]] and [[object destruction]].<ref name="Savitch">{{cite book |title=Absolute C++ |year=2013 |publisher=Pearson |last=Savitch |first=Walter |isbn=978-0132846813 |pages=420–445}}</ref>

==Overview==
Except for a form called the [[Placement new (C++)|"placement new"]], the {{mono|new}} operator denotes a request for memory allocation on a process's [[heap (programming)|heap]]. If sufficient memory is available, {{mono|new}} initialises the memory, calling object constructors if necessary, and returns the address to the newly allocated and initialised memory.<ref name="IBM">{{cite web |url=http://publib.boulder.ibm.com/infocenter/macxhelp/v6v81/index.jsp?topic=/com.ibm.vacpp6m.doc/language/ref/clrc05cplr199.htm |archive-url=https://archive.today/20130103101712/http://publib.boulder.ibm.com/infocenter/macxhelp/v6v81/index.jsp?topic=/com.ibm.vacpp6m.doc/language/ref/clrc05cplr199.htm |url-status=dead |archive-date=2013-01-03 |title=IBM Documentation describing C++'s operator new |access-date=2013-11-06 }}</ref><ref name="USBM">{{cite web |url=http://msdn2.microsoft.com/en-us/library/kewsb8ba(VS.71).aspx |title=Microsoft Visual Studio operator new documentation |access-date=2013-11-06}}</ref> A {{mono|new}} request, in its simplest form, looks as follows:

<syntaxhighlight lang="cpp">p = new T;</syntaxhighlight>

where {{mono|p}} is a previously declared [[pointer (computer programming)|pointer]] of type {{mono|T}} (or some other type to which a {{mono|T}} pointer can be assigned, such as a [[Inheritance (object-oriented programming)#Subclasses and superclasses|superclass]] of {{mono|T}}). The [[default constructor]] for {{mono|T}}, if any, is called to construct a {{mono|T}} instance in the allocated memory buffer.

If not enough memory is available in the free store for an object of type {{mono|T}}, the {{mono|new}} request indicates failure by throwing an [[Exception handling|exception]] of type {{mono|std::bad_alloc}}. This removes the need to explicitly check the result of an allocation.

The deallocation counterpart of {{mono|new}} is {{mono|delete}}, which first calls the destructor (if any) on its argument and then returns the memory allocated by {{mono|new}} back to the free store. Every call to {{mono|new}} must be matched by a call to {{mono|delete}}; failure to do so causes a [[memory leak]].<ref name="Savitch" /> 

{{mono|new}} syntax has several variants that allow finer control over memory allocation and object construction. A function call-like syntax is used to call a different constructor than the default one and pass it arguments, e.g.,

<syntaxhighlight lang="cpp">p = new T(argument);</syntaxhighlight>

calls a single-argument {{mono|T}} constructor instead of the default constructor when initializing the newly allocated buffer.

A different variant allocates and initialises  [[Array data structure|arrays]] of objects rather than single objects:
<syntaxhighlight lang="cpp">p = new T [N];</syntaxhighlight>

This requests a memory buffer from the free store that is large enough to hold a contiguous array of {{mono|N}} objects of type {{mono|T}}, and calls the default constructor on each element of the array.

Memory allocated with the {{mono|new[]}} must be deallocated with the {{mono|delete[]}} operator, rather than {{mono|delete}}. Using the inappropriate form results in [[undefined behavior]]. C++ compilers are not required to generate a diagnostic message for using the wrong form.

The [[C++11]] standard specifies an additional syntax,

<syntaxhighlight lang="cpp">p = new T[N] {initializer1, ..., initializerN};</syntaxhighlight>

that initializes each {{mono|p[''i'']}} to {{mono|initializer'''i+1'''}}.

===Error handling===
If {{mono|new}} cannot find sufficient memory to service an allocation request, it can report its error in three distinct ways. Firstly, the [[ISO/IEC 14882|ISO C++ standard]] allows programs to register a custom function called a {{mono|new_handler}} with the C++ [[Runtime library|runtime]]; if it does, then this function is called whenever {{mono|new}} encounters an error. The {{mono|new_handler}} may attempt to make more memory available, or terminate the program if it can't.

If no {{mono|new_handler}} is installed, {{mono|new}} instead throws an [[exception handling|exception]] of type {{mono|std::bad_alloc}}. Thus, the program does not need to check the value of the returned pointer, as is the habit in [[C dynamic memory allocation|C]]; if no exception was thrown, the allocation succeeded.

The third method of error handling is provided by the variant form {{mono|new(std::nothrow)}}, which specifies that no exception should be thrown; instead, a [[null pointer]] is returned to signal an allocation error.

===Overloading===
The {{mono|new}} operator can be [[operator overloading|overloaded]] so that specific types (classes) use custom memory allocation algorithms for their instances. For example, the following is a variant of the [[singleton pattern]] where the first {{mono|new Singleton}} call allocates an instance and all subsequent calls return this same instance:

<syntaxhighlight lang="c++" line="1">
#include <cstdlib>
#include <cstddef>

class Singleton {
public:
  static void* operator new(std::size_t size) {
    if (!instance) {
      instance = std::malloc(size);
    }
    refcount++;
    return instance;
  }

  static void operator delete(void*) noexcept {
    if (--refcount == 0) {
      std::free(instance);
      instance = nullptr;
    }
  }

private:
  static void* instance = nullptr;
  static std::size_t refcount = 0;
};
</syntaxhighlight>

This feature was available from early on in C++'s history, although the specific overloading mechanism changed. It was added to the language because [[object-oriented programming|object-oriented]] C++ programs tended to allocate many small objects with {{mono|new}}, which internally used the C allocator (see {{slink||Relation to malloc and free}}); that, however, was optimized for the fewer and larger allocations performed by typical C programs. [[Bjarne Stroustrup|Stroustrup]] reported that in early applications, the C function {{mono|malloc}} was "the most common performance bottleneck in real systems", with programs spending up to 50% of their time in this function.{{r|history}}

==Relation to malloc and free==
Since standard C++ subsumes the [[C standard library]], the [[C dynamic memory allocation]] routines {{mono|malloc}}, {{mono|calloc}}, {{mono|realloc}} and {{mono|free}} are also available to C++ programmers. The use of these routines is discouraged for most uses, since they do not perform object initialization and destruction.<ref>{{Cite book |title=Effective C++ |url=https://archive.org/details/effectivecspecif00meye_047 |url-access=limited |first=Scott |last=Meyers |author-link=Scott Meyers |publisher=Addison-Wesley |year=1998 |page=[https://archive.org/details/effectivecspecif00meye_047/page/n37 21]|isbn=9780201924886 }}</ref> {{mono|new}} and {{mono|delete}} were, in fact, introduced in the first version of C++ (then called "[[C with Classes]]") to avoid the necessity of manual object initialization.<ref name="history">{{cite conference |first=Bjarne |last=Stroustrup |author-link=Bjarne Stroustrup |title=A History of C++: 1979–1991 |conference=Proc. ACM History of Programming Languages Conf. |year=1993 |url=http://www.stroustrup.com/hopl2.pdf}}</ref>

In contrast to the C routines, which allow growing or shrinking an allocated array with {{mono|realloc}}, it is not possible to change the size of a memory buffer allocated by {{mono|new[]}}. The [[C++ standard library]] instead provides a [[dynamic array]] (collection) that can be extended or reduced in its {{mono|[[vector (STL)|std::vector]]}} template class.

The C++ standard does not specify any relation between {{mono|new}}/{{mono|delete}} and the C memory allocation routines, but {{mono|new}} and {{mono|delete}} are typically implemented as wrappers around {{mono|malloc}} and {{mono|free}}.<ref>{{Cite book |title=Modern C++ Design: Generic Programming and Design Patterns Applied |url=https://archive.org/details/cmoderncdesignge00alex |url-access=limited |first=Andrei |last=Alexandrescu |publisher=Addison-Wesley |year=2001 |page=[https://archive.org/details/cmoderncdesignge00alex/page/n82 68]}}</ref> Mixing the two families of operations, e.g., {{mono|free}}'ing {{mono|new}}'ly allocated memory or {{mono|delete}}'ing {{mono|malloc}}'d memory, causes undefined behavior and in practice can lead to various catastrophic results such as failure to release [[Lock (computer science)|locks]] and thus [[Deadlock (computer science)|deadlock]].<ref name="secure">{{cite book |title=Secure Coding in C and C++ |first=Robert C. |last=Seacord |publisher=Addison-Wesley |year=2013}} Section 4.4, Common C++ Memory Management Errors.</ref>

==See also==
* [[Allocator (C++)]]
* [[Exception handling]]
* [[Memory pool]]
* [[Pointer (computer programming)]]
* [[Resource Acquisition Is Initialization]] (RAII)
* [[Smart pointers]]

==References==
{{reflist}}

{{C++ programming language}}
{{Memory management navbox}}
{{Programming languages}}

[[Category:C++]]
[[Category:Articles with example C++ code]]