|
| | any_unit (unit_identity id, double base) |
| | constructs an erased quantity from a decoded identity and SI-base magnitude
|
| | any_unit () |
| | constructs an empty erased quantity (dimensionless, zero) — the target for stream extraction
|
| template<class Dimension> |
| bool | is () const noexcept |
| | whether this erased quantity is of the requested dimension
|
| double | value_in_base () const noexcept |
| | the magnitude in SI canonical base units, for logging or routing
|
| const unit_identity & | identity () const noexcept |
| | the decoded dimension signature
|
| std::span< const std::byte > | bytes () const noexcept |
| | the serialized byte stream, as a type-safe view
|
| | operator std::span< const std::byte > () const noexcept |
| | an any_unit is viewable as its serialized bytes
|
| const char * | data () const noexcept |
| | a pointer to the serialized bytes as const char*, for byte-oriented interfaces
|
| std::size_t | size () const noexcept |
| | the number of serialized bytes
|
| std::string | to_string () const |
| | a human-readable text rendering of the erased quantity, for logging and diagnostics
|
| std::string | to_string_raw () const |
| | the dimension-agnostic text rendering, keyed by name-hash — always available, never resolves a name
|
| bool | operator== (const any_unit &other) const noexcept |
| | whether two erased quantities are the same dimension and magnitude
|
| bool | operator!= (const any_unit &other) const noexcept |
| | whether two erased quantities differ in dimension or magnitude
|
| std::partial_ordering | operator<=> (const any_unit &other) const noexcept |
| | orders two erased quantities of the same dimension by magnitude
|
| template<class Unit> |
| std::expected< Unit, deserialize_error > | to () const |
| | collapses into a concrete unit, checked (the safe default)
|
| template<class Unit> |
| Unit | try_to () const |
| | collapses into a concrete unit, throwing on a dimension mismatch
|
| template<class Unit> |
| bool | assign_to (Unit &out) const |
| | collapses into an existing unit variable, leaving it untouched on a dimension mismatch
|
| template<class... Dimensions, class Visitor> |
| void | visit (Visitor &&visitor) const |
| | invokes a visitor with the canonical quantity for the decoded dimension
|
template<class Unit>
| bool units::any_unit::assign_to |
( |
Unit & | out | ) |
const |
|
inline |
collapses into an existing unit variable, leaving it untouched on a dimension mismatch
The mismatch-tolerant collapse: assigns into out and returns true iff the decoded dimension is out's dimension, otherwise returns false and leaves out unchanged. It is the ergonomic form of if (auto v = to<Unit>()) out = *v; — the target unit is deduced from out, so the value need not be named twice, and the boolean says whether the assignment happened. A value that would not fit out's underlying type (to's lossy_target) is also reported as not assigned, so out is written only with a value it represents exactly. Unlike try_to/unit_cast, a mismatch is not an error but an expected outcome — the shape for pulling one erased quantity into whichever of several typed fields it fits, without a throw or a named target at each site.
- Template Parameters
-
| Unit | the target unit type; deduced from out |
- Parameters
-
| [out] | out | receives the collapsed value on a dimension (and representability) match |
- Returns
- true iff out was assigned
| const char * units::any_unit::data |
( |
| ) |
const |
|
inlinenodiscardnoexcept |
a pointer to the serialized bytes as const char*, for byte-oriented interfaces
Paired with size(), this drops directly into the interfaces that take a const char*/const
void* and a length — std::ostream::write, std::fwrite, a socket send — with no cast at the call site. The pointer views the buffer owned by this any_unit and is valid for its lifetime.
- Returns
- a pointer to the first byte
| std::partial_ordering units::any_unit::operator<=> |
( |
const any_unit & | other | ) |
const |
|
inlinenodiscardnoexcept |
orders two erased quantities of the same dimension by magnitude
Ordering is only meaningful within a dimension: two lengths compare by their SI-base magnitude, but a length and a time have no order. Same-dimension operands compare by base value; operands of different dimensions are unordered, so <, <=, >, >= are all false between them. This is a std::partial_ordering precisely because the relation is partial across dimensions.
- Parameters
-
| [in] | other | the erased quantity to compare against |
- Returns
- the base-value ordering when same-dimension, else std::partial_ordering::unordered
| std::string units::any_unit::to_string |
( |
| ) |
const |
|
inlinenodiscard |
a human-readable text rendering of the erased quantity, for logging and diagnostics
For a dimension the library knows, renders the SI-base magnitude in that dimension's canonical unit with its unit name — the same text operator<<(ostream, unit) produces (e.g. 1000 m, 9.81 m s^-2) — resolved without the caller naming a target, over the same candidate set visit() uses. For a dimension outside that set (a user-defined make_dimension), the name cannot be recovered from the wire's name-hash (the runtime→type wall), so it degrades to the raw hash form of to_string_raw(). This is the TEXT form; operator<</operator>> on a stream move the raw BINARY bytes.
- Returns
- the text rendering — a named-unit form when the dimension is known, else the raw hash form
| std::string units::any_unit::to_string_raw |
( |
| ) |
const |
|
inlinenodiscard |
the dimension-agnostic text rendering, keyed by name-hash — always available, never resolves a name
The SI-base magnitude followed by each base term as #<hash>^<exponent> (a fractional exponent as #<hash>^<num>/<den>, dimensionless as [dimensionless]). Unlike to_string(), it never attempts to name the dimension, so it renders identically for a built-in and a user-defined dimension and is the honest diagnostic for a quantity whose type the library cannot know. to_string() falls back to this whenever no known dimension matched.
- Returns
- the raw hash-keyed text rendering
template<class... Dimensions, class Visitor>
| void units::any_unit::visit |
( |
Visitor && | visitor | ) |
const |
|
inline |
invokes a visitor with the canonical quantity for the decoded dimension
The visitor is called with the canonical SI unit of whichever candidate dimension the stream holds, so no target type is named at the call site and all arithmetic inside the visitor is compile-time checked. With no explicit candidates, every dimension the library defines is a candidate (so velocity/force/energy/... resolve out of the box); pass explicit candidate dimensions (visit<my_dimension>(f)) to resolve a user-defined dimension or to disambiguate dimensions that share a signature (e.g. torque vs energy — the first listed wins). The visitor must be a generic callable (e.g. a [](auto q) lambda). Throws if no candidate matched.
- Template Parameters
-
| Dimensions | candidate dimension types (defaults to the library's known dimensions) |
| Visitor | a callable invocable with each candidate's canonical unit |
- Parameters
-
1.17.0