23 General utilities library [utilities]

23.8 Storage for any type [any]

1
#
This section describes components that C++ programs may use to perform operations on objects of a discriminated type.
2
#
[ Note
:
The discriminated type may contain values of different types but does not attempt conversion between them, i.e. 5 is held strictly as an int and is not implicitly convertible either to "5" or to 5.0.
This indifference to interpretation but awareness of type effectively allows safe, generic containers of single values, with no scope for surprises from ambiguous conversions.
— end note
 ]

23.8.1 Header <any> synopsis [any.synop]

namespace std {
  // [any.bad_any_cast], class bad_­any_­cast
  class bad_any_cast;

  // [any.class], class any
  class any;

  // [any.nonmembers], non-member functions
  void swap(any& x, any& y) noexcept;

  template <class T, class... Args>
    any make_any(Args&& ...args);
  template <class T, class U, class... Args>
    any make_any(initializer_list<U> il, Args&& ...args);

  template<class T>
    T any_cast(const any& operand);
  template<class T>
    T any_cast(any& operand);
  template<class T>
    T any_cast(any&& operand);

  template<class T>
    const T* any_cast(const any* operand) noexcept;
  template<class T>
    T* any_cast(any* operand) noexcept;
}

23.8.2 Class bad_­any_­cast [any.bad_any_cast]

class bad_any_cast : public bad_cast {
public:
  const char* what() const noexcept override;
};
1
#
Objects of type bad_­any_­cast are thrown by a failed any_­cast ([any.nonmembers]).
const char* what() const noexcept override;
2
#
Returns: An implementation-defined ntbs.
3
#
Remarks: The message may be a null-terminated multibyte string ([multibyte.strings]), suitable for conversion and display as a wstring ([string.classes], [locale.codecvt]).

23.8.3 Class any [any.class]

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 satisfies 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 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.
[ Example
:
where the object constructed is holding only an int.
— end example
 ]
Such small-object optimization shall only be applied to types T for which is_­nothrow_­move_­constructible_­v<T> is true.

23.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<T>, any_­cast<const T&>(other)) where T is the type of the contained object.
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 object of other, or contains an object of the same type constructed from the contained object of other considering that contained object as an rvalue.
5
#
Postconditions: other is left in a valid but otherwise unspecified state.
template<class T> any(T&& value);
6
#
Let VT be decay_­t<T>.
7
#
Requires: VT shall satisfy the CopyConstructible requirements.
8
#
Effects: Constructs an object of type any that contains an object of type VT direct-initialized with std​::​forward<T>(value).
9
#
Remarks: This constructor shall not participate in overload resolution unless 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.
10
#
Throws: Any exception thrown by the selected constructor of VT.
template <class T, class... Args> explicit any(in_place_type_t<T>, Args&&... args);
11
#
Let VT be decay_­t<T>.
12
#
Requires: VT shall satisfy the CopyConstructible 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.
16
#
Remarks: This constructor shall not participate in overload resolution unless is_­copy_­constructible_­v<VT> is true and is_­constructible_­v<VT, Args...> is true.
template <class T, class U, class... Args> explicit any(in_place_type_t<T>, initializer_list<U> il, Args&&... args);
17
#
Let VT be decay_­t<T>.
18
#
Requires: VT shall satisfy the CopyConstructible 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.
22
#
Remarks: This constructor shall not participate in overload resolution unless is_­copy_­constructible_­v<VT> is true and is_­constructible_­v<VT, initializer_­list<U>&, Args...> is true.
~any();
23
#
Effects: As if by reset().

23.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 and rhs is left in a valid but otherwise unspecified state.
template<class T> any& operator=(T&& rhs);
7
#
Let VT be decay_­t<T>.
8
#
Requires: VT shall satisfy the CopyConstructible requirements.
9
#
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.
10
#
Returns: *this.
11
#
Remarks: This operator shall not participate in overload resolution unless VT is not the same type as any and is_­copy_­constructible_­v<VT> is true.
12
#
Throws: Any exception thrown by the selected constructor of VT.

23.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
#
Requires: VT shall satisfy the CopyConstructible requirements.
3
#
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)....
4
#
Postconditions: *this contains a value.
5
#
Returns: A reference to the new contained value.
6
#
Throws: Any exception thrown by the selected constructor of VT.
7
#
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.
This function shall not participate in overload resolution unless is_­copy_­constructible_­v<VT> is true and is_­constructible_­v<VT, Args...> is true.
template <class T, class U, class... Args> decay_t<T>& emplace(initializer_list<U> il, Args&&... args);
8
#
Let VT be decay_­t<T>.
9
#
Requires: VT shall satisfy the CopyConstructible requirements.
10
#
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)....
11
#
Postconditions: *this contains a value.
12
#
Returns: A reference to the new contained value.
13
#
Throws: Any exception thrown by the selected constructor of VT.
14
#
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.
The function shall not participate in overload resolution unless is_­copy_­constructible_­v<VT> is true and is_­constructible_­v<VT, initializer_­list<U>&, Args...> is true.
void reset() noexcept;
15
#
Effects: If has_­value() is true, destroys the contained value.
16
#
Postconditions: has_­value() is false.
void swap(any& rhs) noexcept;
17
#
Effects: Exchanges the states of *this and rhs.

23.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
 ]

23.8.4 Non-member functions [any.nonmembers]

void swap(any& x, any& y) noexcept;
1
#
Effects: As if by x.swap(y).
template <class T, class... Args> any make_any(Args&& ...args);
2
#
Effects: Equivalent to: return any(in_­place_­type<T>, std​::​forward<Args>(args)...);
template <class T, class U, class... Args> any make_any(initializer_list<U> il, Args&& ...args);
3
#
Effects: Equivalent to: return any(in_­place_­type<T>, il, std​::​forward<Args>(args)...);
template<class T> T any_cast(const any& operand); template<class T> T any_cast(any& operand); template<class T> T any_cast(any&& operand);
4
#
Let U be the type remove_­cv_­t<remove_­reference_­t<ValueType>>.
5
#
Requires: For the first overload, is_­constructible_­v<ValueType, const U&> is true.
For the second overload, is_­constructible_­v<ValueType, U&> is true.
For the third overload, is_­constructible_­v<ValueType, U> is true.
Otherwise the program is ill-formed.
6
#
Returns: For the first and second overload, static_­cast<ValueType>(*any_­cast<U>(&operand)).
For the third overload, static_­cast<ValueType>(std​::​move(*any_­cast<U>(&operand))).
7
#
Throws: bad_­any_­cast if operand.type() != typeid(remove_­reference_­t<T>).
8
#
[ Example
: 
any x(5);                                   // x holds int
assert(any_cast<int>(x) == 5);              // cast to value
any_cast<int&>(x) = 10;                     // cast to reference
assert(any_cast<int>(x) == 10);

x = "Meow";                                 // x holds const char*
assert(strcmp(any_cast<const char*>(x), "Meow") == 0);
any_cast<const char*&>(x) = "Harry";
assert(strcmp(any_cast<const char*>(x), "Harry") == 0);

x = string("Meow");                         // x holds string
string s, s2("Jane");
s = move(any_cast<string&>(x));             // move from any
assert(s == "Meow");
any_cast<string&>(x) = move(s2);            // move to any
assert(any_cast<const string&>(x) == "Jane");

string cat("Meow");
const any y(cat);                           // const y holds string
assert(any_cast<const string&>(y) == cat);

any_cast<string&>(y);                       // error; cannot
                                            // any_­cast away const
— end example
 ]
template<class T> const T* any_cast(const any* operand) noexcept; template<class T> T* any_cast(any* operand) noexcept;
9
#
Returns: If operand != nullptr && operand->type() == typeid(T), a pointer to the object contained by operand; otherwise, nullptr.
10
#
[ Example
: 
bool is_string(const any& operand) {
  return any_cast<string>(&operand) != nullptr;
}
— end example
 ]