utils.hpp

/* Copyright 2023 Jack A Bernard Jr.
 *
 * Licensed under the Apache License, Version 2.0 (the License);
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an AS IS BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
 
/// @mainpage Sumty 🍵
///
/// `sumty` is a header-only C++20 library that provides "better" sum types.
/// The C++ standard library provides `std::variant`, `std::optional`, and
/// `std::exepcted` (as of C++23), but these have some limitiations that
/// `sumty` aims to remove.
///
/// `sumty` provides four sum types, 3 of which correspond to one of the
/// STL types mentioned above.
///
/// * @ref sumty::variant "variant" - improved `std::variant`
/// * @ref sumty::option "option" - improved `std::optional`
/// * @ref sumty::result "result" - improved `std::expected`
/// * @ref sumty::error_set "error_set" - no STL equivalent but similar to
/// `std::variant`
///
/// These sum types differ from those in the STL in a number of ways.
/// Primarily, `sumty`'s sum types extend alternatives to support
/// references (lvalue and rvalue) and `void`. `sumty` also guarantees a
/// few size optimizations that applies to all sum types, the boil down
/// to taking advantage of empty types and the invariant that lvalue
/// references are not null. Some size optimization examples are listed
/// below.
///
///   * `sizeof(variant<std::monostate, std::monostate>) == sizeof(bool)`
///   * `sizeof(option<int&>) == sizeof(void*)`
///   * `sizeof(result<void, void>) == sizeof(bool)`
///   * `sizeof(error_set<empty1, empty2, empty3>) == sizeof(uint8_t)`
 
#ifndef SUMTY_UTILS_HPP
#define SUMTY_UTILS_HPP
 
#include <cstddef>
#include <functional>
#include <type_traits>
#include <utility>
 
#if defined(__GNUC__) && !defined(__clang__)
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wterminate"
#endif
 
#if defined(_MSC_VER)
#pragma warning(push)
#pragma warning(disable : 4297)
#pragma warning(disable : 4645)
#pragma warning(disable : 4702)
#endif
 
#if defined(_MSC_VER) && !defined(__clang__)
#define SUMTY_NO_UNIQ_ADDR [[msvc::no_unique_address]]
#else
#define SUMTY_NO_UNIQ_ADDR [[no_unique_address]]
#endif
 
namespace sumty {
 
using std::in_place_index_t;
using std::in_place_t;
using std::in_place_type_t;
using in_place_error_t = in_place_index_t<1>;
 
using std::in_place;
using std::in_place_index;
using std::in_place_type;
static inline constexpr in_place_error_t in_place_error = in_place_index<1>;
 
/// @relates variant
template <size_t N>
struct index_t {
    template <typename S>
    constexpr
#ifndef DOXYGEN
        decltype(auto)
#else
        DEDUCED
#endif
        operator()(S&& s) const
#ifndef DOXYGEN
        requires requires { std::forward<S>(s)[index_t<N>{}]; }
#endif
    {
        return std::forward<S>(s)[index_t<N>{}];
    }
};
 
/// @relates index_t
template <size_t N>
static inline constexpr index_t<N> index{};
 
/// @relates index_t
template <size_t N>
static inline constexpr index_t<N> index_v{};
 
/// @relates variant
template <typename T>
struct type_t {
    template <typename S>
    constexpr
#ifndef DOXYGEN
        decltype(auto)
#else
        DEDUCED
#endif
        operator()(S&& s) const
#ifndef DOXYGEN
        requires requires { std::forward<S>(s)[type_t<T>{}]; }
#endif
    {
        return std::forward<S>(s)[type_t<T>{}];
    }
};
 
/// @relates type_t
template <typename T>
static inline constexpr type_t<T> type{};
 
/// @relates type_t
template <typename T>
static inline constexpr type_t<T> type_v{};
 
/// @relates variant
struct void_t {
    constexpr void_t() noexcept = default;
 
    constexpr void_t(const void_t&) noexcept = default;
 
    constexpr void_t(void_t&&) noexcept = default;
 
    constexpr ~void_t() noexcept = default;
 
    constexpr void_t& operator=(const void_t&) noexcept = default;
 
    constexpr void_t& operator=(void_t&&) noexcept = default;
 
    template <typename T>
        requires(std::is_default_constructible_v<T>)
    explicit constexpr operator T() const
        noexcept(std::is_nothrow_default_constructible_v<T>) {
        return T{};
    }
};
 
/// @relates void_t
static inline constexpr void_t void_v{};
 
/// @relates option
struct none_t {};
 
/// @relates none_t
static inline constexpr none_t none{};
 
/// @relates none_t
static inline constexpr none_t none_v{};
 
/// @brief A type that can never be instantiated
///
/// @details
/// The @ref never type is a special type that has no possible values. In
/// isolation, it has no purpose, but it can be used with a sum type to
/// represent an alternative that is never used. The sum types of `sumty`
/// optimize around @ref never, using the assumption that an alternative of the
/// type @ref never will never be used.
///
/// The primary use case for @ref never is as the error type for a @ref result.
/// A generic API might require that a function return a @ref result, but the
/// user's function may not have error code paths. In this case, the user could
/// return a `result<T, never>`. Since sumty optimizes around @ref never, the
/// `result<T, never>` will have the same size as `T`, and also be an empty type
/// if `T` is an empty type.
///
/// Despite there being no way to instantiate a @ref never (without invoking
/// undefined behavior), @ref never is copyable and moveable. This ensure that
/// using @ref never as an alternative of a sum type does not make that type
/// uncopyable or immovable.
///
/// @ref never can also be implicitly converted to any other type. Although
/// such a conversion should never be possible at runtime, it allows sum types
/// with a @ref never alternative to be converted. For example, a
/// `result<T, never>` can be implicitly converted to a
/// `result<T, my_error>` (assuming that `my_error` is a valid type). Since the
/// @ref never error type can never be instantiated, the runtime conversion is
/// always on the ok alternative (`T` -> `T` in our example).
struct never {
  private:
    // NOLINTNEXTLINE(bugprone-exception-escape)
    [[noreturn]] static constexpr void unreachable() noexcept {
        if (std::is_constant_evaluated()) {
#ifndef _MSC_VER
            throw 0; // NOLINT(hicpp-exception-baseclass)
#else
            return;
#endif
        } else {
#ifdef __cpp_lib_unreachable
            std::unreachable();
#elif defined(_MSC_VER) && !defined(__clang__)
            __assume(false);
#elif defined(__GNUC__)
            __builtin_unreachable();
#else
            for (;;) {}
#endif
        }
    }
 
  public:
    never() = delete;
 
    // These special constructors/operators are intentionally non-trivial
    // so that instantiation of this type is always UB. This type already
    // has no valid constructor for creating a new instance from scratch.
    // Making these non-trivial ensures that it is also UB to instantiate
    // this type by reinterpretation, whether that be by using
    // reinterpret_cast, std::bit_cast, or anything else. Thus, the type
    // can never be instantiated, but does not prevent copyability or
    // moveability when used in a sum type.
 
    [[noreturn]] constexpr never([[maybe_unused]] const never& other) noexcept {
        unreachable();
    }
 
    [[noreturn]] constexpr never([[maybe_unused]] never&& other) noexcept { unreachable(); }
 
    [[noreturn]] constexpr ~never() noexcept { unreachable(); }
 
    // NOLINTNEXTLINE(cert-oop54-cpp)
    constexpr never& operator=([[maybe_unused]] const never& rhs) noexcept {
        unreachable();
        return *this;
    }
 
    constexpr never& operator=([[maybe_unused]] never&& rhs) noexcept {
        unreachable();
        return *this;
    }
 
    // This type can be implicitly converted to any other type, except
    // that in reality this can never happen, since this type can never
    // be instantiated. For example, this allows a `result<T, never>` to
    // convert to `result<T, E>`, for any `E`.
    template <typename T>
    // NOLINTNEXTLINE(bugprone-exception-escape, hicpp-explicit-conversions)
    [[noreturn]] constexpr operator T() const noexcept {
        unreachable();
        throw 0; // NOLINT(hicpp-exception-baseclass)
    }
};
 
/// @relates variant
template <typename... T>
struct overload : T... {
    using T::operator()...;
};
 
template <typename... T>
overload(T...) -> overload<T...>;
 
/// @brief Invokes a callable and returns the result, transforming `void` to @ref void_t
///
/// @details
/// This function is mostly equivalent to `std::invoke`. The difference is that if the
/// return type of the invocable is `void`, this function instead returns an instance of
/// @ref void_t.
///
/// When dealing with generic code, `void` often presents a problem since an
/// instantiation of `void` can't exist, despite the fact that functions successfully
/// return `void`. In order to simplify generic code, this function ensures that calling
/// a function that returns `void` instead returns a value that can exist, can be bound
/// to a variable, and can be passed into another function.
///
/// ## Example
/// ```
/// option<void> opt;
///
/// opt.emplace(invoke([]{}));
///
/// assert(opt.has_value());
/// ```
///
/// @param f The invocable object
/// @param args The arguments to be passed to the invocable
template <typename F, typename... Args>
constexpr
#ifndef DOXYGEN
    std::conditional_t<std::is_void_v<std::invoke_result_t<F, Args...>>,
                       void_t,
                       std::invoke_result_t<F, Args...>>
#else
    DEDUCED
#endif
    invoke(F&& f, Args&&... args) {
    using ret_t = std::invoke_result_t<F, Args...>;
    if constexpr (std::is_void_v<ret_t>) {
        std::invoke(std::forward<F>(f), std::forward<Args>(args)...);
        return void_v;
    } else {
        return std::invoke(std::forward<F>(f), std::forward<Args>(args)...);
    }
}
 
} // namespace sumty
 
#if defined(__GNUC__) && !defined(__clang__)
#pragma GCC diagnostic pop
#endif
 
#if defined(_MSC_VER)
#pragma warning(pop)
#endif
 
#endif