| description | title | ms.date | f1_keywords | ms.assetid | helpviewer_keywords | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Learn more about: <memory> functions |
<memory> functions |
08/05/2019 |
|
3e1898c2-44b7-4626-87ce-84962e4c6f1a |
|
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++17value
The object or function for which to obtain the true address.
The actual address of the object or function referenced by value, even if an overloaded operator&() exists.
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
);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.
A NULL pointer if the requested aligned buffer wouldn't fit into the available space; otherwise, the new value of ptr.
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.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);alloc
The allocator used to create objects.
args
The zero or more arguments that become the objects.
The function creates the object shared_ptr<T>, a pointer to T(args...) as allocated and constructed by alloc.
template<class T>
bool atomic_compare_exchange_strong(
shared_ptr<T>* u,
shared_ptr<T>* v,
shared_ptr<T> w);template<class T>
bool atomic_compare_exchange_weak(
shared_ptr<T>* u,
shared_ptr<T>* v,
shared_ptr<T> w);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);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);template<class T>
shared_ptr<T> atomic_exchange(
shared_ptr<T>* u,
shared_ptr<T> r);template<class T>
shared_ptr<T> atomic_exchange_explicit(
shared_ptr<T>* u,
shared_ptr<T> r,
memory_order mo);template<class T>
bool atomic_is_lock_free(
const shared_ptr<T>* u);template<class T>
shared_ptr<T> atomic_load(
const shared_ptr<T>* u);template<class T>
shared_ptr<T> atomic_load_explicit(
const shared_ptr<T>* u,
memory_order mo);template<class T>
void atomic_store(
shared_ptr<T>* u,
shared_ptr<T> r);template<class T>
void atomic_store_explicit(
shared_ptr<T>* u,
shared_ptr<T> r,
memory_order mo);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;T
The type controlled by the returned shared pointer.
Other
The type controlled by the argument shared pointer.
sp
The argument shared pointer.
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.
// 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
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);ptr
Address of first character that no longer contains traceable pointers.
size
Size of block that starts at ptr that contains no traceable pointers.
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.)
Informs garbage collection that the indicated address is to allocated storage and is reachable.
void declare_reachable(
void* ptr);ptr
A pointer to a reachable, allocated, valid storage area.
If ptr is not null, the function informs any garbage collector that ptr is now reachable, that is, it points to valid allocated storage.
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;
};ptr
Pointer to the object to delete.
Other
The type of elements in the array to be deleted.
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[]>.
template <class T>
void destroy_at(
T* location);Same as location->~T().
template <class ForwardIterator>
void destroy(
ForwardIterator first,
ForwardIterator last);Same as:
for (; first != last; ++first)
destroy_at(addressof(*first));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 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;T
The type controlled by the returned shared pointer.
Other
The type controlled by the argument shared pointer.
sp
The argument shared pointer.
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.
// 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 the deleter from a shared_ptr.
template <class Deleter, class T>
Deleter* get_deleter(
const shared_ptr<T>& sp) noexcept;Deleter
The type of the deleter.
T
The type controlled by the shared pointer.
sp
The shared pointer.
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.
// 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
Returns the type of pointer safety assumed by any garbage collector.
pointer_safety get_pointer_safety() noexcept;The function returns the type of pointer safety assumed by any automatic garbage collector.
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);count
The maximum number of elements requested for which memory is to be allocated.
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.
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.
// 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.
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);args
Zero or more constructor arguments. The function infers which constructor overload to invoke based on the arguments that are provided.
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.
// 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
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;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.
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.
The following example shows how to use make_unique. For more examples, see How to: Create and Use unique_ptr Instances.
[!code-cppstl_smart_pointers#214]
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.
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;
};left
A shared or weak pointer.
right
A shared or weak pointer.
The class templates define all their member operators as returning left.owner_before(right).
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;ptr
An reference to a shared_ptr<U>.
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.
Deallocates the temporary memory that was allocated using the get_temporary_buffer template function.
template <class T>
void return_temporary_buffer(
T* buffer);buffer
A pointer to the memory to be deallocated.
Only use this function for memory that is temporary.
// 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 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;T
The type controlled by the returned shared pointer.
Other
The type controlled by the argument shared pointer.
sp
The argument shared pointer.
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.
// 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 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;
T
The type controlled by the argument pointer.
Deleter
The deleter of the unique pointer type.
left
The left pointer.
right
The right pointer.
The template functions call left.swap(right).
// 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
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);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.
The function informs any garbage collector that the range of addresses [ptr, ptr + size) may now contain traceable pointers.
Revokes a declaration of reachability for a specified memory location.
template <class T>
T *undeclare_reachable(
T* ptr);ptr
A pointer to the memory address previously marked using declare_reachable.
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.
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);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.
A forward iterator addressing the first position beyond the destination range, unless the source range was empty.
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.
// 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;
}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);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.
A forward iterator that addresses the first position beyond the destination. If the source range was empty, the iterator addresses first.
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.
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);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.
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.
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);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.
A forward iterator addressing the first position beyond the destination range, unless the source range was empty.
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.
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);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.
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.
// 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
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);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.
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.
// 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() << " ";
}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);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.
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.
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);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.
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.
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);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.
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.
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);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.
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.
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;