20 General utilities library [utilities]

20.8 Storage for any type [any]

20.8.3 Class any [any.class]

namespace std {
  class any {
  public:
    // [any.cons], construction and destruction
    constexpr any() noexcept;

    any(const any& other);
    any(any&& other) noexcept;

    template<class T>
      any(T&& value);

    template<class T, class... Args>
      explicit any(in_place_type_t<T>, Args&&...);
    template<class T, class U, class... Args>
      explicit any(in_place_type_t<T>, initializer_list<U>, Args&&...);

    ~any();

    // [any.assign], assignments
    any& operator=(const any& rhs);
    any& operator=(any&& rhs) noexcept;

    template<class T>
      any& operator=(T&& rhs);

    // [any.modifiers], modifiers
    template<class T, class... Args>
      decay_t<T>& emplace(Args&&...);
    template<class T, class U, class... Args>
      decay_t<T>& emplace(initializer_list<U>, Args&&...);
    void reset() noexcept;
    void swap(any& rhs) noexcept;

    // [any.observers], observers
    bool has_value() const noexcept;
    const type_info& type() const noexcept;
  };
}
1
#
An object of class any stores an instance of any type that meets the constructor requirements or it has no value, and this is referred to as the state of the class any object.
The stored instance is called the contained value.
Two states are equivalent if either they both have no value, or they both have a value and the contained values are equivalent.
2
#
The non-member any_­cast functions provide type-safe access to the contained value.
3
#
Implementations should avoid the use of dynamically allocated memory for a small contained value.
However, any such small-object optimization shall only be applied to types T for which is_­nothrow_­move_­constructible_­v<T> is true.
[Example
:
A contained value of type int could be stored in an internal buffer, not in separately-allocated memory.
— end example
]

20.8.3.1 Construction and destruction [any.cons]

🔗
constexpr any() noexcept;
1
#
Postconditions: has_­value() is false.
🔗
any(const any& other);
2
#
Effects: If other.has_­value() is false, constructs an object that has no value.
Otherwise, equivalent to any(in_­place_­type<T>, any_­cast<const T&>(other)) where T is the type of the contained value.
3
#
Throws: Any exceptions arising from calling the selected constructor for the contained value.
🔗
any(any&& other) noexcept;
4
#
Effects: If other.has_­value() is false, constructs an object that has no value.
Otherwise, constructs an object of type any that contains either the contained value of other, or contains an object of the same type constructed from the contained value of other considering that contained value as an rvalue.
🔗
template<class T> any(T&& value);
5
#
Let VT be decay_­t<T>.
6
#
Constraints: VT is not the same type as any, VT is not a specialization of in_­place_­type_­t, and is_­copy_­constructible_­v<VT> is true.
7
#
Preconditions: VT meets the Cpp17CopyConstructible requirements.
8
#
Effects: Constructs an object of type any that contains an object of type VT direct-initialized with std​::​forward<T>(value).
9
#
Throws: Any exception thrown by the selected constructor of VT.
🔗
template<class T, class... Args> explicit any(in_place_type_t<T>, Args&&... args);
10
#
Let VT be decay_­t<T>.
11
#
Constraints: is_­copy_­constructible_­v<VT> is true and is_­constructible_­v<VT, Args...> is true.
12
#
Preconditions: VT meets the Cpp17CopyConstructible requirements.
13
#
Effects: Initializes the contained value as if direct-non-list-initializing an object of type VT with the arguments std​::​forward<Args>(args)....
14
#
Postconditions: *this contains a value of type VT.
15
#
Throws: Any exception thrown by the selected constructor of VT.
🔗
template<class T, class U, class... Args> explicit any(in_place_type_t<T>, initializer_list<U> il, Args&&... args);
16
#
Let VT be decay_­t<T>.
17
#
Constraints: is_­copy_­constructible_­v<VT> is true and is_­constructible_­v<VT, initializer_­list<U>&, Args...> is true.
18
#
Preconditions: VT meets the Cpp17CopyConstructible requirements.
19
#
Effects: Initializes the contained value as if direct-non-list-initializing an object of type VT with the arguments il, std​::​forward<Args>(args)....
20
#
Postconditions: *this contains a value.
21
#
Throws: Any exception thrown by the selected constructor of VT.
🔗
~any();
22
#
Effects: As if by reset().

20.8.3.2 Assignment [any.assign]

🔗
any& operator=(const any& rhs);
1
#
Effects: As if by any(rhs).swap(*this).
No effects if an exception is thrown.
2
#
Returns: *this.
3
#
Throws: Any exceptions arising from the copy constructor for the contained value.
🔗
any& operator=(any&& rhs) noexcept;
4
#
Effects: As if by any(std​::​move(rhs)).swap(*this).
5
#
Returns: *this.
6
#
Postconditions: The state of *this is equivalent to the original state of rhs.
🔗
template<class T> any& operator=(T&& rhs);
7
#
Let VT be decay_­t<T>.
8
#
Constraints: VT is not the same type as any and is_­copy_­constructible_­v<VT> is true.
9
#
Preconditions: VT meets the Cpp17CopyConstructible requirements.
10
#
Effects: Constructs an object tmp of type any that contains an object of type VT direct-initialized with std​::​forward<T>(rhs), and tmp.swap(*this).
No effects if an exception is thrown.
11
#
Returns: *this.
12
#
Throws: Any exception thrown by the selected constructor of VT.

20.8.3.3 Modifiers [any.modifiers]

🔗
template<class T, class... Args> decay_t<T>& emplace(Args&&... args);
1
#
Let VT be decay_­t<T>.
2
#
Constraints: is_­copy_­constructible_­v<VT> is true and is_­constructible_­v<VT, Args...> is true.
3
#
Preconditions: VT meets the Cpp17CopyConstructible requirements.
4
#
Effects: Calls reset().
Then initializes the contained value as if direct-non-list-initializing an object of type VT with the arguments std​::​forward<Args>(args)....
5
#
Postconditions: *this contains a value.
6
#
Returns: A reference to the new contained value.
7
#
Throws: Any exception thrown by the selected constructor of VT.
8
#
Remarks: If an exception is thrown during the call to VT's constructor, *this does not contain a value, and any previously contained value has been destroyed.
🔗
template<class T, class U, class... Args> decay_t<T>& emplace(initializer_list<U> il, Args&&... args);
9
#
Let VT be decay_­t<T>.
10
#
Constraints: is_­copy_­constructible_­v<VT> is true and is_­constructible_­v<VT, initializer_­list<U>&, Args...> is true.
11
#
Preconditions: VT meets the Cpp17CopyConstructible requirements.
12
#
Effects: Calls reset().
Then initializes the contained value as if direct-non-list-initializing an object of type VT with the arguments il, std​::​forward<Args>(args)....
13
#
Postconditions: *this contains a value.
14
#
Returns: A reference to the new contained value.
15
#
Throws: Any exception thrown by the selected constructor of VT.
16
#
Remarks: If an exception is thrown during the call to VT's constructor, *this does not contain a value, and any previously contained value has been destroyed.
🔗
void reset() noexcept;
17
#
Effects: If has_­value() is true, destroys the contained value.
18
#
Postconditions: has_­value() is false.
🔗
void swap(any& rhs) noexcept;
19
#
Effects: Exchanges the states of *this and rhs.

20.8.3.4 Observers [any.observers]

🔗
bool has_value() const noexcept;
1
#
Returns: true if *this contains an object, otherwise false.
🔗
const type_info& type() const noexcept;
2
#
Returns: typeid(T) if *this has a contained value of type T, otherwise typeid(void).
3
#
[Note
:
Useful for querying against types known either at compile time or only at runtime.
— end note
]