serialization.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
//
//--------------------------------------------------------------------------------------------------
//
//
//--------------------------------------------------------------------------------------------------
 
#pragma once
 
#ifndef units_serialization_h_
#define units_serialization_h_
 
#include <array>
#include <cmath>
#include <compare>
#include <cstddef>
#include <cstdint>
#include <cstdio>
#include <cstring>
#include <expected>
#include <functional>
#include <istream>
#include <iterator>
#include <limits>
#include <memory>
#include <ostream>
#include <span>
#include <stdexcept>
#include <string>
#include <string_view>
#include <tuple>
#include <units/core.h>
#include <utility>
#include <vector>
 
namespace units
{
    namespace detail
    {
        using builtin_dimensions = std::tuple<dimension::length, dimension::mass, dimension::time, dimension::current, dimension::temperature, dimension::substance, dimension::luminous_intensity,
            dimension::angle, dimension::data, dimension::solid_angle, dimension::frequency, dimension::velocity, dimension::angular_velocity, dimension::acceleration, dimension::force,
            dimension::area, dimension::volume, dimension::volume_flow_rate, dimension::pressure, dimension::charge, dimension::energy, dimension::power, dimension::voltage, dimension::capacitance,
            dimension::impedance, dimension::conductance, dimension::magnetic_flux, dimension::inductance, dimension::luminous_flux, dimension::illuminance, dimension::luminance,
            dimension::radioactivity, dimension::substance_mass, dimension::substance_concentration, dimension::magnetic_field_strength, dimension::radiant_intensity, dimension::radiance,
            dimension::irradiance, dimension::spectral_intensity, dimension::spectral_flux, dimension::spectral_radiance, dimension::spectral_irradiance, dimension::jerk, dimension::torque,
            dimension::density, dimension::energy_density, dimension::concentration, dimension::data_transfer_rate, dimension::dynamic_viscosity, dimension::kinematic_viscosity>;
 
        //------------------------------------------------------------------------------------------------------------------
        //      FUNCTION: name_hash [static]
        //------------------------------------------------------------------------------------------------------------------
        //------------------------------------------------------------------------------------------------------------------
        constexpr std::uint64_t name_hash(std::string_view name) noexcept
        {
            std::uint64_t h = 1469598103934665603ULL;
            for (const char c : name)
            {
                h ^= static_cast<std::uint8_t>(c);
                h *= 1099511628211ULL;
            }
            return h;
        }
    } // namespace detail

    enum class deserialize_error
    {
        truncated,              
        bad_version,            
        dimension_mismatch,     
        unknown_base_dimension, 
        lossy_target            
    };

    class any_unit;
 
    //======================================================================================================================
    //  VARINT (LEB128) — the terse integer codec
    //======================================================================================================================
 
    namespace detail
    {
        //------------------------------------------------------------------------------------------------------------------
        //      FUNCTION: put_uvarint [static]
        //------------------------------------------------------------------------------------------------------------------
        //------------------------------------------------------------------------------------------------------------------
        inline void put_uvarint(std::vector<std::byte>& out, std::uint64_t value)
        {
            do
            {
                std::uint8_t byte = value & 0x7F;
                value >>= 7;
                if (value != 0)
                    byte |= 0x80;
                out.push_back(std::byte{byte});
            } while (value != 0);
        }
 
        //------------------------------------------------------------------------------------------------------------------
        //      FUNCTION: put_svarint [static]
        //------------------------------------------------------------------------------------------------------------------
        //------------------------------------------------------------------------------------------------------------------
        inline void put_svarint(std::vector<std::byte>& out, std::int64_t value)
        {
            put_uvarint(out, (static_cast<std::uint64_t>(value) << 1) ^ static_cast<std::uint64_t>(value >> 63));
        }
 
        //------------------------------------------------------------------------------------------------------------------
        //      FUNCTION: get_uvarint [static]
        //------------------------------------------------------------------------------------------------------------------
        //------------------------------------------------------------------------------------------------------------------
        inline bool get_uvarint(const std::byte*& cursor, const std::byte* end, std::uint64_t& value)
        {
            value              = 0;
            unsigned int shift = 0;
            while (cursor != end)
            {
                const auto byte = std::to_integer<std::uint8_t>(*cursor++);
                value |= static_cast<std::uint64_t>(byte & 0x7F) << shift;
                if ((byte & 0x80) == 0)
                    return true;
                shift += 7;
                if (shift >= 64)
                    return false;
            }
            return false;
        }
 
        //------------------------------------------------------------------------------------------------------------------
        //      FUNCTION: get_svarint [static]
        //------------------------------------------------------------------------------------------------------------------
        //------------------------------------------------------------------------------------------------------------------
        inline bool get_svarint(const std::byte*& cursor, const std::byte* end, std::int64_t& value)
        {
            std::uint64_t raw;
            if (!get_uvarint(cursor, end, raw))
                return false;
            value = static_cast<std::int64_t>((raw >> 1) ^ (~(raw & 1) + 1));
            return true;
        }
    } // namespace detail
 
    //======================================================================================================================
    //  UNIT IDENTITY — the compile-time dimension signature, and its runtime form
    //======================================================================================================================

    struct dimension_term
    {
        std::uint64_t hash; 
        std::int64_t  num;  
        std::int64_t  den;  
    };

    struct unit_identity
    {
        std::vector<dimension_term> terms;
 
        //------------------------------------------------------------------------------------------------------------------
        //      FUNCTION: operator== [public]
        //------------------------------------------------------------------------------------------------------------------
        //------------------------------------------------------------------------------------------------------------------
        bool operator==(const unit_identity& other) const noexcept
        {
            if (terms.size() != other.terms.size())
                return false;
            for (std::size_t i = 0; i < terms.size(); ++i)
                if (terms[i].hash != other.terms[i].hash || terms[i].num != other.terms[i].num || terms[i].den != other.terms[i].den)
                    return false;
            return true;
        }
    };
 
    namespace detail
    {
        //------------------------------------------------------------------------------------------------------------------
        //      FUNCTION: dimension_arity [static]
        //------------------------------------------------------------------------------------------------------------------
        //------------------------------------------------------------------------------------------------------------------
        template<class DimensionList>
        consteval std::size_t dimension_arity()
        {
            if constexpr (DimensionList::empty)
                return 0;
            else
                return 1 + dimension_arity<typename DimensionList::pop_front>();
        }
 
        //------------------------------------------------------------------------------------------------------------------
        //      FUNCTION: fill_terms [static]
        //------------------------------------------------------------------------------------------------------------------
        //------------------------------------------------------------------------------------------------------------------
        template<class DimensionList, std::size_t N>
        consteval void fill_terms(std::array<dimension_term, N>& out, std::size_t at)
        {
            if constexpr (!DimensionList::empty)
            {
                using front_dim = typename DimensionList::front;
                using tag       = typename front_dim::dimension;
                using exponent  = typename front_dim::exponent;
                out[at]         = dimension_term{name_hash(std::string_view(tag::name)), exponent::num, exponent::den};
                fill_terms<typename DimensionList::pop_front, N>(out, at + 1);
            }
        }

        template<UnitType Unit>
        struct signature
        {
            using Dim                          = traits::dimension_of_t<typename traits::unit_traits<Unit>::conversion_factor>;
            static constexpr std::size_t arity = dimension_arity<Dim>();
 
            static consteval std::array<dimension_term, arity> compute()
            {
                std::array<dimension_term, arity> terms{};
                fill_terms<Dim, arity>(terms, 0);
                // insertion sort by hash — arity is tiny (the base dimensions of one quantity)
                for (std::size_t i = 1; i < arity; ++i)
                {
                    dimension_term key = terms[i];
                    std::size_t    j   = i;
                    while (j > 0 && terms[j - 1].hash > key.hash)
                    {
                        terms[j] = terms[j - 1];
                        --j;
                    }
                    terms[j] = key;
                }
                return terms;
            }
 
            static constexpr std::array<dimension_term, arity> value = compute();
        };
 
        //------------------------------------------------------------------------------------------------------------------
        //      FUNCTION: identity_of [static]
        //------------------------------------------------------------------------------------------------------------------
        //------------------------------------------------------------------------------------------------------------------
        template<UnitType Unit>
        unit_identity identity_of()
        {
            unit_identity id;
            id.terms.assign(signature<Unit>::value.begin(), signature<Unit>::value.end());
            return id;
        }

        template<class Dim>
        using canonical_unit_t = unit<conversion_factor<std::ratio<1>, Dim>, double>;
    } // namespace detail
 
    //======================================================================================================================
    //  WIRE FORMAT
    //======================================================================================================================
 
    namespace detail
    {
        inline constexpr std::uint8_t serialization_version = 1;

        enum class value_kind : std::uint8_t
        {
            ivarint = 0, 
            f32     = 1, 
            f64     = 2  
        };
 
        //------------------------------------------------------------------------------------------------------------------
        //      FUNCTION: encode [static]
        //------------------------------------------------------------------------------------------------------------------
        //------------------------------------------------------------------------------------------------------------------
        inline std::vector<std::byte> encode(const unit_identity& identity, double base)
        {
            value_kind kind;
            if (base == std::floor(base) && std::abs(base) < 9.0e15)
                kind = value_kind::ivarint;
            else if (static_cast<double>(static_cast<float>(base)) == base)
                kind = value_kind::f32;
            else
                kind = value_kind::f64;
 
            // any fractional exponent forces the fracExp flag
            bool fracExp = false;
            for (const auto& term : identity.terms)
                if (term.den != 1)
                    fracExp = true;
 
            std::vector<std::byte> out;
            out.push_back(std::byte{serialization_version});
            const std::uint8_t header = static_cast<std::uint8_t>(static_cast<std::uint8_t>(kind) | (fracExp ? 0x04 : 0x00));
            out.push_back(std::byte{header});
            put_uvarint(out, identity.terms.size());
            for (const auto& term : identity.terms)
            {
                // base dimension keyed by an 8-byte name-hash: fixed size, no central table, any dimension round-trips
                for (unsigned int i = 0; i < 8; ++i)
                    out.push_back(std::byte{static_cast<std::uint8_t>(term.hash >> (8 * i))});
                put_svarint(out, term.num);
                if (fracExp)
                    put_svarint(out, term.den);
            }
 
            switch (kind)
            {
            case value_kind::ivarint: put_svarint(out, static_cast<std::int64_t>(base)); break;
            case value_kind::f32:
            {
                const float   f = static_cast<float>(base);
                std::uint32_t bits;
                std::memcpy(&bits, &f, sizeof(bits));
                for (unsigned int i = 0; i < 4; ++i)
                    out.push_back(std::byte{static_cast<std::uint8_t>(bits >> (8 * i))});
                break;
            }
            case value_kind::f64:
            {
                std::uint64_t bits;
                std::memcpy(&bits, &base, sizeof(bits));
                for (unsigned int i = 0; i < 8; ++i)
                    out.push_back(std::byte{static_cast<std::uint8_t>(bits >> (8 * i))});
                break;
            }
            }
            return out;
        }
    } // namespace detail
 
    //======================================================================================================================
    //  any_unit
    //======================================================================================================================
 
    class any_unit
    {
    public:
        //------------------------------------------------------------------------------------------------------------------
        //      FUNCTION: any_unit [public]
        //------------------------------------------------------------------------------------------------------------------
        //------------------------------------------------------------------------------------------------------------------
        any_unit(unit_identity id, double base)
          : m_identity(std::move(id)),
            m_base(base),
            m_bytes(detail::encode(m_identity, base))
        {
        }
 
        //------------------------------------------------------------------------------------------------------------------
        //      FUNCTION: any_unit [public]
        //------------------------------------------------------------------------------------------------------------------
        //------------------------------------------------------------------------------------------------------------------
        any_unit()
          : m_identity(),
            m_base(0.0),
            m_bytes(detail::encode(m_identity, 0.0))
        {
        }
 
        //------------------------------------------------------------------------------------------------------------------
        //      FUNCTION: is [public]
        //------------------------------------------------------------------------------------------------------------------
        //------------------------------------------------------------------------------------------------------------------
        template<class Dimension>
        [[nodiscard]] bool is() const noexcept
        {
            return m_identity == detail::identity_of<detail::canonical_unit_t<Dimension>>();
        }
 
        //------------------------------------------------------------------------------------------------------------------
        //      FUNCTION: value_in_base [public]
        //------------------------------------------------------------------------------------------------------------------
        //------------------------------------------------------------------------------------------------------------------
        [[nodiscard]] double value_in_base() const noexcept
        {
            return m_base;
        }
 
        //------------------------------------------------------------------------------------------------------------------
        //      FUNCTION: identity [public]
        //------------------------------------------------------------------------------------------------------------------
        //------------------------------------------------------------------------------------------------------------------
        [[nodiscard]] const unit_identity& identity() const noexcept
        {
            return m_identity;
        }
 
        //======================================================================================================================
        //  BYTES — the owned serialized form, in both a type-safe and a C-interface view
        //======================================================================================================================
 
        //------------------------------------------------------------------------------------------------------------------
        //      FUNCTION: bytes [public]
        //------------------------------------------------------------------------------------------------------------------
        //------------------------------------------------------------------------------------------------------------------
        [[nodiscard]] std::span<const std::byte> bytes() const noexcept
        {
            return m_bytes;
        }
 
        //------------------------------------------------------------------------------------------------------------------
        //      FUNCTION: operator std::span<const std::byte> [public]
        //------------------------------------------------------------------------------------------------------------------
        //------------------------------------------------------------------------------------------------------------------
        [[nodiscard]] operator std::span<const std::byte>() const noexcept
        {
            return m_bytes;
        }
 
        //------------------------------------------------------------------------------------------------------------------
        //      FUNCTION: data [public]
        //------------------------------------------------------------------------------------------------------------------
        //------------------------------------------------------------------------------------------------------------------
        [[nodiscard]] const char* data() const noexcept
        {
            return reinterpret_cast<const char*>(m_bytes.data());
        }
 
        //------------------------------------------------------------------------------------------------------------------
        //      FUNCTION: size [public]
        //------------------------------------------------------------------------------------------------------------------
        //------------------------------------------------------------------------------------------------------------------
        [[nodiscard]] std::size_t size() const noexcept
        {
            return m_bytes.size();
        }
 
        //------------------------------------------------------------------------------------------------------------------
        //      FUNCTION: to_string [public]
        //------------------------------------------------------------------------------------------------------------------
        //------------------------------------------------------------------------------------------------------------------
        [[nodiscard]] std::string to_string() const
        {
            std::string named;
            // resolve to the canonical named unit of whichever known dimension matches, and render it exactly as a
            // concrete unit streams (name/abbreviation + dimension form); leave `named` empty if no known dimension matched
            try
            {
                visit([&named](const auto& quantity) { named = units::to_string(quantity); });
            }
            catch (const std::runtime_error&)
            {
            }
            return named.empty() ? to_string_raw() : named;
        }
 
        //------------------------------------------------------------------------------------------------------------------
        //      FUNCTION: to_string_raw [public]
        //------------------------------------------------------------------------------------------------------------------
        //------------------------------------------------------------------------------------------------------------------
        [[nodiscard]] std::string to_string_raw() const
        {
            std::string out = std::to_string(m_base);
            if (m_identity.terms.empty())
            {
                out += " [dimensionless]";
                return out;
            }
            out += " [";
            for (std::size_t i = 0; i < m_identity.terms.size(); ++i)
            {
                if (i != 0)
                    out += ' ';
                char hex[19];
                std::snprintf(hex, sizeof(hex), "#%llx", static_cast<unsigned long long>(m_identity.terms[i].hash));
                out += hex;
                out += '^';
                out += std::to_string(m_identity.terms[i].num);
                if (m_identity.terms[i].den != 1)
                {
                    out += '/';
                    out += std::to_string(m_identity.terms[i].den);
                }
            }
            out += ']';
            return out;
        }
 
        //======================================================================================================================
        //  COMPARISON
        //======================================================================================================================
 
        //------------------------------------------------------------------------------------------------------------------
        //      FUNCTION: operator== [public]
        //------------------------------------------------------------------------------------------------------------------
        //------------------------------------------------------------------------------------------------------------------
        [[nodiscard]] bool operator==(const any_unit& other) const noexcept
        {
            if (!(m_identity == other.m_identity))
                return false;
            const double diff = std::abs(m_base - other.m_base);
            return diff < std::numeric_limits<double>::epsilon() * std::abs(m_base + other.m_base) || diff < std::numeric_limits<double>::min();
        }
 
        //------------------------------------------------------------------------------------------------------------------
        //      FUNCTION: operator!= [public]
        //------------------------------------------------------------------------------------------------------------------
        //------------------------------------------------------------------------------------------------------------------
        [[nodiscard]] bool operator!=(const any_unit& other) const noexcept
        {
            return !(*this == other);
        }
 
        //------------------------------------------------------------------------------------------------------------------
        //      FUNCTION: operator<=> [public]
        //------------------------------------------------------------------------------------------------------------------
        //------------------------------------------------------------------------------------------------------------------
        [[nodiscard]] std::partial_ordering operator<=>(const any_unit& other) const noexcept
        {
            if (!(m_identity == other.m_identity))
                return std::partial_ordering::unordered;
            if (*this == other)
                return std::partial_ordering::equivalent;
            return m_base <=> other.m_base;
        }
 
        //------------------------------------------------------------------------------------------------------------------
        //      FUNCTION: to [public]
        //------------------------------------------------------------------------------------------------------------------
        //------------------------------------------------------------------------------------------------------------------
        template<class Unit>
        [[nodiscard]] std::expected<Unit, deserialize_error> to() const
        {
            static_assert(traits::is_unit_v<Unit>,
                "any_unit::to<T>() collapses into a unit type (e.g. meters<double>), not a bare number. To read a plain value, collapse to a unit first, then call .value() or .to<double>() on that "
                "unit.");
            // gate the body so a non-unit Unit produces ONLY the friendly message above, no downstream template soup
            if constexpr (traits::is_unit_v<Unit>)
            {
                if (m_identity != detail::identity_of<Unit>())
                    return std::unexpected(deserialize_error::dimension_mismatch);
 
                using ConversionFactor = typename traits::unit_traits<Unit>::conversion_factor;
                using Dim              = traits::dimension_of_t<ConversionFactor>;
                using UnderlyingTarget = typename traits::unit_traits<Unit>::underlying_type;
 
                // Express the SI-base magnitude in the TARGET unit's scale, all in double so no lossy unit conversion is
                // attempted: a double-underlying instance of the target unit converts from the canonical base cleanly.
                using TargetAsDouble   = unit<traits::strong_t<ConversionFactor>, double, typename traits::unit_traits<Unit>::numerical_scale_type>;
                const double as_double = TargetAsDouble(detail::canonical_unit_t<Dim>(m_base)).template to<double>();
 
                // Narrow to the target's underlying type. An integral target that cannot represent the value exactly is
                // a lossy_target error rather than a silent truncation.
                if constexpr (!std::is_floating_point_v<UnderlyingTarget>)
                {
                    if (as_double != std::floor(as_double) || std::abs(as_double) > static_cast<double>(std::numeric_limits<UnderlyingTarget>::max()))
                        return std::unexpected(deserialize_error::lossy_target);
                }
                return Unit(static_cast<UnderlyingTarget>(as_double));
            }
            else
            {
                return std::unexpected(deserialize_error::dimension_mismatch); // unreachable; the static_assert fired
            }
        }
 
        //------------------------------------------------------------------------------------------------------------------
        //      FUNCTION: try_to [public]
        //------------------------------------------------------------------------------------------------------------------
        //------------------------------------------------------------------------------------------------------------------
        template<class Unit>
        [[nodiscard]] Unit try_to() const
        {
            static_assert(traits::is_unit_v<Unit>, "any_unit::try_to<T>() collapses into a unit type (e.g. meters<double>), not a bare number.");
            auto result = to<Unit>();
            if (!result)
                throw std::runtime_error("units::any_unit: dimension mismatch collapsing to the requested unit");
            return *result;
        }
 
        //------------------------------------------------------------------------------------------------------------------
        //      FUNCTION: assign_to [public]
        //------------------------------------------------------------------------------------------------------------------
        //------------------------------------------------------------------------------------------------------------------
        template<class Unit>
        bool assign_to(Unit& out) const
        {
            static_assert(traits::is_unit_v<Unit>, "any_unit::assign_to(out) assigns into a unit variable (e.g. meters<double>), not a bare number. Collapse to a unit, then read its value.");
            if (auto result = to<Unit>())
            {
                out = *result;
                return true;
            }
            return false;
        }
 
        //------------------------------------------------------------------------------------------------------------------
        //      FUNCTION: visit [public]
        //------------------------------------------------------------------------------------------------------------------
        //------------------------------------------------------------------------------------------------------------------
        template<class... Dimensions, class Visitor>
        void visit(Visitor&& visitor) const
        {
            // bind to a named lvalue so the traversal passes it through by reference (never moving it), and the
            // single invocation site (try_dispatch_one) is the only place it is used as the caller's value category
            bool matched;
            if constexpr (sizeof...(Dimensions) == 0)
                matched = dispatch_tuple<detail::builtin_dimensions>(std::forward<Visitor>(visitor));
            else
                matched = dispatch_list<Dimensions...>(std::forward<Visitor>(visitor));
            if (!matched)
                throw std::runtime_error("units::any_unit: no candidate dimension matched the stream");
        }
 
    private:
        //------------------------------------------------------------------------------------------------------------------
        //      FUNCTION: try_dispatch_one [private]
        //------------------------------------------------------------------------------------------------------------------
        //------------------------------------------------------------------------------------------------------------------
        template<class Dimension, class Visitor>
        bool try_dispatch_one(Visitor&& visitor) const
        {
            using Base = detail::canonical_unit_t<Dimension>;
            if (m_identity == detail::identity_of<Base>())
            {
                std::forward<Visitor>(visitor)(Base(m_base));
                return true;
            }
            return false;
        }

        template<class... Dimensions, class Visitor>
        bool dispatch_list(Visitor&& visitor) const
        {
            bool matched = false;
            // fold in order; stop invoking once matched
            ((matched = matched || try_dispatch_one<Dimensions>(visitor)), ...);
            return matched;
        }

        template<class DimTuple, std::size_t I = 0, class Visitor>
        bool dispatch_tuple(Visitor&& visitor) const
        {
            if constexpr (I < std::tuple_size_v<DimTuple>)
            {
                if (try_dispatch_one<std::tuple_element_t<I, DimTuple>>(visitor))
                    return true;
                return dispatch_tuple<DimTuple, I + 1>(visitor);
            }
            return false;
        }
 
        unit_identity          m_identity;
        double                 m_base;
        std::vector<std::byte> m_bytes; 
    };
 
    //----------------------------------------------------------------------------------------------------------------------
    //      FUNCTION: operator<< [public]
    //----------------------------------------------------------------------------------------------------------------------
    //----------------------------------------------------------------------------------------------------------------------
    inline std::ostream& operator<<(std::ostream& os, const any_unit& value)
    {
        os.write(value.data(), static_cast<std::streamsize>(value.size()));
        return os;
    }
 
    //======================================================================================================================
    //  unit_cast — reclaimed: the explicit throwing collapse from any_unit to a concrete unit
    //======================================================================================================================
 
    //----------------------------------------------------------------------------------------------------------------------
    //      FUNCTION: unit_cast [public]
    //----------------------------------------------------------------------------------------------------------------------
    //----------------------------------------------------------------------------------------------------------------------
    template<class Target>
    [[nodiscard]] Target unit_cast(const any_unit& value)
    {
        static_assert(traits::is_unit_v<Target>, "units::unit_cast<T>(any_unit) casts to a unit type (e.g. meters<double>), not a bare number. Collapse to a unit, then read its value.");
        return value.try_to<Target>();
    }
 
    //======================================================================================================================
    //  serialize / deserialize
    //======================================================================================================================
 
    //----------------------------------------------------------------------------------------------------------------------
    //      FUNCTION: serialize [public]
    //----------------------------------------------------------------------------------------------------------------------
    //----------------------------------------------------------------------------------------------------------------------
    template<class Unit>
    [[nodiscard]] any_unit serialize(const Unit& quantity)
    {
        static_assert(traits::is_unit_v<Unit>, "units::serialize requires a units quantity (e.g. meters<double>). Its argument is not a unit type; wrap the value in a unit before serializing.");
        // gate the body so a non-unit argument produces ONLY the friendly message above, no downstream template soup
        if constexpr (!traits::is_unit_v<Unit>)
            return any_unit{unit_identity{}, 0.0};
        else
        {
            constexpr auto& sig = detail::signature<Unit>::value; // fixed-array compile-time signature (sorted by hash)
 
            // value in SI canonical base
            using Dim         = traits::dimension_of_t<typename traits::unit_traits<Unit>::conversion_factor>;
            using Base        = detail::canonical_unit_t<Dim>;
            const double base = Base(quantity).value();
 
            // lift the compile-time signature into the runtime identity, then let any_unit own its encoded form
            unit_identity id;
            id.terms.assign(sig.begin(), sig.end());
 
            return any_unit{std::move(id), base};
        }
    }
 
    //----------------------------------------------------------------------------------------------------------------------
    //      FUNCTION: deserialize [public]
    //----------------------------------------------------------------------------------------------------------------------
    //----------------------------------------------------------------------------------------------------------------------
    [[nodiscard]] inline std::expected<any_unit, deserialize_error> deserialize(std::span<const std::byte> bytes)
    {
        const std::byte* cursor = bytes.data();
        const std::byte* end    = bytes.data() + bytes.size();
 
        if (cursor == end)
            return std::unexpected(deserialize_error::truncated);
        const std::uint8_t version = std::to_integer<std::uint8_t>(*cursor++);
        if (version != detail::serialization_version)
            return std::unexpected(deserialize_error::bad_version);
 
        if (cursor == end)
            return std::unexpected(deserialize_error::truncated);
        const std::uint8_t header  = std::to_integer<std::uint8_t>(*cursor++);
        const auto         kind    = static_cast<detail::value_kind>(header & 0x03);
        const bool         fracExp = (header & 0x04) != 0;
 
        std::uint64_t count = 0;
        if (!detail::get_uvarint(cursor, end, count))
            return std::unexpected(deserialize_error::truncated);
 
        unit_identity id;
        id.terms.reserve(count);
        for (std::uint64_t i = 0; i < count; ++i)
        {
            if (end - cursor < 8)
                return std::unexpected(deserialize_error::truncated);
            std::uint64_t hash = 0;
            for (unsigned int byteIndex = 0; byteIndex < 8; ++byteIndex)
                hash |= static_cast<std::uint64_t>(std::to_integer<std::uint8_t>(*cursor++)) << (8 * byteIndex);
            std::int64_t num = 0;
            std::int64_t den = 1;
            if (!detail::get_svarint(cursor, end, num))
                return std::unexpected(deserialize_error::truncated);
            if (fracExp && !detail::get_svarint(cursor, end, den))
                return std::unexpected(deserialize_error::truncated);
            id.terms.push_back(dimension_term{hash, num, den});
        }
 
        double base = 0.0;
        switch (kind)
        {
        case detail::value_kind::ivarint:
        {
            std::int64_t v;
            if (!detail::get_svarint(cursor, end, v))
                return std::unexpected(deserialize_error::truncated);
            base = static_cast<double>(v);
            break;
        }
        case detail::value_kind::f32:
        {
            if (end - cursor < 4)
                return std::unexpected(deserialize_error::truncated);
            std::uint32_t bits = 0;
            for (unsigned int i = 0; i < 4; ++i)
                bits |= static_cast<std::uint32_t>(std::to_integer<std::uint8_t>(*cursor++)) << (8 * i);
            float f;
            std::memcpy(&f, &bits, sizeof(f));
            base = static_cast<double>(f);
            break;
        }
        case detail::value_kind::f64:
        {
            if (end - cursor < 8)
                return std::unexpected(deserialize_error::truncated);
            std::uint64_t bits = 0;
            for (unsigned int i = 0; i < 8; ++i)
                bits |= static_cast<std::uint64_t>(std::to_integer<std::uint8_t>(*cursor++)) << (8 * i);
            std::memcpy(&base, &bits, sizeof(base));
            break;
        }
        default: return std::unexpected(deserialize_error::bad_version);
        }
 
        return any_unit(std::move(id), base);
    }
 
    //----------------------------------------------------------------------------------------------------------------------
    //      FUNCTION: deserialize [public]
    //----------------------------------------------------------------------------------------------------------------------
    //----------------------------------------------------------------------------------------------------------------------
    template<class Unit>
    [[nodiscard]] std::expected<Unit, deserialize_error> deserialize(std::span<const std::byte> bytes)
    {
        static_assert(traits::is_unit_v<Unit>,
            "units::deserialize<T>(bytes) decodes into a unit type (e.g. deserialize<meters<double>>). The requested type is not a unit; use deserialize(bytes) for an erased any_unit.");
        auto erased = deserialize(bytes);
        if (!erased)
            return std::unexpected(erased.error());
        return erased->template to<Unit>();
    }
 
    //----------------------------------------------------------------------------------------------------------------------
    //      FUNCTION: deserialize [public]
    //----------------------------------------------------------------------------------------------------------------------
    //----------------------------------------------------------------------------------------------------------------------
    [[nodiscard]] inline std::expected<any_unit, deserialize_error> deserialize(std::istream& is)
    {
        const std::istream::pos_type start = is.tellg();
        if (start == std::istream::pos_type(-1))
            return std::unexpected(deserialize_error::truncated); // not seekable: records can't be self-delimited here
 
        const std::vector<char> buffer{std::istreambuf_iterator<char>(is), std::istreambuf_iterator<char>()};
        is.clear(); // the drain set eofbit; clear it so a good decode leaves the stream usable
 
        auto decoded = deserialize(std::span<const std::byte>(reinterpret_cast<const std::byte*>(buffer.data()), buffer.size()));
        if (decoded)
            is.seekg(start + static_cast<std::istream::off_type>(decoded->size())); // rewind past exactly this record
        return decoded;
    }
 
    //----------------------------------------------------------------------------------------------------------------------
    //      FUNCTION: operator>> [public]
    //----------------------------------------------------------------------------------------------------------------------
    //----------------------------------------------------------------------------------------------------------------------
    inline std::istream& operator>>(std::istream& is, any_unit& value)
    {
        if (auto decoded = deserialize(is))
            value = std::move(*decoded);
        else
            is.setstate(std::ios::failbit);
        return is;
    }
 
    //----------------------------------------------------------------------------------------------------------------------
    //      FUNCTION: deserialize [public]
    //----------------------------------------------------------------------------------------------------------------------
    //----------------------------------------------------------------------------------------------------------------------
    template<class Unit>
    [[nodiscard]] std::expected<Unit, deserialize_error> deserialize(std::istream& is)
    {
        static_assert(traits::is_unit_v<Unit>,
            "units::deserialize<T>(stream) decodes into a unit type (e.g. deserialize<meters<double>>). The requested type is not a unit; use deserialize(stream) for an erased any_unit.");
        auto erased = deserialize(is);
        if (!erased)
            return std::unexpected(erased.error());
        return erased->template to<Unit>();
    }
} // namespace units
 
//----------------------------------------------------------------------------------------------------------------------
//  std::hash<units::any_unit>
//----------------------------------------------------------------------------------------------------------------------
template<>
struct std::hash<units::any_unit>
{
    std::size_t operator()(const units::any_unit& value) const noexcept
    {
        // FNV-1a-style fold over the term signature, mixed with the base-value hash
        std::size_t seed = std::hash<double>()(value.value_in_base());
        const auto  mix  = [&seed](std::size_t h) noexcept { seed ^= h + 0x9e3779b97f4a7c15ULL + (seed << 6) + (seed >> 2); };
        for (const auto& term : value.identity().terms)
        {
            mix(std::hash<std::uint64_t>()(term.hash));
            mix(std::hash<std::int64_t>()(term.num));
            mix(std::hash<std::int64_t>()(term.den));
        }
        return seed;
    }
};
 
#endif // units_serialization_h_