mp-units/HEAD/api_reference/gen/qty.common.unit.html

<!DOCTYPE html><html lang='en'><head><title>[qty.common.unit]</title><meta charset='UTF-8'/><link rel='stylesheet' type='text/css' href='14882.css'/><link rel='stylesheet' type='text/css' href='https://fonts.googleapis.com/css2?family=Noto+Serif'/><link rel='stylesheet' type='text/css' href='https://fonts.googleapis.com/css2?family=Noto+Sans'/><link rel='stylesheet' type='text/css' href='https://fonts.googleapis.com/css2?family=Noto+Sans+Mono'/><link rel='icon' href='icon.png'/><link rel='stylesheet' type='text/css' href='expanded.css' title='Normal'/><link rel='alternate stylesheet' type='text/css' href='colored.css' title='Notes and examples colored'/><link rel='alternate stylesheet' type='text/css' href='normative-only.css' title='Notes and examples hidden'/></head><body><div class='wrapper'><h1 ><a class='secnum' style='min-width:50pt'>5</a> Quantities and units library <a class='abbr_ref' href='index.html#quantities'>[quantities]</a></h1><h2 ><a class='secnum' style='min-width:65pt'>5.4</a> Reference <a class='abbr_ref' href='qty.ref.html#qty.common.unit'>[qty.ref]</a></h2><h3 ><a class='secnum' style='min-width:80pt'>5.4.4</a> Unit <a class='abbr_ref' href='qty.unit.html#qty.common.unit'>[qty.unit]</a></h3><h4 ><a class='secnum' style='min-width:95pt'>5.4.4.5</a> Types <a class='abbr_ref' href='qty.unit.types.html#qty.common.unit'>[qty.unit.types]</a></h4><h4 ><a class='secnum' style='min-width:110pt'>5.4.4.5.5</a> Common <a class='abbr_ref'>[qty.common.unit]</a></h4><div class='texpara'><span id='lib:common_unit'><div class='marginalizedparent'><a class='itemDeclLink' href='#lib:common_unit'>🔗</a></div><span class='codeblock'><span class='keyword'>namespace</span> mp_units <span class='curlybracket'>{</span>

<span class='keyword'>template</span><span class='anglebracket'>&lt;</span><a href='qty.unit.concepts.html#concept:Unit' title='5.4.4.4&emsp;Concepts&emsp;[qty.unit.concepts]'><span id='conceptref:Unit'><span class='tcode_in_codeblock'>Unit</span></span></a> U1, <a href='qty.unit.concepts.html#concept:Unit' title='5.4.4.4&emsp;Concepts&emsp;[qty.unit.concepts]'><span id='conceptref:Unit_'><span class='tcode_in_codeblock'>Unit</span></span></a> U2, <a href='qty.unit.concepts.html#concept:Unit' title='5.4.4.4&emsp;Concepts&emsp;[qty.unit.concepts]'><span id='conceptref:Unit__'><span class='tcode_in_codeblock'>Unit</span></span></a><span class='operator'>.</span><span class='operator'>.</span><span class='operator'>.</span> Rest<span class='anglebracket'>&gt;</span>
<span class='keyword'>struct</span> common_unit <span class='keyword'>final</span> <span class='operator'>:</span> <span class='keyword'>decltype</span><span class='parenthesis'>(</span><i >get-common-scaled-unit</i><span class='parenthesis'>(</span>U1<span class='curlybracket'>{</span><span class='curlybracket'>}</span>, U2<span class='curlybracket'>{</span><span class='curlybracket'>}</span>, Rest<span class='curlybracket'>{</span><span class='curlybracket'>}</span><span class='operator'>.</span><span class='operator'>.</span><span class='operator'>.</span><span class='parenthesis'>)</span><span class='parenthesis'>)</span><span class='operator'>::</span><i >base-type</i>
<span class='curlybracket'>{</span>
  <span class='keyword'>using</span> <i >base-type</i> <span class='operator'>=</span> common_unit;       <span class='comment'>// <i >exposition only</i></span>
  <span class='keyword'>static</span> <span class='keyword'>constexpr</span> <span class='keyword'>auto</span> <i >common-unit</i> <span class='operator'>=</span>  <span class='comment'>// <i >exposition only</i></span>
    <i >get-common-scaled-unit</i><span class='parenthesis'>(</span>U1<span class='curlybracket'>{</span><span class='curlybracket'>}</span>, U2<span class='curlybracket'>{</span><span class='curlybracket'>}</span>, Rest<span class='curlybracket'>{</span><span class='curlybracket'>}</span><span class='operator'>.</span><span class='operator'>.</span><span class='operator'>.</span><span class='parenthesis'>)</span>;
<span class='curlybracket'>}</span>;

<span class='curlybracket'>}</span>
</span></span></div><div class='para' id='1'><div class='marginalizedparent'><a class='marginalized' href='#1'>1</a></div><div class='sourceLinkParent'><a class='sourceLink' href='https://github.com/mpusz/mp-units329ffdaacb1bd7bed08565ac80d9eef7ccb1e5b5/source/quantities.tex#L2811'>#</a></div><div class='texpara'><div id='1.sentence-1' class='sentence'><span class='texttt'>common_<span class='shy'></span>unit</span> is used by the library
to encapsulate a conversion factor between units (<a href="https://www.electropedia.org/iev/iev.nsf/display?openform&ievref=112-01-33">IEC 60050, 112-01-33</a>)
common to the operands of quantity addition<a class='hidden_link' href='#1.sentence-1'>.</a></div> <div id='example-1' class='example'><div class='texpara'>[<i>Example&nbsp;<a href='#example-1'>1</a></i>:&ensp;<div id='1.sentence-2' class='sentence'>The result of <span class='texttt'><span class='literal'>1</span> <span class='operator'>*</span> km <span class='operator'>+</span> <span class='literal'>1</span> <span class='operator'>*</span> mi</span>
has a common unit <span class="mjx-chtml"><span class="mjx-math"><span class="mjx-mrow" aria-hidden="true"><span class="mjx-mo"><span class="mjx-char MJXc-TeX-main-R" style="padding-top: 0.446em; padding-bottom: 0.593em;">[</span></span><span class="mjx-mn"><span class="mjx-char MJXc-TeX-main-R" style="padding-top: 0.372em; padding-bottom: 0.372em;">8</span></span><span class="mjx-texatom"><span class="mjx-mrow"><span class="mjx-mo"><span class="mjx-char MJXc-TeX-main-R" style="padding-top: 0.446em; padding-bottom: 0.593em;">/</span></span></span></span><span class="mjx-mn"><span class="mjx-char MJXc-TeX-main-R" style="padding-top: 0.372em; padding-bottom: 0.372em;">125</span></span><span class="mjx-mo"><span class="mjx-char MJXc-TeX-main-R" style="padding-top: 0.446em; padding-bottom: 0.593em;">]</span></span><span class="mjx-texatom"><span class="mjx-mrow"><span class="mjx-mtext"><span class="mjx-char MJXc-TeX-main-R" style="padding-top: 0.151em; padding-bottom: 0.372em;"> m</span></span></span></span></span></span></span>
encapsulated by <span class='texttt'>common_<span class='shy'></span>unit<span class='anglebracket'>&lt;</span>mi, km<span class='anglebracket'>&gt;</span></span><a class='hidden_link' href='#1.sentence-2'>.</a></div> —&nbsp;<i>end example</i>]</div></div> <div id='1.sentence-3' class='sentence'>
A program that instantiates a specialization of <span class='texttt'>common_<span class='shy'></span>unit</span>
that is not a possible result of the library specifications
is ill-formed, no diagnostic required<a class='hidden_link' href='#1.sentence-3'>.</a></div></div></div><div class='texpara'><div class='itemdecl' id='itemdecl:1'><div class='marginalizedparent'><a class='itemDeclLink' href='#itemdecl:1'>🔗</a></div><code class='itemdeclcode'><span class='keyword'>template</span><span class='anglebracket'>&lt;</span><a href='qty.unit.concepts.html#concept:Unit' title='5.4.4.4&emsp;Concepts&emsp;[qty.unit.concepts]'><span id='conceptref:Unit___'><span class='texttt'>Unit</span></span></a> U1, <a href='qty.unit.concepts.html#concept:Unit' title='5.4.4.4&emsp;Concepts&emsp;[qty.unit.concepts]'><span id='conceptref:Unit____'><span class='texttt'>Unit</span></span></a> U2, <a href='qty.unit.concepts.html#concept:Unit' title='5.4.4.4&emsp;Concepts&emsp;[qty.unit.concepts]'><span id='conceptref:Unit_____'><span class='texttt'>Unit</span></span></a><span class='operator'>.</span><span class='operator'>.</span><span class='operator'>.</span> Rest<span class='anglebracket'>&gt;</span>
<span class='keyword'>consteval</span> <a href='qty.unit.concepts.html#concept:Unit' title='5.4.4.4&emsp;Concepts&emsp;[qty.unit.concepts]'><span id='conceptref:Unit______'><span class='texttt'>Unit</span></span></a> <span class='keyword'>auto</span> <span class='texttt'><i >get-common-scaled-unit</i></span><span class='parenthesis'>(</span>U1, U2, Rest<span class='operator'>.</span><span class='operator'>.</span><span class='operator'>.</span> rest<span class='parenthesis'>)</span>  <span class='comment'>// <i >exposition only</i></span>
  <span class='keyword'>requires</span> <i ><span class='texttt'>see below</span></i>;
</code></div></div><div class='para' id='2'><div class='marginalizedparent'><a class='marginalized' href='#2'>2</a></div><div class='itemdescr'><div class='sourceLinkParent'><a class='sourceLink' href='https://github.com/mpusz/mp-units329ffdaacb1bd7bed08565ac80d9eef7ccb1e5b5/source/quantities.tex#L2831'>#</a></div><div class='texpara'><div id='2.sentence-1' class='sentence'><i >Effects</i>: Equivalent to:
<span class='codeblock'><span class='keyword'>constexpr</span> <span class='keyword'>auto</span> res <span class='operator'>=</span> <span class='squarebracket'>[</span><span class='squarebracket'>]</span> <span class='curlybracket'>{</span>
  <span class='keyword'>constexpr</span> <span class='keyword'>auto</span> canonical_lhs <span class='operator'>=</span> <i >get-canonical-unit</i><span class='parenthesis'>(</span>U1<span class='curlybracket'>{</span><span class='curlybracket'>}</span><span class='parenthesis'>)</span>;
  <span class='keyword'>constexpr</span> <span class='keyword'>auto</span> canonical_rhs <span class='operator'>=</span> <i >get-canonical-unit</i><span class='parenthesis'>(</span>U2<span class='curlybracket'>{</span><span class='curlybracket'>}</span><span class='parenthesis'>)</span>;
  <span class='keyword'>constexpr</span> <span class='keyword'>auto</span> common_mag <span class='operator'>=</span> <i >common-magnitude</i><span class='parenthesis'>(</span>canonical_lhs<span class='operator'>.</span>mag, canonical_rhs<span class='operator'>.</span>mag<span class='parenthesis'>)</span>;
  <span class='keyword'>if</span> <span class='keyword'>constexpr</span> <span class='parenthesis'>(</span>common_mag <span class='operator'>=</span><span class='operator'>=</span> mag<span class='anglebracket'>&lt;</span><span class='literal'>1</span><span class='anglebracket'>&gt;</span><span class='parenthesis'>)</span>
    <span class='keyword'>return</span> canonical_lhs<span class='operator'>.</span>reference_unit;
  <span class='keyword'>else</span>
    <span class='keyword'>return</span> scaled_unit<span class='anglebracket'>&lt;</span>common_mag, <span class='keyword'>decltype</span><span class='parenthesis'>(</span><span class='keyword'>auto</span><span class='parenthesis'>(</span>canonical_lhs<span class='operator'>.</span>reference_unit<span class='parenthesis'>)</span><span class='parenthesis'>)</span><span class='anglebracket'>&gt;</span><span class='curlybracket'>{</span><span class='curlybracket'>}</span>;
<span class='curlybracket'>}</span><span class='parenthesis'>(</span><span class='parenthesis'>)</span>;
<span class='keyword'>if</span> <span class='keyword'>constexpr</span> <span class='parenthesis'>(</span><span class='keyword'>sizeof</span><span class='operator'>.</span><span class='operator'>.</span><span class='operator'>.</span><span class='parenthesis'>(</span>rest<span class='parenthesis'>)</span> <span class='operator'>=</span><span class='operator'>=</span> <span class='literal'>0</span><span class='parenthesis'>)</span>
  <span class='keyword'>return</span> res;
<span class='keyword'>else</span>
  <span class='keyword'>return</span> <i >get-common-scaled-unit</i><span class='parenthesis'>(</span>res, rest<span class='operator'>.</span><span class='operator'>.</span><span class='operator'>.</span><span class='parenthesis'>)</span>;
</span></div></div></div></div><div class='para' id='3'><div class='marginalizedparent'><a class='marginalized' href='#3'>3</a></div><div class='itemdescr'><div class='sourceLinkParent'><a class='sourceLink' href='https://github.com/mpusz/mp-units329ffdaacb1bd7bed08565ac80d9eef7ccb1e5b5/source/quantities.tex#L2850'>#</a></div><div class='texpara'><div id='3.sentence-1' class='sentence'><i >Remarks</i>: The expression in the <span class='textsf'><i >requires-clause</i></span> is equivalent to:
<span class='codeblock'><span class='parenthesis'>(</span>convertible<span class='parenthesis'>(</span>U1<span class='curlybracket'>{</span><span class='curlybracket'>}</span>, U2<span class='curlybracket'>{</span><span class='curlybracket'>}</span><span class='parenthesis'>)</span> <span class='operator'>&amp;</span><span class='operator'>&amp;</span> <span class='parenthesis'>(</span><span class='keyword'>sizeof</span><span class='operator'>.</span><span class='operator'>.</span><span class='operator'>.</span><span class='parenthesis'>(</span>Rest<span class='parenthesis'>)</span> <span class='operator'>=</span><span class='operator'>=</span> <span class='literal'>0</span> <span class='operator'>|</span><span class='operator'>|</span> <span class='keyword'>requires</span> <span class='curlybracket'>{</span>
   <i >get-common-scaled-unit</i><span class='parenthesis'>(</span><i >get-common-scaled-unit</i><span class='parenthesis'>(</span>u1, u2<span class='parenthesis'>)</span>, rest<span class='operator'>.</span><span class='operator'>.</span><span class='operator'>.</span><span class='parenthesis'>)</span>;
 <span class='curlybracket'>}</span><span class='parenthesis'>)</span><span class='parenthesis'>)</span>
</span></div></div></div></div></div></body></html>