%!TEX root = std.tex

\rSec0[mem]{Memory management library}

\rSec1[mem.general]{General}

\pnum

This Clause describes components for memory management.

\pnum

The following subclauses describe general memory management facilities,

smart pointers, memory resources, and scoped allocators,

as summarized in \tref{mem.summary}.

\begin{libsumtab}{Memory management library summary}{mem.summary}

\ref{memory} & Memory & \tcode{<cstdlib>}, \tcode{<memory>} \\ \rowsep

\ref{smartptr} & Smart pointers & \tcode{<memory>} \\ \rowsep

\ref{mem.composite.types} & Types for composite class design & \tcode{<memory>} \\ \rowsep

\ref{mem.res} & Memory resources & \tcode{<memory_resource>} \\ \rowsep

\ref{allocator.adaptor} & Scoped allocators & \tcode{<scoped_allocator>} \\

\end{libsumtab}

\rSec1[memory]{Memory}

\rSec2[memory.general]{General}

\pnum

Subclause~\ref{memory} describes the contents of the header

\libheaderref{memory} and some

of the contents of the header \libheaderref{cstdlib}.

\rSec2[memory.syn]{Header \tcode{<memory>} synopsis}

\pnum

The header \libheaderdef{memory} defines several types and function templates that

describe properties of pointers and pointer-like types, manage memory

for containers and other template types, destroy objects, and

construct objects in

uninitialized memory

buffers~(\ref{pointer.traits}--\ref{specialized.addressof} and \ref{specialized.algorithms}).

The header also defines the templates

\tcode{unique_ptr}, \tcode{shared_ptr}, \tcode{weak_ptr},

\tcode{out_ptr_t}, \tcode{inout_ptr_t}, and various function

templates that operate on objects of these types\iref{smartptr}.

\pnum

Let \tcode{\exposid{POINTER_OF}(T)} denote a type that is

\begin{itemize}

\item

\tcode{T::pointer} if the \grammarterm{qualified-id} \tcode{T::pointer}

is valid and denotes a type,

\item

otherwise, \tcode{T::element_type*}

if the \grammarterm{qualified-id} \tcode{T::element_type}

is valid and denotes a type,

\item

otherwise, \tcode{pointer_traits<T>::element_type*}.

\end{itemize}

\pnum

Let \tcode{\exposid{POINTER_OF_OR}(T, U)} denote a type that is:

\begin{itemize}

\item

\tcode{\exposid{POINTER_OF}(T)}

if \tcode{\exposid{POINTER_OF}(T)} is valid and denotes a type,

\item

otherwise, \tcode{U}.

\end{itemize}

\begin{codeblock}

#include <compare> // see \ref{compare.syn}

namespace std {

// \ref{pointer.traits}, pointer traits

template<class Ptr> struct pointer_traits; // freestanding

template<class T> struct pointer_traits<T*>; // freestanding

// \ref{pointer.conversion}, pointer conversion

template<class T>

constexpr T* to_address(T* p) noexcept; // freestanding

template<class Ptr>

constexpr auto to_address(const Ptr& p) noexcept; // freestanding

// \ref{ptr.align}, pointer alignment

void* align(size_t alignment, size_t size, void*& ptr, size_t& space); // freestanding

template<size_t N, class T>

constexpr T* assume_aligned(T* ptr); // freestanding

template<size_t Alignment, class T>

bool is_sufficiently_aligned(T* ptr); // freestanding

// \ref{obj.lifetime}, explicit lifetime management

template<class T>

constexpr void start_lifetime(T& r) noexcept; // freestanding

template<class T>

T* start_lifetime_as(void* p) noexcept; // freestanding

template<class T>

const T* start_lifetime_as(const void* p) noexcept; // freestanding

template<class T>

volatile T* start_lifetime_as(volatile void* p) noexcept; // freestanding

template<class T>

const volatile T* start_lifetime_as(const volatile void* p) noexcept; // freestanding

template<class T>

T* start_lifetime_as_array(void* p, size_t n) noexcept; // freestanding

template<class T>

const T* start_lifetime_as_array(const void* p, size_t n) noexcept; // freestanding

template<class T>

volatile T* start_lifetime_as_array(volatile void* p, size_t n) noexcept; // freestanding

template<class T>

const volatile T* start_lifetime_as_array(const volatile void* p, // freestanding

size_t n) noexcept;

// \ref{allocator.tag}, allocator argument tag

struct allocator_arg_t { explicit allocator_arg_t() = default; }; // freestanding

inline constexpr allocator_arg_t allocator_arg{}; // freestanding

// \ref{allocator.uses}, \tcode{uses_allocator}

template<class T, class Alloc> struct uses_allocator; // freestanding

// \ref{allocator.uses.trait}, \tcode{uses_allocator}

template<class T, class Alloc>

constexpr bool @\libglobal{uses_allocator_v}@ = uses_allocator<T, Alloc>::value; // freestanding

// \ref{allocator.uses.construction}, uses-allocator construction

template<class T, class Alloc, class... Args>

constexpr auto uses_allocator_construction_args(const Alloc& alloc, // freestanding

Args&&... args) noexcept;

template<class T, class Alloc, class Tuple1, class Tuple2>

constexpr auto uses_allocator_construction_args(const Alloc& alloc, // freestanding

piecewise_construct_t,

Tuple1&& x, Tuple2&& y) noexcept;

template<class T, class Alloc>

constexpr auto uses_allocator_construction_args(const Alloc& alloc) noexcept; // freestanding

template<class T, class Alloc, class U, class V>

constexpr auto uses_allocator_construction_args(const Alloc& alloc, // freestanding

U&& u, V&& v) noexcept;

template<class T, class Alloc, class U, class V>

constexpr auto uses_allocator_construction_args(const Alloc& alloc, // freestanding

pair<U, V>& pr) noexcept;

template<class T, class Alloc, class U, class V>

constexpr auto uses_allocator_construction_args(const Alloc& alloc, // freestanding

const pair<U, V>& pr) noexcept;

template<class T, class Alloc, class U, class V>

constexpr auto uses_allocator_construction_args(const Alloc& alloc, // freestanding

pair<U, V>&& pr) noexcept;

template<class T, class Alloc, class U, class V>

constexpr auto uses_allocator_construction_args(const Alloc& alloc, // freestanding

const pair<U, V>&& pr) noexcept;

template<class T, class Alloc, @\exposconcept{pair-like}@ P>

constexpr auto uses_allocator_construction_args(const Alloc& alloc, // freestanding

P&& p) noexcept;

template<class T, class Alloc, class U>

constexpr auto uses_allocator_construction_args(const Alloc& alloc, // freestanding

U&& u) noexcept;

template<class T, class Alloc, class... Args>

constexpr T make_obj_using_allocator(const Alloc& alloc, Args&&... args); // freestanding

template<class T, class Alloc, class... Args>

constexpr T* uninitialized_construct_using_allocator(T* p, // freestanding

const Alloc& alloc, Args&&... args);

// \ref{allocator.traits}, allocator traits

template<class Alloc> struct allocator_traits; // freestanding

template<class Pointer, class SizeType = size_t>

struct @\libglobal{allocation_result}@ { // freestanding

Pointer @\libmember{ptr}{allocation_result}@;

SizeType @\libmember{count}{allocation_result}@;

};

// \ref{default.allocator}, the default allocator

template<class T> class allocator;

template<class T, class U>

constexpr bool operator==(const allocator<T>&, const allocator<U>&) noexcept;

// \ref{specialized.addressof}, addressof

template<class T>

constexpr T* addressof(T& r) noexcept; // freestanding

template<class T>

const T* addressof(const T&&) = delete; // freestanding

// \ref{specialized.algorithms}, specialized algorithms

// \ref{special.mem.concepts}, special memory concepts

template<class I>

concept @\exposconcept{nothrow-input-iterator}@ = @\seebelow@; // \expos

template<class I>

concept @\exposconcept{nothrow-forward-iterator}@ = @\seebelow@; // \expos

template<class I>

concept @\exposconcept{nothrow-bidirectional-iterator}@ = @\seebelow@; // \expos

template<class I>

concept @\exposconcept{nothrow-random-access-iterator}@ = @\seebelow@; // \expos

template<class S, class I>

concept @\exposconcept{nothrow-sentinel-for}@ = @\seebelow@; // \expos

template<class S, class I>

concept @\exposconcept{nothrow-sized-sentinel-for}@ = @\seebelow@; // \expos

template<class R>

concept @\exposconcept{nothrow-input-range}@ = @\seebelow@; // \expos

template<class R>

concept @\exposconcept{nothrow-forward-range}@ = @\seebelow@; // \expos

template<class R>

concept @\exposconcept{nothrow-bidirectional-range}@ = @\seebelow@; // \expos

template<class R>

concept @\exposconcept{nothrow-random-access-range}@ = @\seebelow@; // \expos

template<class R>

concept @\exposconcept{nothrow-sized-random-access-range}@ = @\seebelow@; // \expos

template<class NoThrowForwardIterator>

constexpr void uninitialized_default_construct(NoThrowForwardIterator first, // freestanding

NoThrowForwardIterator last);

template<class ExecutionPolicy, class NoThrowForwardIterator>

void uninitialized_default_construct(ExecutionPolicy&& exec, // freestanding-deleted,

NoThrowForwardIterator first, // see \ref{algorithms.parallel.overloads}

NoThrowForwardIterator last);

template<class NoThrowForwardIterator, class Size>

constexpr NoThrowForwardIterator

uninitialized_default_construct_n(NoThrowForwardIterator first, Size n); // freestanding

template<class ExecutionPolicy, class NoThrowForwardIterator, class Size>

NoThrowForwardIterator

uninitialized_default_construct_n(ExecutionPolicy&& exec, // freestanding-deleted,

NoThrowForwardIterator first, // see \ref{algorithms.parallel.overloads}

Size n);

namespace ranges {

template<@\exposconcept{nothrow-forward-iterator}@ I, @\exposconcept{nothrow-sentinel-for}@<I> S>

requires @\libconcept{default_initializable}@<iter_value_t<I>>

constexpr I uninitialized_default_construct(I first, S last); // freestanding

template<@\exposconcept{nothrow-forward-range}@ R>

requires @\libconcept{default_initializable}@<range_value_t<R>>

constexpr borrowed_iterator_t<R> uninitialized_default_construct(R&& r); // freestanding

template<@\exposconcept{nothrow-forward-iterator}@ I>

requires @\libconcept{default_initializable}@<iter_value_t<I>>

constexpr I uninitialized_default_construct_n(I first, // freestanding

iter_difference_t<I> n);

template<@\exposconcept{execution-policy}@ Ep, @\exposconcept{nothrow-random-access-iterator}@ I,

@\exposconcept{nothrow-sized-sentinel-for}@<I> S>

requires @\libconcept{default_initializable}@<iter_value_t<I>>

I uninitialized_default_construct(Ep&& exec, I first, S last); // freestanding-deleted,

// see \ref{algorithms.parallel.overloads}

template<@\exposconcept{execution-policy}@ Ep, @\exposconcept{nothrow-sized-random-access-range}@ R>

requires @\libconcept{default_initializable}@<range_value_t<R>>

borrowed_iterator_t<R> uninitialized_default_construct(Ep&& exec, // freestanding-deleted,

R&& r); // see \ref{algorithms.parallel.overloads}

template<@\exposconcept{execution-policy}@ Ep, @\exposconcept{nothrow-random-access-iterator}@ I>

requires @\libconcept{default_initializable}@<iter_value_t<I>>

I uninitialized_default_construct_n(Ep&& exec, I first, // freestanding-deleted,

iter_difference_t<I> n); // see \ref{algorithms.parallel.overloads}

}

template<class NoThrowForwardIterator>

constexpr void uninitialized_value_construct(NoThrowForwardIterator first, // freestanding

NoThrowForwardIterator last);

template<class ExecutionPolicy, class NoThrowForwardIterator>

void uninitialized_value_construct(ExecutionPolicy&& exec, // freestanding-deleted,

NoThrowForwardIterator first, // see \ref{algorithms.parallel.overloads}

NoThrowForwardIterator last);

template<class NoThrowForwardIterator, class Size>

constexpr NoThrowForwardIterator

uninitialized_value_construct_n(NoThrowForwardIterator first, Size n); // freestanding

template<class ExecutionPolicy, class NoThrowForwardIterator, class Size>

NoThrowForwardIterator

uninitialized_value_construct_n(ExecutionPolicy&& exec, // freestanding-deleted,

NoThrowForwardIterator first, // see \ref{algorithms.parallel.overloads}

Size n);

namespace ranges {

template<@\exposconcept{nothrow-forward-iterator}@ I, @\exposconcept{nothrow-sentinel-for}@<I> S>

requires @\libconcept{default_initializable}@<iter_value_t<I>>

constexpr I uninitialized_value_construct(I first, S last); // freestanding

template<@\exposconcept{nothrow-forward-range}@ R>

requires @\libconcept{default_initializable}@<range_value_t<R>>

constexpr borrowed_iterator_t<R> uninitialized_value_construct(R&& r); // freestanding

template<@\exposconcept{nothrow-forward-iterator}@ I>

requires @\libconcept{default_initializable}@<iter_value_t<I>>

constexpr I uninitialized_value_construct_n(I first, // freestanding

iter_difference_t<I> n);

template<@\exposconcept{execution-policy}@ Ep, @\exposconcept{nothrow-random-access-iterator}@ I,

@\exposconcept{nothrow-sized-sentinel-for}@<I> S>

requires @\libconcept{default_initializable}@<iter_value_t<I>>

I uninitialized_value_construct(Ep&& exec, I first, S last); // freestanding-deleted,

// see \ref{algorithms.parallel.overloads}

template<@\exposconcept{execution-policy}@ Ep, @\exposconcept{nothrow-sized-random-access-range}@ R>

requires @\libconcept{default_initializable}@<range_value_t<R>>

borrowed_iterator_t<R> uninitialized_value_construct(Ep&& exec, // freestanding-deleted,

R&& r); // see \ref{algorithms.parallel.overloads}

template<@\exposconcept{execution-policy}@ Ep, @\exposconcept{nothrow-random-access-iterator}@ I>

requires @\libconcept{default_initializable}@<iter_value_t<I>>

I uninitialized_value_construct_n(Ep&& exec, I first, // freestanding-deleted,

iter_difference_t<I> n); // see \ref{algorithms.parallel.overloads}

}

template<class InputIterator, class NoThrowForwardIterator>

constexpr NoThrowForwardIterator uninitialized_copy(InputIterator first, // freestanding

InputIterator last,

NoThrowForwardIterator result);

template<class ExecutionPolicy, class ForwardIterator, class NoThrowForwardIterator>

NoThrowForwardIterator uninitialized_copy(ExecutionPolicy&& exec, // freestanding-deleted,

ForwardIterator first, // see \ref{algorithms.parallel.overloads}

ForwardIterator last,

NoThrowForwardIterator result);

template<class InputIterator, class Size, class NoThrowForwardIterator>

constexpr NoThrowForwardIterator uninitialized_copy_n(InputIterator first, // freestanding

Size n,

NoThrowForwardIterator result);

template<class ExecutionPolicy, class ForwardIterator, class Size,

class NoThrowForwardIterator>

NoThrowForwardIterator uninitialized_copy_n(ExecutionPolicy&& exec, // freestanding-deleted,

ForwardIterator first, // see \ref{algorithms.parallel.overloads}

Size n,

NoThrowForwardIterator result);

namespace ranges {

template<class I, class O>

using @\libglobal{uninitialized_copy_result}@ = in_out_result<I, O>; // freestanding

template<@\libconcept{input_iterator}@ I, @\libconcept{sentinel_for}@<I> S1,

@\exposconcept{nothrow-forward-iterator}@ O, @\exposconcept{nothrow-sentinel-for}@<O> S2>

requires @\libconcept{constructible_from}@<iter_value_t<O>, iter_reference_t<I>>

constexpr uninitialized_copy_result<I, O>

uninitialized_copy(I ifirst, S1 ilast, O ofirst, S2 olast); // freestanding

template<@\libconcept{input_range}@ IR, @\exposconcept{nothrow-forward-range}@ OR>

requires @\libconcept{constructible_from}@<range_value_t<OR>, range_reference_t<IR>>

constexpr uninitialized_copy_result<borrowed_iterator_t<IR>, borrowed_iterator_t<OR>>

uninitialized_copy(IR&& in_range, OR&& out_range); // freestanding

template<class I, class O>

using @\libglobal{uninitialized_copy_n_result}@ = in_out_result<I, O>; // freestanding

template<@\libconcept{input_iterator}@ I, @\exposconcept{nothrow-forward-iterator}@ O, @\exposconcept{nothrow-sentinel-for}@<O> S>

requires @\libconcept{constructible_from}@<iter_value_t<O>, iter_reference_t<I>>

constexpr uninitialized_copy_n_result<I, O>

uninitialized_copy_n(I ifirst, iter_difference_t<I> n, // freestanding

O ofirst, S olast);

template<@\exposconcept{execution-policy}@ Ep, @\libconcept{random_access_iterator}@ I, @\libconcept{sized_sentinel_for}@<I> S1,

@\exposconcept{nothrow-random-access-iterator}@ O, @\exposconcept{nothrow-sized-sentinel-for}@<O> S2>

requires @\libconcept{constructible_from}@<iter_value_t<O>, iter_reference_t<I>>

uninitialized_copy_result<I, O>

uninitialized_copy(Ep&& exec, I ifirst, S1 ilast, // freestanding-deleted,

O ofirst, S2 olast); // see \ref{algorithms.parallel.overloads}

template<@\exposconcept{execution-policy}@ Ep, @\exposconcept{sized-random-access-range}@ IR,

@\exposconcept{nothrow-sized-random-access-range}@ OR>

requires @\libconcept{constructible_from}@<range_value_t<OR>, range_reference_t<IR>>

uninitialized_copy_result<borrowed_iterator_t<IR>, borrowed_iterator_t<OR>>

uninitialized_copy(Ep&& exec, IR&& in_range, OR&& out_range); // freestanding-deleted,

// see \ref{algorithms.parallel.overloads}

template<@\exposconcept{execution-policy}@ Ep, @\libconcept{random_access_iterator}@ I, @\exposconcept{nothrow-random-access-iterator}@ O,

@\exposconcept{nothrow-sized-sentinel-for}@<O> S>

requires @\libconcept{constructible_from}@<iter_value_t<O>, iter_reference_t<I>>

uninitialized_copy_n_result<I, O>

uninitialized_copy_n(Ep&& exec, I ifirst, iter_difference_t<I> n, // freestanding-deleted,

O ofirst, S olast); // see \ref{algorithms.parallel.overloads}

}

template<class InputIterator, class NoThrowForwardIterator>

constexpr NoThrowForwardIterator uninitialized_move(InputIterator first, // freestanding

InputIterator last,

NoThrowForwardIterator result);

template<class ExecutionPolicy, class ForwardIterator, class NoThrowForwardIterator>

NoThrowForwardIterator uninitialized_move(ExecutionPolicy&& exec, // freestanding-deleted,

ForwardIterator first, // see \ref{algorithms.parallel.overloads}

ForwardIterator last,

NoThrowForwardIterator result);

template<class InputIterator, class Size, class NoThrowForwardIterator>

constexpr pair<InputIterator, NoThrowForwardIterator>

uninitialized_move_n(InputIterator first, Size n, // freestanding

NoThrowForwardIterator result);

template<class ExecutionPolicy, class ForwardIterator, class Size,

class NoThrowForwardIterator>

pair<ForwardIterator, NoThrowForwardIterator>

uninitialized_move_n(ExecutionPolicy&& exec, // freestanding-deleted,

ForwardIterator first, Size n, // see \ref{algorithms.parallel.overloads}

NoThrowForwardIterator result);

namespace ranges {

template<class I, class O>

using @\libglobal{uninitialized_move_result}@ = in_out_result<I, O>; // freestanding

template<@\libconcept{input_iterator}@ I, @\libconcept{sentinel_for}@<I> S1,

@\exposconcept{nothrow-forward-iterator}@ O, @\exposconcept{nothrow-sentinel-for}@<O> S2>

requires @\libconcept{constructible_from}@<iter_value_t<O>, iter_rvalue_reference_t<I>>

constexpr uninitialized_move_result<I, O>

uninitialized_move(I ifirst, S1 ilast, O ofirst, S2 olast); // freestanding

template<@\libconcept{input_range}@ IR, @\exposconcept{nothrow-forward-range}@ OR>

requires @\libconcept{constructible_from}@<range_value_t<OR>, range_rvalue_reference_t<IR>>

constexpr uninitialized_move_result<borrowed_iterator_t<IR>, borrowed_iterator_t<OR>>

uninitialized_move(IR&& in_range, OR&& out_range); // freestanding

template<class I, class O>

using @\libglobal{uninitialized_move_n_result}@ = in_out_result<I, O>; // freestanding

template<@\libconcept{input_iterator}@ I,

@\exposconcept{nothrow-forward-iterator}@ O, @\exposconcept{nothrow-sentinel-for}@<O> S>

requires @\libconcept{constructible_from}@<iter_value_t<O>, iter_rvalue_reference_t<I>>

constexpr uninitialized_move_n_result<I, O>

uninitialized_move_n(I ifirst, iter_difference_t<I> n, // freestanding

O ofirst, S olast);

template<@\exposconcept{execution-policy}@ Ep, @\libconcept{random_access_iterator}@ I, @\libconcept{sized_sentinel_for}@<I> S1,

@\exposconcept{nothrow-random-access-iterator}@ O, @\exposconcept{nothrow-sized-sentinel-for}@<O> S2>

requires @\libconcept{constructible_from}@<iter_value_t<O>, iter_rvalue_reference_t<I>>

uninitialized_move_result<I, O>

uninitialized_move(Ep&& exec, I ifirst, S1 ilast, // freestanding-deleted,

O ofirst, S2 olast); // see \ref{algorithms.parallel.overloads}

template<@\exposconcept{execution-policy}@ Ep, @\exposconcept{sized-random-access-range}@ IR,

@\exposconcept{nothrow-sized-random-access-range}@ OR>

requires @\libconcept{constructible_from}@<range_value_t<OR>, range_rvalue_reference_t<IR>>

uninitialized_move_result<borrowed_iterator_t<IR>, borrowed_iterator_t<OR>>

uninitialized_move(Ep&& exec, IR&& in_range, OR&& out_range); // freestanding-deleted,

// see \ref{algorithms.parallel.overloads}

template<@\exposconcept{execution-policy}@ Ep, @\libconcept{random_access_iterator}@ I,

@\exposconcept{nothrow-random-access-iterator}@ O, @\exposconcept{nothrow-sized-sentinel-for}@<O> S>

requires @\libconcept{constructible_from}@<iter_value_t<O>, iter_rvalue_reference_t<I>>

uninitialized_move_n_result<I, O>

uninitialized_move_n(Ep&& exec, I ifirst, iter_difference_t<I> n, // freestanding-deleted,

O ofirst, S olast); // see \ref{algorithms.parallel.overloads}

}

template<class NoThrowForwardIterator,

class T = iterator_traits<NoThrowForwardIterator>::value_type>

constexpr void uninitialized_fill(NoThrowForwardIterator first, // freestanding

NoThrowForwardIterator last, const T& x);

template<class ExecutionPolicy, class NoThrowForwardIterator,

class T = iterator_traits<NoThrowForwardIterator>::value_type>

void uninitialized_fill(ExecutionPolicy&& exec, // freestanding-deleted,

NoThrowForwardIterator first, // see \ref{algorithms.parallel.overloads}

NoThrowForwardIterator last,

const T& x);

template<class NoThrowForwardIterator, class Size,

class T = iterator_traits<NoThrowForwardIterator>::value_type>

constexpr NoThrowForwardIterator

uninitialized_fill_n(NoThrowForwardIterator first, Size n, const T& x); // freestanding

template<class ExecutionPolicy, class NoThrowForwardIterator, class Size,

class T = iterator_traits<NoThrowForwardIterator>::value_type>

NoThrowForwardIterator

uninitialized_fill_n(ExecutionPolicy&& exec, // freestanding-deleted,

NoThrowForwardIterator first, // see \ref{algorithms.parallel.overloads}

Size n, const T& x);

namespace ranges {

template<@\exposconcept{nothrow-forward-iterator}@ I, @\exposconcept{nothrow-sentinel-for}@<I> S, class T = iter_value_t<I>>

requires @\libconcept{constructible_from}@<iter_value_t<I>, const T&>

constexpr I uninitialized_fill(I first, S last, const T& x); // freestanding

template<@\exposconcept{nothrow-forward-range}@ R, class T = range_value_t<R>>

requires @\libconcept{constructible_from}@<range_value_t<R>, const T&>

constexpr borrowed_iterator_t<R> uninitialized_fill(R&& r, const T& x); // freestanding

template<@\exposconcept{nothrow-forward-iterator}@ I, class T = iter_value_t<I>>

requires @\libconcept{constructible_from}@<iter_value_t<I>, const T&>

constexpr I uninitialized_fill_n(I first, // freestanding

iter_difference_t<I> n, const T& x);

template<@\exposconcept{execution-policy}@ Ep, @\exposconcept{nothrow-random-access-iterator}@ I,

@\exposconcept{nothrow-sized-sentinel-for}@<I> S, class T = iter_value_t<I>>

requires @\libconcept{constructible_from}@<iter_value_t<I>, const T&>

I uninitialized_fill(Ep&& exec, I first, S last, const T& x); // freestanding-deleted,

// see \ref{algorithms.parallel.overloads}

template<@\exposconcept{execution-policy}@ Ep, @\exposconcept{nothrow-sized-random-access-range}@ R,

class T = range_value_t<R>>

requires @\libconcept{constructible_from}@<range_value_t<R>, const T&>

borrowed_iterator_t<R> uninitialized_fill(Ep&& exec, R&& r, // freestanding-deleted,

const T& x); // see \ref{algorithms.parallel.overloads}

template<@\exposconcept{execution-policy}@ Ep, @\exposconcept{nothrow-random-access-iterator}@ I, class T = iter_value_t<I>>

requires @\libconcept{constructible_from}@<iter_value_t<I>, const T&>

I uninitialized_fill_n(Ep&& exec, I first, // freestanding-deleted,

iter_difference_t<I> n, const T& x); // see \ref{algorithms.parallel.overloads}

}

// \ref{specialized.construct}, \tcode{construct_at}

template<class T, class... Args>

constexpr T* construct_at(T* location, Args&&... args); // freestanding

namespace ranges {

template<class T, class... Args>

constexpr T* construct_at(T* location, Args&&... args); // freestanding

}

// \ref{specialized.destroy}, \tcode{destroy}

template<class T>

constexpr void destroy_at(T* location); // freestanding

template<class NoThrowForwardIterator>

constexpr void destroy(NoThrowForwardIterator first, // freestanding

NoThrowForwardIterator last);

template<class ExecutionPolicy, class NoThrowForwardIterator>

void destroy(ExecutionPolicy&& exec, // freestanding-deleted,

NoThrowForwardIterator first, // see \ref{algorithms.parallel.overloads}

NoThrowForwardIterator last);

template<class NoThrowForwardIterator, class Size>

constexpr NoThrowForwardIterator destroy_n(NoThrowForwardIterator first, // freestanding

Size n);

template<class ExecutionPolicy, class NoThrowForwardIterator, class Size>

NoThrowForwardIterator destroy_n(ExecutionPolicy&& exec, // freestanding-deleted,

NoThrowForwardIterator first, Size n); // see \ref{algorithms.parallel.overloads}

namespace ranges {

template<@\libconcept{destructible}@ T>

constexpr void destroy_at(T* location) noexcept; // freestanding

template<@\exposconcept{nothrow-input-iterator}@ I, @\exposconcept{nothrow-sentinel-for}@<I> S>

requires @\libconcept{destructible}@<iter_value_t<I>>

constexpr I destroy(I first, S last) noexcept; // freestanding

template<@\exposconcept{nothrow-input-range}@ R>

requires @\libconcept{destructible}@<range_value_t<R>>

constexpr borrowed_iterator_t<R> destroy(R&& r) noexcept; // freestanding

template<@\exposconcept{nothrow-input-iterator}@ I>

requires @\libconcept{destructible}@<iter_value_t<I>>

constexpr I destroy_n(I first, iter_difference_t<I> n) noexcept; // freestanding

template<@\exposconcept{execution-policy}@ Ep, @\exposconcept{nothrow-random-access-iterator}@ I,

@\exposconcept{nothrow-sized-sentinel-for}@<I> S>

requires @\libconcept{destructible}@<iter_value_t<I>>

I destroy(Ep&& exec, I first, S last); // freestanding-deleted,

// see \ref{algorithms.parallel.overloads}

template<@\exposconcept{execution-policy}@ Ep, @\exposconcept{nothrow-sized-random-access-range}@ R>

requires @\libconcept{destructible}@<range_value_t<R>>

borrowed_iterator_t<R> destroy(Ep&& exec, R&& r); // freestanding-deleted,

// see \ref{algorithms.parallel.overloads}

template<@\exposconcept{execution-policy}@ Ep, @\exposconcept{nothrow-random-access-iterator}@ I>

requires @\libconcept{destructible}@<iter_value_t<I>>

I destroy_n(Ep&& exec, I first, iter_difference_t<I> n); // freestanding-deleted,

// see \ref{algorithms.parallel.overloads}

}

// \ref{unique.ptr}, class template \tcode{unique_ptr}

template<class T> struct default_delete; // freestanding

template<class T> struct default_delete<T[]>; // freestanding

template<class T, class D = default_delete<T>> class unique_ptr; // freestanding

template<class T, class D> class unique_ptr<T[], D>; // freestanding

template<class T, class... Args>

constexpr unique_ptr<T> make_unique(Args&&... args); // \tcode{T} is not array

template<class T>

constexpr unique_ptr<T> make_unique(size_t n); // \tcode{T} is \tcode{U[]}

template<class T, class... Args>

@\unspecnc@ make_unique(Args&&...) = delete; // \tcode{T} is \tcode{U[N]}

template<class T>

constexpr unique_ptr<T> make_unique_for_overwrite(); // \tcode{T} is not array

template<class T>

constexpr unique_ptr<T> make_unique_for_overwrite(size_t n); // \tcode{T} is \tcode{U[]}

template<class T, class... Args>

@\unspecnc@ make_unique_for_overwrite(Args&&...) = delete; // \tcode{T} is \tcode{U[N]}

template<class T, class D>

constexpr void swap(unique_ptr<T, D>& x, unique_ptr<T, D>& y) noexcept; // freestanding

template<class T1, class D1, class T2, class D2>

constexpr bool operator==(const unique_ptr<T1, D1>& x, // freestanding

const unique_ptr<T2, D2>& y);

template<class T1, class D1, class T2, class D2>

constexpr bool operator<(const unique_ptr<T1, D1>& x, // freestanding

const unique_ptr<T2, D2>& y);

template<class T1, class D1, class T2, class D2>

constexpr bool operator>(const unique_ptr<T1, D1>& x, // freestanding

const unique_ptr<T2, D2>& y);

template<class T1, class D1, class T2, class D2>

constexpr bool operator<=(const unique_ptr<T1, D1>& x, // freestanding

const unique_ptr<T2, D2>& y);

template<class T1, class D1, class T2, class D2>

constexpr bool operator>=(const unique_ptr<T1, D1>& x, // freestanding

const unique_ptr<T2, D2>& y);

template<class T1, class D1, class T2, class D2>

requires @\libconcept{three_way_comparable_with}@<typename unique_ptr<T1, D1>::pointer,

typename unique_ptr<T2, D2>::pointer>

constexpr compare_three_way_result_t<typename unique_ptr<T1, D1>::pointer,

typename unique_ptr<T2, D2>::pointer>

operator<=>(const unique_ptr<T1, D1>& x, const unique_ptr<T2, D2>& y); // freestanding

template<class T, class D>

constexpr bool operator==(const unique_ptr<T, D>& x, nullptr_t) noexcept; // freestanding

template<class T, class D>

constexpr bool operator<(const unique_ptr<T, D>& x, nullptr_t); // freestanding

template<class T, class D>

constexpr bool operator<(nullptr_t, const unique_ptr<T, D>& y); // freestanding

template<class T, class D>

constexpr bool operator>(const unique_ptr<T, D>& x, nullptr_t); // freestanding

template<class T, class D>

constexpr bool operator>(nullptr_t, const unique_ptr<T, D>& y); // freestanding

template<class T, class D>

constexpr bool operator<=(const unique_ptr<T, D>& x, nullptr_t); // freestanding

template<class T, class D>

constexpr bool operator<=(nullptr_t, const unique_ptr<T, D>& y); // freestanding

template<class T, class D>

constexpr bool operator>=(const unique_ptr<T, D>& x, nullptr_t); // freestanding

template<class T, class D>

constexpr bool operator>=(nullptr_t, const unique_ptr<T, D>& y); // freestanding

template<class T, class D>

requires @\libconcept{three_way_comparable}@<typename unique_ptr<T, D>::pointer>

constexpr compare_three_way_result_t<typename unique_ptr<T, D>::pointer>

operator<=>(const unique_ptr<T, D>& x, nullptr_t); // freestanding

template<class E, class T, class Y, class D>

basic_ostream<E, T>& operator<<(basic_ostream<E, T>& os, const unique_ptr<Y, D>& p);

// \ref{util.smartptr.weak.bad}, class \tcode{bad_weak_ptr}

class bad_weak_ptr;

// \ref{util.smartptr.shared}, class template \tcode{shared_ptr}

template<class T> class shared_ptr;

// \ref{util.smartptr.shared.create}, \tcode{shared_ptr} creation

template<class T, class... Args>

constexpr shared_ptr<T> make_shared(Args&&... args); // \tcode{T} is not array

template<class T, class A, class... Args>

constexpr shared_ptr<T> allocate_shared(const A& a, Args&&... args); // \tcode{T} is not array

template<class T>

constexpr shared_ptr<T> make_shared(size_t N); // \tcode{T} is \tcode{U[]}

template<class T, class A>

constexpr shared_ptr<T> allocate_shared(const A& a, size_t N); // \tcode{T} is \tcode{U[]}

template<class T>

constexpr shared_ptr<T> make_shared(); // \tcode{T} is \tcode{U[N]}

template<class T, class A>

constexpr shared_ptr<T> allocate_shared(const A& a); // \tcode{T} is \tcode{U[N]}

template<class T>

constexpr shared_ptr<T> make_shared(size_t N, const remove_extent_t<T>& u); // \tcode{T} is \tcode{U[]}

template<class T, class A>

constexpr shared_ptr<T> allocate_shared(const A& a, size_t N,

const remove_extent_t<T>& u); // \tcode{T} is \tcode{U[]}

template<class T>

constexpr shared_ptr<T> make_shared(const remove_extent_t<T>& u); // \tcode{T} is \tcode{U[N]}

template<class T, class A>

constexpr shared_ptr<T> allocate_shared(const A& a, // \tcode{T} is \tcode{U[N]}

const remove_extent_t<T>& u);

template<class T>

constexpr shared_ptr<T> make_shared_for_overwrite(); // \tcode{T} is not \tcode{U[]}

template<class T, class A>

constexpr shared_ptr<T> allocate_shared_for_overwrite(const A& a); // \tcode{T} is not \tcode{U[]}

template<class T>

constexpr shared_ptr<T> make_shared_for_overwrite(size_t N); // \tcode{T} is \tcode{U[]}

template<class T, class A>

constexpr shared_ptr<T> allocate_shared_for_overwrite(const A& a, size_t N); // \tcode{T} is \tcode{U[]}

// \ref{util.smartptr.shared.cmp}, \tcode{shared_ptr} comparisons

template<class T, class U>

constexpr bool operator==(const shared_ptr<T>& a, const shared_ptr<U>& b) noexcept;

template<class T, class U>

constexpr strong_ordering operator<=>(const shared_ptr<T>& a,

const shared_ptr<U>& b) noexcept;

template<class T>

constexpr bool operator==(const shared_ptr<T>& x, nullptr_t) noexcept;

template<class T>

constexpr strong_ordering operator<=>(const shared_ptr<T>& x, nullptr_t) noexcept;

// \ref{util.smartptr.shared.spec}, \tcode{shared_ptr} specialized algorithms

template<class T>

constexpr void swap(shared_ptr<T>& a, shared_ptr<T>& b) noexcept;

// \ref{util.smartptr.shared.cast}, \tcode{shared_ptr} casts

template<class T, class U>

constexpr shared_ptr<T> static_pointer_cast(const shared_ptr<U>& r) noexcept;

template<class T, class U>

constexpr shared_ptr<T> static_pointer_cast(shared_ptr<U>&& r) noexcept;

template<class T, class U>

constexpr shared_ptr<T> dynamic_pointer_cast(const shared_ptr<U>& r) noexcept;

template<class T, class U>

constexpr shared_ptr<T> dynamic_pointer_cast(shared_ptr<U>&& r) noexcept;

template<class T, class U>

constexpr shared_ptr<T> const_pointer_cast(const shared_ptr<U>& r) noexcept;

template<class T, class U>

constexpr shared_ptr<T> const_pointer_cast(shared_ptr<U>&& r) noexcept;

template<class T, class U>

shared_ptr<T> reinterpret_pointer_cast(const shared_ptr<U>& r) noexcept;

template<class T, class U>

shared_ptr<T> reinterpret_pointer_cast(shared_ptr<U>&& r) noexcept;

// \ref{util.smartptr.getdeleter}, \tcode{shared_ptr} \tcode{get_deleter}

template<class D, class T>

constexpr D* get_deleter(const shared_ptr<T>& p) noexcept;

// \ref{util.smartptr.shared.io}, \tcode{shared_ptr} I/O

template<class E, class T, class Y>

basic_ostream<E, T>& operator<<(basic_ostream<E, T>& os, const shared_ptr<Y>& p);

// \ref{util.smartptr.weak}, class template \tcode{weak_ptr}

template<class T> class weak_ptr;

// \ref{util.smartptr.weak.spec}, \tcode{weak_ptr} specialized algorithms

template<class T> constexpr void swap(weak_ptr<T>& a, weak_ptr<T>& b) noexcept;

// \ref{util.smartptr.ownerless}, class template \tcode{owner_less}

template<class T = void> struct owner_less;

// \ref{util.smartptr.owner.hash}, struct \tcode{owner_hash}

struct owner_hash;

// \ref{util.smartptr.owner.equal}, struct \tcode{owner_equal}

struct owner_equal;

// \ref{util.smartptr.enab}, class template \tcode{enable_shared_from_this}

template<class T> class enable_shared_from_this;

// \ref{util.smartptr.hash}, hash support

template<class T> struct hash; // freestanding

template<class T, class D> struct hash<unique_ptr<T, D>>; // freestanding

template<class T> struct hash<shared_ptr<T>>;

// \ref{util.smartptr.atomic}, atomic smart pointers

template<class T> struct atomic; // freestanding

template<class T> struct atomic<shared_ptr<T>>;

template<class T> struct atomic<weak_ptr<T>>;

// \ref{out.ptr.t}, class template \tcode{out_ptr_t}

template<class Smart, class Pointer, class... Args>

class out_ptr_t; // freestanding

// \ref{out.ptr}, function template \tcode{out_ptr}

template<class Pointer = void, class Smart, class... Args>

constexpr auto out_ptr(Smart& s, Args&&... args); // freestanding

// \ref{inout.ptr.t}, class template \tcode{inout_ptr_t}

template<class Smart, class Pointer, class... Args>

class inout_ptr_t; // freestanding

// \ref{inout.ptr}, function template \tcode{inout_ptr}

template<class Pointer = void, class Smart, class... Args>

constexpr auto inout_ptr(Smart& s, Args&&... args); // freestanding

// \ref{indirect}, class template \tcode{indirect}

template<class T, class Allocator = allocator<T>>

class indirect;

// \ref{indirect.hash}, hash support

template<class T, class Alloc> struct hash<indirect<T, Alloc>>;

// \ref{polymorphic}, class template \tcode{polymorphic}

template<class T, class Allocator = allocator<T>>

class polymorphic;

namespace pmr {

template<class T> using indirect = indirect<T, polymorphic_allocator<T>>;

template<class T> using polymorphic = polymorphic<T, polymorphic_allocator<T>>;

}

}

\end{codeblock}

\rSec2[pointer.traits]{Pointer traits}

\rSec3[pointer.traits.general]{General}

\pnum

The class template \tcode{pointer_traits} supplies a uniform interface to certain

attributes of pointer-like types.

\indexlibraryglobal{pointer_traits}%

\begin{codeblock}

namespace std {

template<class Ptr> struct pointer_traits {

@\seebelow@;

};

template<class T> struct pointer_traits<T*> {

using pointer = T*;

using element_type = T;

using difference_type = ptrdiff_t;

template<class U> using rebind = U*;

static constexpr pointer pointer_to(@\seebelow@ r) noexcept;

};

}

\end{codeblock}

\rSec3[pointer.traits.types]{Member types}

\pnum

The definitions in this subclause make use of

the following exposition-only class template and concept:

\begin{codeblock}

template<class T>

struct @\exposid{ptr-traits-elem}@ // \expos

{ };

template<class T> requires requires { typename T::element_type; }

struct @\exposid{ptr-traits-elem}@<T>

{ using type = T::element_type; };

template<template<class...> class SomePointer, class T, class... Args>

requires (!requires { typename SomePointer<T, Args...>::element_type; })

struct @\exposid{ptr-traits-elem}@<SomePointer<T, Args...>>

{ using type = T; };

template<class Ptr>

concept @\defexposconcept{has-elem-type}@ = // \expos

requires { typename @\exposid{ptr-traits-elem}@<Ptr>::type; }

\end{codeblock}

\pnum

If \tcode{Ptr} satisfies \exposconcept{has-elem-type},

a specialization \tcode{pointer_traits<Ptr>}

generated from the \tcode{pointer_traits} primary template

has the following members

as well as those described in~\ref{pointer.traits.functions};

otherwise, such a specialization has no members by any of those names.

\indexlibrarymember{pointer}{pointer_traits}%

\begin{itemdecl}

using pointer = @\seebelow@;

\end{itemdecl}

\begin{itemdescr}

\pnum

\ctype \tcode{Ptr}.

\end{itemdescr}

\indexlibrarymember{element_type}{pointer_traits}%

\begin{itemdecl}

using element_type = @\seebelow@;

\end{itemdecl}

\begin{itemdescr}

\pnum

\ctype \tcode{typename \exposid{ptr-traits-elem}<Ptr>::type}.

\end{itemdescr}

\indexlibrarymember{difference_type}{pointer_traits}%

\begin{itemdecl}

using difference_type = @\seebelow@;

\end{itemdecl}

\begin{itemdescr}

\pnum

\ctype \tcode{Ptr::difference_type} if

the \grammarterm{qualified-id} \tcode{Ptr::difference_type} is valid and denotes a

type\iref{temp.deduct}; otherwise,

\tcode{ptrdiff_t}.

\end{itemdescr}

\indexlibrarymember{rebind}{pointer_traits}%

\begin{itemdecl}

template<class U> using rebind = @\seebelow@;

\end{itemdecl}

\begin{itemdescr}

\pnum

\templalias \tcode{Ptr::rebind<U>} if

the \grammarterm{qualified-id} \tcode{Ptr::rebind<U>} is valid and denotes a

type\iref{temp.deduct}; otherwise,

\tcode{SomePointer<U, Args>} if

\tcode{Ptr} is a class template specialization of the form \tcode{SomePointer<T, Args>},

where \tcode{Args} is zero or more type arguments; otherwise, the instantiation of

\tcode{rebind} is ill-formed.

\end{itemdescr}

\rSec3[pointer.traits.functions]{Member functions}

\indexlibrarymember{pointer_to}{pointer_traits}%

\begin{itemdecl}

static constexpr pointer pointer_traits::pointer_to(@\seebelow@ r);

static constexpr pointer pointer_traits<T*>::pointer_to(@\seebelow@ r) noexcept;

\end{itemdecl}

\begin{itemdescr}

\pnum

\mandates

For the first member function,

\tcode{Ptr::pointer_to(r)} is well-formed.

\pnum

\expects

For the first member function,

\tcode{Ptr::pointer_to(r)} returns a pointer to \tcode{r}

through which indirection is valid.

\pnum

\returns

The first member function returns \tcode{Ptr::pointer_to(r)}.

The second member function returns \tcode{addressof(r)}.

\pnum

\remarks

If \tcode{element_type} is \cv{}~\keyword{void}, the type of

\tcode{r} is unspecified; otherwise, it is \tcode{element_type\&}.

\end{itemdescr}

\rSec3[pointer.traits.optmem]{Optional members}

\pnum

Specializations of \tcode{pointer_traits} may define the member declared

in this subclause to customize the behavior of the standard library.

A specialization generated from the \tcode{pointer_traits} primary template

has no member by this name.

\indexlibrarymember{to_address}{pointer_traits}%

\begin{itemdecl}

static element_type* to_address(pointer p) noexcept;

\end{itemdecl}

\begin{itemdescr}

\pnum

\returns

A pointer of type \tcode{element_type*} that references

the same location as the argument \tcode{p}.

\pnum

\begin{note}

This function is intended to be the inverse of \tcode{pointer_to}.

If defined, it customizes the behavior of

the non-member function

\tcode{to_address}\iref{pointer.conversion}.

\end{note}

\end{itemdescr}

\rSec2[pointer.conversion]{Pointer conversion}

\indexlibraryglobal{to_address}%

\begin{itemdecl}

template<class T> constexpr T* to_address(T* p) noexcept;

\end{itemdecl}

\begin{itemdescr}

\pnum

\mandates

\tcode{T} is not a function type.

\pnum

\returns

\tcode{p}.

\end{itemdescr}

\indexlibraryglobal{to_address}%

\begin{itemdecl}

template<class Ptr> constexpr auto to_address(const Ptr& p) noexcept;

\end{itemdecl}

\begin{itemdescr}

\pnum

\returns

\tcode{pointer_traits<Ptr>::to_address(p)} if that expression is well-formed

(see \ref{pointer.traits.optmem}),

otherwise \tcode{to_address(p.operator->())}.

\end{itemdescr}

\rSec2[ptr.align]{Pointer alignment}

\indexlibraryglobal{align}%

\begin{itemdecl}

void* align(size_t alignment, size_t size, void*& ptr, size_t& space);

\end{itemdecl}

\begin{itemdescr}

\pnum

\expects

\begin{itemize}

\item

\tcode{alignment} is a power of two

\item

\tcode{ptr} represents the address of contiguous storage of at least

\tcode{space} bytes

\end{itemize}

\pnum

\effects

If it is possible to fit \tcode{size} bytes

of storage aligned by \tcode{alignment} into the buffer pointed to by

\tcode{ptr} with length \tcode{space}, the function updates

\tcode{ptr} to represent the first possible address of such storage

and decreases \tcode{space} by the number of bytes used for alignment.

Otherwise, the function does nothing.

\pnum

\returns

A null pointer if the requested aligned buffer

would not fit into the available space, otherwise the adjusted value

of \tcode{ptr}.

\pnum

\begin{note}

The function updates its \tcode{ptr}

and \tcode{space} arguments so that it can be called repeatedly

with possibly different \tcode{alignment} and \tcode{size}

arguments for the same buffer.

\end{note}

\end{itemdescr}

\indexlibraryglobal{assume_aligned}%

\begin{itemdecl}

template<size_t N, class T>

constexpr T* assume_aligned(T* ptr);

\end{itemdecl}

\begin{itemdescr}

\pnum

\mandates

\tcode{N} is a power of two.

\pnum

\expects

\tcode{ptr} points to an object $X$ of

a type similar\iref{conv.qual} to \tcode{T},

where $X$ has alignment \tcode{N}\iref{basic.align}.