boost/scope/error_code_checker.hpp

0001 /*
0002  * Distributed under the Boost Software License, Version 1.0.
0003  * (See accompanying file LICENSE_1_0.txt or copy at
0004  * https://www.boost.org/LICENSE_1_0.txt)
0005  *
0006  * Copyright (c) 2023 Andrey Semashev
0007  */
0008 /*!
0009  * \file scope/error_code_checker.hpp
0010  *
0011  * This header contains definition of \c error_code_checker type.
0012  */
0013
0014 #ifndef BOOST_SCOPE_ERROR_CODE_CHECKER_HPP_INCLUDED_
0015 #define BOOST_SCOPE_ERROR_CODE_CHECKER_HPP_INCLUDED_
0016
0017 #include <boost/core/addressof.hpp>
0018 #include <boost/scope/detail/config.hpp>
0019 #include <boost/scope/detail/header.hpp>
0020
0021 #ifdef BOOST_HAS_PRAGMA_ONCE
0022 #pragma once
0023 #endif
0024
0025 namespace boost {
0026 namespace scope {
0027
0028 /*!
0029  * \brief A predicate for checking whether an error code indicates error.
0030  *
0031  * The predicate captures a reference to an external error code object, which it
0032  * tests for an error indication when called. The error code object must remain
0033  * valid for the whole lifetime duration of the predicate.
0034  *
0035  * For an error code object `ec`, an expression `!ec` must be valid, never throw exceptions,
0036  * and return a value contextually convertible to `bool`. If the returned value converts
0037  * to `false`, then this is taken as an error indication, and the predicate returns `true`.
0038  * Otherwise, the predicate returns `false`.
0039  *
0040  * A few examples of error code types:
0041  *
0042  * \li `std::error_code` or `boost::system::error_code`,
0043  * \li `std::expected`, `boost::outcome_v2::basic_outcome` or `boost::outcome_v2::basic_result`,
0044  * \li `int`, where the value of 0 indicates no error,
0045  * \li `bool`, where the value of `false` indicates no error,
0046  * \li `T*`, where a null pointer indicates no error.
0047  *
0048  * \tparam ErrorCode Error code type.
0049  */
0050 template< typename ErrorCode >
0051 class error_code_checker
0052 {
0053 public:
0054     //! Predicate result type
0055     using result_type = bool;
0056
0057 private:
0058     ErrorCode* m_error_code;
0059
0060 public:
0061     /*!
0062      * \brief Constructs the predicate.
0063      *
0064      * Upon construction, the predicate saves a reference to the external error code object.
0065      * The referenced object must remain valid for the whole lifetime duration of the predicate.
0066      *
0067      * **Throws:** Nothing.
0068      */
0069     explicit error_code_checker(ErrorCode& ec) noexcept :
0070         m_error_code(boost::addressof(ec))
0071     {
0072     }
0073
0074     /*!
0075      * \brief Checks if the error code indicates error.
0076      *
0077      * **Throws:** Nothing.
0078      *
0079      * \returns As if `!!ec`, where `ec` is the error code object passed to the predicate constructor.
0080      */
0081     result_type operator()() const noexcept
0082     {
0083         return !!(*m_error_code);
0084     }
0085 };
0086
0087 /*!
0088  * \brief Creates a predicate for checking whether an exception is being thrown
0089  *
0090  * **Throws:** Nothing.
0091  */
0092 template< typename ErrorCode >
0093 inline error_code_checker< ErrorCode > check_error_code(ErrorCode& ec) noexcept
0094 {
0095     return error_code_checker< ErrorCode >(ec);
0096 }
0097
0098 } // namespace scope
0099 } // namespace boost
0100
0101 #include <boost/scope/detail/footer.hpp>
0102
0103 #endif // BOOST_SCOPE_ERROR_CODE_CHECKER_HPP_INCLUDED_