[#mp_units-value_cast-0f]
= xref:mp_units.adoc[mp_units]::value_cast
:relfileprefix: ../
:mrdocs:

Explicit cast of a quantity point's representation type and unit

== Synopsis

Declared in `<mp‐units/framework/value_cast.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template<
    typename ToRep,
    xref:mp_units/Unit.adoc[Unit] auto ToU,
    typename FwdQP,
    xref:mp_units/RoundingPolicy.adoc[RoundingPolicy] Policy = xref:mp_units/truncated_t.adoc[truncated_t],
    xref:mp_units/QuantityPoint.adoc[QuantityPoint] QP = std::remove_cvref_t<FwdQP>>
requires UnitOf<MP_UNITS_REMOVE_CONST(decltype(ToU)), QP::quantity_spec> &&
           RepresentationOf<ToRep, QP::quantity_spec> && std::constructible_from<ToRep, typename QP::rep> &&
           detail::ExplicitlyCastable<QP::unit, ToU, ToRep> &&
           detail::ValidRoundingPolicyFor<Policy, typename QP::rep, ToRep>
[[nodiscard]]
constexpr
xref:mp_units/QuantityPoint.adoc[QuantityPoint] auto
value_cast(
    FwdQP&& qp,
    Policy policy = Policy{});
----

== Description

Implicit conversions between quantity points of different types are allowed only for "safe" (e.g. non‐truncating) conversion. In truncating cases an explicit cast have to be used.

auto qp = value_cast<int, us>(quantity_point{1.23 * ms});

== Return Value

the quantity point converted to unit `ToU` and representation type `ToRep`

[NOTE]
====
The return value https://en.cppreference.com/cpp/language/attributes/nodiscard[should not be discarded^].
====
== Template Parameters

[cols="1,4"]
|===
| Name| Description
| *ToRep*
| a representation type to use for the target quantity
| *ToU*
| a unit to use for the target quantity
|===

== Parameters

[cols="1,4"]
|===
| Name| Description
| *qp*
| the quantity point to cast
| *policy*
| an optional rounding policy (`truncated` when not provided)
|===


[.small]#Created with https://www.mrdocs.com[MrDocs]#