From b0ef682e3d94f98478c00513ea7819f384a36f83 Mon Sep 17 00:00:00 2001 From: Peter Dimov Date: Thu, 14 Sep 2023 02:20:46 +0300 Subject: [PATCH] Update documentation --- doc/system/changes.adoc | 4 + doc/system/reference.adoc | 295 +++++++++++++++++++++++++++++++- include/boost/system/result.hpp | 3 +- 3 files changed, 297 insertions(+), 5 deletions(-) diff --git a/doc/system/changes.adoc b/doc/system/changes.adoc index 2497353..2efa68d 100644 --- a/doc/system/changes.adoc +++ b/doc/system/changes.adoc @@ -8,6 +8,10 @@ https://www.boost.org/LICENSE_1_0.txt # Revision History :idprefix: +## Changes in Boost 1.84 + +* Added support for `result`. + ## Changes in Boost 1.81 * The macro `BOOST_SYSTEM_DISABLE_THREADS` can now be defined to disable diff --git a/doc/system/reference.adoc b/doc/system/reference.adoc index 8859b34..01b2d7d 100644 --- a/doc/system/reference.adoc +++ b/doc/system/reference.adoc @@ -1713,7 +1713,7 @@ Effects: :: ensures that `*this` holds the error `E( std::forward(a)... )`. - Otherwise, this constructor does not participate in overload resolution. Remarks: :: - This constructor is only enabled when `sizeof...(T) > 0`. + This constructor is only enabled when `sizeof...(A) > 0`. ``` template @@ -1747,7 +1747,7 @@ template * {blank} + Ensures: :: - If `r2.has_value()` is `true`, `*this` holds the value `T( *r2 )`, otherwise `*this` holds the value `E( r2.error() )`. + If `r2.has_value()` is `true`, `*this` holds the value `T( *r2 )`, otherwise `*this` holds the error `E( r2.error() )`. Remarks: :: This constructor is only enabled when `std::is_convertible::value && std::is_convertible::value` is `true`. @@ -1759,7 +1759,7 @@ template * {blank} + Ensures: :: - If `r2.has_value()` is `true`, `*this` holds the value `T( std::move( *r2 ) )`, otherwise `*this` holds the value `E( r2.error() )`. + If `r2.has_value()` is `true`, `*this` holds the value `T( std::move( *r2 ) )`, otherwise `*this` holds the error `E( r2.error() )`. Remarks: :: This constructor is only enabled when `std::is_convertible::value && std::is_convertible::value` is `true`. @@ -1961,6 +1961,9 @@ public: template constexpr result( in_place_error_t, A&&... a ); + template + constexpr result( result const& r2 ); + // queries constexpr bool has_value() const noexcept; @@ -2032,7 +2035,7 @@ Effects: :: ensures that `*this` holds the error `E( std::forward(a)... )`. - Otherwise, this constructor does not participate in overload resolution. Remarks: :: - This constructor is only enabled when `sizeof...(T) > 0`. + This constructor is only enabled when `sizeof...(A) > 0`. ``` template @@ -2056,6 +2059,18 @@ Ensures: :: Remarks: :: This constructor is only enabled when `std::is_constructible::value` is `true`. +``` +template + constexpr result( result const& r2 ); +``` +[none] +* {blank} ++ +Ensures: :: + If `r2.has_value()` is `true`, `*this` holds an unspecified value, otherwise `*this` holds the error `E( r2.error() )`. +Remarks: :: + This constructor is only enabled when `std::is_convertible::value` is `true`. + #### Queries ``` @@ -2201,6 +2216,278 @@ Effects: :: Returns: :: `os`. +### result + +``` +namespace boost { +namespace system { + +template class result +{ +public: + + using value_type = U&; + using error_type = E; + + static constexpr in_place_value_t in_place_value{}; + static constexpr in_place_error_t in_place_error{}; + + // constructors + + template + constexpr result( A&& a ) noexcept; + + template + constexpr result( A&&... a ); + + template + constexpr result( in_place_value_t, A&& a ) noexcept; + + template + constexpr result( in_place_error_t, A&&... a ); + + template + constexpr result( result const& r2 ); + + // queries + + constexpr bool has_value() const noexcept; + constexpr bool has_error() const noexcept; + constexpr explicit operator bool() const noexcept; + + // checked value access + + constexpr U& value( boost::source_location const & loc = + BOOST_CURRENT_LOCATION ) const; + + // unchecked value access + + constexpr U* operator->() const noexcept; + constexpr U& operator*() const noexcept; + + // error access + + constexpr E error() const &; + constexpr E error() &&; + + // emplace + + template + constexpr U& emplace( A&& a ) noexcept; + + // swap + + constexpr void swap( result& r ); + friend constexpr void swap( result & r1, result & r2 ); + + // equality + + friend constexpr bool operator==( result const & r1, result const & r2 ); + friend constexpr bool operator!=( result const & r1, result const & r2 ); +}; + +} // namespace system +} // namespace boost +``` + +#### Constructors + +``` +template + constexpr result( A&& a ) noexcept; +``` +[none] +* {blank} ++ +Ensures: :: + `*this` holds the reference `static_cast( std::forward(a) )`. +Remarks: :: + This constructor is only enabled when `A` is `B&` and `std::is_convertible::value` is `true`. + +``` +template + constexpr result( A&&... a ); +``` +[none] +* {blank} ++ +Effects: :: + - If `std::is_constructible::value && !std::is_constructible::value`, + ensures that `*this` holds the error `E( std::forward(a)... )`. + - Otherwise, this constructor does not participate in overload resolution. +Remarks: :: + This constructor is only enabled when `sizeof...(A) > 0`. + +``` +template + constexpr result( in_place_value_t, A&& a ) noexcept; +``` +[none] +* {blank} ++ +Ensures: :: + `*this` holds the reference `static_cast( std::forward(a) )`. +Remarks: :: + This constructor is only enabled when `A` is `B&` and `std::is_convertible::value` is `true`. + +``` +template + constexpr result( in_place_error_t, A&&... a ); +``` +[none] +* {blank} ++ +Ensures: :: + `*this` holds the error `E( std::forward(a)... )`. +Remarks: :: + This constructor is only enabled when `std::is_constructible::value` is `true`. + +``` +template + constexpr result( result const& r2 ); +``` +[none] +* {blank} ++ +Ensures: :: + If `r2.has_value()` is `true`, `*this` holds the reference `static_cast( *r2 )`, otherwise `*this` holds the error `E( r2.error() )`. +Remarks: :: + This constructor is only enabled when `std::is_convertible::value && std::is_convertible::value` is `true`. + +#### Queries + +``` +constexpr bool has_value() const noexcept; +``` +[none] +* {blank} ++ +Returns: :: + `true` when `*this` holds a value, `false` otherwise. + +``` +constexpr bool has_error() const noexcept; +``` +[none] +* {blank} ++ +Returns: :: + `!has_value()`. + +``` +constexpr explicit operator bool() const noexcept; +``` +[none] +* {blank} ++ +Returns: :: + `has_value()`. + +#### Checked Value Access + +``` +constexpr U& value( + boost::source_location const & loc = BOOST_CURRENT_LOCATION ) const; +``` +[none] +* {blank} ++ +Effects: :: + If `*this` holds a reference, returns it. Otherwise, + calls `throw_exception_from_error`, passing it a reference to + the held error, and `loc`. + +#### Unchecked Value Access + +``` +constexpr U* operator->() const noexcept; +``` +[none] +* {blank} ++ +Returns: :: + If `*this` holds a reference, a pointer to its referent. Otherwise, `nullptr`. + +``` +constexpr U& operator*() const noexcept; +``` +[none] +* {blank} ++ +Requires: :: `*this` holds a reference. +Returns: :: + `*operator\->()`. + +#### Error Access + +``` +constexpr E error() const &; +constexpr E error() &&; +``` +[none] +* {blank} ++ +Effects: :: + If `*this` holds an error, returns it. Otherwise, returns `E()`. + +#### emplace + +``` +template + constexpr U& emplace( A&& a ) noexcept; +``` +[none] +* {blank} ++ +Ensures: :: + `*this` holds the reference `static_cast( std::forward(a)... )`. +Returns: :: + The contained reference. +Remarks: :: + This function is only enabled when `A` is `B&` and `std::is_convertible::value` is `true`. + +#### swap + +``` +constexpr void swap( result& r ); +``` +[none] +* {blank} ++ +Effects: :: + Exchanges the contents of `*this` and `r`. + +``` +friend constexpr void swap( result & r1, result & r2 ); +``` +[none] +* {blank} ++ +Effects: :: + Exchanges the contents of `r1` and `r2`. + +#### Equality + +``` +friend constexpr bool operator==( result const & r1, result const & r2 ); +``` +[none] +* {blank} ++ +Effects: :: + - If `r1` holds a reference `t1` and `r2` holds a reference `t2`, returns `t1 == t2`. + - If `r1` holds an error `e1` and `r2` holds an error `e2`, returns `e1 == e2`. + - Otherwise, returns `false`. + +``` +friend constexpr bool operator!=( result const & r1, result const & r2 ); +``` +[none] +* {blank} ++ +Returns: :: + `!( r1 == r2 )`. + ## This convenience header includes all the headers previously described. diff --git a/include/boost/system/result.hpp b/include/boost/system/result.hpp index e6a4339..2c6b381 100644 --- a/include/boost/system/result.hpp +++ b/include/boost/system/result.hpp @@ -744,7 +744,8 @@ public: // tagged, value template::value + std::is_constructible::value && + !detail::reference_to_temporary::value >::type> constexpr result( in_place_value_t, A&& a ) noexcept( std::is_nothrow_constructible::value )