Line data    Source code

       1           1 : // Distributed under the MIT License.
       2             : // See LICENSE.txt for details.
       3             : 
       4             : #pragma once
       5             : 
       6             : /// \file
       7             : /// Defines the type alias Requires
       8             : 
       9             : #include <cstddef>
      10             : 
      11             : namespace Requires_detail {
      12             : template <bool B>
      13             : struct requires_impl {
      14             :   using template_error_type_failed_to_meet_requirements_on_template_parameters =
      15             :       std::nullptr_t;
      16             : };
      17             : 
      18             : template <>
      19             : struct requires_impl<false> {};
      20             : }  // namespace Requires_detail
      21             : 
      22             : /*!
      23             :  * \ingroup UtilitiesGroup
      24             :  * \brief Express requirements on the template parameters of a function or
      25             :  * class, replaces `std::enable_if_t`
      26             :  *
      27             :  * Replacement for `std::enable_if_t` and Concepts for expressing requirements
      28             :  * on template parameters. This does not require merging of the Concepts
      29             :  * TS (whose merit is debatable) and provides an "error message" if substitution
      30             :  * of a template parameter failed. Specifically, the compiler error will contain
      31             :  * "template_error_type_failed_to_meet_requirements_on_template_parameters",
      32             :  * aiding the user of a function or class in tracking down the list of
      33             :  * requirements on the deduced type.
      34             :  *
      35             :  * For example, if a function `foo` is defined as:
      36             :  * \snippet Utilities/Test_Requires.cpp foo_definition
      37             :  * then calling the function with a list, `foo(std::list<double>{});` results in
      38             :  * the following compilation error from clang:
      39             :  * \code
      40             :  * ./tests/Unit/Utilities/Test_Requires.cpp:29:3: error: no matching function
      41             :  *    for call to 'foo'
      42             :  *   foo(std::list<double>{});
      43             :  *   ^~~
      44             :  * ./tests/Unit/Utilities/Test_Requires.cpp:15:13: note: candidate
      45             :  *     template ignored: substitution failure [with T = std::__1::list<double,
      46             :  *     std::__1::allocator<double> >]: no type named
      47             :  *     'template_error_type_failed_to_meet_requirements_on_template_parameters'
      48             :  *     in 'Requires_detail::requires_impl<false>'
      49             :  * std::string foo(const T&) {
      50             :  *             ^
      51             :  * 1 error generated.
      52             :  * \endcode
      53             :  *
      54             :  * Here is an example of how write function overloads using `Requires` or to
      55             :  * express constraints on the template parameters:
      56             :  * \snippet Utilities/Test_Requires.cpp function_definitions
      57             :  *
      58             :  * \note
      59             :  * Using `Requires` is safer than using `std::enable_if_t` because the
      60             :  * nested type alias is of type `std::nullptr_t` and so usage is always:
      61             :  * \code
      62             :  * template <typename T, Requires<(bool depending on T)> = nullptr>
      63             :  * \endcode
      64             :  */
      65             : template <bool B>
      66           1 : using Requires = typename Requires_detail::requires_impl<
      67             :     B>::template_error_type_failed_to_meet_requirements_on_template_parameters;