[any] - C++14 → C++17

Files changed (1) hide show

tmp/tmpi5jlgddj/{from.md → to.md} +453 -0

tmp/tmpi5jlgddj/{from.md → to.md} RENAMED Viewed

	@@ -0,0 +1,453 @@

+## Storage for any type <a id="any">[[any]]</a>
+This section describes components that C++programs may use to perform
+operations on objects of a discriminated type.
+[*Note 1*: 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*]
+### Header `<any>` synopsis <a id="any.synop">[[any.synop]]</a>
+``` cpp
+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;
+}
+```
+### Class `bad_any_cast` <a id="any.bad_any_cast">[[any.bad_any_cast]]</a>
+``` cpp
+class bad_any_cast : public bad_cast {
+public:
+  const char* what() const noexcept override;
+};
+```
+Objects of type `bad_any_cast` are thrown by a failed `any_cast` (
+[[any.nonmembers]]).
+``` cpp
+const char* what() const noexcept override;
+```
+*Returns:* An *implementation-defined* NTBS.
+*Remarks:* The message may be a null-terminated multibyte
+string ([[multibyte.strings]]), suitable for conversion and display as
+a wstring ([[string.classes]], [[locale.codecvt]]).
+### Class `any` <a id="any.class">[[any.class]]</a>
+``` cpp
+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;
+};
+```
+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.
+The non-member `any_cast` functions provide type-safe access to the
+contained value.
+Implementations should avoid the use of dynamically allocated memory for
+a small contained value.
+[*Example 1*: 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`.
+#### Construction and destruction <a id="any.cons">[[any.cons]]</a>
+``` cpp
+constexpr any() noexcept;
+```
+*Postconditions:* `has_value()` is `false`.
+``` cpp
+any(const any& other);
+```
+*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.
+*Throws:* Any exceptions arising from calling the selected constructor
+for the contained value.
+``` cpp
+any(any&& other) noexcept;
+```
+*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.
+*Postconditions:* `other` is left in a valid but otherwise unspecified
+state.
+``` cpp
+template<class T>
+  any(T&& value);
+```
+Let `VT` be `decay_t<T>`.
+*Requires:* `VT` shall satisfy the `CopyConstructible` requirements.
+*Effects:* Constructs an object of type `any` that contains an object of
+type `VT` direct-initialized with `std::forward<T>(value)`.
+*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`.
+*Throws:* Any exception thrown by the selected constructor of `VT`.
+``` cpp
+template <class T, class... Args>
+  explicit any(in_place_type_t<T>, Args&&... args);
+```
+Let `VT` be `decay_t<T>`.
+*Requires:* `VT` shall satisfy the `CopyConstructible` requirements.
+*Effects:* Initializes the contained value as if
+direct-non-list-initializing an object of type `VT` with the arguments
+`std::forward<Args>(args)...`.
+*Postconditions:* `*this` contains a value of type `VT`.
+*Throws:* Any exception thrown by the selected constructor of `VT`.
+*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`.
+``` cpp
+template <class T, class U, class... Args>
+  explicit any(in_place_type_t<T>, initializer_list<U> il, Args&&... args);
+```
+Let `VT` be `decay_t<T>`.
+*Requires:* `VT` shall satisfy the `CopyConstructible` requirements.
+*Effects:* Initializes the contained value as if
+direct-non-list-initializing an object of type `VT` with the arguments
+`il, std::forward<Args>(args)...`.
+*Postconditions:* `*this` contains a value.
+*Throws:* Any exception thrown by the selected constructor of `VT`.
+*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`.
+``` cpp
+~any();
+```
+*Effects:* As if by `reset()`.
+#### Assignment <a id="any.assign">[[any.assign]]</a>
+``` cpp
+any& operator=(const any& rhs);
+```
+*Effects:* As if by `any(rhs).swap(*this)`. No effects if an exception
+is thrown.
+*Returns:* `*this`.
+*Throws:* Any exceptions arising from the copy constructor for the
+contained value.
+``` cpp
+any& operator=(any&& rhs) noexcept;
+```
+*Effects:* As if by `any(std::move(rhs)).swap(*this)`.
+*Returns:* `*this`.
+*Postconditions:* The state of `*this` is equivalent to the original
+state of `rhs` and `rhs` is left in a valid but otherwise unspecified
+state.
+``` cpp
+template<class T>
+  any& operator=(T&& rhs);
+```
+Let `VT` be `decay_t<T>`.
+*Requires:* `VT` shall satisfy the `CopyConstructible` requirements.
+*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.
+*Returns:* `*this`.
+*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`.
+*Throws:* Any exception thrown by the selected constructor of `VT`.
+#### Modifiers <a id="any.modifiers">[[any.modifiers]]</a>
+``` cpp
+template <class T, class... Args>
+  decay_t<T>& emplace(Args&&... args);
+```
+Let `VT` be `decay_t<T>`.
+*Requires:* `VT` shall satisfy the `CopyConstructible` requirements.
+*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)...`.
+*Postconditions:* `*this` contains a value.
+*Returns:* A reference to the new contained value.
+*Throws:* Any exception thrown by the selected constructor of `VT`.
+*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`.
+``` cpp
+template <class T, class U, class... Args>
+  decay_t<T>& emplace(initializer_list<U> il, Args&&... args);
+```
+Let `VT` be `decay_t<T>`.
+*Requires:* `VT` shall satisfy the `CopyConstructible` requirements.
+*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)...`.
+*Postconditions:* `*this` contains a value.
+*Returns:* A reference to the new contained value.
+*Throws:* Any exception thrown by the selected constructor of `VT`.
+*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`.
+``` cpp
+void reset() noexcept;
+```
+*Effects:* If `has_value()` is `true`, destroys the contained value.
+*Postconditions:* `has_value()` is `false`.
+``` cpp
+void swap(any& rhs) noexcept;
+```
+*Effects:* Exchanges the states of `*this` and `rhs`.
+#### Observers <a id="any.observers">[[any.observers]]</a>
+``` cpp
+bool has_value() const noexcept;
+```
+*Returns:* `true` if `*this` contains an object, otherwise `false`.
+``` cpp
+const type_info& type() const noexcept;
+```
+*Returns:* `typeid(T)` if `*this` has a contained value of type `T`,
+otherwise `typeid(void)`.
+[*Note 1*: Useful for querying against types known either at compile
+time or only at runtime. — *end note*]
+### Non-member functions <a id="any.nonmembers">[[any.nonmembers]]</a>
+``` cpp
+void swap(any& x, any& y) noexcept;
+```
+*Effects:* As if by `x.swap(y)`.
+``` cpp
+template <class T, class... Args>
+  any make_any(Args&& ...args);
+```
+*Effects:* Equivalent to:
+`return any(in_place_type<T>, std::forward<Args>(args)...);`
+``` cpp
+template <class T, class U, class... Args>
+  any make_any(initializer_list<U> il, Args&& ...args);
+```
+*Effects:* Equivalent to:
+`return any(in_place_type<T>, il, std::forward<Args>(args)...);`
+``` cpp
+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);
+```
+Let `U` be the type `remove_cv_t<remove_reference_t<ValueType>>`.
+*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.
+*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)))`.
+*Throws:* `bad_any_cast` if
+`operand.type() != typeid(remove_reference_t<T>)`.
+[*Example 1*:
+``` cpp
+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*]
+``` cpp
+template<class T>
+  const T* any_cast(const any* operand) noexcept;
+template<class T>
+  T* any_cast(any* operand) noexcept;
+```
+*Returns:* If `operand != nullptr && operand->type() == typeid(T)`, a
+pointer to the object contained by `operand`; otherwise, `nullptr`.
+[*Example 2*:
+``` cpp
+bool is_string(const any& operand) {
+  return any_cast<string>(&operand) != nullptr;
+}
+```
+— *end example*]

Diff to HTML by rtfpessoa