30 KiB
[indirect]
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 isvalueless 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::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 callingallocator_traits::construct(a, p, args...) whereargs is an expression pack,a is an allocator, andp is a pointer obtained by calling allocator_traits::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]):
allocator_traits::propagate_on_container_copy_assignment::value, or
allocator_traits::propagate_on_container_move_assignment::value, or
allocator_traits::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>class indirect {public:using value_type = T; using allocator_type = Allocator; using pointer = typename allocator_traits::pointer; using const_pointer = typename allocator_traits::const_pointer; // [indirect.ctor], constructorsconstexpr 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); templateconstexpr explicit indirect(U&& u); templateconstexpr 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], destructorconstexpr ~indirect(); // [indirect.assign], assignmentconstexpr indirect& operator=(const indirect& other); constexpr indirect& operator=(indirect&& other) noexcept(see below); templateconstexpr indirect& operator=(U&& u); // [indirect.obs], observersconstexpr 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], swapconstexpr void swap(indirect& other) noexcept(see below); friend constexpr void swap(indirect& lhs, indirect& rhs) noexcept(see below); // [indirect.relops], relational operatorstemplate<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 Ttemplatefriend constexpr bool operator==(const indirect& lhs, const U& rhs) noexcept(see below); templatefriend 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 indirect(Value) -> indirect; template<class Allocator, class Value> indirect(allocator_arg_t, Allocator, Value)-> indirect<Value, typename allocator_traits::template rebind_alloc>;}
20.4.1.3 Constructors [indirect.ctor]
The following element applies to all functions in [indirect.ctor]:
Throws: Nothing unless allocator_traits::allocate orallocator_traits::construct throws.
constexpr explicit indirect();
Constraints: is_default_constructible_v is true.
Mandates: is_default_constructible_v 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 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 is true.
Effects: alloc is direct-non-list-initialized withallocator_traits::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 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 fromstd::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::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:
is_same_v<remove_cvref_t, indirect> is false,
is_same_v<remove_cvref_t, in_place_t> is false,
is_constructible_v<T, U> is true, and
is_default_constructible_v 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:
is_same_v<remove_cvref_t, indirect> is false,
is_same_v<remove_cvref_t, in_place_t> is false, and
is_constructible_v<T, U> is true.
Effects: alloc is direct-non-list-initialized with a.
Constructs an owned object of type T withstd::forward(u), using the allocator alloc.
template<class... Us> constexpr explicit indirect(in_place_t, Us&&... us);
Constraints:
is_constructible_v<T, Us...> is true, and
is_default_constructible_v is true.
Effects: Constructs an owned object of type T withstd::forward(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 withstd::forward(us)..., using the allocator alloc.
template<class I, class... Us> constexpr explicit indirect(in_place_t, initializer_list<I> ilist, Us&&... us);
Constraints:
is_constructible_v<T, initializer_list&, Us...> is true, and
is_default_constructible_v is true.
Effects: Constructs an owned object of type T with the argumentsilist, std::forward(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 argumentsilist, std::forward(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::destroy and then the storage is deallocated.
20.4.1.5 Assignment [indirect.assign]
constexpr indirect& operator=(const indirect& other);
Mandates:
is_copy_assignable_v is true, and
is_copy_constructible_v is true.
Effects: If addressof(other) == this is true, there are no effects.
Otherwise:
-
The allocator needs updating ifallocator_traits::propagate_on_container_copy_assignment::value is true.
-
If other is valueless,*this becomes valueless and the owned object in *this, if any, is destroyed using allocator_traits::destroy and then the storage is deallocated.
-
Otherwise, if alloc == other.alloc is true and*this is not valueless, equivalent to **this = *other.
-
Otherwise a new owned object is constructed in *this using allocator_traits::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. -
The previously owned object in *this, if any, is destroyed using allocator_traits::
destroy and then the storage is deallocated. -
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 owned object is as defined by the exception safety guarantee ofT'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 is true.
Effects: If addressof(other) == this is true, there are no effects.
Otherwise:
-
The allocator needs updating ifallocator_traits::propagate_on_container_move_assignment::value is true.
-
If other is valueless,*this becomes valueless and the owned object in *this, if any, is destroyed using allocator_traits::destroy and then the storage is deallocated.
-
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::destroy and then the storage is deallocated.
-
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.
-
The previously owned object in *this, if any, is destroyed using allocator_traits::
destroy and then the storage is deallocated. -
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:
is_same_v<remove_cvref_t, indirect> is false,
is_constructible_v<T, U> is true, and
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: Ifallocator_traits::propagate_on_container_swap::value is true, thenAllocator 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::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(); otherwisesynth-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 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()(*i), if i is not valueless; otherwise to animplementation-defined value.
The member functions are not guaranteed to be noexcept.