20 Memory management library [mem]

20.4 Types for composite class design [mem.composite.types]

20.4.1 Class template indirect [indirect]

20.4.1.1 General [indirect.general]

An indirect object manages the lifetime of an owned object.

An indirect object is valueless if it has no owned object.

An indirect object may become valueless only after it has been moved from.

In every specialization indirect<T, Allocator>, if the type allocator_traits<Allocator>::value_type is not the same type as T, the program is ill-formed.

Every object of type indirect<T, Allocator> uses an object of type Allocator to allocate and free storage for the owned object as needed.

Constructing an owned object with args... using the allocator a means calling allocator_traits<Allocator>::construct(a, p, args...) where args is an expression pack, a is an allocator, and p is a pointer obtained by calling allocator_traits<Allocator>::allocate.

The member alloc is used for any memory allocation and element construction performed by member functions during the lifetime of each indirect object.

The allocator alloc may be replaced only via assignment or swap().

Allocator replacement is performed by copy assignment, move assignment, or swapping of the allocator only if ([container.reqmts]):

(4.1)
allocator_traits<Allocator>::propagate_on_container_copy_assignment::value, or
(4.2)
allocator_traits<Allocator>::propagate_on_container_move_assignment::value, or
(4.3)
allocator_traits<Allocator>::propagate_on_container_swap::value

is true within the implementation of the corresponding indirect operation.

A program that instantiates the definition of the template indirect<T, Allocator> with a type for the T parameter that is a non-object type, an array type, in_place_t, a specialization of in_place_type_t, or a cv-qualified type is ill-formed.

The template parameter T of indirect may be an incomplete type.

The template parameter Allocator of indirect shall meet the Cpp17Allocator requirements.

If a program declares an explicit or partial specialization of indirect, the behavior is undefined.

20.4.1.2 Synopsis [indirect.syn]

🔗

namespace std { template<class T, class Allocator = allocator<T>> class indirect { public: using value_type = T; using allocator_type = Allocator; using pointer = typename allocator_traits<Allocator>::pointer; using const_pointer = typename allocator_traits<Allocator>::const_pointer; // [indirect.ctor], constructors constexpr explicit indirect(); constexpr explicit indirect(allocator_arg_t, const Allocator& a); constexpr indirect(const indirect& other); constexpr indirect(allocator_arg_t, const Allocator& a, const indirect& other); constexpr indirect(indirect&& other) noexcept; constexpr indirect(allocator_arg_t, const Allocator& a, indirect&& other) noexcept(see below); template<class U = T> constexpr explicit indirect(U&& u); template<class U = T> constexpr explicit indirect(allocator_arg_t, const Allocator& a, U&& u); template<class... Us> constexpr explicit indirect(in_place_t, Us&&... us); template<class... Us> constexpr explicit indirect(allocator_arg_t, const Allocator& a, in_place_t, Us&&... us); template<class I, class... Us> constexpr explicit indirect(in_place_t, initializer_list ilist, Us&&... us); template<class I, class... Us> constexpr explicit indirect(allocator_arg_t, const Allocator& a, in_place_t, initializer_list ilist, Us&&... us); // [indirect.dtor], destructor constexpr ~indirect(); // [indirect.asgn], assignment constexpr indirect& operator=(const indirect& other); constexpr indirect& operator=(indirect&& other) noexcept(see below); template<class U = T> constexpr indirect& operator=(U&& u); // [indirect.obs], observers constexpr const T& operator*() const & noexcept; constexpr T& operator*() & noexcept; constexpr const T&& operator*() const && noexcept; constexpr T&& operator*() && noexcept; constexpr const_pointer operator->() const noexcept; constexpr pointer operator->() noexcept; constexpr bool valueless_after_move() const noexcept; constexpr allocator_type get_allocator() const noexcept; // [indirect.swap], swap constexpr void swap(indirect& other) noexcept(see below); friend constexpr void swap(indirect& lhs, indirect& rhs) noexcept(see below); // [indirect.relops], relational operators template<class U, class AA> friend constexpr bool operator==(const indirect& lhs, const indirect<U, AA>& rhs) noexcept(see below); template<class U, class AA> friend constexpr auto operator<=>(const indirect& lhs, const indirect<U, AA>& rhs) -> synth-three-way-result<T, U>; // [indirect.comp.with.t], comparison with T template<class U> friend constexpr bool operator==(const indirect& lhs, const U& rhs) noexcept(see below); template<class U> friend constexpr auto operator<=>(const indirect& lhs, const U& rhs) -> synth-three-way-result<T, U>; private: pointer p; // exposition only Allocator alloc = Allocator(); // exposition only }; template<class Value> indirect(Value) -> indirect<Value>; template<class Allocator, class Value> indirect(allocator_arg_t, Allocator, Value) -> indirect<Value, typename allocator_traits<Allocator>::template rebind_alloc<Value>>; }

20.4.1.3 Constructors [indirect.ctor]

The following element applies to all functions in [indirect.ctor]:

Throws: Nothing unless allocator_traits<Allocator>::allocate or allocator_traits<Allocator>::construct throws.

🔗

constexpr explicit indirect();

Constraints: is_default_constructible_v<Allocator> is true.

Mandates: is_default_constructible_v<T> is true.

Effects: Constructs an owned object of type T with an empty argument list, using the allocator alloc.

🔗

constexpr explicit indirect(allocator_arg_t, const Allocator& a);

Mandates: is_default_constructible_v<T> is true.

Effects: alloc is direct-non-list-initialized with a.

Constructs an owned object of type T with an empty argument list, using the allocator alloc.

🔗

constexpr indirect(const indirect& other);

Mandates: is_copy_constructible_v<T> is true.

Effects: alloc is direct-non-list-initialized with allocator_traits<Allocator>::select_on_container_copy_construction(other.alloc).

If other is valueless, *this is valueless.

Otherwise, constructs an owned object of type T with *other, using the allocator alloc.

🔗

constexpr indirect(allocator_arg_t, const Allocator& a, const indirect& other);

Mandates: is_copy_constructible_v<T> is true.

Effects: alloc is direct-non-list-initialized with a.

If other is valueless, *this is valueless.

Otherwise, constructs an owned object of type T with *other, using the allocator alloc.

🔗

constexpr indirect(indirect&& other) noexcept;

Effects: alloc is direct-non-list-initialized from std::move(other.alloc).

If other is valueless, *this is valueless.

Otherwise *this takes ownership of the owned object of other.

Postconditions: other is valueless.

🔗

constexpr indirect(allocator_arg_t, const Allocator& a, indirect&& other)
  noexcept(allocator_traits<Allocator>::is_always_equal::value);

Mandates: If allocator_traits<Allocator>::is_always_equal::value is false then T is a complete type.

Effects: alloc is direct-non-list-initialized with a.

If other is valueless, *this is valueless.

Otherwise, if alloc == other.alloc is true, constructs an object of type indirect that takes ownership of the owned object of other.

Otherwise, constructs an owned object of type T with *std::move(other), using the allocator alloc.

Postconditions: other is valueless.

🔗

template<class U = T>
  constexpr explicit indirect(U&& u);

Constraints:

(17.1)
is_same_v<remove_cvref_t, indirect> is false,
(17.2)
is_same_v<remove_cvref_t, in_place_t> is false,
(17.3)
is_constructible_v<T, U> is true, and
(17.4)
is_default_constructible_v<Allocator> is true.

Effects: Constructs an owned object of type T with std::forward(u), using the allocator alloc.

🔗

template<class U = T>
  constexpr explicit indirect(allocator_arg_t, const Allocator& a, U&& u);

Constraints:

(19.1)
is_same_v<remove_cvref_t, indirect> is false,
(19.2)
is_same_v<remove_cvref_t, in_place_t> is false, and
(19.3)
is_constructible_v<T, U> is true.

Effects: alloc is direct-non-list-initialized with a.

Constructs an owned object of type T with std::forward(u), using the allocator alloc.

🔗

template<class... Us>
  constexpr explicit indirect(in_place_t, Us&&... us);

Constraints:

(21.1)
is_constructible_v<T, Us...> is true, and
(21.2)
is_default_constructible_v<Allocator> is true.

Effects: Constructs an owned object of type T with std::forward<Us>(us)..., using the allocator alloc.

🔗

template<class... Us>
  constexpr explicit indirect(allocator_arg_t, const Allocator& a,
                              in_place_t, Us&& ...us);

Constraints: is_constructible_v<T, Us...> is true.

Effects: alloc is direct-non-list-initialized with a.

Constructs an owned object of type T with std::forward<Us>(us)..., using the allocator alloc.

🔗

template<class I, class... Us>
  constexpr explicit indirect(in_place_t, initializer_list<I> ilist, Us&&... us);

Constraints:

(25.1)
is_constructible_v<T, initializer_list&, Us...> is true, and
(25.2)
is_default_constructible_v<Allocator> is true.

Effects: Constructs an owned object of type T with the arguments ilist, std::forward<Us>(us)..., using the allocator alloc.

🔗

template<class I, class... Us>
  constexpr explicit indirect(allocator_arg_t, const Allocator& a,
                              in_place_t, initializer_list<I> ilist, Us&&... us);

Constraints: is_constructible_v<T, initializer_list&, Us...> is true.

Effects: alloc is direct-non-list-initialized with a.

Constructs an owned object of type T with the arguments ilist, std::forward<Us>(us)..., using the allocator alloc.

20.4.1.4 Destructor [indirect.dtor]

🔗

constexpr ~indirect();

Mandates: T is a complete type.

Effects: If *this is not valueless, destroys the owned object using allocator_traits<Allocator>::destroy and then the storage is deallocated.

20.4.1.5 Assignment [indirect.asgn]

🔗

constexpr indirect& operator=(const indirect& other);

Mandates:

(1.1)
is_copy_assignable_v<T> is true, and
(1.2)
is_copy_constructible_v<T> is true.

Effects: If addressof(other) == this is true, there are no effects.

Otherwise:

(2.1)
The allocator needs updating if allocator_traits<Allocator>::propagate_on_container_copy_assignment::value is true.
(2.2)
If other is valueless, *this becomes valueless and the owned object in *this, if any, is destroyed using allocator_traits<Allocator>::destroy and then the storage is deallocated.
(2.3)
Otherwise, if alloc == other.alloc is true and *this is not valueless, equivalent to **this = *other.
(2.4)
Otherwise a new owned object is constructed in *this using allocator_traits<Allocator>::con
struct with the owned object from other as the argument, using either the allocator in *this or the allocator in other if the allocator needs updating.
(2.5)
The previously owned object in *this, if any, is destroyed using allocator_traits<Allocator>::
destroy and then the storage is deallocated.
(2.6)
If the allocator needs updating, the allocator in *this is replaced with a copy of the allocator in other.

Returns: A reference to *this.

Remarks: If any exception is thrown, the result of the expression this->valueless_after_move() remains unchanged.

If an exception is thrown during the call to T's selected copy constructor, no effect.

If an exception is thrown during the call to T's copy assignment, the state of its contained value is as defined by the exception safety guarantee of T's copy assignment.

🔗

constexpr indirect& operator=(indirect&& other)
  noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value ||
           allocator_traits<Allocator>::is_always_equal::value);

Mandates: is_copy_constructible_t<T> is true.

Effects: If addressof(other) == this is true, there are no effects.

Otherwise:

(6.1)
The allocator needs updating if allocator_traits<Allocator>::propagate_on_container_move_assignment::value is true.
(6.2)
If other is valueless, *this becomes valueless and the owned object in *this, if any, is destroyed using allocator_traits<Allocator>::destroy and then the storage is deallocated.
(6.3)
Otherwise, if alloc == other.alloc is true, swaps the owned objects in *this and other; the owned object in other, if any, is then destroyed using allocator_traits<Allocator>::destroy and then the storage is deallocated.
(6.4)
Otherwise, constructs a new owned object with the owned object of other as the argument as an rvalue, using either the allocator in *this or the allocator in other if the allocator needs updating.
(6.5)
The previously owned object in *this, if any, is destroyed using allocator_traits<Allocator>::
destroy and then the storage is deallocated.
(6.6)
If the allocator needs updating, the allocator in *this is replaced with a copy of the allocator in other.

Postconditions: other is valueless.

Returns: A reference to *this.

Remarks: If any exception is thrown, there are no effects on *this or other.

🔗

template<class U = T>
  constexpr indirect& operator=(U&& u);

Constraints:

(10.1)
is_same_v<remove_cvref_t, indirect> is false,
(10.2)
is_constructible_v<T, U> is true, and
(10.3)
is_assignable_v<T&, U> is true.

Effects: If *this is valueless then constructs an owned object of type T with std::forward(u) using the allocator alloc.

Otherwise, equivalent to **this = std::forward(u).

Returns: A reference to *this.

20.4.1.6 Observers [indirect.obs]

🔗

constexpr const T& operator*() const & noexcept;
constexpr T& operator*() & noexcept;

Preconditions: *this is not valueless.

Returns: *p.

🔗

constexpr const T&& operator*() const && noexcept;
constexpr T&& operator*() && noexcept;

Preconditions: *this is not valueless.

Returns: std::move(*p).

🔗

constexpr const_pointer operator->() const noexcept;
constexpr pointer operator->() noexcept;

Preconditions: *this is not valueless.

Returns: p.

🔗

constexpr bool valueless_after_move() const noexcept;

Returns: true if *this is valueless, otherwise false.

🔗

constexpr allocator_type get_allocator() const noexcept;

Returns: alloc.

20.4.1.7 Swap [indirect.swap]

🔗

constexpr void swap(indirect& other)
  noexcept(allocator_traits<Allocator>::propagate_on_container_swap::value ||
           allocator_traits<Allocator>::is_always_equal::value);

Preconditions: If allocator_traits<Allocator>::propagate_on_container_swap::value is true, then Allocator meets the Cpp17Swappable requirements.

Otherwise get_allocator() == other.
get_allocator() is true.

Effects: Swaps the states of *this and other, exchanging owned objects or valueless states.

If allocator_traits<Allocator>::propagate_on_container_swap::value is true, then the allocators of *this and other are exchanged by calling swap as described in [swappable.requirements].

Otherwise, the allocators are not swapped.

[Note 1:

Does not call swap on the owned objects directly.

— end note]

🔗

constexpr void swap(indirect& lhs, indirect& rhs) noexcept(noexcept(lhs.swap(rhs)));

Effects: Equivalent to lhs.swap(rhs).

20.4.1.8 Relational operators [indirect.relops]

🔗

template<class U, class AA>
  constexpr bool operator==(const indirect& lhs, const indirect<U, AA>& rhs)
    noexcept(noexcept(*lhs == *rhs));

Mandates: The expression *lhs == *rhs is well-formed and its result is convertible to bool.

Returns: If lhs is valueless or rhs is valueless, lhs.valueless_after_move() == rhs.valueless_after_move(); otherwise *lhs == *rhs.

🔗

template<class U, class AA>
  constexpr synth-three-way-result<T, U>
    operator<=>(const indirect& lhs, const indirect<U, AA>& rhs);

Returns: If lhs is valueless or rhs is valueless, !lhs.valueless_after_move() <=> !rhs.valueless_after_move(); otherwise synth-three-way(*lhs, *rhs).

20.4.1.9 Comparison with T [indirect.comp.with.t]

🔗

template<class U>
  constexpr bool operator==(const indirect& lhs, const U& rhs) noexcept(noexcept(*lhs == rhs));

Mandates: The expression *lhs == rhs is well-formed and its result is convertible to bool.

Returns: If lhs is valueless, false; otherwise *lhs == rhs.

🔗

template<class U>
  constexpr synth-three-way-result<T, U>
    operator<=>(const indirect& lhs, const U& rhs);

Returns: If lhs is valueless, strong_ordering::less; otherwise synth-three-way(*lhs, rhs).

20.4.1.10 Hash support [indirect.hash]

🔗

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

The specialization hash<indirect<T, Allocator>> is enabled ([unord.hash]) if and only if hash<T> is enabled.

When enabled for an object i of type indirect<T, Allocator>, hash<indirect<T, Allocator>>()(i) evaluates to either the same value as hash<T>()(*i), if i is not valueless; otherwise to an implementation-defined value.

The member functions are not guaranteed to be noexcept.