<memory> functions
addressof
Gets the true address of an object.
template <class T>
T* addressof(
T& value) noexcept; // before C++17
template <class T>
constexpr T* addressof(
T& value) noexcept; // C++17
template <class T>
const T* addressof(
const T&& value) = delete; // C++17
Parameters
value
The object or function for which to obtain the true address.
Return Value
The actual address of the object or function referenced by value, even if an overloaded operator&() exists.
Remarks
align
Fits storage of the given size, aligned by the given alignment specification, into the first possible address of the given storage.
void* align(
size_t alignment, // input
size_t size, // input
void*& ptr, // input/output
size_t& space // input/output
);
Parameters
alignment
The alignment bound to attempt.
size
The size in bytes for the aligned storage.
ptr
The starting address of the available contiguous storage pool to use. This parameter is also an output parameter, and is set to contain the new starting address if the alignment is successful. If align() is unsuccessful, this parameter isn't modified.
space
The total space available to align() to use in creating the aligned storage. This parameter is also an output parameter, and contains the adjusted space left in the storage buffer after the aligned storage and any associated overhead is subtracted.
If align() is unsuccessful, this parameter isn't modified.
Return Value
A NULL pointer if the requested aligned buffer wouldn't fit into the available space; otherwise, the new value of ptr.
Remarks
The modified ptr and space parameters enable you to call align() repeatedly on the same buffer, possibly with different values for alignment and size. The following code snippet shows one use of align().
#include <type_traits> // std::alignment_of()
#include <memory>
//...
char buffer[256]; // for simplicity
size_t alignment = std::alignment_of<int>::value;
void * ptr = buffer;
std::size_t space = sizeof(buffer); // Be sure this results in the true size of your buffer
while (std::align(alignment, sizeof(MyObj), ptr, space)) {
// You now have storage the size of MyObj, starting at ptr, aligned on
// int boundary. Use it here if you like, or save off the starting address
// contained in ptr for later use.
// ...
// Last, move starting pointer and decrease available space before
// the while loop restarts.
ptr = reinterpret_cast<char*>(ptr) + sizeof(MyObj);
space -= sizeof(MyObj);
}
// At this point, align() has returned a null pointer, signaling it is not
// possible to allow more aligned storage in this buffer.
allocate_shared
Creates a shared_ptr to objects that are allocated and constructed for a given type by using a specified allocator. Returns the shared_ptr.
template <class T, class Allocator, class... Args>
shared_ptr<T> allocate_shared(
Allocator alloc,
Args&&... args);
Parameters
alloc
The allocator used to create objects.
args
The zero or more arguments that become the objects.
Remarks
The function creates the object shared_ptr<T>, a pointer to T(args...) as allocated and constructed by alloc.
atomic_compare_exchange_strong
template<class T>
bool atomic_compare_exchange_strong(
shared_ptr<T>* u,
shared_ptr<T>* v,
shared_ptr<T> w);
atomic_compare_exchange_weak
template<class T>
bool atomic_compare_exchange_weak(
shared_ptr<T>* u,
shared_ptr<T>* v,
shared_ptr<T> w);
atomic_compare_exchange_strong_explicit
template<class T>
bool atomic_compare_exchange_strong_explicit(
shared_ptr<T>* u,
shared_ptr<T>* v,
shared_ptr<T> w,
memory_order success,
memory_order failure);
atomic_compare_exchange_weak_explicit
template<class T>
bool atomic_compare_exchange_weak_explicit(
shared_ptr<T>* u,
shared_ptr<T>* v,
shared_ptr<T> w,
memory_order success,
memory_order failure);
atomic_exchange
template<class T>
shared_ptr<T> atomic_exchange(
shared_ptr<T>* u,
shared_ptr<T> r);
atomic_exchange_explicit
template<class T>
shared_ptr<T> atomic_exchange_explicit(
shared_ptr<T>* u,
shared_ptr<T> r,
memory_order mo);
atomic_is_lock_free
template<class T>
bool atomic_is_lock_free(
const shared_ptr<T>* u);
atomic_load
template<class T>
shared_ptr<T> atomic_load(
const shared_ptr<T>* u);
atomic_load_explicit
template<class T>
shared_ptr<T> atomic_load_explicit(
const shared_ptr<T>* u,
memory_order mo);
atomic_store
template<class T>
void atomic_store(
shared_ptr<T>* u,
shared_ptr<T> r);
atomic_store_explicit
template<class T>
void atomic_store_explicit(
shared_ptr<T>* u,
shared_ptr<T> r,
memory_order mo);
const_pointer_cast
Const cast to shared_ptr.
template <class T, class Other>
shared_ptr<T> const_pointer_cast(
const shared_ptr<Other>& sp) noexcept;
template <class T, class Other>
shared_ptr<T> const_pointer_cast(
shared_ptr<Other>&& sp) noexcept;
Parameters
T
The type controlled by the returned shared pointer.
Other
The type controlled by the argument shared pointer.
sp
The argument shared pointer.
Remarks
The template function returns an empty shared_ptr object if const_cast<T*>(sp.get()) returns a null pointer; otherwise it returns a shared_ptr<T> object that owns the resource that is owned by sp. The expression const_cast<T*>(sp.get()) must be valid.
Example
// std__memory__const_pointer_cast.cpp
// compile with: /EHsc
#include <memory>
#include <iostream>
int main()
{
std::shared_ptr<int> sp0(new int);
std::shared_ptr<const int> sp1 =
std::const_pointer_cast<const int>(sp0);
*sp0 = 3;
std::cout << "sp1 == " << *sp1 << std::endl;
return (0);
}
sp1 == 3
declare_no_pointers
Informs a garbage collector that the characters in the memory block defined by a base address pointer and block size contains no traceable pointers.
void declare_no_pointers(
char* ptr,
size_t size);
Parameters
ptr
Address of first character that no longer contains traceable pointers.
size
Size of block that starts at ptr that contains no traceable pointers.
Remarks
The function informs any garbage collector that the addresses in the range [ptr, ptr + size) no longer contain traceable pointers. (Any pointers to allocated storage must not be dereferenced unless made reachable.)
declare_reachable
Informs garbage collection that the indicated address is to allocated storage and is reachable.
void declare_reachable(
void* ptr);
Parameters
ptr
A pointer to a reachable, allocated, valid storage area.
Remarks
If ptr is not null, the function informs any garbage collector that ptr is now reachable, that is, it points to valid allocated storage.
default_delete
Deletes objects allocated with operator new. Suitable for use with unique_ptr.
struct default_delete
{
constexpr default_delete() noexcept = default;
template <class Other, class = typename enable_if<is_convertible<Other*, T*>::value, void>::type>>
default_delete(const default_delete<Other>&) noexcept;
void operator()(T* ptr) const noexcept;
};
Parameters
ptr
Pointer to the object to delete.
Other
The type of elements in the array to be deleted.
Remarks
The class template describes a deleter that deletes scalar objects allocated with operator new, suitable for use with class template unique_ptr. It also has the explicit specialization default_delete<T[]>.
destroy_at
template <class T>
void destroy_at(
T* location);
Same as location->~T().
destroy
template <class ForwardIterator>
void destroy(
ForwardIterator first,
ForwardIterator last);
Same as:
for (; first != last; ++first)
destroy_at(addressof(*first));
destroy_n
template <class ForwardIterator, class Size>
ForwardIterator destroy_n(
ForwardIterator first,
Size count);
Same as:
for (; count > 0; (void)++first, --count)
destroy_at(addressof(*first));
return first;
dynamic_pointer_cast
Dynamic cast to shared_ptr.
template <class T, class Other>
shared_ptr<T> dynamic_pointer_cast(
const shared_ptr<Other>& sp) noexcept;
template <class T, class Other>
shared_ptr<T> dynamic_pointer_cast(
shared_ptr<Other>&& sp) noexcept;
Parameters
T
The type controlled by the returned shared pointer.
Other
The type controlled by the argument shared pointer.
sp
The argument shared pointer.
Remarks
The template function returns an empty shared_ptr object if dynamic_cast<T*>(sp.get()) returns a null pointer; otherwise it returns a shared_ptr<T> object that owns the resource that is owned by sp. The expression dynamic_cast<T*>(sp.get()) must be valid.
Example
// std__memory__dynamic_pointer_cast.cpp
// compile with: /EHsc
#include <memory>
#include <iostream>
struct base
{
virtual ~base() {}
int value;
};
struct derived
: public base
{
};
int main()
{
std::shared_ptr<base> sp0(new derived);
std::shared_ptr<derived> sp1 =
std::dynamic_pointer_cast<derived>(sp0);
sp0->value = 3;
std::cout << "sp1->value == " << sp1->value << std::endl;
return (0);
}
sp1->value == 3
get_deleter
Get the deleter from a shared_ptr.
template <class Deleter, class T>
Deleter* get_deleter(
const shared_ptr<T>& sp) noexcept;
Parameters
Deleter
The type of the deleter.
T
The type controlled by the shared pointer.
sp
The shared pointer.
Remarks
The template function returns a pointer to the deleter of type Deleter that belongs to the shared_ptr object sp. If sp has no deleter, or if its deleter is not of type Deleter, the function returns 0.
Example
// std__memory__get_deleter.cpp
// compile with: /EHsc
#include <memory>
#include <iostream>
struct base
{
int value;
};
struct deleter
{
void operator()(base *pb)
{
delete pb;
}
};
int main()
{
std::shared_ptr<base> sp0(new base);
sp0->value = 3;
std::cout << "get_deleter(sp0) != 0 == " << std::boolalpha
<< (std::get_deleter<deleter>(sp0) != 0) << std::endl;
std::shared_ptr<base> sp1(new base, deleter());
sp0->value = 3;
std::cout << "get_deleter(sp1) != 0 == " << std::boolalpha
<< (std::get_deleter<deleter>(sp1) != 0) << std::endl;
return (0);
}
get_deleter(sp0) != 0 == false
get_deleter(sp1) != 0 == true
get_pointer_safety
Returns the type of pointer safety assumed by any garbage collector.
pointer_safety get_pointer_safety() noexcept;
Remarks
The function returns the type of pointer safety assumed by any automatic garbage collector.
get_temporary_buffer
Allocates temporary storage for a sequence of elements that doesn't exceed a specified number of elements.
template <class T>
pair<T *, ptrdiff_t> get_temporary_buffer(
ptrdiff_t count);
Parameters
count
The maximum number of elements requested for which memory is to be allocated.
Return Value
A pair whose first component is a pointer to the memory that was allocated, and whose second component gives the size of the buffer, indicating the largest number of elements that it could store.
Remarks
The function makes a request for memory and it may not succeed. If no buffer is allocated, then the function returns a pair, with the second component equal to zero and the first component equal to the null pointer.
Only use this function for memory that is temporary.
Example
// memory_get_temp_buf.cpp
// compile with: /EHsc
#include <memory>
#include <iostream>
using namespace std;
int main( )
{
// Create an array of ints
int intArray [] = { 10, 20, 30, 40, 100, 200, 300, 1000, 2000 };
int count = sizeof ( intArray ) / sizeof ( int );
cout << "The number of integers in the array is: "
<< count << "." << endl;
pair<int *, ptrdiff_t> resultPair;
resultPair = get_temporary_buffer<int>( count );
cout << "The number of elements that the allocated memory\n"
<< "could store is given by: resultPair.second = "
<< resultPair.second << "." << endl;
}
The number of integers in the array is: 9.
The number of elements that the allocated memory
could store is given by: resultPair.second = 9.
make_shared
Creates and returns a shared_ptr that points to the allocated objects that are constructed from zero or more arguments by using the default allocator. Allocates and constructs both an object of the specified type and a shared_ptr to manage shared ownership of the object, and returns the shared_ptr.
template <class T, class... Args>
shared_ptr<T> make_shared(
Args&&... args);
Parameters
args
Zero or more constructor arguments. The function infers which constructor overload to invoke based on the arguments that are provided.
Remarks
Use make_shared as a simple and more efficient way to create an object and a shared_ptr to manage shared access to the object at the same time. Semantically, these two statements are equivalent:
auto sp = std::shared_ptr<Example>(new Example(argument));
auto msp = std::make_shared<Example>(argument);
However, the first statement makes two allocations, and if the allocation of the shared_ptr fails after the allocation of the Example object has succeeded, then the unnamed Example object is leaked. The statement that uses make_shared is simpler because there's only one function call involved. It's more efficient because the library can make a single allocation for both the object and the smart pointer. This function is both faster and leads to less memory fragmentation, and there's no chance of an exception on one allocation but not the other. Performance is improved by better locality for code that references the object and updates the reference counts in the smart pointer.
Consider using make_unique if you don't need shared access to the object. Use allocate_shared if you need to specify a custom allocator for the object. You can't use make_shared if your object requires a custom deleter, because there's no way to pass the deleter as an argument.
The following example shows how to create shared pointers to a type by invoking specific constructor overloads.
Example
// stl_make_shared.cpp
// Compile by using: cl /W4 /EHsc stl_make_shared.cpp
#include <iostream>
#include <string>
#include <memory>
#include <vector>
class Song {
public:
std::wstring title_;
std::wstring artist_;
Song(std::wstring title, std::wstring artist) : title_(title), artist_(artist) {}
Song(std::wstring title) : title_(title), artist_(L"Unknown") {}
};
void CreateSharedPointers()
{
// Okay, but less efficient to have separate allocations for
// Song object and shared_ptr control block.
auto song = new Song(L"Ode to Joy", L"Beethoven");
std::shared_ptr<Song> sp0(song);
// Use make_shared function when possible. Memory for control block
// and Song object are allocated in the same call:
auto sp1 = std::make_shared<Song>(L"Yesterday", L"The Beatles");
auto sp2 = std::make_shared<Song>(L"Blackbird", L"The Beatles");
// make_shared infers which constructor to use based on the arguments.
auto sp3 = std::make_shared<Song>(L"Greensleeves");
// The playlist vector makes copies of the shared_ptr pointers.
std::vector<std::shared_ptr<Song>> playlist;
playlist.push_back(sp0);
playlist.push_back(sp1);
playlist.push_back(sp2);
playlist.push_back(sp3);
playlist.push_back(sp1);
playlist.push_back(sp2);
for (auto&& sp : playlist)
{
std::wcout << L"Playing " << sp->title_ <<
L" by " << sp->artist_ << L", use count: " <<
sp.use_count() << std::endl;
}
}
int main()
{
CreateSharedPointers();
}
The example produces this output:
Playing Ode to Joy by Beethoven, use count: 2
Playing Yesterday by The Beatles, use count: 3
Playing Blackbird by The Beatles, use count: 3
Playing Greensleeves by Unknown, use count: 2
Playing Yesterday by The Beatles, use count: 3
Playing Blackbird by The Beatles, use count: 3
make_unique
Creates and returns a unique_ptr to an object of the specified type, which is constructed by using the specified arguments.
// make_unique<T>
template <class T, class... Args>
unique_ptr<T> make_unique(Args&&... args);
// make_unique<T[]>
template <class T>
unique_ptr<T> make_unique(size_t size);
// make_unique<T[N]> disallowed
template <class T, class... Args>
/* unspecified */ make_unique(Args&&...) = delete;
Parameters
T
The type of the object that the unique_ptr will point to.
Args
The types of the constructor arguments specified by args.
args
The arguments to be passed to the constructor of the object of type T.
elements
An array of elements of type T.
size
The number of elements to allocate space for in the new array.
Remarks
The first overload is used for single objects. The second overload is invoked for arrays. The third overload prevents you from specifying an array size in the type argument (make_unique<T[N]>); this construction isn't supported by the current standard. When you use make_unique to create a unique_ptr to an array, you have to initialize the array elements separately. Rather than using this overload, perhaps a better choice is to use a std::vector.
Because make_unique is carefully implemented for exception safety, we recommend that you use make_unique instead of directly calling unique_ptr constructors.
Example
The following example shows how to use make_unique. For more examples, see How to: Create and Use unique_ptr Instances.
class Animal
{
private:
std::wstring genus;
std::wstring species;
int age;
double weight;
public:
Animal(const wstring&, const wstring&, int, double){/*...*/ }
Animal(){}
};
void MakeAnimals()
{
// Use the Animal default constructor.
unique_ptr<Animal> p1 = make_unique<Animal>();
// Use the constructor that matches these arguments
auto p2 = make_unique<Animal>(L"Felis", L"Catus", 12, 16.5);
// Create a unique_ptr to an array of 5 Animals
unique_ptr<Animal[]> p3 = make_unique<Animal[]>(5);
// Initialize the elements
p3[0] = Animal(L"Rattus", L"norvegicus", 3, 2.1);
p3[1] = Animal(L"Corynorhinus", L"townsendii", 4, 1.08);
// auto p4 = p2; //C2280
vector<unique_ptr<Animal>> vec;
// vec.push_back(p2); //C2280
// vector<unique_ptr<Animal>> vec2 = vec; // C2280
// OK. p2 no longer points to anything
vec.push_back(std::move(p2));
// unique_ptr overloads operator bool
wcout << boolalpha << (p2 == false) << endl; // Prints "true"
// OK but now you have two pointers to the same memory location
Animal* pAnimal = p2.get();
// OK. p2 no longer points to anything
Animal* p5 = p2.release();
}
When you see error C2280 in connection with a unique_ptr, it is almost certainly because you are attempting to invoke its copy constructor, which is a deleted function.
owner_less
Allows ownership-based mixed comparisons of shared and weak pointers. Returns true if the left parameter is ordered before right parameter by the member function owner_before.
template <class T>
struct owner_less; // not defined
template <class T>
struct owner_less<shared_ptr<T>>
{
bool operator()(
const shared_ptr<T>& left,
const shared_ptr<T>& right) const noexcept;
bool operator()(
const shared_ptr<T>& left,
const weak_ptr<T>& right) const noexcept;
bool operator()(
const weak_ptr<T>& left,
const shared_ptr<T>& right) const noexcept;
};
template <class T>
struct owner_less<weak_ptr<T>>
bool operator()(
const weak_ptr<T>& left,
const weak_ptr<T>& right) const noexcept;
bool operator()(
const weak_ptr<T>& left,
const shared_ptr<T>& right) const noexcept;
bool operator()(
const shared_ptr<T>& left,
const weak_ptr<T>& right) const noexcept;
};
template<> struct owner_less<void>
{
template<class T, class U>
bool operator()(
const shared_ptr<T>& left,
const shared_ptr<U>& right) const noexcept;
template<class T, class U>
bool operator()(
const shared_ptr<T>& left,
const weak_ptr<U>& right) const noexcept;
template<class T, class U>
bool operator()(
const weak_ptr<T>& left,
const shared_ptr<U>& right) const noexcept;
template<class T, class U>
bool operator()(
const weak_ptr<T>& left,
const weak_ptr<U>& right) const noexcept;
};
Parameters
left
A shared or weak pointer.
right
A shared or weak pointer.
Remarks
The class templates define all their member operators as returning left.owner_before(right).
reinterpret_pointer_cast
Creates a new shared_ptr from an existing shared pointer by using a cast.
template<class T, class U>
shared_ptr<T> reinterpret_pointer_cast(
const shared_ptr<U>& ptr) noexcept;
template<class T, class U>
shared_ptr<T> reinterpret_pointer_cast(
shared_ptr<U>&& ptr) noexcept;
Parameters
ptr
An reference to a shared_ptr<U>.
Remarks
If ptr is empty, the new shared_ptr is also empty, otherwise it shares ownership with ptr. The new shared pointer is the result of evaluating reinterpret_cast<Y*>(ptr.get()), where Y is typename std::shared_ptr<T>::element_type. The behavior is undefined if reinterpret_cast<T*>((U*)nullptr) is not well-formed.
The template function that takes an lvalue reference is new in C++17. The template function that takes an rvalue reference is new in C++20.
return_temporary_buffer
Deallocates the temporary memory that was allocated using the get_temporary_buffer template function.
template <class T>
void return_temporary_buffer(
T* buffer);
Parameters
buffer
A pointer to the memory to be deallocated.
Remarks
Only use this function for memory that is temporary.
Example
// memory_ret_temp_buf.cpp
// compile with: /EHsc
#include <memory>
#include <iostream>
using namespace std;
int main( )
{
// Create an array of ints
int intArray [] = { 10, 20, 30, 40, 100, 200, 300 };
int count = sizeof ( intArray ) / sizeof ( int );
cout << "The number of integers in the array is: "
<< count << "." << endl;
pair<int *, ptrdiff_t> resultPair;
resultPair = get_temporary_buffer<int>( count );
cout << "The number of elements that the allocated memory\n"
<< " could store is given by: resultPair.second = "
<< resultPair.second << "." << endl;
int* tempBuffer = resultPair.first;
// Deallocates memory allocated with get_temporary_buffer
return_temporary_buffer( tempBuffer );
}
The number of integers in the array is: 7.
The number of elements that the allocated memory
could store is given by: resultPair.second = 7.
static_pointer_cast
Static cast to shared_ptr.
template <class T, class Other>
shared_ptr<T> static_pointer_cast(
const shared_ptr<Other>& sp) noexcept;
template <class T, class Other>
shared_ptr<T> static_pointer_cast(
shared_ptr<Other>&& sp) noexcept;
Parameters
T
The type controlled by the returned shared pointer.
Other
The type controlled by the argument shared pointer.
sp
The argument shared pointer.
Remarks
The template function returns an empty shared_ptr object if sp is an empty shared_ptr object; otherwise it returns a shared_ptr<T> object that owns the resource that is owned by sp. The expression static_cast<T*>(sp.get()) must be valid.
Example
// std__memory__static_pointer_cast.cpp
// compile with: /EHsc
#include <memory>
#include <iostream>
struct base
{
int value;
};
struct derived
: public base
{
};
int main()
{
std::shared_ptr<base> sp0(new derived);
std::shared_ptr<derived> sp1 =
std::static_pointer_cast<derived>(sp0);
sp0->value = 3;
std::cout << "sp1->value == " << sp1->value << std::endl;
return (0);
}
sp1->value == 3
swap
Swap two shared_ptr, unique_ptr, or weak_ptr objects.
template <class T>
void swap(
shared_ptr<T>& left,
shared_ptr<T>& right) noexcept;
template <class T, class Deleter>
void swap(
unique_ptr<T, Deleter>& left,
unique_ptr<T, Deleter>& right) noexcept;
template <class T>
void swap(
weak_ptr<T>& left,
weak_ptr<T>& right) noexcept;
Parameters
T
The type controlled by the argument pointer.
Deleter
The deleter of the unique pointer type.
left
The left pointer.
right
The right pointer.
Remarks
The template functions call left.swap(right).
Example
// std__memory__swap.cpp
// compile with: /EHsc
#include <memory>
#include <iostream>
int main()
{
std::shared_ptr<int> sp1(new int(5));
std::shared_ptr<int> sp2(new int(10));
std::cout << "*sp1 == " << *sp1 << std::endl;
sp1.swap(sp2);
std::cout << "*sp1 == " << *sp1 << std::endl;
swap(sp1, sp2);
std::cout << "*sp1 == " << *sp1 << std::endl;
std::cout << std::endl;
std::weak_ptr<int> wp1(sp1);
std::weak_ptr<int> wp2(sp2);
std::cout << "*wp1 == " << *wp1.lock() << std::endl;
wp1.swap(wp2);
std::cout << "*wp1 == " << *wp1.lock() << std::endl;
swap(wp1, wp2);
std::cout << "*wp1 == " << *wp1.lock() << std::endl;
return (0);
}
*sp1 == 5
*sp1 == 10
*sp1 == 5
*wp1 == 5
*wp1 == 10
*wp1 == 5
undeclare_no_pointers
Informs a garbage collector that the characters in the memory block defined by a base address pointer and block size may now contain traceable pointers.
void undeclare_no_pointers(
char* ptr,
size_t size);
Parameters
ptr
A pointer to the memory address previously marked using declare_no_pointers.
size
The number of bytes in the memory range. This value must equal the number used in the declare_no_pointers call.
Remarks
The function informs any garbage collector that the range of addresses [ptr, ptr + size) may now contain traceable pointers.
undeclare_reachable
Revokes a declaration of reachability for a specified memory location.
template <class T>
T *undeclare_reachable(
T* ptr);
Parameters
ptr
A pointer to the memory address previously marked using declare_reachable.
Remarks
If ptr is not nullptr, the function informs any garbage collector that ptr is no longer reachable. It returns a safely derived pointer that compares equal to ptr.
uninitialized_copy
Copies objects from a specified source range into an uninitialized destination range.
template <class InputIterator, class ForwardIterator>
ForwardIterator uninitialized_copy(
InputIterator first,
InputIterator last,
ForwardIterator dest);
template <class ExecutionPolicy, class InputIterator, class ForwardIterator>
ForwardIterator uninitialized_copy(
ExecutionPolicy&& policy,
InputIterator first,
InputIterator last,
ForwardIterator dest);
Parameters
policy
The execution policy to use.
first
An input iterator addressing the first element in the source range.
last
An input iterator addressing the last element in the source range.
dest
A forward iterator addressing the first element in the destination range.
Return Value
A forward iterator addressing the first position beyond the destination range, unless the source range was empty.
Remarks
This algorithm allows the decoupling of memory allocation from object construction.
The template function effectively executes:
while (first != last)
{
new (static_cast<void*>(&* dest++))
typename iterator_traits<InputIterator>::value_type(*first++);
}
return dest;
unless the code throws an exception. In that case, all constructed objects are destroyed and the exception is rethrown.
The overload with an execution policy is new in C++17.
Example
// memory_uninit_copy.cpp
// compile with: /EHsc /W3
#include <memory>
#include <iostream>
using namespace std;
class Integer
{
public:
Integer(int x) : value(x) {}
int get() { return value; }
private:
int value;
};
int main()
{
int Array[] = { 10, 20, 30, 40 };
const int N = sizeof(Array) / sizeof(int);
cout << "The initialized Array contains " << N << " elements: ";
for (int i = 0; i < N; i++)
{
cout << " " << Array[i];
}
cout << endl;
Integer* ArrayPtr = (Integer*)malloc(N * sizeof(int));
Integer* LArrayPtr = uninitialized_copy(
Array, Array + N, ArrayPtr); // C4996
cout << "Address of position after the last element in the array is: "
<< &Array[0] + N << endl;
cout << "The iterator returned by uninitialized_copy addresses: "
<< (void*)LArrayPtr << endl;
cout << "The address just beyond the last copied element is: "
<< (void*)(ArrayPtr + N) << endl;
if ((&Array[0] + N) == (void*)LArrayPtr)
cout << "The return value is an iterator "
<< "pointing just beyond the original array." << endl;
else
cout << "The return value is an iterator "
<< "not pointing just beyond the original array." << endl;
if ((void*)LArrayPtr == (void*)(ArrayPtr + N))
cout << "The return value is an iterator "
<< "pointing just beyond the copied array." << endl;
else
cout << "The return value is an iterator "
<< "not pointing just beyond the copied array." << endl;
free(ArrayPtr);
cout << "Note that the exact addresses returned will vary\n"
<< "with the memory allocation in individual computers."
<< endl;
}
uninitialized_copy_n
Creates a copy of a specified number of elements from an input iterator. The copies are put in a forward iterator.
template <class InputIterator, class Size, class ForwardIterator>
ForwardIterator uninitialized_copy_n(
InputIterator first,
Size count,
ForwardIterator dest);
template <class ExecutionPolicy, class InputIterator, class Size, class ForwardIterator>
ForwardIterator uninitialized_copy_n(
ExecutionPolicy&& policy,
InputIterator first,
Size count,
ForwardIterator dest);
Parameters
policy
The execution policy to use.
first
An input iterator that refers to the object to copy.
count
A signed or unsigned integer type specifying the number of times to copy the object.
dest
A forward iterator that refers to where the new copies go.
Return Value
A forward iterator that addresses the first position beyond the destination. If the source range was empty, the iterator addresses first.
Remarks
The template function effectively executes the following code:
for (; 0 < count; --count)
new (static_cast<void*>(&* dest++))
typename iterator_traits<InputIterator>::value_type(*first++);
return dest;
unless the code throws an exception. In that case, all constructed objects are destroyed and the exception is rethrown.
The overload with an execution policy is new in C++17.
uninitialized_default_construct
Default constructs objects of the iterators' value_type in the specified range.
template <class ForwardIterator>
void uninitialized_default_construct(
ForwardIterator first,
ForwardIterator last);
template <class ExecutionPolicy, class ForwardIterator>
void uninitialized_default_construct(
ExecutionPolicy&& policy,
ForwardIterator first,
ForwardIterator last);
Parameters
policy
The execution policy to use.
first
An iterator addressing the first element in the range to construct.
last
An iterator addressing one past the last element in the range to construct.
Remarks
The version without an execution policy is effectively the same as:
for (; first != last; ++first)
::new (static_cast<void*>(addressof(*first)))
typename iterator_traits<ForwardIterator>::value_type;
If an exception is thrown, previously constructed objects are destroyed in unspecified order.
The version with an execution policy has the same result, but executes according to the specified policy.
These functions are new in C++17.
uninitialized_default_construct_n
Default constructs a specified number of objects of the iterator's value_type, starting at the specified location.
template <class ForwardIterator, class Size>
ForwardIterator uninitialized_default_construct_n(
ForwardIterator first,
Size count);
template <class ExecutionPolicy, class ForwardIterator, class Size>
ForwardIterator uninitialized_default_construct_n(
ExecutionPolicy&& policy,
ForwardIterator first,
Size count);
Parameters
policy
The execution policy to use.
first
An iterator addressing the first element in the destination range to construct.
count
The count of elements in the destination range to construct.
Return Value
A forward iterator addressing the first position beyond the destination range, unless the source range was empty.
Remarks
The version without an execution policy is effectively the same as:
for (; count>0; (void)++first, --count)
::new (static_cast<void*>(addressof(*first)))
typename iterator_traits<ForwardIterator>::value_type;
return first;
If an exception is thrown, previously constructed objects are destroyed in unspecified order.
The version with an execution policy has the same result, but executes according to the specified policy.
These functions are new in C++17.
uninitialized_fill
Copies objects of a specified value into an uninitialized destination range.
template <class ForwardIterator, class T>
void uninitialized_fill(
ForwardIterator first,
ForwardIterator last,
const T& value);
template <class ExecutionPolicy, class ForwardIterator, class T>
void uninitialized_fill(
ExecutionPolicy&& policy,
ForwardIterator first,
ForwardIterator last,
const T& value);
Parameters
policy
The execution policy to use.
first
A forward iterator addressing the first element in the destination range to initialize.
last
A forward iterator addressing the last element in the destination range to initialize.
value
The value to be used to initialize the destination range.
Remarks
This algorithm allows the decoupling of memory allocation from object construction.
The template function effectively executes:
while (first != last)
new (static_cast<void*>(&* first ++))
typename iterator_traits<ForwardIterator>::value_type (value);
unless the code throws an exception. In that case, all constructed objects are destroyed and the exception is rethrown.
The overload with an execution policy is new in C++17.
Example
// memory_uninit_fill.cpp
// compile with: /EHsc
#include <memory>
#include <iostream>
using namespace std;
class Integer
{
public:
// No default constructor
Integer( int x ) : value( x ) {}
int get() { return value; }
private:
int value;
};
int main()
{
const int N = 10;
Integer value ( 25 );
Integer* Array = ( Integer* ) malloc( N * sizeof( int ) );
uninitialized_fill( Array, Array + N, value );
cout << "The initialized Array contains: ";
for ( int i = 0; i < N; i++ )
{
cout << Array[ i ].get() << " ";
}
cout << endl;
}
The initialized Array contains: 25 25 25 25 25 25 25 25 25 25
uninitialized_fill_n
Copies objects of a specified value into the specified number of elements of an uninitialized destination range.
template <class ForwardIterator, class Size, class T>
ForwardIterator uninitialized_fill_n(
ForwardIterator first,
Size count,
const T& value);
template <class ExecutionPolicy, class ForwardIterator, class Size, class T>
ForwardIterator uninitialized_fill_n(
ExecutionPolicy&& policy,
ForwardIterator first,
Size count,
const T& value);
Parameters
policy
The execution policy to use.
first
A forward iterator addressing the first element in the destination range to initialize.
count
The number of elements to initialize.
value
The value to use to initialize the destination range.
Remarks
This algorithm allows the decoupling of memory allocation from object construction.
The template function effectively executes:
while (0 < count--)
new (static_cast<void*>(&* first++))
typename iterator_traits<ForwardIterator>::value_type(value);
return first;
unless the code throws an exception. In that case, all constructed objects are destroyed and the exception is rethrown.
The overload with an execution policy is new in C++17.
Example
// memory_uninit_fill_n.cpp
// compile with: /EHsc /W3
#include <memory>
#include <iostream>
using namespace std;
class Integer
{
public:
// No default constructor
Integer( int x ) : value( x ) {}
int get() { return value; }
private:
int value;
};
int main()
{
const int N = 10;
Integer value( 60 );
Integer* Array = ( Integer* ) malloc( N * sizeof( int ) );
uninitialized_fill_n( Array, N, value ); // C4996
cout << "The uninitialized Array contains: ";
for ( int i = 0; i < N; i++ )
cout << Array[ i ].get() << " ";
}
uninitialized_move
Moves elements from a source range to an uninitialized destination memory area.
template <class InputIterator, class ForwardIterator>
ForwardIterator uninitialized_move(
InputIterator first,
InputIterator last,
ForwardIterator dest);
template <class ExecutionPolicy, class InputIterator, class ForwardIterator>
ForwardIterator uninitialized_move(
ExecutionPolicy&& policy,
InputIterator first,
InputIterator last,
ForwardIterator dest);
Parameters
policy
The execution policy to use.
first
An input iterator addressing the first element in the source range to move.
last
An input iterator addressing one past the last element in the source range to move.
dest
The beginning of the destination range.
Remarks
The version without an execution policy is effectively the same as:
for (; first != last; (void)++dest, ++first)
::new (static_cast<void*>(addressof(*dest)))
typename iterator_traits<ForwardIterator>::value_type(std::move(*first));
return dest;
If an exception is thrown, some objects in the source range might be left in a valid but unspecified state. Previously constructed objects are destroyed in unspecified order.
The version with an execution policy has the same result, but executes according to the specified policy.
These functions are new in C++17.
uninitialized_move_n
Moves a specified number of elements from a source range to an uninitialized destination memory area.
template <class InputIterator, class Size, class ForwardIterator>
pair<InputIterator, ForwardIterator> uninitialized_move_n(
InputIterator first,
Size count,
ForwardIterator dest);
template <class ExecutionPolicy, class InputIterator, class Size, class ForwardIterator>
pair<InputIterator, ForwardIterator> uninitialized_move_n(
ExecutionPolicy&& policy,
InputIterator first,
Size count,
ForwardIterator dest);
Parameters
policy
The execution policy to use.
first
An input iterator addressing the first element in the source range to move.
count
The count of elements in the source range to move.
dest
The beginning of the destination range.
Remarks
The version without an execution policy is effectively the same as:
for (; count > 0; ++dest, (void) ++first, --count)
::new (static_cast<void*>(addressof(*dest)))
typename iterator_traits<ForwardIterator>::value_type(std::move(*first));
return {first, dest};
If an exception is thrown, some objects in the source range might be left in a valid but unspecified state. Previously constructed objects are destroyed in unspecified order.
The version with an execution policy has the same result, but executes according to the specified policy.
These functions are new in C++17.
uninitialized_value_construct
Constructs objects of the iterators' value_type by value initialization, in the specified range.
template <class ForwardIterator>
void uninitialized_value_construct(
ForwardIterator first,
ForwardIterator last);
template <class ExecutionPolicy, class ForwardIterator>
void uninitialized_value_construct(
ExecutionPolicy&& policy,
ForwardIterator first,
ForwardIterator last);
Parameters
policy
The execution policy to use.
first
An iterator addressing the first element in the range to value construct.
last
An iterator addressing one past the last element in the range to value construct.
Remarks
The version without an execution policy is effectively the same as:
for (; first != last; ++first)
::new (static_cast<void*>(addressof(*first)))
typename iterator_traits<ForwardIterator>::value_type();
If an exception is thrown, previously constructed objects are destroyed in unspecified order.
The version with an execution policy has the same result, but executes according to the specified policy.
If a memory allocation failure occurs, a std::bad_alloc exception is thrown.
These functions are new in C++17.
uninitialized_value_construct_n
Constructs a specified number of objects of the iterator's value_type by value initialization, starting at the specified location.
template <class ForwardIterator, class Size>
ForwardIterator uninitialized_value_construct_n(
ForwardIterator first,
Size count);
template <class ExecutionPolicy, class ForwardIterator, class Size>
ForwardIterator uninitialized_value_construct_n(
ExecutionPolicy&& policy,
ForwardIterator first,
Size count);
Parameters
policy
The execution policy to use.
first
An iterator addressing the first element in the destination range to construct.
count
The count of elements in the destination range to construct.
Remarks
The version without an execution policy is effectively the same as:
for (; count > 0; (void)++first, --count)
::new (static_cast<void*>(addressof(*first)))
typename iterator_traits<ForwardIterator>::value_type();
return first;
If an exception is thrown, previously constructed objects are destroyed in unspecified order.
The version with an execution policy has the same result, but executes according to the specified policy.
If a memory allocation failure occurs, a std::bad_alloc exception is thrown.
These functions are new in C++17.
uses_allocator_v
A helper variable template to access the value of the uses_allocator template.
template <class T, class Alloc>
inline constexpr bool uses_allocator_v = uses_allocator<T, Alloc>::value;