A unit-tagged, optionally-empty exact value with a declared precision in its type and (optionally) a recorded derivation.
More...
|
|
constexpr | Quantity () noexcept=default |
| | Constructs the empty state (no recorded derivation).
|
| | Quantity (math::Rational engaged) |
| | Engages with engaged (which keeps its own runtime precision).
|
| | Quantity (std::optional< math::Rational > adopted) |
| | Adopts an optional payload as-is.
|
template<std::uint32_t OtherDecimals>
requires (OtherDecimals != DeclaredDecimals) |
| | Quantity (const Quantity< U, OtherDecimals > &other) |
| | Converts from the same unit at another declared precision; the value, its runtime tag, and its derivation carry over unchanged.
|
| constexpr bool | hasValue () const noexcept |
| | Whether a value has been entered/measured.
|
| constexpr bool | withinDeclaredBounds () const noexcept |
| | Pre-decode validation seam: whether the current payload falls within this field's unit-declared bounds (UnitTraits<E>::bounds), when the unit declares any. An empty payload, or a unit with no declared bounds() (HasUnitBounds not satisfied), is always within bounds — this is an opt-in check, not a new default restriction, so a unit system that declares no bounds behaves exactly as it did before this feature existed.
|
| constexpr const std::optional< math::Rational > & | value () const noexcept |
| | The payload, for pattern-matching / -> access.
|
| constexpr math::Rational | value_or (const math::Rational &fallback) const noexcept |
| | The payload if engaged, otherwise a caller-supplied fallback.
|
| constexpr const math::Rational & | operator* () const noexcept |
| | Unchecked access to the engaged value (UB when empty, exactly like std::optional::operator*).
|
| Quantity | withDecimalPlaces (math::DecimalPlaces newPrecision) const |
| | Retags the value's runtime precision (the exact value itself is unchanged — precision only affects rounding and formatting).
|
| Quantity | roundedToDecimalPlaces (math::DecimalPlaces newPrecision, math::RoundingMode mode=math::RoundingMode::HalfAwayFromZero) const |
| | Rounds the value to a runtime precision, changing the exact value as well as the tag — unlike withDecimalPlaces, which retags only and leaves display and storage free to disagree.
|
| Quantity | atDeclaredPrecision () const |
| | Rounds the value to this field's declared precision — the one the generated schema advertises as x-decimalPlaces.
|
| Quantity | named (std::string label) const |
| | Seals this value with a name: equation() shows the name instead of expanding its derivation. Builds a fresh node (never mutates a shared one); a no-op returning empty on empty or with tracing off.
|
| std::vector< std::string > | equation (std::size_t maxSteps=kDefaultEquationSteps) const |
| | The worked derivation as print-ready lines (see docs/spec/util/quantity_type.md).
|
template<auto To>
requires Convertible<U, To> |
| | operator Quantity< To > () const |
| | Implicit within-dimension conversion to another unit; delegates to convert, propagates empty, and records a provenance step.
|
template<auto U, std::uint32_t DeclaredDecimals>
requires UnitEnum<decltype(U)>
struct morph::units::Quantity< U, DeclaredDecimals >
A unit-tagged, optionally-empty exact value with a declared precision in its type and (optionally) a recorded derivation.
- Template Parameters
-
| U | An enumerator of an application unit enum satisfying UnitEnum. |
| DeclaredDecimals | Declared decimal places of the field; defaults to the unit's UnitMeta::defaultDecimals. |
Definition at line 671 of file quantity.hpp.
template<auto U, std::uint32_t DeclaredDecimals>
template<std::uint32_t OtherDecimals>
requires (OtherDecimals != DeclaredDecimals)
Converts from the same unit at another declared precision; the value, its runtime tag, and its derivation carry over unchanged.
- Parameters
-
| other | Same-unit quantity with a different declared precision. |
Definition at line 699 of file quantity.hpp.
template<auto U, std::uint32_t DeclaredDecimals>
|
|
inlinenodiscardconstexprnoexcept |
Pre-decode validation seam: whether the current payload falls within this field's unit-declared bounds (UnitTraits<E>::bounds), when the unit declares any. An empty payload, or a unit with no declared bounds() (HasUnitBounds not satisfied), is always within bounds — this is an opt-in check, not a new default restriction, so a unit system that declares no bounds behaves exactly as it did before this feature existed.
Comparison is on the exact Rational value only (never a lossy double), consistent with every other exact comparison in this header.
- Returns
- true when empty, when the unit declares no bounds, or when the engaged value satisfies min <= value <= max.
Definition at line 763 of file quantity.hpp.
template<auto U, std::uint32_t DeclaredDecimals>
Retags the value's runtime precision (the exact value itself is unchanged — precision only affects rounding and formatting).
This is the display-hint half of the pair: after it, the value shown at newPrecision and the value stored may differ. Use roundedToDecimalPlaces when the stored value must be the one displayed.
- Parameters
-
| newPrecision | Runtime precision; silently clamped to the valid range. |
- Returns
- The retagged quantity, or empty if this is empty.
Definition at line 805 of file quantity.hpp.
template<auto U, std::uint32_t DeclaredDecimals>
Rounds the value to a runtime precision, changing the exact value as well as the tag — unlike withDecimalPlaces, which retags only and leaves display and storage free to disagree.
Delegates to math::roundToDecimalPlaces, and so shares its saturation behaviour: a value whose scaled form leaves int64 range clamps and logs instead of overflowing. A value already representable at newPrecision is unchanged apart from its tag.
- Parameters
-
| newPrecision | Runtime precision; silently clamped to the valid range. |
| mode | Tie-breaking rule; defaults to half away from zero, matching the decimal display path. |
- Returns
- The rounded quantity, or empty if this is empty.
Definition at line 835 of file quantity.hpp.
template<auto U, std::uint32_t DeclaredDecimals>
Rounds the value to this field's declared precision — the one the generated schema advertises as x-decimalPlaces.
The enforcement half of the x-decimalPlaces contract: the stored value becomes the value that renders at the declared precision, so a handler never persists digits the form does not show. Rounds half away from zero, the rule the decimal formatter uses.
- Returns
- The rounded quantity, or empty if this is empty.
Definition at line 860 of file quantity.hpp.
template<auto U, std::uint32_t DeclaredDecimals>
template<auto To>
requires Convertible<U, To>
Implicit within-dimension conversion to another unit; delegates to convert, propagates empty, and records a provenance step.
- Template Parameters
-
| To | Target unit enumerator (same enum, different value, convertible). |
- Returns
- The converted quantity in unit To.
Definition at line 910 of file quantity.hpp.
1.17.0