kind.h

Go to the documentation of this file.

//--------------------------------------------------------------------------------------------------
//
//  UnitConversion: A compile-time c++23 unit conversion library with no dependencies
//
//--------------------------------------------------------------------------------------------------
//
// The MIT License (MIT)
//
// Permission is hereby granted, free of charge, to any person obtaining a copy of this software
// and associated documentation files (the "Software"), to deal in the Software without
// restriction, including without limitation the rights to use, copy, modify, merge, publish,
// distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the
// Software is furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in all copies or
// substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
// BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
// DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
//
//--------------------------------------------------------------------------------------------------
//
// Copyright (c) 2016 Nic Holthaus
//
//--------------------------------------------------------------------------------------------------
//
// ATTRIBUTION:
// Parts of this work have been adapted from:
// http://stackoverflow.com/questions/35069778/create-comparison-trait-for-template-classes-whose-parameters-are-in-a-different
// http://stackoverflow.com/questions/28253399/check-traits-for-all-variadic-template-arguments/28253503
// http://stackoverflow.com/questions/36321295/rational-approximation-of-square-root-of-stdratio-at-compile-time?noredirect=1#comment60266601_36321295
// https://github.com/swatanabe/cppnow17-units
//
//--------------------------------------------------------------------------------------------------
//
//
//--------------------------------------------------------------------------------------------------
 
#pragma once
 
#ifndef UNIT_KIND_H
#define UNIT_KIND_H
 
#include <units/core.h>
 
#include <algorithm>
#include <cstddef>
#include <ostream>
#include <string>
 
namespace units
{
    //----------------------------------------------------------------------------------------------------------------------
    //  AFFINE POINT / DELTA WRAPPERS
    //----------------------------------------------------------------------------------------------------------------------
    // Opt-in wrappers that make the point-vs-amount distinction explicit in the type. `absolute<U>` is a POINT on
    // a scale (it carries the unit's datum — 0 degC is 273.15 K); `delta<U>` is an AMOUNT (offset-free — a 10 degC
    // delta is a 10 K delta). Reach for these where the distinction matters (temperatures, epochs vs durations,
    // absolute vs gauge pressure, positions vs displacements); for a non-affine unit the datum is zero, so the two
    // coincide numerically. The type algebra:
    //   absolute - absolute -> delta      (the datum offsets cancel)
    //   absolute +/- delta   -> absolute  (move the point by a relative amount)
    //   delta +/- delta      -> delta
    //   delta * / scalar     -> delta
    //   absolute + absolute  -> ill-formed
    //
    // The wrappers exist only where <units/kind.h> is included, so a user's own `absolute`/`delta` names are
    // undisturbed otherwise. They live in `inline namespace affine`, so `units::absolute` and
    // `units::affine::absolute` name the same type; the `affine::` qualifier disambiguates when needed.
 
    namespace detail
    {
        template<UnitType U>
        using delta_unit_t = unit<traits::strong_t<conversion_factor<typename traits::conversion_factor_traits<typename traits::unit_traits<U>::conversion_factor>::conversion_ratio,
                                             typename traits::conversion_factor_traits<typename traits::unit_traits<U>::conversion_factor>::dimension_type,
                                             typename traits::conversion_factor_traits<typename traits::unit_traits<U>::conversion_factor>::pi_exponent_ratio, std::ratio<0>>>,
            typename traits::unit_traits<U>::underlying_type, typename traits::unit_traits<U>::numerical_scale_type>;

        template<UnitType From, UnitType To>
        inline constexpr bool is_losslessly_point_convertible_unit =
            is_losslessly_convertible_unit<From, To> &&
            (std::is_floating_point_v<typename traits::unit_traits<To>::underlying_type> ||
                std::ratio_equal_v<typename traits::conversion_factor_traits<typename traits::unit_traits<From>::conversion_factor>::translation_ratio,
                    typename traits::conversion_factor_traits<typename traits::unit_traits<To>::conversion_factor>::translation_ratio>);

        template<UnitType U, UnitType V>
        using absolute_result_unit_t = std::conditional_t<is_losslessly_point_convertible_unit<V, U>, U, traits::replace_underlying_t<U, floating_point_promotion_t<typename traits::unit_traits<U>::underlying_type>>>;

        template<UnitType U, UnitType V>
        using delta_result_unit_t = std::conditional_t<is_losslessly_convertible_unit<delta_unit_t<V>, delta_unit_t<U>>, U,
            traits::replace_underlying_t<U, floating_point_promotion_t<typename traits::unit_traits<U>::underlying_type>>>;
    } // namespace detail
 
    inline namespace affine
    {
        template<UnitType U>
        class absolute;
        template<UnitType U>
        class delta;
        template<std::size_t N>
        struct fixed_string;
        template<fixed_string Tag, UnitType U>
        class basic_kind;
 // DOXYGEN IGNORE
        namespace wrap_detail
        {
            // `to<Target>()` on every wrapper follows ONE rule: the TARGET type decides the result. A plain-unit
            // target unwraps to that plain unit (applying the wrapper's own conversion rule); a WRAPPER target keeps
            // that wrapper. These detect whether a `to<>` target is a wrapper (so the method returns the wrapper) or
            // a plain unit (so it unwraps). Declared before the wrappers so their `to<>` can use them.
            template<class T>
            inline constexpr bool is_wrapper = false;
            template<UnitType U>
            inline constexpr bool is_wrapper<absolute<U>> = true;
            template<UnitType U>
            inline constexpr bool is_wrapper<delta<U>> = true;
            template<fixed_string Tag, UnitType U>
            inline constexpr bool is_wrapper<basic_kind<Tag, U>> = true;

            template<class Wrapper>
            using wrapper_unit_t = typename Wrapper::unit_type;

            template<class Wrapper>
            constexpr auto unwrap(const Wrapper& w) noexcept
            {
                return w.template to<typename Wrapper::unit_type>();
            }

            template<fixed_string...>
            inline constexpr bool dependent_false = false;
            template<class...>
            inline constexpr bool dependent_false_t = false;

            template<class LhsUnit, class RhsUnit>
            constexpr std::partial_ordering order(const LhsUnit& lhs, const RhsUnit& rhs) noexcept
            {
                if (lhs < rhs)
                    return std::partial_ordering::less;
                if (rhs < lhs)
                    return std::partial_ordering::greater;
                if (lhs == rhs)
                    return std::partial_ordering::equivalent;
                return std::partial_ordering::unordered;
            }
        } // namespace wrap_detail // END DOXYGEN IGNORE
    } // inline namespace affine (forward declarations only)
 
    // The wrapper traits + concepts are defined here — after the forward declarations, before the class bodies — so
    // each wrapper's `to<>` overloads can constrain on `AbsoluteType`/`DeltaType`/`KindType`.
    namespace traits
    { // DOXYGEN IGNORE
        namespace detail
        {
            template<class T>
            struct is_absolute_impl : std::false_type
            {
            };
            template<UnitType U>
            struct is_absolute_impl<units::affine::absolute<U>> : std::true_type
            {
            };
 
            template<class T>
            struct is_delta_impl : std::false_type
            {
            };
            template<UnitType U>
            struct is_delta_impl<units::affine::delta<U>> : std::true_type
            {
            };
 
            template<class T>
            struct is_kind_impl : std::false_type
            {
            };
            template<units::affine::fixed_string Tag, UnitType U>
            struct is_kind_impl<units::affine::basic_kind<Tag, U>> : std::true_type
            {
            };
        } // namespace detail // END DOXYGEN IGNORE

        template<class T>
        struct is_absolute : detail::is_absolute_impl<std::remove_cv_t<T>>
        {
        };
 
        template<class T>
        inline constexpr bool is_absolute_v = is_absolute<T>::value;

        template<class T>
        struct is_delta : detail::is_delta_impl<std::remove_cv_t<T>>
        {
        };
 
        template<class T>
        inline constexpr bool is_delta_v = is_delta<T>::value;

        template<class T>
        struct is_kind : detail::is_kind_impl<std::remove_cv_t<T>>
        {
        };
 
        template<class T>
        inline constexpr bool is_kind_v = is_kind<T>::value;
    } // namespace traits

    template<class T>
    concept AbsoluteType = traits::is_absolute_v<T>;

    template<class T>
    concept DeltaType = traits::is_delta_v<T>;

    template<class T>
    concept KindType = traits::is_kind_v<T>;
 
    inline namespace affine
    {
        //  ----------------------------------------------------------------------------
        //  CLASS       absolute
        //  ----------------------------------------------------------------------------
        //  ----------------------------------------------------------------------------
        template<UnitType U>
        class absolute
        {
        public:
            using unit_type       = U;                                               
            using underlying_type = typename traits::unit_traits<U>::underlying_type; 
 
            constexpr absolute() noexcept = default;
            constexpr explicit absolute(const U& point) noexcept : m_point(point) {}

            constexpr explicit absolute(underlying_type value) noexcept : m_point(value) {}

            constexpr auto value() const noexcept { return m_point.value(); }
            constexpr auto raw() const noexcept { return m_point.raw(); }
            constexpr auto to_linearized() const noexcept { return m_point.to_linearized(); }
            [[nodiscard]] constexpr const char* name() const noexcept { return m_point.name(); }
            [[nodiscard]] constexpr const char* abbreviation() const noexcept { return m_point.abbreviation(); }

            template<ArithmeticType Arithmetic>
            constexpr Arithmetic to() const noexcept
            {
                return m_point.template to<Arithmetic>();
            }

            template<UnitType PlainTarget>
                requires traits::is_same_dimension_unit_v<U, PlainTarget>
            constexpr PlainTarget to() const noexcept
            {
                return PlainTarget(m_point); // the datum participates in the unit conversion
            }

            template<AbsoluteType WrapperTarget>
                requires traits::is_same_dimension_unit_v<U, typename WrapperTarget::unit_type>
            constexpr WrapperTarget to() const noexcept
            {
                return WrapperTarget(typename WrapperTarget::unit_type(m_point));
            }
 
        private:
            U m_point{}; 
        };
 
        //  ----------------------------------------------------------------------------
        //  CLASS       delta
        //  ----------------------------------------------------------------------------
        //  ----------------------------------------------------------------------------
        template<UnitType U>
        class delta
        {
        public:
            using unit_type       = U;                                               
            using underlying_type = typename traits::unit_traits<U>::underlying_type; 
 
            constexpr delta() noexcept = default;
            constexpr explicit delta(const U& amount) noexcept : m_amount(amount) {}

            constexpr explicit delta(underlying_type value) noexcept : m_amount(value) {}

            constexpr auto value() const noexcept { return m_amount.value(); }
            constexpr auto raw() const noexcept { return m_amount.raw(); }
            constexpr auto to_linearized() const noexcept { return m_amount.to_linearized(); }
            [[nodiscard]] constexpr const char* name() const noexcept { return m_amount.name(); }
            [[nodiscard]] constexpr const char* abbreviation() const noexcept { return m_amount.abbreviation(); }

            template<ArithmeticType Arithmetic>
            constexpr Arithmetic to() const noexcept
            {
                return m_amount.template to<Arithmetic>();
            }

            template<UnitType PlainTarget>
                requires traits::is_same_dimension_unit_v<U, PlainTarget>
            constexpr PlainTarget to() const noexcept
            {
                static_assert(units::detail::is_losslessly_convertible_unit<units::detail::delta_unit_t<U>, units::detail::delta_unit_t<PlainTarget>>,
                    "units::delta::to<PlainTarget>(): converting this delta into PlainTarget would truncate an "
                    "integer value; convert to a floating-point delta first (e.g. delta<meters<double>>) if intended.");
                return PlainTarget(scaled_to<PlainTarget>());
            }

            template<DeltaType WrapperTarget>
                requires traits::is_same_dimension_unit_v<U, typename WrapperTarget::unit_type>
            constexpr WrapperTarget to() const noexcept
            {
                using V = typename WrapperTarget::unit_type;
                static_assert(units::detail::is_losslessly_convertible_unit<units::detail::delta_unit_t<U>, units::detail::delta_unit_t<V>>,
                    "units::delta::to<delta<V>>(): converting this delta into V would truncate an integer value; "
                    "convert to a floating-point delta first (e.g. delta<meters<double>>) if intended.");
                return WrapperTarget(scaled_to<V>());
            }
 
        private:
            U m_amount{}; 

            template<UnitType V>
            constexpr V scaled_to() const noexcept
            {
                const units::detail::delta_unit_t<U> here(m_amount.raw());
                const units::detail::delta_unit_t<V> there(here); // scale-only conversion (no translation on either)
                return V(there.raw());
            }
        };
 
        //  ----------------------------------------------------------------------------
        //  CLASS       fixed_string
        //  ----------------------------------------------------------------------------
        //  ----------------------------------------------------------------------------
        template<std::size_t N>
        struct fixed_string
        {
            char value[N]{}; 
 
            constexpr fixed_string(const char (&str)[N]) noexcept { std::copy_n(str, N, value); }

            template<std::size_t M>
            constexpr bool operator==(const fixed_string<M>& rhs) const noexcept
            {
                if constexpr (N != M)
                    return false;
                else
                    return std::equal(value, value + N, rhs.value);
            }
        };
        template<std::size_t N>
        fixed_string(const char (&)[N]) -> fixed_string<N>;
 
        //  ----------------------------------------------------------------------------
        //  CLASS       kind
        //  ----------------------------------------------------------------------------
        //  ----------------------------------------------------------------------------
        template<fixed_string Tag, UnitType U>
        class basic_kind
        {
        public:
            using unit_type       = U;                                               
            using underlying_type = typename traits::unit_traits<U>::underlying_type; 
 
            constexpr basic_kind() noexcept = default;

            constexpr basic_kind(const U& value) noexcept : m_value(value) {}

            constexpr explicit basic_kind(underlying_type value) noexcept : m_value(value) {}

            constexpr basic_kind& operator=(const U& value) noexcept
            {
                m_value = value;
                return *this;
            }

            static constexpr auto tag() noexcept { return Tag; }
            constexpr auto value() const noexcept { return m_value.value(); }
            constexpr auto raw() const noexcept { return m_value.raw(); }
            constexpr auto to_linearized() const noexcept { return m_value.to_linearized(); }
            [[nodiscard]] constexpr const char* abbreviation() const noexcept { return m_value.abbreviation(); }
            [[nodiscard]] std::string name() const { return std::string(Tag.value).append(" ").append(m_value.name()); }

            template<ArithmeticType Arithmetic>
            constexpr Arithmetic to() const noexcept
            {
                return m_value.template to<Arithmetic>();
            }

            template<UnitType PlainTarget>
                requires traits::is_same_dimension_unit_v<U, PlainTarget>
            constexpr PlainTarget to() const noexcept
            {
                return PlainTarget(m_value);
            }

            template<KindType WrapperTarget>
                requires(WrapperTarget::tag() == Tag && traits::is_same_dimension_unit_v<U, typename WrapperTarget::unit_type>)
            constexpr WrapperTarget to() const noexcept
            {
                return WrapperTarget(typename WrapperTarget::unit_type(m_value));
            }
 
        private:
            U m_value{}; 
        };
 
        //----------------------------------
        //  ABSOLUTE / DELTA OPERATORS
        //----------------------------------
 
        // The wrapper operators keep the LHS UNIT (the "LHS-unit tie-break") so `.value()` reads in the left
        // operand's unit — a point difference `100 degC - 32 degF` is 100 celsius-degrees. Keeping the LHS unit
        // would narrow when the LHS is a coarse integer that cannot hold the RHS losslessly, so in that case the
        // underlying is promoted to floating point (an `absolute`
        // operator uses `units::detail::absolute_result_unit_t`, datum-aware; a `delta` operator uses
        // `units::detail::delta_result_unit_t`, scale-only); the result UNIT stays the LHS unit, only the underlying
        // widens. This keeps `absolute<kilometers<int>> - absolute<meters<int>>` well-formed (a km delta with a
        // promoted underlying) instead of hard-erroring in the conversion.

        template<UnitType U, UnitType V>
            requires traits::is_same_dimension_unit_v<U, V>
        constexpr auto operator-(const absolute<U>& lhs, const absolute<V>& rhs) noexcept
        {
            // The result unit is the LHS unit (underlying promoted only if keeping U's underlying would narrow the
            // RHS). The rhs point is converted into that unit AFFINELY (offset applied), then subtracted; the datum
            // cancels, leaving an offset-free delta expressed in the LHS unit.
            using R = units::detail::absolute_result_unit_t<U, V>;
            return delta<R>(R(R(wrap_detail::unwrap(lhs)).raw() - R(wrap_detail::unwrap(rhs)).raw()));
        }

        template<UnitType U, UnitType V>
            requires traits::is_same_dimension_unit_v<U, V>
        constexpr auto operator+(const absolute<U>& lhs, const delta<V>& rhs) noexcept
        {
            using R = units::detail::absolute_result_unit_t<U, V>;
            return absolute<R>(R(R(wrap_detail::unwrap(lhs)).raw() + rhs.template to<R>().raw()));
        }

        template<UnitType U, UnitType V>
            requires traits::is_same_dimension_unit_v<V, U>
        constexpr auto operator+(const delta<V>& lhs, const absolute<U>& rhs) noexcept
        {
            return rhs + lhs;
        }

        template<UnitType U, UnitType V>
            requires traits::is_same_dimension_unit_v<U, V>
        constexpr auto operator-(const absolute<U>& lhs, const delta<V>& rhs) noexcept
        {
            using R = units::detail::absolute_result_unit_t<U, V>;
            return absolute<R>(R(R(wrap_detail::unwrap(lhs)).raw() - rhs.template to<R>().raw()));
        }

        template<UnitType U, UnitType V>
            requires traits::is_same_dimension_unit_v<U, V>
        constexpr auto operator+(const delta<U>& lhs, const delta<V>& rhs) noexcept
        {
            using R = units::detail::delta_result_unit_t<U, V>;
            return delta<R>(R(lhs.template to<R>().raw() + rhs.template to<R>().raw()));
        }

        template<UnitType U, UnitType V>
            requires traits::is_same_dimension_unit_v<U, V>
        constexpr auto operator-(const delta<U>& lhs, const delta<V>& rhs) noexcept
        {
            using R = units::detail::delta_result_unit_t<U, V>;
            return delta<R>(R(lhs.template to<R>().raw() - rhs.template to<R>().raw()));
        }

        template<UnitType U>
        constexpr delta<U> operator-(const delta<U>& d) noexcept
        {
            return delta<U>(U(-wrap_detail::unwrap(d).raw()));
        }

        template<UnitType U, ArithmeticType T>
        constexpr auto operator*(const delta<U>& lhs, T rhs) noexcept
        {
            using ScaledUnit = decltype(wrap_detail::unwrap(lhs) * rhs);
            return delta<ScaledUnit>(wrap_detail::unwrap(lhs) * rhs);
        }
        template<UnitType U, ArithmeticType T>
        constexpr auto operator*(T lhs, const delta<U>& rhs) noexcept
        {
            return rhs * lhs;
        }

        template<UnitType U, ArithmeticType T>
        constexpr auto operator/(const delta<U>& lhs, T rhs) noexcept
        {
            using ScaledUnit = decltype(wrap_detail::unwrap(lhs) / rhs);
            return delta<ScaledUnit>(wrap_detail::unwrap(lhs) / rhs);
        }

        template<UnitType U, UnitType V>
            requires traits::is_same_dimension_unit_v<U, V>
        constexpr absolute<U>& operator+=(absolute<U>& lhs, const delta<V>& rhs) noexcept
        {
            lhs = absolute<U>(U(wrap_detail::unwrap(lhs).raw() + rhs.template to<U>().raw()));
            return lhs;
        }
        template<UnitType U, UnitType V>
            requires traits::is_same_dimension_unit_v<U, V>
        constexpr absolute<U>& operator-=(absolute<U>& lhs, const delta<V>& rhs) noexcept
        {
            lhs = absolute<U>(U(wrap_detail::unwrap(lhs).raw() - rhs.template to<U>().raw()));
            return lhs;
        }

        template<UnitType U, UnitType V>
            requires traits::is_same_dimension_unit_v<U, V>
        constexpr delta<U>& operator+=(delta<U>& lhs, const delta<V>& rhs) noexcept
        {
            lhs = delta<U>(U(wrap_detail::unwrap(lhs).raw() + rhs.template to<U>().raw()));
            return lhs;
        }
        template<UnitType U, UnitType V>
            requires traits::is_same_dimension_unit_v<U, V>
        constexpr delta<U>& operator-=(delta<U>& lhs, const delta<V>& rhs) noexcept
        {
            lhs = delta<U>(U(wrap_detail::unwrap(lhs).raw() - rhs.template to<U>().raw()));
            return lhs;
        }

        template<UnitType U, ArithmeticType T>
        constexpr delta<U>& operator*=(delta<U>& lhs, T rhs) noexcept
        {
            lhs = delta<U>(U(wrap_detail::unwrap(lhs).raw() * rhs));
            return lhs;
        }
        template<UnitType U, ArithmeticType T>
        constexpr delta<U>& operator/=(delta<U>& lhs, T rhs) noexcept
        {
            lhs = delta<U>(U(wrap_detail::unwrap(lhs).raw() / rhs));
            return lhs;
        }
 
        //----------------------------------
        //  ABSOLUTE / DELTA COMPARISONS
        //----------------------------------
 
        // Comparisons reconcile to the common (finer) unit — never narrowing — so a mixed integer comparison
        // (e.g. delta<kilometers<int>> vs delta<meters<int>>) is well-formed rather than hard-erroring. A
        // comparison has no `.value()` to keep intuitive, so the common-unit reconciliation (which cannot lose an
        // equality) is the right choice here even though the arithmetic operators keep the LHS unit.
 
        // Point/amount comparisons delegate to the WRAPPED plain units' own comparison operators, so they inherit
        // the core's value-based (signedness-safe) integer comparison: a signed-rep and an unsigned-rep wrapper of
        // the same dimension compare by mathematical value, not by unsigned wraparound.

        template<UnitType U, UnitType V>
            requires traits::is_same_dimension_unit_v<U, V>
        constexpr bool operator==(const absolute<U>& lhs, const absolute<V>& rhs) noexcept
        {
            return wrap_detail::unwrap(lhs) == wrap_detail::unwrap(rhs);
        }
        template<UnitType U, UnitType V>
            requires traits::is_same_dimension_unit_v<U, V>
        constexpr std::partial_ordering operator<=>(const absolute<U>& lhs, const absolute<V>& rhs) noexcept
        {
            return wrap_detail::order(wrap_detail::unwrap(lhs), wrap_detail::unwrap(rhs));
        }
 
        // Reconcile two deltas to the common UNIT (scale only) while keeping EACH side's own underlying type — so a
        // signed and an unsigned delta reach the plain-unit comparison in their own representations, and the core's
        // value-based comparison orders them by mathematical value rather than wrapping the negative side.
        template<UnitType U, UnitType V>
            requires traits::is_same_dimension_unit_v<U, V>
        constexpr bool operator==(const delta<U>& lhs, const delta<V>& rhs) noexcept
        {
            using C     = std::common_type_t<U, V>;
            using CLhs  = traits::replace_underlying_t<C, typename traits::unit_traits<U>::underlying_type>;
            using CRhs  = traits::replace_underlying_t<C, typename traits::unit_traits<V>::underlying_type>;
            return lhs.template to<CLhs>() == rhs.template to<CRhs>();
        }
        template<UnitType U, UnitType V>
            requires traits::is_same_dimension_unit_v<U, V>
        constexpr std::partial_ordering operator<=>(const delta<U>& lhs, const delta<V>& rhs) noexcept
        {
            using C    = std::common_type_t<U, V>;
            using CLhs = traits::replace_underlying_t<C, typename traits::unit_traits<U>::underlying_type>;
            using CRhs = traits::replace_underlying_t<C, typename traits::unit_traits<V>::underlying_type>;
            return wrap_detail::order(lhs.template to<CLhs>(), rhs.template to<CRhs>());
        }
 
        //----------------------------------
        //  ABSOLUTE / DELTA FORMATTING
        //----------------------------------
 
        // A wrapper prints its wrapped quantity with a leading role marker so a point and an amount are visually
        // distinct: `delta ` (an ASCII "delta " prefix) marks a delta; a point prints bare (it is the common,
        // unmarked case). The numeric+abbreviation body forwards to the wrapped unit's own inserter, so the
        // wrapper never re-implements formatting.

        template<UnitType U>
        std::ostream& operator<<(std::ostream& os, const absolute<U>& obj)
        {
            return os << wrap_detail::unwrap(obj);
        }

        template<UnitType U>
        std::ostream& operator<<(std::ostream& os, const delta<U>& obj)
        {
            return os << "delta " << wrap_detail::unwrap(obj);
        }

        template<UnitType U>
        std::string to_string(const absolute<U>& obj)
        {
            return units::to_string(wrap_detail::unwrap(obj));
        }

        template<UnitType U>
        std::string to_string(const delta<U>& obj)
        {
            return std::string("delta ").append(units::to_string(wrap_detail::unwrap(obj)));
        }
 
        //----------------------------------
        //  ABSOLUTE / DELTA MATH
        //----------------------------------
 
        // A delta is an AMOUNT, so magnitude/extremum functions are meaningful on it (a point has a datum, so its
        // magnitude is not — but two points still order, so min/max of points ARE meaningful). Each forwards to
        // the wrapped unit's own cmath analog, so the result underlying promotes exactly as the plain unit does.

        template<UnitType U>
        constexpr auto abs(const delta<U>& d) noexcept
        {
            using R = detail::floating_point_promotion_t<U>;
            return delta<R>(units::abs(R(wrap_detail::unwrap(d))));
        }

        template<UnitType U, UnitType V>
            requires traits::is_same_dimension_unit_v<U, V>
        constexpr auto min(const delta<U>& lhs, const delta<V>& rhs) noexcept
        {
            using R          = units::detail::delta_result_unit_t<U, V>;
            const delta<R> a = lhs.template to<delta<R>>();
            const delta<R> b = rhs.template to<delta<R>>();
            return a < b ? a : b;
        }

        template<UnitType U, UnitType V>
            requires traits::is_same_dimension_unit_v<U, V>
        constexpr auto max(const delta<U>& lhs, const delta<V>& rhs) noexcept
        {
            using R          = units::detail::delta_result_unit_t<U, V>;
            const delta<R> a = lhs.template to<delta<R>>();
            const delta<R> b = rhs.template to<delta<R>>();
            return a > b ? a : b;
        }

        template<UnitType U, UnitType V, UnitType W>
            requires(traits::is_same_dimension_unit_v<U, V> && traits::is_same_dimension_unit_v<U, W>)
        constexpr auto clamp(const delta<U>& value, const delta<V>& lo, const delta<W>& hi) noexcept
        {
            return affine::min(affine::max(value, lo), hi);
        }

        template<UnitType U, UnitType V>
            requires traits::is_same_dimension_unit_v<U, V>
        constexpr auto min(const absolute<U>& lhs, const absolute<V>& rhs) noexcept
        {
            using R             = units::detail::absolute_result_unit_t<U, V>;
            const absolute<R> a = lhs.template to<absolute<R>>();
            const absolute<R> b = rhs.template to<absolute<R>>();
            return a < b ? a : b;
        }

        template<UnitType U, UnitType V>
            requires traits::is_same_dimension_unit_v<U, V>
        constexpr auto max(const absolute<U>& lhs, const absolute<V>& rhs) noexcept
        {
            using R             = units::detail::absolute_result_unit_t<U, V>;
            const absolute<R> a = lhs.template to<absolute<R>>();
            const absolute<R> b = rhs.template to<absolute<R>>();
            return a > b ? a : b;
        }

        template<UnitType U, UnitType V, UnitType W>
            requires(traits::is_same_dimension_unit_v<U, V> && traits::is_same_dimension_unit_v<U, W>)
        constexpr auto clamp(const absolute<U>& value, const absolute<V>& lo, const absolute<W>& hi) noexcept
        {
            return affine::min(affine::max(value, lo), hi);
        }
 
        //----------------------------------
        //  ABSOLUTE / DELTA MISUSE DIAGNOSTICS (readable, not a candidate wall)
        //----------------------------------
        // The common naive fumbles get a one-line library message instead of an overload-resolution wall. Each
        // returns a real value so the compiler must instantiate the body (fires the static_assert on MSVC too).

        template<UnitType U, ArithmeticType T>
        constexpr auto operator*(const absolute<U>& lhs, T) noexcept
        {
            static_assert(wrap_detail::dependent_false_t<U>,
                "units::absolute: a point cannot be scaled (a point has no magnitude). Take the difference of two "
                "points for a delta, or scale a delta.");
            return lhs;
        }
        template<UnitType U, ArithmeticType T>
        constexpr auto operator*(T, const absolute<U>& rhs) noexcept
        {
            static_assert(wrap_detail::dependent_false_t<U>,
                "units::absolute: a point cannot be scaled (a point has no magnitude). Scale a delta instead.");
            return rhs;
        }
        template<UnitType U, ArithmeticType T>
        constexpr auto operator/(const absolute<U>& lhs, T) noexcept
        {
            static_assert(wrap_detail::dependent_false_t<U>,
                "units::absolute: a point cannot be divided by a number (a point has no magnitude). Divide a delta.");
            return lhs;
        }
        template<UnitType U, UnitType V>
            requires traits::is_same_dimension_unit_v<U, V>
        constexpr auto operator/(const absolute<U>& lhs, const absolute<V>&) noexcept
        {
            static_assert(wrap_detail::dependent_false_t<U>,
                "units::absolute: a point cannot be divided by a point (there is no ratio of two positions). "
                "Take the difference of two points for a delta.");
            return lhs;
        }

        template<UnitType U, UnitType V>
            requires traits::is_same_dimension_unit_v<U, V>
        constexpr auto operator+(const absolute<U>& lhs, const absolute<V>&) noexcept
        {
            static_assert(wrap_detail::dependent_false_t<U>,
                "units::absolute: cannot add two points (the sum of two positions has no meaning). Subtract them "
                "for a delta, or add a delta to move a point.");
            return lhs;
        }

        template<UnitType U, ArithmeticType T>
        constexpr auto operator+(const delta<U>& lhs, T) noexcept
        {
            static_assert(wrap_detail::dependent_false_t<U>,
                "units::delta: cannot add a bare number to a delta. Wrap the number in a delta of the same unit "
                "(e.g. delta<meters<double>>(3)).");
            return lhs;
        }
        template<UnitType U, ArithmeticType T>
        constexpr auto operator-(const delta<U>& lhs, T) noexcept
        {
            static_assert(wrap_detail::dependent_false_t<U>,
                "units::delta: cannot subtract a bare number from a delta. Wrap the number in a delta of the same "
                "unit.");
            return lhs;
        }
        template<UnitType U, ArithmeticType T>
        constexpr auto operator+(const absolute<U>& lhs, T) noexcept
        {
            static_assert(wrap_detail::dependent_false_t<U>,
                "units::absolute: cannot add a bare number to a point. Add a delta of the same unit to move the "
                "point (e.g. point + delta<meters<double>>(3)).");
            return lhs;
        }
 
        //----------------------------------
        //  KIND (TAGGED) OPERATORS
        //----------------------------------
 
        // A `kind` interoperates ONLY with the SAME tag: every binary operator is constrained on `Tag1 == Tag2`, so
        // two different kinds (radial vs. straight distance, torque vs. energy) do not add, subtract, or compare —
        // mixing them is ill-formed. The result keeps the LHS unit (the same tie-break as the other wrappers),
        // promoting the underlying only when the RHS would narrow it; the tag is preserved.

        template<fixed_string Tag, UnitType U, UnitType V>
            requires traits::is_same_dimension_unit_v<U, V>
        constexpr auto operator+(const basic_kind<Tag, U>& lhs, const basic_kind<Tag, V>& rhs) noexcept
        {
            using R = units::detail::delta_result_unit_t<U, V>;
            return basic_kind<Tag, R>(R(R(wrap_detail::unwrap(lhs)).raw() + R(wrap_detail::unwrap(rhs)).raw()));
        }

        template<fixed_string Tag, UnitType U, UnitType V>
            requires traits::is_same_dimension_unit_v<U, V>
        constexpr auto operator-(const basic_kind<Tag, U>& lhs, const basic_kind<Tag, V>& rhs) noexcept
        {
            using R = units::detail::delta_result_unit_t<U, V>;
            return basic_kind<Tag, R>(R(R(wrap_detail::unwrap(lhs)).raw() - R(wrap_detail::unwrap(rhs)).raw()));
        }

        template<fixed_string Tag, UnitType U>
        constexpr basic_kind<Tag, U> operator-(const basic_kind<Tag, U>& k) noexcept
        {
            return basic_kind<Tag, U>(U(-wrap_detail::unwrap(k).raw()));
        }

        template<fixed_string Tag, UnitType U, ArithmeticType T>
        constexpr auto operator*(const basic_kind<Tag, U>& lhs, T rhs) noexcept
        {
            using ScaledUnit = decltype(wrap_detail::unwrap(lhs) * rhs);
            return basic_kind<Tag, ScaledUnit>(wrap_detail::unwrap(lhs) * rhs);
        }
        template<fixed_string Tag, UnitType U, ArithmeticType T>
        constexpr auto operator*(T lhs, const basic_kind<Tag, U>& rhs) noexcept
        {
            return rhs * lhs;
        }

        template<fixed_string Tag, UnitType U, ArithmeticType T>
        constexpr auto operator/(const basic_kind<Tag, U>& lhs, T rhs) noexcept
        {
            using ScaledUnit = decltype(wrap_detail::unwrap(lhs) / rhs);
            return basic_kind<Tag, ScaledUnit>(wrap_detail::unwrap(lhs) / rhs);
        }

        template<fixed_string Tag, UnitType U, UnitType V>
            requires traits::is_same_dimension_unit_v<U, V>
        constexpr auto operator/(const basic_kind<Tag, U>& lhs, const basic_kind<Tag, V>& rhs) noexcept
        {
            return wrap_detail::unwrap(lhs) / wrap_detail::unwrap(rhs);
        }

        template<fixed_string Tag, UnitType U, ArithmeticType T>
        constexpr basic_kind<Tag, U>& operator*=(basic_kind<Tag, U>& lhs, T rhs) noexcept
        {
            lhs = basic_kind<Tag, U>(U(lhs.raw() * rhs));
            return lhs;
        }
        template<fixed_string Tag, UnitType U, ArithmeticType T>
        constexpr basic_kind<Tag, U>& operator/=(basic_kind<Tag, U>& lhs, T rhs) noexcept
        {
            lhs = basic_kind<Tag, U>(U(lhs.raw() / rhs));
            return lhs;
        }

        template<fixed_string Tag, UnitType U, UnitType V>
            requires traits::is_same_dimension_unit_v<U, V>
        constexpr basic_kind<Tag, U>& operator+=(basic_kind<Tag, U>& lhs, const basic_kind<Tag, V>& rhs) noexcept
        {
            lhs = basic_kind<Tag, U>(U(wrap_detail::unwrap(lhs).raw() + U(wrap_detail::unwrap(rhs)).raw()));
            return lhs;
        }
        template<fixed_string Tag, UnitType U, UnitType V>
            requires traits::is_same_dimension_unit_v<U, V>
        constexpr basic_kind<Tag, U>& operator-=(basic_kind<Tag, U>& lhs, const basic_kind<Tag, V>& rhs) noexcept
        {
            lhs = basic_kind<Tag, U>(U(wrap_detail::unwrap(lhs).raw() - U(wrap_detail::unwrap(rhs)).raw()));
            return lhs;
        }

        template<fixed_string Tag, UnitType U, UnitType V>
            requires traits::is_same_dimension_unit_v<U, V>
        constexpr bool operator==(const basic_kind<Tag, U>& lhs, const basic_kind<Tag, V>& rhs) noexcept
        {
            return wrap_detail::unwrap(lhs) == wrap_detail::unwrap(rhs);
        }
        template<fixed_string Tag, UnitType U, UnitType V>
            requires traits::is_same_dimension_unit_v<U, V>
        constexpr std::partial_ordering operator<=>(const basic_kind<Tag, U>& lhs, const basic_kind<Tag, V>& rhs) noexcept
        {
            return wrap_detail::order(wrap_detail::unwrap(lhs), wrap_detail::unwrap(rhs));
        }
 
        //----------------------------------
        //  KIND MISMATCH DIAGNOSTICS (great errors, not overload-resolution soup)
        //----------------------------------
 
        // Combining two DIFFERENT kinds is meaningless (a radial distance is not a straight-line distance; a torque
        // is not an energy). These catch-all overloads are the LEAST-preferred candidates (the same-tag overloads
        // above win whenever the tags match), so a mismatched combination selects one of these and stops at a single
        // readable message naming the mistake — instead of a wall of "no matching operator". They return a real
        // value (not void) so the compiler must instantiate the body to deduce the return type, which fires the
        // static_assert on g++, clang, AND MSVC (a void-returning body is not instantiated by MSVC's return-type
        // deduction, so the assert would be skipped there). To do arithmetic across kinds you must intend it:
        // unwrap one side with to<PlainUnit>().
        template<fixed_string TagL, fixed_string TagR, UnitType U, UnitType V>
            requires(!(TagL == TagR))
        constexpr auto operator+(const basic_kind<TagL, U>&, const basic_kind<TagR, V>&) noexcept
        {
            static_assert(wrap_detail::dependent_false<TagL, TagR>,
                "units::kind: cannot add two DIFFERENT kinds (their tags differ, e.g. \"radial\" vs \"straight\"). "
                "They share a unit and a dimension but are semantically distinct; unwrap one side with "
                "to<PlainUnit>() to operate on the plain unit if that is truly intended.");
            return basic_kind<TagL, U>{};
        }
        template<fixed_string TagL, fixed_string TagR, UnitType U, UnitType V>
            requires(!(TagL == TagR))
        constexpr auto operator-(const basic_kind<TagL, U>&, const basic_kind<TagR, V>&) noexcept
        {
            static_assert(wrap_detail::dependent_false<TagL, TagR>,
                "units::kind: cannot subtract two DIFFERENT kinds (their tags differ, e.g. \"radial\" vs "
                "\"straight\"). Unwrap one side with to<PlainUnit>() to operate on the plain unit if intended.");
            return basic_kind<TagL, U>{};
        }
        template<fixed_string TagL, fixed_string TagR, UnitType U, UnitType V>
            requires(!(TagL == TagR))
        constexpr bool operator==(const basic_kind<TagL, U>&, const basic_kind<TagR, V>&) noexcept
        {
            static_assert(wrap_detail::dependent_false<TagL, TagR>,
                "units::kind: cannot compare two DIFFERENT kinds (their tags differ, e.g. \"radial\" vs "
                "\"straight\"). Unwrap one side with to<PlainUnit>() to compare the plain units if intended.");
            return false;
        }
 
        // Mixing a `kind` with a PLAIN unit is ill-formed: a plain unit carries no kind. A plain unit becomes a
        // kind only by construction/assignment (`kind<Tag,U> k = plain;`), never in arithmetic. These
        // catch-alls turn the raw "no matching operator" wall into one readable message.
        template<fixed_string Tag, UnitType U, UnitType Plain>
        constexpr auto operator+(const basic_kind<Tag, U>& lhs, const Plain&) noexcept
        {
            static_assert(wrap_detail::dependent_false_t<Plain>,
                "units::kind: cannot add a plain unit to a kind - a plain unit carries no kind, so mixing them in "
                "arithmetic is disallowed. Wrap the plain unit in the same kind first, or unwrap the kind with "
                "to<PlainUnit>() to work in plain units.");
            return lhs;
        }
        template<fixed_string Tag, UnitType U, UnitType Plain>
        constexpr auto operator+(const Plain&, const basic_kind<Tag, U>& rhs) noexcept
        {
            static_assert(wrap_detail::dependent_false_t<Plain>,
                "units::kind: cannot add a plain unit to a kind - a plain unit carries no kind. Wrap the plain unit "
                "in the same kind first, or unwrap the kind with to<PlainUnit>() to work in plain units.");
            return rhs;
        }
        template<fixed_string Tag, UnitType U, UnitType Plain>
        constexpr auto operator-(const basic_kind<Tag, U>& lhs, const Plain&) noexcept
        {
            static_assert(wrap_detail::dependent_false_t<Plain>,
                "units::kind: cannot subtract a plain unit from a kind - a plain unit carries no kind. Wrap it in the "
                "same kind first, or unwrap the kind with to<PlainUnit>().");
            return lhs;
        }
 
        // A bare NUMBER does not add to / subtract from a kind (only kind +/- same-tag kind, and kind * / scalar
        // are defined). The most common naive fumble (`aKind + 3.0`) gets this message rather than a candidate wall.
        template<fixed_string Tag, UnitType U, ArithmeticType T>
        constexpr auto operator+(const basic_kind<Tag, U>& lhs, T) noexcept
        {
            static_assert(wrap_detail::dependent_false<Tag>,
                "units::kind: cannot add a bare number to a kind. Wrap the number in the same kind, or unwrap the "
                "kind with to<PlainUnit>() to work in plain units.");
            return lhs;
        }
        template<fixed_string Tag, UnitType U, ArithmeticType T>
        constexpr auto operator+(T, const basic_kind<Tag, U>& rhs) noexcept
        {
            static_assert(wrap_detail::dependent_false<Tag>,
                "units::kind: cannot add a bare number to a kind. Wrap the number in the same kind first.");
            return rhs;
        }
        template<fixed_string Tag, UnitType U, ArithmeticType T>
        constexpr auto operator-(const basic_kind<Tag, U>& lhs, T) noexcept
        {
            static_assert(wrap_detail::dependent_false<Tag>,
                "units::kind: cannot subtract a bare number from a kind. Wrap the number in the same kind first.");
            return lhs;
        }
 
        //----------------------------------
        //  KIND (TAGGED) FORMATTING
        //----------------------------------

        template<fixed_string Tag, UnitType U>
        std::ostream& operator<<(std::ostream& os, const basic_kind<Tag, U>& obj)
        {
            return os << '[' << Tag.value << "] " << wrap_detail::unwrap(obj);
        }

        template<fixed_string Tag, UnitType U>
        std::string to_string(const basic_kind<Tag, U>& obj)
        {
            return std::string("[").append(Tag.value).append("] ").append(units::to_string(wrap_detail::unwrap(obj)));
        }
 
        //----------------------------------
        //  KIND (TAGGED) MATH
        //----------------------------------
        // Parity with `delta`: magnitude and extrema keep the tag (the tag is preserved through the operation).

        template<fixed_string Tag, UnitType U>
        constexpr auto abs(const basic_kind<Tag, U>& k) noexcept
        {
            using R = detail::floating_point_promotion_t<U>;
            return basic_kind<Tag, R>(units::abs(R(wrap_detail::unwrap(k))));
        }

        template<fixed_string Tag, UnitType U, UnitType V>
            requires traits::is_same_dimension_unit_v<U, V>
        constexpr auto min(const basic_kind<Tag, U>& lhs, const basic_kind<Tag, V>& rhs) noexcept
        {
            using R               = units::detail::delta_result_unit_t<U, V>;
            const basic_kind<Tag, R> a = lhs.template to<basic_kind<Tag, R>>();
            const basic_kind<Tag, R> b = rhs.template to<basic_kind<Tag, R>>();
            return a < b ? a : b;
        }

        template<fixed_string Tag, UnitType U, UnitType V>
            requires traits::is_same_dimension_unit_v<U, V>
        constexpr auto max(const basic_kind<Tag, U>& lhs, const basic_kind<Tag, V>& rhs) noexcept
        {
            using R               = units::detail::delta_result_unit_t<U, V>;
            const basic_kind<Tag, R> a = lhs.template to<basic_kind<Tag, R>>();
            const basic_kind<Tag, R> b = rhs.template to<basic_kind<Tag, R>>();
            return a > b ? a : b;
        }

        template<fixed_string Tag, UnitType U, UnitType V, UnitType W>
            requires(traits::is_same_dimension_unit_v<U, V> && traits::is_same_dimension_unit_v<U, W>)
        constexpr auto clamp(const basic_kind<Tag, U>& value, const basic_kind<Tag, V>& lo, const basic_kind<Tag, W>& hi) noexcept
        {
            return affine::min(affine::max(value, lo), hi);
        }
    } // inline namespace affine
 
 
    //----------------------------------------------------------------------------------------------------------------------
    //  TOP-LEVEL `kind` ALIAS (the preferred spelling)
    //----------------------------------------------------------------------------------------------------------------------
    template<affine::fixed_string Tag, UnitType U>
    using kind = affine::basic_kind<Tag, U>;
} // end namespace units
 
//----------------------------------------------------------------------------------------------------------------------
//      STD Namespace extensions
//----------------------------------------------------------------------------------------------------------------------
// A wrapper is hashable and has numeric limits exactly as the unit it wraps does — so a wrapper drops into an
// unordered container and generic `numeric_limits`-driven code the same way the plain unit does.
 
//------------------------------
//  std::hash
//------------------------------

template<units::UnitType U>
struct std::hash<units::affine::absolute<U>>
{
    constexpr std::size_t operator()(const units::affine::absolute<U>& x) const noexcept { return std::hash<U>()(x.template to<U>()); }
};

template<units::UnitType U>
struct std::hash<units::affine::delta<U>>
{
    constexpr std::size_t operator()(const units::affine::delta<U>& x) const noexcept { return std::hash<U>()(x.template to<U>()); }
};

template<units::affine::fixed_string Tag, units::UnitType U>
struct std::hash<units::affine::basic_kind<Tag, U>>
{
    constexpr std::size_t operator()(const units::affine::basic_kind<Tag, U>& x) const noexcept { return std::hash<U>()(x.template to<U>()); }
};
 
//------------------------------
//  std::numeric_limits
//------------------------------
 
namespace std
{
    template<units::UnitType U>
    struct numeric_limits<units::affine::absolute<U>>
    {
        static constexpr bool is_specialized = true;
        static constexpr units::affine::absolute<U> min() { return units::affine::absolute<U>(std::numeric_limits<U>::min()); }
        static constexpr units::affine::absolute<U> max() { return units::affine::absolute<U>(std::numeric_limits<U>::max()); }
        static constexpr units::affine::absolute<U> lowest() { return units::affine::absolute<U>(std::numeric_limits<U>::lowest()); }
    };

    template<units::UnitType U>
    struct numeric_limits<units::affine::delta<U>>
    {
        static constexpr bool is_specialized = true;
        static constexpr units::affine::delta<U> min() { return units::affine::delta<U>(std::numeric_limits<U>::min()); }
        static constexpr units::affine::delta<U> max() { return units::affine::delta<U>(std::numeric_limits<U>::max()); }
        static constexpr units::affine::delta<U> lowest() { return units::affine::delta<U>(std::numeric_limits<U>::lowest()); }
    };

    template<units::affine::fixed_string Tag, units::UnitType U>
    struct numeric_limits<units::affine::basic_kind<Tag, U>>
    {
        static constexpr bool is_specialized = true;
        static constexpr units::affine::basic_kind<Tag, U> min() { return units::affine::basic_kind<Tag, U>(std::numeric_limits<U>::min()); }
        static constexpr units::affine::basic_kind<Tag, U> max() { return units::affine::basic_kind<Tag, U>(std::numeric_limits<U>::max()); }
        static constexpr units::affine::basic_kind<Tag, U> lowest() { return units::affine::basic_kind<Tag, U>(std::numeric_limits<U>::lowest()); }
    };
} // namespace std
 
#endif // UNIT_KIND_H