strong_typedef.hpp

Go to the documentation of this file.

#pragma once
 
/// @file userver/utils/strong_typedef.hpp
/// @brief @copybrief utils::StrongTypedef
 
#include <compare>
#include <functional>
#include <iosfwd>
#include <string>
#include <type_traits>
#include <utility>
 
#include <userver/compiler/impl/lifetime.hpp>
#include <userver/formats/common/meta.hpp>
#include <userver/utils/fmt_compat.hpp>
#include <userver/utils/meta.hpp>
#include <userver/utils/strong_typedef_fwd.hpp>
#include <userver/utils/underlying_value.hpp>
 
// clang-format off
#include <fmt/format.h>
#include <boost/functional/hash_fwd.hpp>
// clang-format on
 
/// @brief GoogleTest-related helpers used from headers in test-only paths.
namespace testing {
 
template <typename T>
std::string PrintToString(const T& value);
 
}  // namespace testing
 
USERVER_NAMESPACE_BEGIN
 
namespace logging {
class LogHelper;  // Forward declaration
}
 
namespace utils {
 
constexpr bool operator&(StrongTypedefOps op, StrongTypedefOps mask) noexcept {
    return utils::UnderlyingValue(op) & utils::UnderlyingValue(mask);
}
 
constexpr auto operator|(StrongTypedefOps op1, StrongTypedefOps op2) noexcept {
    return StrongTypedefOps{utils::UnderlyingValue(op1) | utils::UnderlyingValue(op2)};
}
 
// Helpers
namespace impl::strong_typedef {
 
template <class T>
struct InitializerListImpl {
    struct DoNotMatch;
    using type = DoNotMatch;
};
 
template <class T>
requires requires { typename T::value_type; }
struct InitializerListImpl<T> {
    using type = std::initializer_list<typename T::value_type>;
};
 
// We have to invent this alias to avoid hard error in StrongTypedef<Tag, T> for
// types T that does not have T::value_type.
template <class T>
using InitializerList = typename InitializerListImpl<T>::type;
 
template <class T, class U>
constexpr void CheckStrongCompare() {
    static_assert(
        std::is_same_v<typename T::UnderlyingType, typename U::UnderlyingType> &&
            std::is_same_v<typename T::TagType, typename U::TagType> && T::kOps == U::kOps &&
            (T::kOps & StrongTypedefOps::kCompareStrong),
        "Comparing those StrongTypedefs is forbidden"
    );
}
 
template <class Typedef>
constexpr void CheckTransparentCompare() {
    static_assert(
        Typedef::kOps & StrongTypedefOps::kCompareTransparentOnly,
        "Comparing this StrongTypedef to a raw value is forbidden"
    );
}
 
template <class T>
const auto& UnwrapIfStrongTypedef(const T& value) {
    if constexpr (IsStrongTypedef<T>) {
        return value.GetUnderlying();
    } else {
        return value;
    }
}
 
// For 'std::string', begin-end methods are not forwarded, because otherwise
// it might get serialized as an array.
template <typename T>
concept Range = meta::kIsRange<T> && !meta::kIsInstantiationOf<std::basic_string, std::remove_const_t<T>>;
 
template <typename T>
constexpr void CheckIfAllowsLogging() {
    static_assert(IsStrongTypedef<T>);
 
    if constexpr (T::kOps & StrongTypedefOps::kNonLoggable) {
        static_assert(!sizeof(T), "Trying to print a non-loggable StrongTypedef");
    }
}
 
template <class To, class... Args>
constexpr bool IsStrongToStrongConversion() noexcept {
    static_assert(IsStrongTypedef<To>);
 
    if constexpr (sizeof...(Args) == 1) {
        using FromDecayed = std::decay_t<decltype((std::declval<Args>(), ...))>;
        if constexpr (IsStrongTypedef<FromDecayed>) {
            // Required to make `MyVariant v{MySpecialInt{10}};` compile.
            return !std::is_same_v<FromDecayed, To> &&
                   (std::is_same_v<typename FromDecayed::UnderlyingType, typename To::UnderlyingType> ||
                    std::is_arithmetic_v<typename To::UnderlyingType>);
        }
    }
 
    return false;
}
 
}  // namespace impl::strong_typedef
 
/// @ingroup userver_universal userver_containers
///
/// @brief Strong typedef for a type T.
///
/// Typical usage:
/// @snippet utils/strong_typedef_test.cpp  StrongTypedef typical usage
///
/// Has all the:
/// * comparison (see "Operators" below)
/// * hashing
/// * streaming operators
/// * optimizaed logging for LOG_XXX()
///
/// If used with container-like type also has common STL functions:
/// * begin()
/// * end()
/// * cbegin()
/// * cend()
/// * size()
/// * empty()
/// * clear()
/// * operator[]
///
/// Operators:
///   You can customize the operators that are available by passing the third
///   argument of type StrongTypedefOps. See its docs for more info.
template <class Tag, class T, StrongTypedefOps Ops>
class StrongTypedef : public impl::strong_typedef::StrongTypedefTag {
    static_assert(!std::is_reference_v<T>);
    static_assert(!std::is_pointer_v<T>);
 
    static_assert(!std::is_reference_v<Tag>);
    static_assert(!std::is_pointer_v<Tag>);
 
public:
    using UnderlyingType = T;
    using TagType = Tag;
    static constexpr StrongTypedefOps kOps = Ops;
 
    StrongTypedef() = default;
    StrongTypedef(const StrongTypedef&) = default;
    StrongTypedef(StrongTypedef&&) noexcept = default;
    StrongTypedef& operator=(const StrongTypedef&) = default;
    StrongTypedef& operator=(StrongTypedef&&) noexcept = default;
 
    constexpr StrongTypedef(impl::strong_typedef::InitializerList<T> lst)
        : data_(lst)
    {}
 
    template <typename... Args>
    requires std::is_constructible_v<T, Args...>
    constexpr explicit StrongTypedef(Args&&... args) noexcept(noexcept(T(std::forward<Args>(args)...)))
        : data_(std::forward<Args>(args)...)
    {
        using impl::strong_typedef::IsStrongToStrongConversion;
        static_assert(
            !IsStrongToStrongConversion<StrongTypedef, Args...>(),
            "Attempt to convert one StrongTypedef to another. Use "
            "utils::StrongCast to do that"
        );
    }
 
    constexpr explicit operator const T&() const& noexcept USERVER_IMPL_LIFETIME_BOUND { return data_; }
    constexpr explicit operator T() && noexcept { return std::move(data_); }
    constexpr explicit operator T&() & noexcept USERVER_IMPL_LIFETIME_BOUND { return data_; }
 
    constexpr const T& GetUnderlying() const& noexcept USERVER_IMPL_LIFETIME_BOUND { return data_; }
    constexpr T GetUnderlying() && noexcept { return std::move(data_); }
    constexpr T& GetUnderlying() & noexcept USERVER_IMPL_LIFETIME_BOUND { return data_; }
 
    auto begin()
    requires impl::strong_typedef::Range<T>
    {
        return std::begin(data_);
    }
 
    auto end()
    requires impl::strong_typedef::Range<T>
    {
        return std::end(data_);
    }
 
    auto begin() const
    requires impl::strong_typedef::Range<T>
    {
        return std::begin(data_);
    }
 
    auto end() const
    requires impl::strong_typedef::Range<T>
    {
        return std::end(data_);
    }
 
    auto cbegin() const
    requires impl::strong_typedef::Range<T>
    {
        return std::cbegin(data_);
    }
 
    auto cend() const
    requires impl::strong_typedef::Range<T>
    {
        return std::cend(data_);
    }
 
    auto size() const
    requires meta::kIsSizable<T>
    {
        return std::size(data_);
    }
 
    auto empty() const { return data_.empty(); }
 
    auto clear() { return data_.clear(); }
 
    template <class Arg>
    decltype(auto) operator[](Arg&& i) {
        return data_[std::forward<Arg>(i)];
    }
    template <class Arg>
    decltype(auto) operator[](Arg&& i) const {
        return data_[std::forward<Arg>(i)];
    }
 
private:
    T data_{};
};
 
// Relational operators
 
// NOLINTNEXTLINE(cppcoreguidelines-macro-usage)
#define UTILS_STRONG_TYPEDEF_REL_OP(OPERATOR)
    template <
        class T,
        class U,
        std::enable_if_t<
            impl::strong_typedef::IsStrongTypedef<T> || impl::strong_typedef::IsStrongTypedef<U>,
            int> /*Enable*/
        = 0>
    constexpr auto operator OPERATOR(const T& lhs, const U& rhs)
        ->decltype(impl::strong_typedef::UnwrapIfStrongTypedef(lhs
        ) OPERATOR impl::strong_typedef::UnwrapIfStrongTypedef(rhs)) {
        if constexpr (impl::strong_typedef::IsStrongTypedef<T>) {
            if constexpr (impl::strong_typedef::IsStrongTypedef<U>) {
                impl::strong_typedef::CheckStrongCompare<T, U>();
                return lhs.GetUnderlying() OPERATOR rhs.GetUnderlying();
            } else {
                impl::strong_typedef::CheckTransparentCompare<T>();
                return lhs.GetUnderlying() OPERATOR rhs;
            }
        } else {
            impl::strong_typedef::CheckTransparentCompare<U>();
            return lhs OPERATOR rhs.GetUnderlying();
        }
    }
 
// Replacing std::enable_if_t with constraints leads to the return type always being computed,
// which results in infinite recursion for non-StrongTypedef types.
// NOLINTBEGIN(modernize-use-constraints)
UTILS_STRONG_TYPEDEF_REL_OP(==)
UTILS_STRONG_TYPEDEF_REL_OP(!=)
UTILS_STRONG_TYPEDEF_REL_OP(<)
UTILS_STRONG_TYPEDEF_REL_OP(>)
UTILS_STRONG_TYPEDEF_REL_OP(<=)
UTILS_STRONG_TYPEDEF_REL_OP(>=)
UTILS_STRONG_TYPEDEF_REL_OP(<=>)
// NOLINTEND(modernize-use-constraints)
 
#undef UTILS_STRONG_TYPEDEF_REL_OP
 
/// Ostreams and Logging
 
template <class Tag, class T, StrongTypedefOps Ops>
std::ostream& operator<<(std::ostream& os, const StrongTypedef<Tag, T, Ops>& v) {
    impl::strong_typedef::CheckIfAllowsLogging<StrongTypedef<Tag, T, Ops>>();
    return os << v.GetUnderlying();
}
 
template <class Tag, class T, StrongTypedefOps Ops>
logging::LogHelper& operator<<(logging::LogHelper& os, const StrongTypedef<Tag, T, Ops>& v) {
    impl::strong_typedef::CheckIfAllowsLogging<StrongTypedef<Tag, T, Ops>>();
    return os << v.GetUnderlying();
}
 
// UnderlyingValue
template <class Tag, class T, StrongTypedefOps Ops>
constexpr decltype(auto) UnderlyingValue(const StrongTypedef<Tag, T, Ops>& v) noexcept {
    return v.GetUnderlying();
}
 
template <class Tag, class T, StrongTypedefOps Ops>
constexpr T UnderlyingValue(StrongTypedef<Tag, T, Ops>&& v) noexcept {
    return std::move(v).GetUnderlying();
}
 
constexpr bool IsStrongTypedefLoggable(StrongTypedefOps ops) { return !(ops & StrongTypedefOps::kNonLoggable); }
 
// Serialization
 
template <impl::strong_typedef::IsStrongTypedef T, formats::common::IsFormatValue Value>
T Parse(const Value& source, formats::parse::To<T>) {
    return T{source.template As<typename T::UnderlyingType>()};
}
 
template <impl::strong_typedef::IsStrongTypedef T, typename Value>
Value Serialize(const T& object, formats::serialize::To<Value>) {
    impl::strong_typedef::CheckIfAllowsLogging<T>();
    return typename Value::Builder(object.GetUnderlying()).ExtractValue();
}
 
template <impl::strong_typedef::IsStrongTypedef T, typename StringBuilder>
void WriteToStream(const T& object, StringBuilder& sw) {
    impl::strong_typedef::CheckIfAllowsLogging<T>();
    WriteToStream(object.GetUnderlying(), sw);
}
 
template <typename Tag, StrongTypedefOps Ops>
std::string ToString(const StrongTypedef<Tag, std::string, Ops>& object) {
    impl::strong_typedef::CheckIfAllowsLogging<StrongTypedef<Tag, std::string, Ops>>();
    return object.GetUnderlying();
}
 
template <typename Tag, meta::kIsInteger T, StrongTypedefOps Ops>
std::string ToString(const StrongTypedef<Tag, T, Ops>& object) {
    impl::strong_typedef::CheckIfAllowsLogging<StrongTypedef<Tag, std::string, Ops>>();
    return std::to_string(object.GetUnderlying());
}
 
template <typename Tag, std::floating_point T, StrongTypedefOps Ops>
std::string ToString(const StrongTypedef<Tag, T, Ops>& object) {
    impl::strong_typedef::CheckIfAllowsLogging<StrongTypedef<Tag, std::string, Ops>>();
    return fmt::to_string(object.GetUnderlying());
}
 
// Explicit casting
 
/// Explicitly cast from one strong typedef to another, to replace constructions
/// `SomeStrongTydef{utils::UnderlyingValue(another_strong_val)}` with
/// `utils::StrongCast<SomeStrongTydef>(another_strong_val)`
template <typename Target, typename Tag, typename T, StrongTypedefOps Ops>
constexpr Target StrongCast(const StrongTypedef<Tag, T, Ops>& src) {
    static_assert(impl::strong_typedef::IsStrongTypedef<Target>, "Expected strong typedef as target type");
    static_assert(
        std::is_convertible_v<T, typename Target::UnderlyingType>,
        "Source strong typedef underlying type must be convertible to "
        "target's underlying type"
    );
    return Target{src.GetUnderlying()};
}
 
template <typename Target, typename Tag, typename T, StrongTypedefOps Ops>
constexpr Target StrongCast(StrongTypedef<Tag, T, Ops>&& src) {
    static_assert(impl::strong_typedef::IsStrongTypedef<Target>, "Expected strong typedef as target type");
    static_assert(
        std::is_convertible_v<T, typename Target::UnderlyingType>,
        "Source strong typedef underlying type must be convertible to "
        "target's underlying type"
    );
    return Target{std::move(src).GetUnderlying()};
}
 
template <class Tag, class T, StrongTypedefOps Ops>
std::size_t hash_value(const StrongTypedef<Tag, T, Ops>& v) {  // NOLINT(readability-identifier-naming)
    return boost::hash<T>{}(v.GetUnderlying());
}
 
/// gtest formatter for utils::StrongTypedef
template <class Tag, class T, StrongTypedefOps Ops>
void PrintTo(const StrongTypedef<Tag, T, Ops>& v, std::ostream* os) {
    *os << testing::PrintToString(v.GetUnderlying());
}
 
/// A StrongTypedef for data that MUST NOT be logged or outputted in some other
/// way. Also prevents the data from appearing in backtrace prints of debugger.
///
/// @snippet storages/secdist/secdist_test.cpp UserPasswords
template <class Tag, class T>
using NonLoggable = StrongTypedef<Tag, T, StrongTypedefOps::kCompareStrong | StrongTypedefOps::kNonLoggable>;
 
}  // namespace utils
 
USERVER_NAMESPACE_END
 
// std::hash support
template <class Tag, class T, USERVER_NAMESPACE::utils::StrongTypedefOps Ops>
struct std::hash<USERVER_NAMESPACE::utils::StrongTypedef<Tag, T, Ops>> : std::hash<T> {
    std::size_t operator()(const USERVER_NAMESPACE::utils::StrongTypedef<Tag, T, Ops>& v
    ) const noexcept(noexcept(std::declval<const std::hash<T>>()(std::declval<const T&>()))) {
        return std::hash<T>::operator()(v.GetUnderlying());
    }
};
 
// fmt::format support
template <USERVER_NAMESPACE::utils::impl::strong_typedef::IsStrongTypedef T, class Char>
struct fmt::formatter<T, Char> : fmt::formatter<typename T::UnderlyingType, Char> {
    template <typename FormatContext>
    auto format(const T& v, FormatContext& ctx) USERVER_FMT_CONST {
        USERVER_NAMESPACE::utils::impl::strong_typedef::CheckIfAllowsLogging<T>();
        return fmt::formatter<typename T::UnderlyingType, Char>::format(v.GetUnderlying(), ctx);
    }
};