[support.exception] - C++14 → C++17

Files changed (1) hide show

tmp/tmpcgsxnulb/{from.md → to.md} +75 -63

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

@@ -1,29 +1,26 @@
 ## Exception handling <a id="support.exception">[[support.exception]]</a>
 The header `<exception>` defines several types and functions related to
 the handling of exceptions in a C++program.
 ``` cpp
 namespace std {
   class exception;
   class bad_exception;
   class nested_exception;
- typedef void (*unexpected_handler)();
-  unexpected_handler get_unexpected() noexcept;
-  unexpected_handler set_unexpected(unexpected_handler f) noexcept;
-  [[noreturn]] void unexpected();
-  typedef void (*terminate_handler)();
   terminate_handler get_terminate() noexcept;
   terminate_handler set_terminate(terminate_handler f) noexcept;
   [[noreturn]] void terminate() noexcept;
- bool uncaught_exception() noexcept;
- typedef unspecified exception_ptr;
   exception_ptr current_exception() noexcept;
   [[noreturn]] void rethrow_exception(exception_ptr p);
   template<class E> exception_ptr make_exception_ptr(E e) noexcept;
@@ -71,11 +68,12 @@ exception(const exception& rhs) noexcept;
 exception& operator=(const exception& rhs) noexcept;
 ```
 *Effects:* Copies an `exception` object.
-If `*this` and `rhs` both have dynamic type `exception` then
 `strcmp(what(), rhs.what())` shall equal 0.
 ``` cpp
 virtual ~exception();
 ```
@@ -102,36 +100,35 @@ namespace std {
   class bad_exception : public exception {
   public:
     bad_exception() noexcept;
     bad_exception(const bad_exception&) noexcept;
     bad_exception& operator=(const bad_exception&) noexcept;
- virtual const char* what() const noexcept;
   };
 }
 ```
-The class `bad_exception` defines the type of objects thrown as
-described in ([[except.unexpected]]).
 ``` cpp
 bad_exception() noexcept;
 ```
 *Effects:* Constructs an object of class `bad_exception`.
-*Remarks:* The result of calling `what()` on the newly constructed
-object is implementation-defined.
 ``` cpp
 bad_exception(const bad_exception&) noexcept;
 bad_exception& operator=(const bad_exception&) noexcept;
 ```
 *Effects:* Copies an object of class `bad_exception`.
 ``` cpp
-virtual const char* what() const noexcept;
 ```
 *Returns:* An *implementation-defined* NTBS.
 *Remarks:* The message may be a null-terminated multibyte
@@ -141,11 +138,11 @@ a `wstring` ([[string.classes]], [[locale.codecvt]]).
 ### Abnormal termination <a id="exception.terminate">[[exception.terminate]]</a>
 #### Type `terminate_handler` <a id="terminate.handler">[[terminate.handler]]</a>
 ``` cpp
-typedef void (*terminate_handler)();
 ```
 The type of a *handler function* to be called by `std::terminate()` when
 terminating exception processing.
@@ -173,51 +170,51 @@ default `terminate_handler`.
 ``` cpp
 terminate_handler get_terminate() noexcept;
 ```
-*Returns:* The current `terminate_handler`. This may be a null pointer
-value.
 #### `terminate` <a id="terminate">[[terminate]]</a>
 ``` cpp
 [[noreturn]] void terminate() noexcept;
 ```
 *Remarks:* Called by the implementation when exception handling must be
-abandoned for any of several reasons ([[except.terminate]]), in effect
-immediately after throwing the exception. May also be called directly by
-the program.
-*Effects:* Calls the current `terminate_handler` function. A default
-`terminate_handler` is always considered a callable handler in this
-context.
-### `uncaught_exception` <a id="uncaught">[[uncaught]]</a>
 ``` cpp
-bool uncaught_exception() noexcept;
 ```
-*Returns:* `true` after the current thread has initialized an exception
-object ([[except.throw]]) until a handler for the exception (including
-`std::unexpected()` or `std::terminate()`) is
-activated ([[except.handle]]). This includes stack
-unwinding ([[except.ctor]]).
-*Remarks:* When `uncaught_exception()` returns `true`, throwing an
-exception can result in a call of
 `std::terminate()` ([[except.terminate]]).
 ### Exception propagation <a id="propagation">[[propagation]]</a>
 ``` cpp
-typedef unspecified exception_ptr;
 ```
-The type exception_ptr can be used to refer to an exception object.
 `exception_ptr` shall satisfy the requirements of
 `NullablePointer` ([[nullablepointer.requirements]]).
 Two non-null values of type `exception_ptr` are equivalent and compare
@@ -227,22 +224,24 @@ The default constructor of `exception_ptr` produces the null value of
 the type.
 `exception_ptr` shall not be implicitly convertible to any arithmetic,
 enumeration, or pointer type.
-An implementation might use a reference-counted smart pointer as
-`exception_ptr`.
 For purposes of determining the presence of a data race, operations on
 `exception_ptr` objects shall access and modify only the `exception_ptr`
 objects themselves and not the exceptions they refer to. Use of
 `rethrow_exception` on `exception_ptr` objects that refer to the same
-exception object shall not introduce a data race. if `rethrow_exception`
-rethrows the same exception object (rather than a copy), concurrent
-access to that rethrown exception object may introduce a data race.
-Changes in the number of `exception_ptr` objects that refer to a
-particular exception do not introduce a data race.
 ``` cpp
 exception_ptr current_exception() noexcept;
 ```
@@ -252,43 +251,49 @@ handled exception, or a null `exception_ptr` object if no exception is
 being handled. The referenced object shall remain valid at least as long
 as there is an `exception_ptr` object that refers to it. If the function
 needs to allocate memory and the attempt fails, it returns an
 `exception_ptr` object that refers to an instance of `bad_alloc`. It is
 unspecified whether the return values of two successive calls to
-`current_exception` refer to the same exception object. That is, it is
-unspecified whether `current_exception` creates a new copy each time it
-is called. If the attempt to copy the current exception object throws an
-exception, the function returns an `exception_ptr` object that refers to
-the thrown exception or, if this is not possible, to an instance of
-`bad_exception`. The copy constructor of the thrown exception may also
-fail, so the implementation is allowed to substitute a `bad_exception`
-object to avoid infinite recursion.
 ``` cpp
 [[noreturn]] void rethrow_exception(exception_ptr p);
 ```
 *Requires:* `p` shall not be a null pointer.
-*Throws:* the exception object to which `p` refers.
 ``` cpp
 template<class E> exception_ptr make_exception_ptr(E e) noexcept;
 ```
 *Effects:* Creates an `exception_ptr` object that refers to a copy of
-`e`, as if
 ``` cpp
 try {
   throw e;
 } catch(...) {
   return current_exception();
 }
 ```
-This function is provided for convenience and efficiency reasons.
 ### `nested_exception` <a id="except.nested">[[except.nested]]</a>
 ``` cpp
 namespace std {
@@ -311,12 +316,13 @@ namespace std {
 The class `nested_exception` is designed for use as a mixin through
 multiple inheritance. It captures the currently handled exception and
 stores it for later use.
-`nested_exception` has a virtual destructor to make it a polymorphic
-class. Its presence can be tested for with `dynamic_cast`.
 ``` cpp
 nested_exception() noexcept;
 ```
@@ -340,22 +346,28 @@ object.
 ``` cpp
 template <class T> [[noreturn]] void throw_with_nested(T&& t);
 ```
-Let `U` be `remove_reference_t<T>`.
 *Requires:* `U` shall be `CopyConstructible`.
-*Throws:* if `U` is a non-union class type not derived from
-`nested_exception`, an exception of unspecified type that is publicly
-derived from both `U` and `nested_exception` and constructed from
 `std::forward<T>(t)`, otherwise `std::forward<T>(t)`.
 ``` cpp
 template <class E> void rethrow_if_nested(const E& e);
 ```
-*Effects:* If the dynamic type of `e` is publicly and unambiguously
-derived from `nested_exception`, calls `dynamic_cast<const`
-`nested_exception&>(e).rethrow_nested()`.

 ## Exception handling <a id="support.exception">[[support.exception]]</a>
 The header `<exception>` defines several types and functions related to
 the handling of exceptions in a C++program.
+### Header `<exception>` synopsis <a id="exception.syn">[[exception.syn]]</a>
 ``` cpp
 namespace std {
   class exception;
   class bad_exception;
   class nested_exception;
+ using terminate_handler = void (*)();
   terminate_handler get_terminate() noexcept;
   terminate_handler set_terminate(terminate_handler f) noexcept;
   [[noreturn]] void terminate() noexcept;
+ int uncaught_exceptions() noexcept;
+ using exception_ptr = unspecified;
   exception_ptr current_exception() noexcept;
   [[noreturn]] void rethrow_exception(exception_ptr p);
   template<class E> exception_ptr make_exception_ptr(E e) noexcept;
 exception& operator=(const exception& rhs) noexcept;
 ```
 *Effects:* Copies an `exception` object.
+*Postconditions:* If `*this` and `rhs` both have dynamic type
+`exception` then the value of the expression
 `strcmp(what(), rhs.what())` shall equal 0.
 ``` cpp
 virtual ~exception();
 ```
   class bad_exception : public exception {
   public:
     bad_exception() noexcept;
     bad_exception(const bad_exception&) noexcept;
     bad_exception& operator=(const bad_exception&) noexcept;
+    const char* what() const noexcept override;
   };
 }
 ```
+The class `bad_exception` defines the type of the object referenced by
+the `exception_ptr` returned from a call to `current_exception` (
+[[propagation]]) when the currently active exception object fails to
+copy.
 ``` cpp
 bad_exception() noexcept;
 ```
 *Effects:* Constructs an object of class `bad_exception`.
 ``` cpp
 bad_exception(const bad_exception&) noexcept;
 bad_exception& operator=(const bad_exception&) noexcept;
 ```
 *Effects:* Copies an object of class `bad_exception`.
 ``` cpp
+const char* what() const noexcept override;
 ```
 *Returns:* An *implementation-defined* NTBS.
 *Remarks:* The message may be a null-terminated multibyte
 ### Abnormal termination <a id="exception.terminate">[[exception.terminate]]</a>
 #### Type `terminate_handler` <a id="terminate.handler">[[terminate.handler]]</a>
 ``` cpp
+using terminate_handler = void (*)();
 ```
 The type of a *handler function* to be called by `std::terminate()` when
 terminating exception processing.
 ``` cpp
 terminate_handler get_terminate() noexcept;
 ```
+*Returns:* The current `terminate_handler`.
+[*Note 1*: This may be a null pointer value. — *end note*]
 #### `terminate` <a id="terminate">[[terminate]]</a>
 ``` cpp
 [[noreturn]] void terminate() noexcept;
 ```
 *Remarks:* Called by the implementation when exception handling must be
+abandoned for any of several reasons ([[except.terminate]]). May also
+be called directly by the program.
+*Effects:* Calls a `terminate_handler` function. It is unspecified which
+`terminate_handler` function will be called if an exception is active
+during a call to `set_terminate`. Otherwise calls the current
+`terminate_handler` function.
+[*Note 1*: A default `terminate_handler` is always considered a
+callable handler in this context. — *end note*]
+### `uncaught_exceptions` <a id="uncaught.exceptions">[[uncaught.exceptions]]</a>
 ``` cpp
+int uncaught_exceptions() noexcept;
 ```
+*Returns:* The number of uncaught exceptions ([[except.uncaught]]).
+*Remarks:* When `uncaught_exceptions() > 0`, throwing an exception can
+result in a call of
 `std::terminate()` ([[except.terminate]]).
 ### Exception propagation <a id="propagation">[[propagation]]</a>
 ``` cpp
+using exception_ptr = unspecified;
 ```
+The type `exception_ptr` can be used to refer to an exception object.
 `exception_ptr` shall satisfy the requirements of
 `NullablePointer` ([[nullablepointer.requirements]]).
 Two non-null values of type `exception_ptr` are equivalent and compare
 the type.
 `exception_ptr` shall not be implicitly convertible to any arithmetic,
 enumeration, or pointer type.
+[*Note 1*: An implementation might use a reference-counted smart
+pointer as `exception_ptr`. — *end note*]
 For purposes of determining the presence of a data race, operations on
 `exception_ptr` objects shall access and modify only the `exception_ptr`
 objects themselves and not the exceptions they refer to. Use of
 `rethrow_exception` on `exception_ptr` objects that refer to the same
+exception object shall not introduce a data race.
+[*Note 2*: If `rethrow_exception` rethrows the same exception object
+(rather than a copy), concurrent access to that rethrown exception
+object may introduce a data race. Changes in the number of
+`exception_ptr` objects that refer to a particular exception do not
+introduce a data race. — *end note*]
 ``` cpp
 exception_ptr current_exception() noexcept;
 ```
 being handled. The referenced object shall remain valid at least as long
 as there is an `exception_ptr` object that refers to it. If the function
 needs to allocate memory and the attempt fails, it returns an
 `exception_ptr` object that refers to an instance of `bad_alloc`. It is
 unspecified whether the return values of two successive calls to
+`current_exception` refer to the same exception object.
+[*Note 3*: That is, it is unspecified whether `current_exception`
+creates a new copy each time it is called. — *end note*]
+If the attempt to copy the current exception object throws an exception,
+the function returns an `exception_ptr` object that refers to the thrown
+exception or, if this is not possible, to an instance of
+`bad_exception`.
+[*Note 4*: The copy constructor of the thrown exception may also fail,
+so the implementation is allowed to substitute a `bad_exception` object
+to avoid infinite recursion. — *end note*]
 ``` cpp
 [[noreturn]] void rethrow_exception(exception_ptr p);
 ```
 *Requires:* `p` shall not be a null pointer.
+*Throws:* The exception object to which `p` refers.
 ``` cpp
 template<class E> exception_ptr make_exception_ptr(E e) noexcept;
 ```
 *Effects:* Creates an `exception_ptr` object that refers to a copy of
+`e`, as if:
 ``` cpp
 try {
   throw e;
 } catch(...) {
   return current_exception();
 }
 ```
+[*Note 5*: This function is provided for convenience and efficiency
+reasons. — *end note*]
 ### `nested_exception` <a id="except.nested">[[except.nested]]</a>
 ``` cpp
 namespace std {
 The class `nested_exception` is designed for use as a mixin through
 multiple inheritance. It captures the currently handled exception and
 stores it for later use.
+[*Note 1*: `nested_exception` has a virtual destructor to make it a
+polymorphic class. Its presence can be tested for with
+`dynamic_cast`. — *end note*]
 ``` cpp
 nested_exception() noexcept;
 ```
 ``` cpp
 template <class T> [[noreturn]] void throw_with_nested(T&& t);
 ```
+Let `U` be `decay_t<T>`.
 *Requires:* `U` shall be `CopyConstructible`.
+*Throws:* If
+`is_class_v<U> && !is_final_v<U> && !is_base_of_v<nested_exception, U>`
+is `true`, an exception of unspecified type that is publicly derived
+from both `U` and `nested_exception` and constructed from
 `std::forward<T>(t)`, otherwise `std::forward<T>(t)`.
 ``` cpp
 template <class E> void rethrow_if_nested(const E& e);
 ```
+*Effects:* If `E` is not a polymorphic class type, or if
+`nested_exception` is an inaccessible or ambiguous base class of `E`,
+there is no effect. Otherwise, performs:
+``` cpp
+if (auto p = dynamic_cast<const nested_exception*>(addressof(e)))
+  p->rethrow_nested();
+```

Diff to HTML by rtfpessoa