\rSec0[mem]{Memory management library}

\rSec1[mem.general]{General}

This Clause describes components for memory management.

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.res} & Memory resources & \tcode{<memory_resource>} \\ \rowsep

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

\end{libsumtab}

\rSec1[memory]{Memory}

\rSec2[memory.general]{In general}

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}

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}.

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

\begin{itemize}

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

is valid and denotes a type,

otherwise, \tcode{T::element_type*}

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

is valid and denotes a type,

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

\end{itemize}

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

\begin{itemize}

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

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

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>

[[nodiscard]] constexpr T* assume_aligned(T* ptr); // freestanding

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

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 { // freestanding

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 allocation_result { // freestanding

Pointer ptr;

SizeType count;

};

// \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 S, class I>

concept @\exposconcept{nothrow-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 NoThrowForwardIterator>

void uninitialized_default_construct(NoThrowForwardIterator first, // freestanding

NoThrowForwardIterator last);

template<class ExecutionPolicy, class NoThrowForwardIterator>

void uninitialized_default_construct(ExecutionPolicy&& exec, // see \ref{algorithms.parallel.overloads}

NoThrowForwardIterator first,

NoThrowForwardIterator last);

template<class NoThrowForwardIterator, class Size>

NoThrowForwardIterator

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

template<class ExecutionPolicy, class NoThrowForwardIterator, class Size>

NoThrowForwardIterator

uninitialized_default_construct_n(ExecutionPolicy&& exec, // see \ref{algorithms.parallel.overloads}

NoThrowForwardIterator first, Size n);

namespace ranges {

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

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

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

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

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

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

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

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

I uninitialized_default_construct_n(I first, iter_difference_t<I> n); // freestanding

}

template<class NoThrowForwardIterator>

void uninitialized_value_construct(NoThrowForwardIterator first, // freestanding

NoThrowForwardIterator last);

template<class ExecutionPolicy, class NoThrowForwardIterator>

void uninitialized_value_construct(ExecutionPolicy&& exec, // see \ref{algorithms.parallel.overloads}

NoThrowForwardIterator first,

NoThrowForwardIterator last);

template<class NoThrowForwardIterator, class Size>

NoThrowForwardIterator

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

template<class ExecutionPolicy, class NoThrowForwardIterator, class Size>

NoThrowForwardIterator

uninitialized_value_construct_n(ExecutionPolicy&& exec, // see \ref{algorithms.parallel.overloads}

NoThrowForwardIterator first, Size n);

namespace ranges {

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

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

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

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

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

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

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

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

I uninitialized_value_construct_n(I first, iter_difference_t<I> n); // freestanding

}

template<class InputIterator, class NoThrowForwardIterator>

NoThrowForwardIterator uninitialized_copy(InputIterator first, // freestanding

InputIterator last,

NoThrowForwardIterator result);

template<class ExecutionPolicy, class ForwardIterator, class NoThrowForwardIterator>

NoThrowForwardIterator uninitialized_copy(ExecutionPolicy&& exec, // see \ref{algorithms.parallel.overloads}

ForwardIterator first, ForwardIterator last,

NoThrowForwardIterator result);

template<class InputIterator, class Size, class NoThrowForwardIterator>

NoThrowForwardIterator uninitialized_copy_n(InputIterator first, Size n, // freestanding

NoThrowForwardIterator result);

template<class ExecutionPolicy, class ForwardIterator, class Size,

class NoThrowForwardIterator>

NoThrowForwardIterator uninitialized_copy_n(ExecutionPolicy&& exec, // see \ref{algorithms.parallel.overloads}

ForwardIterator first, Size n,

NoThrowForwardIterator result);

namespace ranges {

template<class I, class O>

using 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>>

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>>

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 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>>

uninitialized_copy_n_result<I, O>

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

O ofirst, S olast);

}

template<class InputIterator, class NoThrowForwardIterator>

NoThrowForwardIterator uninitialized_move(InputIterator first, // freestanding

InputIterator last,

NoThrowForwardIterator result);

template<class ExecutionPolicy, class ForwardIterator, class NoThrowForwardIterator>

NoThrowForwardIterator uninitialized_move(ExecutionPolicy&& exec, // see \ref{algorithms.parallel.overloads}

ForwardIterator first, ForwardIterator last,

NoThrowForwardIterator result);

template<class InputIterator, class Size, class NoThrowForwardIterator>

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, // see \ref{algorithms.parallel.overloads}

ForwardIterator first, Size n, NoThrowForwardIterator result);

namespace ranges {

template<class I, class O>

using 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>>

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>>

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 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>>

uninitialized_move_n_result<I, O>

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

O ofirst, S olast);

}

template<class NoThrowForwardIterator, class T>

void uninitialized_fill(NoThrowForwardIterator first, // freestanding

NoThrowForwardIterator last, const T& x);

template<class ExecutionPolicy, class NoThrowForwardIterator, class T>

void uninitialized_fill(ExecutionPolicy&& exec, // see \ref{algorithms.parallel.overloads}

NoThrowForwardIterator first, NoThrowForwardIterator last,

const T& x);

template<class NoThrowForwardIterator, class Size, class T>

NoThrowForwardIterator

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

template<class ExecutionPolicy, class NoThrowForwardIterator, class Size, class T>

NoThrowForwardIterator

uninitialized_fill_n(ExecutionPolicy&& exec, // see \ref{algorithms.parallel.overloads}

NoThrowForwardIterator first, Size n, const T& x);

namespace ranges {

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

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

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

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

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

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

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

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

I uninitialized_fill_n(I first, iter_difference_t<I> n, const T& x); // freestanding

}

// \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, // see \ref{algorithms.parallel.overloads}

NoThrowForwardIterator first, 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, // see \ref{algorithms.parallel.overloads}

NoThrowForwardIterator first, Size n);

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

}

// \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>

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

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

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

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

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

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

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

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>

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>

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

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

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

template<class T>

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

template<class T, class A>

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

template<class T>

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

template<class T, class A>

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

template<class T>

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

template<class T, class A>

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>

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

template<class T, class A>

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

template<class T>

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

template<class T, class A>

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

template<class T>

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

template<class T, class A>

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>

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

template<class T, class U>

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

template<class T>

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

template<class T>

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

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

template<class T>

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>

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

template<class T, class U>

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

template<class T, class U>

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

template<class T, class U>

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

template<class T, class U>

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

template<class T, class U>

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>

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> 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;

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

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

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

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

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

class inout_ptr_t;

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

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

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

}

\end{codeblock}

\rSec2[pointer.traits]{Pointer traits}

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

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}

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 = typename 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}

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}

\ctype \tcode{Ptr}.

\end{itemdescr}

\indexlibrarymember{element_type}{pointer_traits}%

\begin{itemdecl}

using element_type = @\seebelow@;

\end{itemdecl}

\begin{itemdescr}

\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}

\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}

\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 instantiation 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 pointer pointer_traits::pointer_to(@\seebelow@ r);

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

\end{itemdecl}

\begin{itemdescr}

For the first member function,

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

For the first member function,

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

through which indirection is valid.

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

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

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}

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}

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

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

\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}

\tcode{T} is not a function type.

\tcode{p}.

\end{itemdescr}

\indexlibraryglobal{to_address}%

\begin{itemdecl}

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

\end{itemdecl}

\begin{itemdescr}

\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}

\begin{itemize}

\tcode{alignment} is a power of two

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

\tcode{space} bytes

\end{itemize}

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.

A null pointer if the requested aligned buffer

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

of \tcode{ptr}.

\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>

[[nodiscard]] constexpr T* assume_aligned(T* ptr);

\end{itemdecl}

\begin{itemdescr}

\tcode{N} is a power of two.

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

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

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

\tcode{ptr}.

Nothing.

\begin{note}

The alignment assumption on an object \tcode{X}

expressed by a call to \tcode{assume_aligned}

might result in generation of more efficient code.

It is up to the program to ensure that the assumption actually holds.

The call does not cause the implementation to verify or enforce this.

An implementation might only make the assumption

for those operations on \tcode{X} that access \tcode{X}

through the pointer returned by \tcode{assume_aligned}.

\end{note}

\end{itemdescr}

\rSec2[obj.lifetime]{Explicit lifetime management}

\indexlibraryglobal{start_lifetime_as}%

\begin{itemdecl}

template<class T>

T* start_lifetime_as(void* p) noexcept;

template<class T>

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

template<class T>

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

template<class T>

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

\end{itemdecl}

\begin{itemdescr}

\tcode{T} is an implicit-lifetime type\iref{basic.types.general}

and not an incomplete type\iref{term.incomplete.type}.

\range{p}{(char*)p + sizeof(T)} denotes a region of allocated storage

that is

a subset of the region of storage

reachable through\iref{basic.compound} \tcode{p} and

suitably aligned for the type \tcode{T}.

Implicitly creates objects\iref{intro.object} within the denoted region

consisting of an object \placeholder{a} of type \tcode{T}

whose address is \tcode{p}, and

objects nested within \placeholder{a},

as follows:

The object representation of \placeholder{a}

is the contents of the storage prior to the call to \tcode{start_lifetime_as}.

The value of each created object \placeholder{o}

of trivially-copyable type \tcode{U}

is determined in the same manner as for a call

to \tcode{bit_cast<U>(E)}\iref{bit.cast},

where \tcode{E} is an lvalue of type \tcode{U} denoting \placeholder{o},

except that the storage is not accessed.

The value of any other created object is unspecified.

\begin{note}

The unspecified value can be indeterminate.

\end{note}

A pointer to the \placeholder{a} defined in the \Fundescx{Effects} paragraph.

\end{itemdescr}

\indexlibraryglobal{start_lifetime_as_array}%

\begin{itemdecl}

template<class T>

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

template<class T>

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

template<class T>

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

template<class T>

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

\end{itemdecl}

\begin{itemdescr}

\tcode{T} is a complete type.

\tcode{p} is suitably aligned for an array of \tcode{T} or is null.

\tcode{n <= size_t(-1) / sizeof(T)} is \tcode{true}.

If \tcode{n > 0} is \tcode{true},

\range{(char*)p}{(char*)p + (n * sizeof(T))} denotes

a region of allocated storage that is

a subset of the region of storage

reachable through\iref{basic.compound} \tcode{p}.

If \tcode{n > 0} is \tcode{true},

equivalent to

\tcode{start_lifetime_as<U>(p)}

where \tcode{U} is the type ``array of \tcode{n} \tcode{T}''.

Otherwise, there are no effects.

A pointer to the first element of the created array,

if any;

otherwise,

a pointer that compares equal to \tcode{p}\iref{expr.eq}.

\end{itemdescr}

\rSec2[allocator.tag]{Allocator argument tag}

\indexlibraryglobal{allocator_arg_t}%

\indexlibraryglobal{allocator_arg}%

\begin{itemdecl}

namespace std {

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

inline constexpr allocator_arg_t allocator_arg{};

}

\end{itemdecl}

The \tcode{allocator_arg_t} struct is an empty class type used as a unique type to

disambiguate constructor and function overloading. Specifically, several types (see

\tcode{tuple}~\ref{tuple}) have constructors with \tcode{allocator_arg_t} as the first

argument, immediately followed by an argument of a type that meets the

\oldconcept{Allocator} requirements\iref{allocator.requirements.general}.

\rSec2[allocator.uses]{\tcode{uses_allocator}}

\rSec3[allocator.uses.trait]{\tcode{uses_allocator} trait}

\indexlibraryglobal{uses_allocator}%

\begin{itemdecl}

template<class T, class Alloc> struct uses_allocator;

\end{itemdecl}

\begin{itemdescr}

Automatically detects whether \tcode{T} has a nested \tcode{allocator_type} that

is convertible from \tcode{Alloc}. Meets the \oldconcept{BinaryTypeTrait}

requirements\iref{meta.rqmts}. The implementation shall provide a definition that is

derived from \tcode{true_type} if the \grammarterm{qualified-id} \tcode{T::allocator_type}

is valid and denotes a type\iref{temp.deduct} and