1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<head> 4<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 5<title>Quantities</title> 6<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css"> 7<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 8<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset"> 9<link rel="up" href="../boost_units.html" title="Chapter 43. Boost.Units 1.1.0"> 10<link rel="prev" href="Units.html" title="Units"> 11<link rel="next" href="Examples.html" title="Examples"> 12</head> 13<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 14<table cellpadding="2" width="100%"><tr> 15<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td> 16<td align="center"><a href="../../../index.html">Home</a></td> 17<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td> 18<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> 19<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> 20<td align="center"><a href="../../../more/index.htm">More</a></td> 21</tr></table> 22<hr> 23<div class="spirit-nav"> 24<a accesskey="p" href="Units.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../boost_units.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="Examples.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> 25</div> 26<div class="section"> 27<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 28<a name="boost_units.Quantities"></a><a class="link" href="Quantities.html" title="Quantities">Quantities</a> 29</h2></div></div></div> 30<div class="toc"><dl class="toc"> 31<dt><span class="section"><a href="Quantities.html#boost_units.Quantities.Heterogeneous_Operators">Heterogeneous 32 Operators</a></span></dt> 33<dt><span class="section"><a href="Quantities.html#boost_units.Quantities.Conversions">Conversions</a></span></dt> 34<dt><span class="section"><a href="Quantities.html#boost_units.Quantities.Quantity_Construction_and_Conversion">Construction 35 and Conversion of Quantities</a></span></dt> 36</dl></div> 37<p> 38 A <span class="bold"><strong>quantity</strong></span> is defined as a value of an arbitrary 39 value type that is associated with a specific unit. For example, while meter 40 is a unit, 3.0 meters is a quantity. Quantities obey two separate algebras: 41 the native algebra for their value type, and the dimensional analysis algebra 42 for the associated unit. In addition, algebraic operations are defined between 43 units and quantities to simplify the definition of quantities; it is effectively 44 equivalent to algebra with a unit-valued quantity. 45 </p> 46<p> 47 Quantities are implemented by the <span class="underline"><code class="computeroutput"><a class="link" href="../boost/units/quantity.html" title="Class template quantity">quantity</a></code></span> 48 template class defined in <code class="computeroutput"><a class="link" href="Reference.html#header.boost.units.quantity_hpp" title="Header <boost/units/quantity.hpp>">boost/units/quantity.hpp</a></code> 49 : 50 </p> 51<pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">Unit</span><span class="special">,</span><span class="keyword">class</span> <span class="identifier">Y</span> <span class="special">=</span> <span class="keyword">double</span><span class="special">></span> <span class="keyword">class</span> <span class="identifier">quantity</span><span class="special">;</span> 52</pre> 53<p> 54 This class is templated on both unit type (<code class="computeroutput"><span class="identifier">Unit</span></code>) 55 and value type (<code class="computeroutput"><span class="identifier">Y</span></code>), with the 56 latter defaulting to double-precision floating point if not otherwise specified. 57 The value type must have a normal copy constructor and copy assignment operator. 58 Operators +, -, *, and / are provided for algebraic operations between scalars 59 and units, scalars and quantities, units and quantities, and between quantities. 60 In addition, integral and rational powers and roots can be computed using the 61 <span class="underline"><code class="computeroutput"><a class="link" href="../boost/units/pow_1_3_44_10_2_5_3_1_29.html" title="Function template pow">pow</a></code></span><R> 62 and <span class="underline"><code class="computeroutput"><a class="link" href="Reference.html#boost.units.root_1_3_44_10_2_35_2_1_3">root</a></code></span><R> 63 functions. Finally, the standard set of boolean comparison operators ( <code class="computeroutput"><span class="special">==,</span> <span class="special">!=,</span> <span class="special"><,</span> 64 <span class="special"><=,</span> <span class="special">>,</span> 65 <span class="keyword">and</span> <span class="special">>=</span></code> 66 ) are provided to allow comparison of quantities from the same unit system. 67 All operators simply delegate to the corresponding operator of the value type 68 if the units permit. 69 </p> 70<div class="section"> 71<div class="titlepage"><div><div><h3 class="title"> 72<a name="boost_units.Quantities.Heterogeneous_Operators"></a><a class="link" href="Quantities.html#boost_units.Quantities.Heterogeneous_Operators" title="Heterogeneous Operators">Heterogeneous 73 Operators</a> 74</h3></div></div></div> 75<p> 76 For most common value types, the result type of arithmetic operators is the 77 same as the value type itself. For example, the sum of two double precision 78 floating point numbers is another double precision floating point number. 79 However, there are instances where this is not the case. A simple example 80 is given by the <a href="http://en.wikipedia.org/wiki/Natural_number" target="_top">natural 81 numbers</a> where the operator arithmetic obeys the following rules (using 82 the standard notation for <a href="http://en.wikipedia.org/wiki/Number" target="_top">number 83 systems</a>): 84 </p> 85<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 86<li class="listitem"> 87 <span class="inlinemediaobject"><img src="../../../libs/units/images/form_12.png" alt="form_12"></span> 88 </li> 89<li class="listitem"> 90 <span class="inlinemediaobject"><img src="../../../libs/units/images/form_13.png" alt="form_13"></span> 91 </li> 92<li class="listitem"> 93 <span class="inlinemediaobject"><img src="../../../libs/units/images/form_14.png" alt="form_14"></span> 94 </li> 95<li class="listitem"> 96 <span class="inlinemediaobject"><img src="../../../libs/units/images/form_15.png" alt="form_15"></span> 97 </li> 98</ul></div> 99<p> 100 This library is designed to support arbitrary value type algebra for addition, 101 subtraction, multiplication, division, and rational powers and roots. It 102 uses Boost.Typeof to deduce the result of these operators. For compilers 103 that support <code class="computeroutput"><span class="identifier">typeof</span></code>, the 104 appropriate value type will be automatically deduced. For compilers that 105 do not provide language support for <code class="computeroutput"><span class="identifier">typeof</span></code> 106 it is necessary to register all the types used. For the case of natural numbers, 107 this would amount to something like the following: 108 </p> 109<pre class="programlisting"><span class="identifier">BOOST_TYPEOF_REGISTER_TYPE</span><span class="special">(</span><span class="identifier">natural</span><span class="special">);</span> 110<span class="identifier">BOOST_TYPEOF_REGISTER_TYPE</span><span class="special">(</span><span class="identifier">integer</span><span class="special">);</span> 111<span class="identifier">BOOST_TYPEOF_REGISTER_TYPE</span><span class="special">(</span><span class="identifier">rational</span><span class="special">);</span> 112</pre> 113</div> 114<div class="section"> 115<div class="titlepage"><div><div><h3 class="title"> 116<a name="boost_units.Quantities.Conversions"></a><a class="link" href="Quantities.html#boost_units.Quantities.Conversions" title="Conversions">Conversions</a> 117</h3></div></div></div> 118<p> 119 Conversion is only meaningful for quantities as it implies the presence of 120 at least a multiplicative scale factor and, possibly, and affine linear offset. 121 Macros for simplifying the definition of conversions between units can be 122 found in <code class="computeroutput"><a class="link" href="Reference.html#header.boost.units.conversion_hpp" title="Header <boost/units/conversion.hpp>">boost/units/conversion.hpp</a></code> 123 and <code class="computeroutput"><a class="link" href="Reference.html#header.boost.units.absolute_hpp" title="Header <boost/units/absolute.hpp>">boost/units/absolute.hpp</a></code> 124 (for affine conversions with offsets). 125 </p> 126<p> 127 The macro <span class="underline"><code class="computeroutput"><a class="link" href="../BOOST_UNIT_1_3_44_10_2_7_3.html" title="Macro BOOST_UNITS_DEFINE_CONVERSION_FACTOR">BOOST_UNITS_DEFINE_CONVERSION_FACTOR</a></code></span> 128 specifies a scale factor for conversion from the first unit type to the second. 129 The first argument must be a <span class="underline"><code class="computeroutput"><a class="link" href="../boost/units/base_unit.html" title="Class template base_unit">base_unit</a></code></span>. 130 The second argument can be either a <span class="underline"><code class="computeroutput"><a class="link" href="../boost/units/base_unit.html" title="Class template base_unit">base_unit</a></code></span> or a <span class="underline"><code class="computeroutput"><a class="link" href="../boost/units/unit.html" title="Class template unit">unit</a></code></span>. 131 </p> 132<p> 133 Let's declare a simple base unit: 134 </p> 135<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">foot_base_unit</span> <span class="special">:</span> <span class="identifier">base_unit</span><span class="special"><</span><span class="identifier">foot_base_unit</span><span class="special">,</span> <span class="identifier">length_dimension</span><span class="special">,</span> <span class="number">10</span><span class="special">></span> <span class="special">{</span> <span class="special">};</span> 136</pre> 137<p> 138 Now, we want to be able to convert feet to meters and vice versa. The foot 139 is defined as exactly 0.3048 meters, so we can write the following 140 </p> 141<pre class="programlisting"><span class="identifier">BOOST_UNITS_DEFINE_CONVERSION_FACTOR</span><span class="special">(</span><span class="identifier">foot_base_unit</span><span class="special">,</span> <span class="identifier">meter_base_unit</span><span class="special">,</span> <span class="keyword">double</span><span class="special">,</span> <span class="number">0.3048</span><span class="special">);</span> 142</pre> 143<p> 144 Alternately, we could use the SI length <code class="computeroutput"><span class="keyword">typedef</span></code>: 145 </p> 146<pre class="programlisting"><span class="identifier">BOOST_UNITS_DEFINE_CONVERSION_FACTOR</span><span class="special">(</span><span class="identifier">foot_base_unit</span><span class="special">,</span> <span class="identifier">SI</span><span class="special">::</span><span class="identifier">length</span><span class="special">,</span> <span class="keyword">double</span><span class="special">,</span> <span class="number">0.3048</span><span class="special">);</span> 147</pre> 148<p> 149 Since the SI unit of length is the meter, these two definitions are equivalent. 150 If these conversions have been defined, then converting between scaled forms 151 of these units will also automatically work. 152 </p> 153<p> 154 The macro <span class="underline"><code class="computeroutput"><a class="link" href="../BOOST_UNIT_1_3_44_10_2_7_5.html" title="Macro BOOST_UNITS_DEFAULT_CONVERSION">BOOST_UNITS_DEFAULT_CONVERSION</a></code></span> 155 specifies a conversion that will be applied to a base unit when no direct 156 conversion is possible. This can be used to make arbitrary conversions work 157 with a single specialization: 158 </p> 159<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">my_unit_tag</span> <span class="special">:</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">units</span><span class="special">::</span><span class="identifier">base_unit</span><span class="special"><</span><span class="identifier">my_unit_tag</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">units</span><span class="special">::</span><span class="identifier">force_type</span><span class="special">,</span> <span class="number">1</span><span class="special">></span> <span class="special">{};</span> 160<span class="comment">// define the conversion factor</span> 161<span class="identifier">BOOST_UNITS_DEFINE_CONVERSION_FACTOR</span><span class="special">(</span><span class="identifier">my_unit_tag</span><span class="special">,</span> <span class="identifier">SI</span><span class="special">::</span><span class="identifier">force</span><span class="special">,</span> <span class="keyword">double</span><span class="special">,</span> <span class="number">3.14159265358979323846</span><span class="special">);</span> 162<span class="comment">// make conversion to SI the default.</span> 163<span class="identifier">BOOST_UNITS_DEFAULT_CONVERSION</span><span class="special">(</span><span class="identifier">my_unit_tag</span><span class="special">,</span> <span class="identifier">SI</span><span class="special">::</span><span class="identifier">force</span><span class="special">);</span> 164</pre> 165</div> 166<div class="section"> 167<div class="titlepage"><div><div><h3 class="title"> 168<a name="boost_units.Quantities.Quantity_Construction_and_Conversion"></a><a class="link" href="Quantities.html#boost_units.Quantities.Quantity_Construction_and_Conversion" title="Construction and Conversion of Quantities">Construction 169 and Conversion of Quantities</a> 170</h3></div></div></div> 171<p> 172 This library is designed to emphasize safety above convenience when performing 173 operations with dimensioned quantities. Specifically, construction of quantities 174 is required to fully specify both value and unit. Direct construction from 175 a scalar value is prohibited (though the static member function <span class="underline"><code class="computeroutput"><a class="link" href="../boost/units/quantity.html#id-1_3_44_10_2_36_1_1_3_18_1-bb">from_value</a></code></span> 176 is provided to enable this functionality where it is necessary. In addition, 177 a <span class="underline"><code class="computeroutput"><a class="link" href="Reference.html#boost.units.quant_1_3_44_10_2_36_1_1_7">quantity_cast</a></code></span> 178 to a reference allows direct access to the underlying value of a <span class="underline"><code class="computeroutput"><a class="link" href="../boost/units/quantity.html" title="Class template quantity">quantity</a></code></span> 179 variable. An explicit constructor is provided to enable conversion between 180 dimensionally compatible quantities in different unit systems. Implicit conversions 181 between unit systems are allowed only when the reduced units are identical, 182 allowing, for example, trivial conversions between equivalent units in different 183 systems (such as SI seconds and CGS seconds) while simultaneously enabling 184 unintentional unit system mismatches to be caught at compile time and preventing 185 potential loss of precision and performance overhead from unintended conversions. 186 Assignment follows the same rules. An exception is made for quantities for 187 which the unit reduces to dimensionless; in this case, implicit conversion 188 to the underlying value type is allowed via class template specialization. 189 Quantities of different value types are implicitly convertible only if the 190 value types are themselves implicitly convertible. The <span class="underline"><code class="computeroutput"><a class="link" href="../boost/units/quantity.html" title="Class template quantity">quantity</a></code></span> class also defines 191 a <code class="computeroutput"><span class="identifier">value</span><span class="special">()</span></code> 192 member for directly accessing the underlying value. 193 </p> 194<p> 195 To summarize, conversions are allowed under the following conditions : 196 </p> 197<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 198<li class="listitem"> 199 implicit conversion of <code class="computeroutput"><span class="identifier">quantity</span><span class="special"><</span><span class="identifier">Unit</span><span class="special">,</span><span class="identifier">Y</span><span class="special">></span></code> to <code class="computeroutput"><span class="identifier">quantity</span><span class="special"><</span><span class="identifier">Unit</span><span class="special">,</span><span class="identifier">Z</span><span class="special">></span></code> is allowed if <code class="computeroutput"><span class="identifier">Y</span></code> 200 and <code class="computeroutput"><span class="identifier">Z</span></code> are implicitly 201 convertible. 202 </li> 203<li class="listitem"> 204 assignment between <code class="computeroutput"><span class="identifier">quantity</span><span class="special"><</span><span class="identifier">Unit</span><span class="special">,</span><span class="identifier">Y</span><span class="special">></span></code> and <code class="computeroutput"><span class="identifier">quantity</span><span class="special"><</span><span class="identifier">Unit</span><span class="special">,</span><span class="identifier">Z</span><span class="special">></span></code> is allowed if <code class="computeroutput"><span class="identifier">Y</span></code> 205 and <code class="computeroutput"><span class="identifier">Z</span></code> are implicitly 206 convertible. 207 </li> 208<li class="listitem"> 209 explicit conversion between <code class="computeroutput"><span class="identifier">quantity</span><span class="special"><</span><span class="identifier">Unit1</span><span class="special">,</span><span class="identifier">Y</span><span class="special">></span></code> and <code class="computeroutput"><span class="identifier">quantity</span><span class="special"><</span><span class="identifier">Unit2</span><span class="special">,</span><span class="identifier">Z</span><span class="special">></span></code> is allowed if <code class="computeroutput"><span class="identifier">Unit1</span></code> 210 and <code class="computeroutput"><span class="identifier">Unit2</span></code> have the same 211 dimensions and if <code class="computeroutput"><span class="identifier">Y</span></code> and 212 <code class="computeroutput"><span class="identifier">Z</span></code> are implicitly convertible. 213 </li> 214<li class="listitem"> 215 implicit conversion between <code class="computeroutput"><span class="identifier">quantity</span><span class="special"><</span><span class="identifier">Unit1</span><span class="special">,</span><span class="identifier">Y</span><span class="special">></span></code> and <code class="computeroutput"><span class="identifier">quantity</span><span class="special"><</span><span class="identifier">Unit2</span><span class="special">,</span><span class="identifier">Z</span><span class="special">></span></code> is allowed if <code class="computeroutput"><span class="identifier">Unit1</span></code> 216 reduces to exactly the same combination of base units as <code class="computeroutput"><span class="identifier">Unit2</span></code> and if <code class="computeroutput"><span class="identifier">Y</span></code> 217 and <code class="computeroutput"><span class="identifier">Z</span></code> are convertible. 218 </li> 219<li class="listitem"> 220 assignment between <code class="computeroutput"><span class="identifier">quantity</span><span class="special"><</span><span class="identifier">Unit1</span><span class="special">,</span><span class="identifier">Y</span><span class="special">></span></code> and <code class="computeroutput"><span class="identifier">quantity</span><span class="special"><</span><span class="identifier">Unit2</span><span class="special">,</span><span class="identifier">Z</span><span class="special">></span></code> is allowed under the same conditions 221 as implicit conversion. 222 </li> 223<li class="listitem"> 224 <code class="computeroutput"><span class="identifier">quantity</span><span class="special"><</span><span class="identifier">Unit</span><span class="special">,</span><span class="identifier">Y</span><span class="special">></span></code> 225 can be directly constructed from a value of type <code class="computeroutput"><span class="identifier">Y</span></code> 226 using the static member function <span class="underline"><code class="computeroutput"><a class="link" href="../boost/units/quantity.html#id-1_3_44_10_2_36_1_1_3_18_1-bb">from_value</a></code></span>. 227 Doing so, naturally, bypasses any type-checking of the newly assigned 228 value, so this method should be used only when absolutely necessary. 229 </li> 230</ul></div> 231<p> 232 Of course, any time implicit conversion is allowed, an explicit conversion 233 is also legal. 234 </p> 235<p> 236 Because dimensionless quantities have no associated units, they behave as 237 normal scalars, and allow implicit conversion to and from the underlying 238 value type or types that are convertible to/from that value type. 239 </p> 240</div> 241</div> 242<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 243<td align="left"></td> 244<td align="right"><div class="copyright-footer">Copyright © 2003-2008 Matthias Christian Schabel<br>Copyright © 2007-2010 Steven 245 Watanabe<p> 246 Distributed under the Boost Software License, Version 1.0. (See accompanying 247 file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) 248 </p> 249</div></td> 250</tr></table> 251<hr> 252<div class="spirit-nav"> 253<a accesskey="p" href="Units.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../boost_units.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="Examples.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> 254</div> 255</body> 256</html> 257
