[#mp_units-value_cast-0e3]
= xref:mp_units.adoc[mp&lowbar;units]::value&lowbar;cast
:relfileprefix: ../
:mrdocs:

Explicit cast of a quantity point&apos;s representation, including potentially the point origin

== Synopsis

Declared in `&lt;mp&hyphen;units&sol;framework&sol;value&lowbar;cast&period;h&gt;`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template&lt;
    xref:mp_units/QuantityPoint.adoc[QuantityPoint] ToQP,
    typename FwdQP,
    xref:mp_units/QuantityPoint.adoc[QuantityPoint] QP = std::remove&lowbar;cvref&lowbar;t&lt;FwdQP&gt;&gt;
requires (ToQP&colon;&colon;quantity&lowbar;spec &equals;&equals; QP&colon;&colon;quantity&lowbar;spec) &amp;&amp; UnitOf&lt;MP&lowbar;UNITS&lowbar;NONCONST&lowbar;TYPE(ToQP&colon;&colon;unit), QP&colon;&colon;quantity&lowbar;spec&gt; &amp;&amp;
          (detail&colon;&colon;same&lowbar;absolute&lowbar;point&lowbar;origins(ToQP&colon;&colon;point&lowbar;origin, QP&colon;&colon;point&lowbar;origin)) &amp;&amp;
          std&colon;&colon;constructible&lowbar;from&lt;typename ToQP&colon;&colon;rep, typename QP&colon;&colon;rep&gt; &amp;&amp;
          detail&colon;&colon;ExplicitlyCastable&lt;QP&colon;&colon;unit, ToQP&colon;&colon;unit, typename ToQP&colon;&colon;rep&gt;
&lsqb;&lsqb;nodiscard&rsqb;&rsqb;
constexpr
xref:mp_units/QuantityPoint.adoc[QuantityPoint] auto
value&lowbar;cast(FwdQP&& qp);
----

== Description

Implicit conversions between quantities of different types are allowed only for &quot;safe&quot; (e&period;g&period; non&hyphen;truncating) conversion&period; In truncating cases an explicit cast have to be used&period;

inline constexpr struct A &colon; absolute&lowbar;point&lowbar;origin[ A&semi;] inline constexpr struct B &colon; relative&lowbar;point&lowbar;origin[ B&semi;]

using ToQP &equals; quantity&lowbar;point&lt;mm, B, int&gt;&semi; auto qp &equals; value&lowbar;cast&lt;ToQP&gt;(quantity&lowbar;point&lcub;1&period;23 &ast; m&rcub;)&semi;

Note that value&lowbar;cast only changes the &quot;representation aspects&quot; (unit, representation type and point origin), but not the &quot;meaning&quot; (quantity type or the actual point that is being described)&period;

Note also that changing the point origin bears risks regarding truncation and overflow similar to other casts that change representation (which is why we require a `value&lowbar;cast` and disallow implicit conversions)&period; This cast is guaranteed not to cause overflow of any intermediate representation type provided that the input quantity point is within the range of `ToQP`&period; Calling `value&lowbar;cast&lt;ToQP&gt;(qp)` on a `qp` outside of the range of `ToQP` is potentially undefined behaviour&period; The implementation further attempts not to cause more than rounding error than approximately the sum of the resolution of `qp` as represented in `FromQP`, plus the resolution of `qp` as represented in `ToQP`&period;

== Return Value

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

[cols="1,4"]
|===
| Name| Description
| *ToQP*
| a target quantity point type to which to cast the representation of the point
|===


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