Standard Template Library Programmer's Guide

• construct
• destroy
• uninitialized_copy
• uninitialized_fill
• uninitialized_fill_n
• get_temporary_buffer
• return_temporary_buffer

Notes

[1] The reason for this change is that the new interface reduces memory fragmentation, and that it allows an implementation that is both efficient and thread-safe.

[2] Different containers may use different allocators. You might, for example, have some containers that use the default allocator alloc and others that use pthread_alloc. Note, however, that vector<int> and vector<int, pthread_alloc> are distinct types.

Functions

construct

Category: allocators

Component type: function

Prototype

template <class T1, class T2>
void construct(T1* p, const T2& value);

Description

In C++, the operator new allocates memory for an object and then creates an object at that location by calling a constructor. Occasionally, however, it is useful to separate those two operations. [1] If p is a pointer to memory that has been allocated but not initialized, then construct(p, value) creates an object of type T1 at the location pointed to by p. The argument value is passed as an argument to T1's constructor.

Definition

Defined in the standard header memory, and in the nonstandard backward-compatibility header algo.h. The construct algorithm is no longer part of the C++ standard; it was present in early drafts, and it is retained in this implementation for backward compatibility.

Requirements on types

• T1 must have a constructor that takes a single argument of type T2.

Preconditions

• p is a valid pointer that points to a region of memory whose size is at least sizeof(T1).

• The memory pointed to by p is uninitialized. That is, no object has been constructed at the location p.

Example

double* dp = (double*)malloc(sizeof(double));
construct(dp, 3);
assert(*dp == 3);

Notes

[1] In particular, construct, along with other low-level memory allocation primitives, is used to implement container classes.

See also

Allocators, destroy, uninitialized_copy, uninitialized_fill, uninitialized_fill_n, raw_storage_iterator

destroy

Category: allocators

Component type: function

Prototype

Destroy is an overloaded name; there are actually two destroy functions.

template <class T>
void destroy(T* pointer);
template <class ForwardIterator>
void destroy(ForwardIterator first, ForwardIterator last);

Description

In C++, the operator delete destroys an object by calling its destructor, and then deallocates the memory where that object was stored. Occasionally, however, it is useful to separate those two operations. [1] Destroy calls an object's destructor without deallocating the memory where the object was stored.

The first version of destroy destroys the object pointed to by pointer by calling the destructor T::~T(). The memory pointed to by pointer is not deallocated, and can be reused for some other object.

The second version of destroy destroys all of the objects in the range of elements [first, last). It is equivalent to calling destroy(&*i) for each iterator i in the range [first, last).

Definition

Defined in the standard header memory, and in the nonstandard backward-compatibility header algo.h. The destroy algorithms are no longer part of the C++ standard; they were present in early drafts, and they are retained in this implementation for backward compatibility.

Requirements on types

For the first version of destroy :

• T's destructor, ~T, is accessible.

For the second version of destroy:

• ForwardIterator is a model of Forward Iterator.

• ForwardIterator is mutable.

• ForwardIterator's value type has an accessible destructor.

Preconditions

For the first version of destroy:

• pointer points to a valid object of type T.

For the second version of destroy: