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

Explicit cast of a quantity's representation type

== Synopsis

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

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template<
    typename ToRep,
    typename FwdQ,
    xref:mp_units/RoundingPolicy.adoc[RoundingPolicy] Policy = xref:mp_units/truncated_t.adoc[truncated_t],
    xref:mp_units/Quantity.adoc[Quantity] Q = std::remove_cvref_t<FwdQ>>
requires RepresentationOf<ToRep, Q::quantity_spec> && std::constructible_from<ToRep, typename Q::rep> &&
           detail::ValidRoundingPolicyFor<Policy, typename Q::rep, ToRep>
[[nodiscard]]
constexpr
xref:mp_units/quantity-01.adoc[quantity<Q::reference, ToRep>]
value_cast(
    FwdQ&& q,
    Policy = Policy{});
----

== Description

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

auto q = value_cast<int>(1.23 * ms); auto r = value_cast<int>(1.55 * ms, rounded);

== Return Value

A quantity

[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 a target quantity
|===

== Parameters

[cols="1,4"]
|===
| Name| Description
| *policy*
| an optional rounding policy (`truncated` when not provided)
|===


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