serialization.h File Reference

self-describing binary serialization of quantities More...

#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>

Include dependency graph for serialization.h:

Go to the source code of this file.

Classes
struct	units::dimension_term
	one base-dimension term of a signature: which base dimension (by name-hash), and its rational exponent More...
struct	units::unit_identity
	the runtime identity of a quantity's dimension — the set of nonzero base-dimension terms More...
struct	units::detail::signature< Unit >
	the compile-time signature of a unit as a fixed-size, sorted array of terms More...
class	units::any_unit
struct	std::hash< units::any_unit >
	hashes an erased quantity by its dimension signature and SI-base magnitude, so any_unit is usable as an unordered-container key. More...

Namespaces
namespace	units
	Unit Conversion Library namespace.

Typedefs
using	units::detail::builtin_dimensions
	The library's known dimensions, offered to visit as the default candidate set so a stream of any built-in dimension resolves without the caller naming it.
template<class Dim>
using	units::detail::canonical_unit_t = unit<conversion_factor<std::ratio<1>, Dim>, double>
	the canonical SI base unit of a dimension (ratio 1, no pi, no translation)

Enumerations
enum class	units::deserialize_error {   units::truncated , units::bad_version , units::dimension_mismatch , units::unknown_base_dimension ,   units::lossy_target }
	the reasons a deserialize can fail More...
enum class	units::detail::value_kind : std::uint8_t { ivarint = 0 , f32 = 1 , f64 = 2 }
	header byte layout: [ valueKind:2 | fracExp:1 | reserved:5 ] More...

Functions
constexpr std::uint64_t	units::detail::name_hash (std::string_view name) noexcept
	FNV-1a 64-bit hash of a base dimension's name.
void	units::detail::put_uvarint (std::vector< std::byte > &out, std::uint64_t value)
	appends an unsigned integer to a byte buffer as an LEB128 varint
void	units::detail::put_svarint (std::vector< std::byte > &out, std::int64_t value)
	appends a signed integer to a byte buffer as a zig-zag LEB128 varint
bool	units::detail::get_uvarint (const std::byte *&cursor, const std::byte *end, std::uint64_t &value)
	reads an LEB128 unsigned varint from a byte cursor
bool	units::detail::get_svarint (const std::byte *&cursor, const std::byte *end, std::int64_t &value)
	reads a zig-zag LEB128 signed varint from a byte cursor
template<class DimensionList>
consteval std::size_t	units::detail::dimension_arity ()
	the number of base-dimension terms in a dimension_t<...> list
template<class DimensionList, std::size_t N>
consteval void	units::detail::fill_terms (std::array< dimension_term, N > &out, std::size_t at)
	writes a term per base dimension of a dimension_t<...> list into a fixed span
template<UnitType Unit>
unit_identity	units::detail::identity_of ()
	the dimension signature of a unit type, as the runtime (vector-backed) identity
std::vector< std::byte >	units::detail::encode (const unit_identity &identity, double base)
	encodes a dimension identity and SI-base magnitude to the self-describing byte stream
std::ostream &	units::operator<< (std::ostream &os, const any_unit &value)
	writes an erased quantity's self-describing BINARY bytes to a stream
template<class Target>
Target	units::unit_cast (const any_unit &value)
	explicit cast from an erased any_unit to a concrete unit, throwing on a dimension mismatch
template<class Unit>
any_unit	units::serialize (const Unit &quantity)
	serializes a quantity to a self-describing, erased any_unit
std::expected< any_unit, deserialize_error >	units::deserialize (std::span< const std::byte > bytes)
	decodes a self-describing byte stream into an erased quantity
template<class Unit>
std::expected< Unit, deserialize_error >	units::deserialize (std::span< const std::byte > bytes)
	decodes a self-describing byte stream directly into a known unit type (fully static)
std::expected< any_unit, deserialize_error >	units::deserialize (std::istream &is)
	reads and decodes one self-describing erased quantity from a binary stream, in a single expression
std::istream &	units::operator>> (std::istream &is, any_unit &value)
	reads one self-describing erased quantity from a binary stream (classic stream-extraction form)
template<class Unit>
std::expected< Unit, deserialize_error >	units::deserialize (std::istream &is)
	reads and decodes one record from a binary stream directly into a known unit type

Variables
constexpr std::uint8_t	units::detail::serialization_version = 1

Detailed Description

self-describing binary serialization of quantities

Typedef Documentation

builtin_dimensions

using units::detail::builtin_dimensions

Initial value:

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>

The library's known dimensions, offered to visit as the default candidate set so a stream of any built-in dimension resolves without the caller naming it.

This is NOT the wire vocabulary: the stream keys each base dimension by a hash of its name STRING, so a dimension the library has never seen — including a user-defined make_dimension<my_tag> — still serializes and round-trips. visit cannot resolve a user-defined dimension unless the caller lists it (visit<my_dimension>(f)), because C++ cannot materialize a type from the runtime hash — the runtime→type wall. The set is otherwise open by design.

Enumeration Type Documentation

value_kind

enum class units::detail::value_kind : std::uint8_t

strong

header byte layout: [ valueKind:2 | fracExp:1 | reserved:5 ]

Enumerator
ivarint	value is an integer in SI base, zig-zag varint
f32	value is an exact 32-bit float
f64	value is a 64-bit double

Function Documentation

dimension_arity()

template<class DimensionList>

std::size_t units::detail::dimension_arity ( )

consteval

the number of base-dimension terms in a dimension_t<...> list

Template Parameters

DimensionList

a dimension_t<...> specialization

Returns

the term count

encode()

std::vector< std::byte > units::detail::encode ( const unit_identity & identity, double base )

inline

encodes a dimension identity and SI-base magnitude to the self-describing byte stream

The single source of truth for the wire format, used by both serialize (from a compile-time signature) and any_unit (from its decoded runtime identity), so a value and its round-tripped form encode byte-identically. The value encoding is chosen from base alone (tersest exact: integer varint, else exact 32-bit float, else 64-bit double), so it does not depend on the source unit's underlying type.

Parameters

[in]	identity	the ordered base-dimension terms (sorted by hash)
[in]	base	the magnitude in SI canonical base

Returns

the encoded bytes

fill_terms()

template<class DimensionList, std::size_t N>

void units::detail::fill_terms ( std::array< dimension_term, N > & out, std::size_t at )

consteval

writes a term per base dimension of a dimension_t<...> list into a fixed span

Each term is keyed by a hash of the base dimension's name, so ANY base dimension — built-in or user-defined make_dimension<my_tag> — is captured; there is no fixed vocabulary.

Template Parameters

DimensionList	a dimension_t<...> specialization
N	the fixed capacity of the destination array

Parameters

[out]	out	the destination array
[in]	at	the index to write the front term at

get_svarint()

bool units::detail::get_svarint ( const std::byte *& cursor, const std::byte * end, std::int64_t & value )

inline

reads a zig-zag LEB128 signed varint from a byte cursor

Parameters

[in,out]	cursor	pointer into the buffer; advanced past the value on success
[in]	end	one-past-the-end of the buffer
[out]	value	decoded value

Returns

true on success, false if the buffer was truncated

get_uvarint()

bool units::detail::get_uvarint ( const std::byte *& cursor, const std::byte * end, std::uint64_t & value )

inline

reads an LEB128 unsigned varint from a byte cursor

Parameters

[in,out]	cursor	pointer into the buffer; advanced past the value on success
[in]	end	one-past-the-end of the buffer
[out]	value	decoded value

Returns

true on success, false if the buffer was truncated

identity_of()

template<UnitType Unit>

unit_identity units::detail::identity_of

(

)

the dimension signature of a unit type, as the runtime (vector-backed) identity

Materializes the compile-time fixed-array signature into a unit_identity for runtime compare.

Template Parameters

Unit	a UnitType

Returns

the unit_identity (nonzero base-dimension terms, sorted by hash)

name_hash()

std::uint64_t units::detail::name_hash ( std::string_view name )

constexprnoexcept

FNV-1a 64-bit hash of a base dimension's name.

Hashing the library-controlled name string (not a compiler-generated type name) is portable across compilers and versions, is a fixed 8 bytes regardless of name length, and needs no central table — any dimension name, built-in or user-defined, hashes to a stable wire key.

Parameters

[in]

name

the dimension name

Returns

the 64-bit hash

put_svarint()

void units::detail::put_svarint ( std::vector< std::byte > & out, std::int64_t value )

inline

appends a signed integer to a byte buffer as a zig-zag LEB128 varint

Parameters

[out]	out	buffer to append to
[in]	value	value to encode

put_uvarint()

void units::detail::put_uvarint ( std::vector< std::byte > & out, std::uint64_t value )

inline

appends an unsigned integer to a byte buffer as an LEB128 varint

Parameters

[out]	out	buffer to append to
[in]	value	value to encode