Merge branch 'develop' into feature/error-condition

doc/system.adoc

@@ -10,7 +10,7 @@ http://www.boost.org/LICENSE_1_0.txt
 # Boost.System: Extensible Error Reporting
 Beman Dawes, Christopher Kohlhoff, Peter Dimov
 :toc: left
-:toclevels: 3
+:toclevels: 4
 :idprefix:
 :docinfo: private-footer
 

doc/system/copyright.adoc

@@ -1,5 +1,5 @@
 ////
-Copyright 2018 Peter Dimov
+Copyright 2018-2021 Peter Dimov
 
 Distributed under the Boost Software License, Version 1.0.
 
@@ -14,6 +14,6 @@ http://www.boost.org/LICENSE_1_0.txt
 This documentation is
 
 * Copyright 2003-2017 Beman Dawes
-* Copyright 2018 Peter Dimov
+* Copyright 2018-2021 Peter Dimov
 
 and is distributed under the http://www.boost.org/LICENSE_1_0.txt[Boost Software License, Version 1.0].

doc/system/reference.adoc

@@ -1,6 +1,6 @@
 ////
 Copyright 2003-2017 Beman Dawes
-Copyright 2018 Peter Dimov
+Copyright 2018-2021 Peter Dimov
 
 Distributed under the Boost Software License, Version 1.0.
 
@@ -48,31 +48,53 @@ the old names, but will provide them when the macro `BOOST_SYSTEM_ENABLE_DEPRECA
 |`native_ecat`|`system_category()`
 |===
 
-## <boost/system/error_code.hpp>
+## <boost/system/{zwsp}is_error_code_enum.hpp>
 
-### Synopsis
+### is_error_code_enum
 
 ```
 namespace boost {
   namespace system {
 
-    class error_category;
-
-    constexpr const error_category & system_category() noexcept;
-    constexpr const error_category & generic_category() noexcept;
-
-    class error_code;
-    class error_condition;
-
-    // "Concept" helpers
-
     template<class T>
       struct is_error_code_enum { static const bool value = false; };
 
+  } // namespace system
+} // namespace boost
+```
+
+Users may specialize `is_error_code_enum` for their error enumeration
+types to indicate that they should be eligible for automatic conversions
+to `error_code`. This conversion calls `make_error_code(e)`, which should
+be provided in the same namespace as the enumeration type.
+
+## <boost/system/{zwsp}is_error_condition_enum.hpp>
+
+### is_error_condition_enum
+
+```
+namespace boost {
+  namespace system {
+
     template<class T>
       struct is_error_condition_enum { static const bool value = false; };
 
-    // generic error conditions
+  } // namespace system
+} // namespace boost
+```
+
+Users may specialize `is_error_condition_enum` for their error enumeration
+types to indicate that they should be eligible for automatic conversions
+to `error_condition`. This conversion calls `make_error_condition(e)`, which
+should be provided in the same namespace as the enumeration type.
+
+## <boost/system/{zwsp}errc.hpp>
+
+### errc
+
+```
+namespace boost {
+  namespace system {
 
     namespace errc {
       enum errc_t
@@ -163,52 +185,80 @@ namespace boost {
     template<> struct is_error_condition_enum<errc::errc_t>
       { static const bool value = true; };
 
-    // non-member functions
-
-    constexpr bool operator==( const error_code & lhs,
-      const error_code & rhs ) noexcept;
-    bool operator==( const error_code & code,
-      const error_condition & condition ) noexcept;
-    bool operator==( const error_condition & condition,
-      const error_code & code ) noexcept;
-    constexpr bool operator==( const error_condition & lhs,
-      const error_condition & rhs ) noexcept;
-
-    constexpr bool operator!=( const error_code & lhs,
-      const error_code & rhs ) noexcept;
-    bool operator!=( const error_code & code,
-      const error_condition & condition ) noexcept;
-    bool operator!=( const error_condition & condition,
-      const error_code & code ) noexcept;
-    constexpr bool operator!=( const error_condition & lhs,
-      const error_condition & rhs ) noexcept;
-
-    constexpr bool operator<( const error_code & lhs,
-      const error_code & rhs ) noexcept;
-    constexpr bool operator<( const error_condition & lhs,
-      const error_condition & rhs ) noexcept;
-
     constexpr error_code make_error_code( errc::errc_t e ) noexcept;
     constexpr error_condition make_error_condition( errc::errc_t e ) noexcept;
 
-    template <class charT, class traits>
-      std::basic_ostream<charT, traits>&
-        operator<<( basic_ostream<charT, traits>& os, const error_code & ec );
-
-    std::size_t hash_value( const error_code & ec );
-
   } // namespace system
 } // namespace boost
 ```
 
-The value of each `errc_t` constant is the same as the value of the `<cerrno>`
+The predefined enumeration type `errc::errc_t` provides named constants
-macro shown in the above synopsis.
+corresponding to the values of the `<cerrno>` macros.
 
-Users may specialize `is_error_code_enum` and `is_error_condition_enum`
+```
-templates to indicate that a type is eligible for class `error_code` and
+constexpr error_condition make_error_condition( errc::errc_t e ) noexcept;
-`error_condition` automatic conversions respectively.
+```
+[none]
+* {blank}
++
+Returns: :: `error_condition( e, generic_category() )`.
 
-### Class error_category
+Since `errc::errc_t` provides a specialization of `is_error_condition_enum`
+and an overload of `make_error_condition`, it can be converted implicitly to
+an `error_condition`. This is typically useful when comparing `error_code`
+values returned from APIs to a portable condition, as in the below example:
+* {blank}
++
+```
+void api_function( boost::system::error_code& ec );
+
+void my_function()
+{
+    boost::system::error_code ec;
+    api_function( ec );
+
+    if( ec == boost::system::errc::no_such_file_or_directory )
+    {
+        // an entity wasn't found (ENOENT)
+        // handle this condition
+    }
+}
+```
+
+```
+constexpr error_code make_error_code( errc::errc_t e ) noexcept;
+```
+[none]
+* {blank}
++
+Returns: :: `error_code( e, generic_category() )`.
+
+In addition to `make_error_condition`, `errc::errc_t` provides an overload of
+`make_error_code`. This allows the creation of generic error codes, an
+operation typically useful when a function needs to signal a generic failure
+that does not come from an underlying API, such as for instance an out of
+memory condition:
+* {blank}
++
+```
+void my_api_function( boost::system::error_code& ec )
+{
+    void* p = std::malloc( 16 );
+
+    if( p == 0 )
+    {
+        // return ENOMEM
+        ec = make_error_code( boost::system::errc::out_of_memory );
+        return;
+    }
+
+    // use p
+}
+```
+
+## <boost/system/{zwsp}error_category.hpp>
+
+### error_category
 
 The class `error_category` defines the base class for types used
 to identify the source and encoding of a particular category of error code.
@@ -251,9 +301,13 @@ namespace boost {
 
       virtual bool failed( int ev ) const noexcept;
 
-      constexpr bool operator==( const error_category & rhs ) const noexcept;
+      friend constexpr bool operator==( const error_category & lhs,
-      constexpr bool operator!=( const error_category & rhs ) const noexcept;
+        const error_category & rhs ) noexcept;
-      constexpr bool operator< ( const error_category & rhs ) const noexcept;
+      friend constexpr bool operator!=( const error_category & lhs,
+        const error_category & rhs ) noexcept;
+
+      friend constexpr bool operator< ( const error_category & lhs,
+        const error_category & rhs ) noexcept;
 
       operator std::error_category const & () const;
 
@@ -397,37 +451,42 @@ Returns: ::
 Remarks: ::
   All calls to this function with the same `ev` must return the same value.
 
-#### Nonvirtuals
+#### Comparisons
 
 ```
-constexpr bool operator==( const error_category & rhs ) const noexcept;
+friend constexpr bool operator==( const error_category & lhs,
+  const error_category & rhs ) noexcept;
 ```
 [none]
 * {blank}
 +
-Returns: :: `rhs.id_ == 0? this == &rhs: id_ == rhs.id_`.
+Returns: :: `rhs.id_ == 0? &lhs == &rhs: lhs.id_ == rhs.id_`.
-Remarks: :: Two category objects are considered equivalent when they have matching
+Remarks: :: Two category objects are considered equivalent when they have
-  nonzero identifiers, or are the same object.
+  matching nonzero identifiers, or are the same object.
 
 ```
-constexpr bool operator!=( const error_category & rhs ) const noexcept;
+friend constexpr bool operator!=( const error_category & lhs,
+  const error_category & rhs ) noexcept;
 ```
 [none]
 * {blank}
 +
-Returns: :: `!( *this == rhs )`.
+Returns: :: `!( lhs == rhs )`.
 
 ```
-constexpr bool operator< ( const error_category & rhs ) const noexcept;
+constexpr bool operator< ( const error_category & lhs,
+  const error_category & rhs ) const noexcept;
 ```
 [none]
 * {blank}
 +
 Returns: ::
-** If `id_ < rhs.id_`, `true`;
+** If `lhs.id_ < rhs.id_`, `true`;
-** Otherwise, if `id_ > rhs.id_`, `false`;
+** Otherwise, if `lhs.id_ > rhs.id_`, `false`;
 ** Otherwise, if `rhs.id_ != 0`, `false`;
-** Otherwise, `std::less<error_category const *>()( this, &rhs )`.
+** Otherwise, `std::less<error_category const *>()( &lhs, &rhs )`.
+
+#### Conversions
 
 ```
 operator std::error_category const & () const;
@@ -438,7 +497,19 @@ operator std::error_category const & () const;
 Returns: :: A reference to an `std::error_category` object corresponding
   to `*this`.
 
-### Predefined Categories
+## <boost/system/{zwsp}system_category.hpp>
+
+### system_category
+
+```
+namespace boost {
+  namespace system {
+
+    constexpr const error_category & system_category() noexcept;
+
+  } // namespace system
+} // namespace boost
+```
 
 ```
 constexpr const error_category & system_category() noexcept;
@@ -446,8 +517,22 @@ constexpr const error_category & system_category() noexcept;
 [none]
 * {blank}
 +
-Returns: :: A reference to an `error_category` object identifying errors
+Returns: :: A reference to a predefined `error_category` object identifying
-  originating from the operating system.
+  errors originating from the operating system.
+
+## <boost/system/{zwsp}generic_category.hpp>
+
+### generic_category
+
+```
+namespace boost {
+  namespace system {
+
+    constexpr const error_category & generic_category() noexcept;
+
+  } // namespace system
+} // namespace boost
+```
 
 ```
 constexpr const error_category & generic_category() noexcept;
@@ -455,10 +540,12 @@ constexpr const error_category & generic_category() noexcept;
 [none]
 * {blank}
 +
-Returns: :: A reference to an `error_category` object identifying portable
+Returns: :: A reference to a predefined `error_category` object identifying
-  error conditions.
+  portable error codes and conditions.
 
-### Class error_code
+## <boost/system/{zwsp}error_code.hpp>
+
+### error_code
 
 The class `error_code` describes an object used to hold error code
 values, such as those originating from the operating system or other
@@ -502,14 +589,39 @@ namespace boost {
       constexpr bool failed() const noexcept;
       constexpr explicit operator bool() const noexcept;
 
+      // comparisons:
+
+      friend constexpr bool operator==( const error_code & lhs,
+        const error_code & rhs ) noexcept;
+      friend constexpr bool operator!=( const error_code & lhs,
+        const error_code & rhs ) noexcept;
+
+      friend constexpr bool operator<( const error_code & lhs,
+        const error_code & rhs ) noexcept;
+
+      // conversions:
+
       operator std::error_code() const;
-
-    private: // exposition only
-
-      int val_;
-      const error_category * cat_;
-
     };
+
+    // non-member functions
+
+    bool operator==( const error_code & code,
+      const error_condition & condition ) noexcept;
+    bool operator==( const error_condition & condition,
+      const error_code & code ) noexcept;
+
+    bool operator!=( const error_code & code,
+      const error_condition & condition ) noexcept;
+    bool operator!=( const error_condition & condition,
+      const error_code & code ) noexcept;
+
+    template <class charT, class traits>
+      std::basic_ostream<charT, traits>&
+        operator<<( basic_ostream<charT, traits>& os, const error_code & ec );
+
+    std::size_t hash_value( const error_code & ec );
+
   }
 }
 ```
@@ -522,7 +634,7 @@ constexpr error_code() noexcept;
 [none]
 * {blank}
 +
-Ensures: :: `val_ == 0`; `*cat_ == system_category()`.
+Ensures: :: `value() == 0`; `category() == system_category()`.
 
 ```
 constexpr error_code( int val, const error_category & cat ) noexcept;
@@ -530,7 +642,7 @@ constexpr error_code( int val, const error_category & cat ) noexcept;
 [none]
 * {blank}
 +
-Ensures: :: `val_ == val`; `cat_ == &cat`.
+Ensures: :: `value() == val`; `category() == cat`.
 
 ```
 template <class ErrorCodeEnum>
@@ -550,7 +662,7 @@ constexpr void assign( int val, const error_category & cat ) noexcept;
 [none]
 * {blank}
 +
-Ensures: :: `val_ == val`; `cat_ == &cat`.
+Ensures: :: `value() == val`; `category() == cat`.
 
 ```
 template<typename ErrorCodeEnum>
@@ -569,7 +681,7 @@ constexpr void clear() noexcept;
 * {blank}
 +
 Ensures: ::
-  `val_ == 0`; `*cat_ == system_category()`.
+  `value() == 0`; `category() == system_category()`.
 
 #### Observers
 
@@ -579,7 +691,7 @@ constexpr int value() const noexcept;
 [none]
 * {blank}
 +
-Returns: :: `val_`.
+Returns: :: the error value.
 
 ```
 constexpr const error_category & category() const noexcept;
@@ -587,7 +699,7 @@ constexpr const error_category & category() const noexcept;
 [none]
 * {blank}
 +
-Returns: :: `*cat_`.
+Returns: :: the error category.
 
 ```
 error_condition default_error_condition() const noexcept;
@@ -595,7 +707,7 @@ error_condition default_error_condition() const noexcept;
 [none]
 * {blank}
 +
-Returns: :: `cat_\->default_error_condition( val_ )`.
+Returns: :: `category().default_error_condition( value() )`.
 
 ```
 std::string message() const;
@@ -603,7 +715,7 @@ std::string message() const;
 [none]
 * {blank}
 +
-Returns: :: `cat_\->message( val_ )`.
+Returns: :: `category().message( value() )`.
 
 ```
 char const * message( char * buffer, std::size_t len ) const noexcept;
@@ -611,7 +723,7 @@ char const * message( char * buffer, std::size_t len ) const noexcept;
 [none]
 * {blank}
 +
-Returns: :: `cat_\->message( val_, buffer, len )`.
+Returns: :: `category().message( value(), buffer, len )`.
 
 ```
 constexpr bool failed() const noexcept;
@@ -619,7 +731,7 @@ constexpr bool failed() const noexcept;
 [none]
 * {blank}
 +
-Returns: :: `cat_\->failed( val_ )`.
+Returns: :: `category().failed( value() )`.
 
 ```
 constexpr explicit operator bool() const noexcept;
@@ -627,7 +739,40 @@ constexpr explicit operator bool() const noexcept;
 [none]
 * {blank}
 +
-Returns: :: `failed()`.
+Returns: ::
+  `failed()`.
+
+#### Comparisons
+
+```
+friend constexpr bool operator==( const error_code & lhs,
+  const error_code & rhs ) noexcept;
+```
+[none]
+* {blank}
++
+Returns: :: `lhs.value() == rhs.value() && lhs.category() == rhs.category()`.
+
+```
+friend constexpr bool operator!=( const error_code & lhs,
+  const error_code & rhs ) noexcept;
+```
+[none]
+* {blank}
++
+Returns: :: `!( lhs == rhs )`.
+
+```
+friend constexpr bool operator<( const error_code & lhs,
+  const error_code & rhs ) noexcept;
+```
+[none]
+* {blank}
++
+Returns: ::
+  `lhs.category() < rhs.category() || (lhs.category() == rhs.category() && lhs.value() < rhs.value())`.
+
+#### Conversions
 
 ```
 operator std::error_code() const;
@@ -636,9 +781,55 @@ operator std::error_code() const;
 * {blank}
 +
 Returns: ::
-  `std::error_code( val_, *cat_ )`.
+  `std::error_code( value(), category() )`.
 
-### Class error_condition
+#### Nonmembers
+
+```
+bool operator==( const error_code & code,
+  const error_condition & condition ) noexcept;
+bool operator==( const error_condition & condition,
+  const error_code & code ) noexcept;
+```
+[none]
+* {blank}
++
+Returns: :: `code.category().equivalent(code.value(), condition) || condition.category().equivalent(code, condition.value())`.
+
+```
+bool operator!=( const error_code & code,
+  const error_condition & condition ) noexcept;
+bool operator!=( const error_condition & condition,
+  const error_code & code ) noexcept;
+```
+[none]
+* {blank}
++
+Returns: :: `!( lhs == rhs )`.
+
+```
+template <class charT, class traits>
+  std::basic_ostream<charT, traits>&
+    operator<<( basic_ostream<charT, traits>& os, const error_code & ec );
+```
+[none]
+* {blank}
++
+Effects: :: `os << ec.category().name() << ':' << ec.value()`.
+Returns: :: `os`.
+
+```
+std::size_t hash_value( const error_code & ec );
+```
+[none]
+* {blank}
++
+Returns: ::
+  A hash value representing `ec`.
+
+## <boost/system/{zwsp}error_condition.hpp>
+
+### error_condition
 
 ```
 namespace boost {
@@ -675,13 +866,19 @@ namespace boost {
       constexpr bool failed() const noexcept;
       constexpr explicit operator bool() const noexcept;
 
+      // comparisons:
+
+      friend constexpr bool operator==( const error_condition & lhs,
+        const error_condition & rhs ) noexcept;
+      friend constexpr bool operator!=( const error_condition & lhs,
+        const error_condition & rhs ) noexcept;
+
+      friend constexpr bool operator<( const error_condition & lhs,
+        const error_condition & rhs ) noexcept;
+
+      // conversions:
+
       operator std::error_condition() const;
-
-    private: // exposition only
-
-      int val_;
-      const error_category * cat_;
-
     };
   }
 }
@@ -695,7 +892,7 @@ constexpr error_condition() noexcept;
 [none]
 * {blank}
 +
-Ensures: :: `val_ == 0`; `*cat_ == generic_category()`.
+Ensures: :: `value() == 0`; `category() == generic_category()`.
 
 ```
 constexpr error_condition( int val, const error_category & cat ) noexcept;
@@ -703,7 +900,7 @@ constexpr error_condition( int val, const error_category & cat ) noexcept;
 [none]
 * {blank}
 +
-Ensures: :: `val_ == val`; `cat_ == &cat`.
+Ensures: :: `value() == val`; `category() == cat`.
 
 ```
 template <class ErrorConditionEnum>
@@ -724,7 +921,7 @@ constexpr void assign( int val, const error_category & cat ) noexcept;
 [none]
 * {blank}
 +
-Ensures: :: `val_ == val`; `cat_ == &cat`.
+Ensures: :: `value() == val`; `category() == cat`.
 
 ```
 template <class ErrorConditionEnum>
@@ -743,7 +940,7 @@ constexpr void clear() noexcept;
 * {blank}
 +
 Ensures: ::
-  `val_ == 0`; `*cat_ == generic_category()`.
+  `value() == 0`; `category() == generic_category()`.
 
 #### Observers
 
@@ -753,7 +950,7 @@ constexpr int value() const noexcept;
 [none]
 * {blank}
 +
-Returns: :: `val_`.
+Returns: :: the error value.
 
 ```
 constexpr const error_category & category() const noexcept;
@@ -761,7 +958,7 @@ constexpr const error_category & category() const noexcept;
 [none]
 * {blank}
 +
-Returns: :: `*cat_`.
+Returns: :: the error category.
 
 ```
 std::string message() const;
@@ -769,7 +966,7 @@ std::string message() const;
 [none]
 * {blank}
 +
-Returns: :: `cat_\->message( val_ )`.
+Returns: :: `category().message( value() )`.
 
 ```
 char const * message( char * buffer, std::size_t len ) const noexcept;
@@ -777,7 +974,7 @@ char const * message( char * buffer, std::size_t len ) const noexcept;
 [none]
 * {blank}
 +
-Returns: :: `cat_\->message( val_, buffer, len )`.
+Returns: :: `category().message( value(), buffer, len )`.
 
 ```
 constexpr bool failed() const noexcept;
@@ -785,7 +982,7 @@ constexpr bool failed() const noexcept;
 [none]
 * {blank}
 +
-Returns: :: `cat_\->failed( val_ )`.
+Returns: :: `category().failed( value() )`.
 
 ```
 constexpr explicit operator bool() const noexcept;
@@ -793,23 +990,13 @@ constexpr explicit operator bool() const noexcept;
 [none]
 * {blank}
 +
-Returns: :: `failed()`.
-
-```
-operator std::error_condition() const;
-```
-[none]
-* {blank}
-+
 Returns: ::
-  `std::error_condition( val_, *cat_ )`.
+  `failed()`.
 
-### Nonmember functions
+#### Comparisons
 
 ```
-constexpr bool operator==( const error_code & lhs,
+friend constexpr bool operator==( const error_condition & lhs,
-  const error_code & rhs ) noexcept;
-constexpr bool operator==( const error_condition & lhs,
   const error_condition & rhs ) noexcept;
 ```
 [none]
@@ -818,25 +1005,8 @@ constexpr bool operator==( const error_condition & lhs,
 Returns: :: `lhs.value() == rhs.value() && lhs.category() == rhs.category()`.
 
 ```
-bool operator==( const error_code & code,
+friend constexpr bool operator!=( const error_condition & lhs,
-  const error_condition & condition ) noexcept;
-bool operator==( const error_condition & condition,
-  const error_code & code ) noexcept;
-```
-[none]
-* {blank}
-+
-Returns: :: `code.category().equivalent( code.value(), condition ) || condition.category().equivalent( code, condition.value() )`.
-
-```
-constexpr bool operator!=( const error_code & lhs,
-  const error_code & rhs ) noexcept;
-constexpr bool operator!=( const error_condition & lhs,
   const error_condition & rhs ) noexcept;
-bool operator!=( const error_code & code,
-  const error_condition & condition ) noexcept;
-bool operator!=( const error_condition & condition,
-  const error_code & code ) noexcept;
 ```
 [none]
 * {blank}
@@ -844,53 +1014,27 @@ bool operator!=( const error_condition & condition,
 Returns: :: `!( lhs == rhs )`.
 
 ```
-constexpr bool operator<( const error_code & lhs,
+friend constexpr bool operator<( const error_condition & lhs,
-  const error_code & rhs ) noexcept;
-constexpr bool operator<( const error_condition & lhs,
   const error_condition & rhs ) noexcept;
 ```
 [none]
 * {blank}
 +
-Returns: :: `lhs.category() < rhs.category() || ( lhs.category() == rhs.category() && lhs.value() < rhs.value() )`.
+Returns: ::
+  `lhs.category() < rhs.category() || (lhs.category() == rhs.category() && lhs.value() < rhs.value())`.
+
+#### Conversions
 
 ```
-constexpr error_code make_error_code( errc::errc_t e ) noexcept;
+operator std::error_condition() const;
-```
-[none]
-* {blank}
-+
-Returns: :: `error_code( e, generic_category() )`.
-
-```
-constexpr error_condition make_error_condition( errc::errc_t e ) noexcept;
-```
-[none]
-* {blank}
-+
-Returns: :: `error_condition( e, generic_category() )`.
-
-```
-template <class charT, class traits>
-  std::basic_ostream<charT, traits>&
-    operator<<( basic_ostream<charT, traits>& os, const error_code & ec );
-```
-[none]
-* {blank}
-+
-Effects: :: `os << ec.category().name() << ':' << ec.value()`.
-Returns: :: `os`.
-
-```
-std::size_t hash_value( const error_code & ec );
 ```
 [none]
 * {blank}
 +
 Returns: ::
-  A hash value representing `ec`.
+  `std::error_condition( value(), category() )`.
 
-## <boost/system/system_error.hpp>
+## <boost/system/{zwsp}system_error.hpp>
 
 ### Class system_error
 
@@ -967,4 +1111,8 @@ const char * what() const noexcept;
 * {blank}
 +
 Returns: :: A null-terminated character string incorporating the arguments supplied
-  in the constructor, typically of the form `what_arg + ": " + code.message()`.
+  in the constructor, typically of the form `what_arg + ": " + code().message()`.
+
+## <boost/system.hpp>
+
+This convenience header includes all the headers previously described.