Compiler Explorer

Source code

/**@file
   @brief Simple types that can be used when defining functions.
*/
#ifndef NS_UTILITY_PARAMETER_HPP
#define NS_UTILITY_PARAMETER_HPP
#include <cerrno>
#include <new>
#include <stdexcept>
#include <type_traits>
#include <utility>

namespace ns {

///////////////////////////////////////////////////////////////////////////
/**Noncopyable trait.
   A type that inherits from this type will be noncopyable, however, it may
   still be moved from. As a base class, this type is zero-cost.
*/
struct noncopyable {
    /**@cond DOXYGEN_IGNORE*/
    noncopyable(const noncopyable&) = delete;
    noncopyable& operator=(const noncopyable&) = delete;

protected:
    noncopyable() noexcept = default;
    ~noncopyable() noexcept = default;
    noncopyable(noncopyable&&) noexcept = default;
    noncopyable& operator=(noncopyable&&) noexcept = default;
    /**@endcond*/
};

///////////////////////////////////////////////////////////////////////////
/**Error handler used by the library.
   By default, this type throws a standard exception based on the value of an
   error code. If the exception object stores a pointer to a C-string, it will
   point to an explanatory string.

The error handling strategy may be specialized for each type by providing a
   template specialization:
   @code{.cpp}
   namespace ns {

//specialize handler behavior for a single type
   template <>
   struct handler<my_type> {
       [[noreturn]] void operator()(const int code, const char *const what) const {
           std::cerr << what << '\n';
           abort();
       }
   };

//specialize handler behavior for a "family" of types
   template <typename T>
   struct handler<T, std::enable_if_t<std::is_same_v<T, my_type1> || std::is_same<T, my_type2>>> {
       [[noreturn]] void operator()(const int code, const char *const what) const {
           std::cerr << "only my_type1 and my_type2 use this handler\n";
           abort();
       }
   };

//replace the default behavior for all types in your program
   template <typename T>
   struct handler<T, std::enable_if_t<1>> {
       [[noreturn]] void operator()(const int code, const char *const what) const {
           std::cerr << "this handler is always called on error\n";
           abort();
       }
   }

}
   @endcode
   @note [[noreturn]] is not considered part of the function signature, however
   the behavior is undefined if this function returns.
*/
template <typename T, typename = void>
struct handler {
    /**Handle error.
       The behavior is undefined if this function returns. Here are some things
       you may choose to do in your override:
       - Log error message and abort() (abort() honors the [[noreturn]]
       contract).
       - Spin forever (not returning honors the [[noreturn]] contract).
       - Throw an exception (leaving a function via an exception honors the
       [[noreturn]] contract).
       @attention Errors cannot be ignored. Of all the options listed above, throwing
       an exception is the only way to dynamically recover from an error. If you
       choose to throw an exception, pay attention to the exception guarantees
       of the functions you are calling (functions with the basic exception
       guarantee may change state in an observable way after catching an
       exception).
       @exception Guarantee: Strong exception guarantee.
       @exception std::domain_error if code == EDOM.
       @exception std::runtime_error if code == EFAULT.
       @exception std::invalid_argument if code == EINVAL.
       @exception std::bad_alloc if code == ENOMEM.
       @exception std::overflow_error if code == EOVERFLOW.
       @exception std::out_of_range if code == ERANGE.
       @exception std::exception for all other error codes.
       @param code Error code.
       @param what Explanatory string.
    */
    [[noreturn]] void operator()(const int code, const char *const what) const {
        switch (code) {
          case EDOM:      throw std::domain_error{what};
          case EFAULT:    throw std::runtime_error{what};
          case EINVAL:    throw std::invalid_argument{what};
          case ENOMEM:    throw std::bad_alloc{};
          case EOVERFLOW: throw std::overflow_error{what};
          case ERANGE:    throw std::out_of_range{what};
          default:        throw std::exception{};
        }
    }
};

///////////////////////////////////////////////////////////////////////////
/**Type for input parameters.
   If the type is small and trivially copy constructible, we'll pass it by
   value. Otherwise, pass by reference to const.

@code{.cpp}
   void int_func(in_t<int> i) {} //i is of type int
   void vec_int_func(in_t<std::vector<int>> v) {} //v is of type const std::vector<int>&

void poly_func(in_t<Base*> base_ptr) { //base_ptr is of type Base*
       base_ptr->virtual_func();
   }

void poly_func(in_t<Base> base) { //assuming Base is a type with virtual functions, base is of type const Base&
       base.virtual_func();
   }
   @endcode
*/
template <typename T>
using in_t = std::conditional_t<sizeof (T) <= 2*sizeof (void*) && std::is_trivially_copy_constructible_v<T>, T, const T&>;

/**Type for out parameters.
   @attention Out parameters are a little old-school. Prefer returning
   structs/tuples by value. You may still be thinking "but I've always used out
   parameters and have never had a problem"... Have you considered exceptions?
   If a function updates an out parameter and throws an exception in the middle
   of its execution, what is the state of your out param? This does not happen as
   easily when returning structs/tuples by value. Remember, this is modern C++,
   and expensive copies are usually elided by the compiler.
*/
template <typename T>
using out_t = std::remove_reference_t<T>&;

/**Type for in/out parameters.
   @attention In/out parameters are typically used when a function needs to
   modify an object directly (i.e. not operate on a separate copy of an
   object). Any time a function takes an inout parameter, make sure you state
   the preconditions that must be met. You may write assertions based on these
   preconditions, but it is better to use types that maintain some invariant
   throughout their lives.
*/
template <typename T>
using inout_t = out_t<T>;

/**Type for explicit ownership transfer.
   This is an r-value reference. When using this type in a parameter list, you
   are explicitly letting readers of your code know that you are taking
   ownership of an object. Users must use std::move() at the callsite, and users
   should not use the object again until it has been re-assigned to.
*/
template <typename T>
using own_t = std::remove_reference_t<T>;

/**Return type.
   Not especially useful, just provided for consistency.
*/
template <typename T>
using ret_t = T;

namespace detail {

/**Provides common definitions for function parameter/return types in this module.*/
template <typename T>
class function_data {
  public:
    /**Constructor.
       Captures data either by value or by reference.
       @exception Guarantee: No throw/no fail guarantee.
       @param data Data to capture.
    */
    template <typename U>
    constexpr function_data(U&& data) noexcept
      : data{std::forward<U>(data)}
    {}

/**Conversion to reference to data.
       @exception Guarantee: No throw/no fail guarantee.
       @return Reference to the captured data.
    */
    constexpr operator auto&() noexcept { return get(); }

/**Get reference to captured data.
       @exception Guarantee: No throw/no fail guarantee.
       @return Reference to the captured data.
    */
    constexpr auto& get() noexcept { return data; }

protected:
    T data; /**<Captured data.*/
};

}

/**Input argument with precondition.
   Passes the type as in_t<T>, but applies Pre at the callsite.

@code{.cpp}
   struct is_even {
       bool operator()(int val) { return (val % 2) == 0; }
   };

int div2(in<int, is_even> val) {
       return val.get() / 2;
   }

div2(42); //ok
   div2(13); //handler<in<int, is_even>>{}(EINVAL) invoked here
   @endcode
*/
template <typename T, typename Pre>
class in : public detail::function_data<in_t<T>> {
  public:
    /**Constructor.
       Creates a function input argument.
       @exception Guarantee: Strong exception guarantee.
       @exception handler<in<T, Pre>>{}(EINVAL) if param violates precondition.
       @param param Input.
       @param check Precondition function object.
    */
    constexpr in(in_t<T> param, Pre check = {})
      : detail::function_data<in_t<T>>{param}
    {
        if (!check(this->data))
            handler<in<T, Pre>>{}(EINVAL, "precondition violation");
    }
};

/**Output argument with postcondition.
   Passes the type as out_t<T>, but applies Post when the function returns.
   This type is noncopyable and nonmovable.

@code{.cpp}
   struct is_even {
       bool operator()(int val) { return (val % 2) == 0; }
   };

void div2(out_t<int, is_even> val) {
       val.get() = val / 2;
   }

int x = 13;
   div2(x); //ok, x == 6
   div2(x); //error, x == 3 when the function returns
   @endcode
*/
template <typename T, typename Post>
class out : public detail::function_data<out_t<T>> {
  public:
    /**Constructor.
       Creates a function output argument.
       @exception Guarantee: No throw/no fail guarantee.
       @param param Reference to output variable.
       @param check Postcondition function object.
    */
    constexpr out(out_t<T> param, Post check = {})
      : detail::function_data<out_t<T>>{param},
        copy{param},
        check{std::move(check)},
        exception_count{std::uncaught_exceptions()}
    {}

/**Destructor.
       Checks the output argument postcondition.
       @exception Guarantee: Strong exception guarantee.
       @exception handler<out<T, Post>>{}(EINVAL) if postcondition is violated.
    */
    ~out() noexcept(false) {
        if (!check(this->data)) {
            this->data = std::move(copy);
            if (exception_count == std::uncaught_exceptions())
                handler<out<T, Post>>{}(EINVAL, "postcondition violation");
        }
    }

/**Noncopyable and nonmovable.*/
    /**@{*/
    constexpr out(const out&) = delete;
    constexpr out(out&&) = delete;
    constexpr out& operator=(const out&) = delete;
    constexpr out& operator=(out&&) = delete;
    /**@}*/

protected:
    own_t<T> copy; /**<Copy of parameter for rolling back state.*/
    Post check; /**<Postcondition function object.*/
    int exception_count; /**<Exception count on construction.*/
};

/**In/Out argument that checks precondition and postcondition.
   Passes the type as inout_t<T> and checks Pre when the function is called.
   Before returning from function, Post is checked.
   This type is noncopyable and nonmovable.
   @note Pre and Post can check different conditions, but if only Pre is
   specified, this condition will also be checked before returning.

@code{.cpp}
   template <typename T>
   struct logical_not {
       template <typename U>
       bool operator()(U&& val) { return !T{}(std::forward<U>(val)); }
   };
   struct is_even {
       bool operator()(int val) { return (val % 2) == 0; }
   };

void div2(inout_t<int, is_even, logical_not<is_even>> val) {
       val.get() = val / 2;
   }

int x = 6;
   div2(x); //ok, x is even when the function is called and odd when returned
   x = 7;
   div2(x); //error, precondition is violated
   x = 8;
   div2(x); //error, x is even when returning
   @endcode
*/
template <typename T, typename Pre, typename Post = Pre>
class inout : public out<T, Post> {
  public:
    /**Constructors.
       Creates an in-out argument.
       @exception Guarantee: Strong exception guarantee.
       @exception handler<inout<T, Pre, Post>>{}(EINVAL) if precondition is violated.
       @param param Reference to in-out variable.
       @param pre Precondition function object.
       @param post Postcondition function object.
    */
    /**@{*/
    constexpr inout(inout_t<T> param, Pre pre = {}, Post post = {})
      : out<T, Post>{param, post}
    {
        if (!pre(this->data))
            handler<inout<T, Pre, Post>>{}(EINVAL, "precondition violation");
    }
    /**@}*/
};

/**Owning function argument.
   Creates a function argument that takes ownership of the object.
   This type is noncopyable.
*/
template <typename T, typename Pre>
class own : public detail::function_data<own_t<T>>, public noncopyable {
  public:
    /**Constructor.
       Creates owning function argument.
       @exception Guarantee: Basic exception guarantee. If an exception is thrown,
       the object whose ownership was transferred is destroyed.
       @exception handler<own<T, Pre>>{}(EINVAL) if precondition is violated.
       @param param R-value reference to object to transfer ownership of.
       @param check Precondition function object.
    */
    constexpr own(own_t<T>&& param, Pre check = {})
      : detail::function_data<own_t<T>>{std::move(param)}
    {
        if (!check(this->data))
            handler<own<T, Pre>>{}(EINVAL, "precondition violation");
    }
};

/**Function return value.
   Checks Pre before returning from function.
*/
template <typename T, typename Pre>
class ret : public detail::function_data<ret_t<T>> {
  public:
    /**Constructor.
       @exception Guarantee: Strong exception guarantee.
       @exception handler<ret<T, Pre>>{}(EINVAL) if precondition is violated.
       @param retval Value to return.
       @param check Precondition function object.
    */
    constexpr ret(ret_t<T> retval, Pre check = {})
      : detail::function_data<ret_t<T>>{retval}
    {
        if (!check(this->data))
            handler<ret<T, Pre>>{}(EINVAL, "return violation");
    }
};

}

#endif //NS_UTILITY_PARAMETER_HPP

#include <print>

struct string_must_be_foo
{
    auto operator()(std::string const& s) { return s == "foo"; }
};

auto func(ns::in<std::string, string_must_be_foo> s)
{
    std::println("thanks to the precondition, this will always print foo, right? = {}", s.get());
}

auto main() -> int
{
    using namespace std::literals;

auto s = "foo"s;
    auto s_i = ns::in<std::string, string_must_be_foo>{s};
    func(s_i);
    s = "bar";
    func(s_i);
}