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>Units</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="Dimensional_Analysis.html" title="Dimensional Analysis"> 11<link rel="next" href="Quantities.html" title="Quantities"> 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="Dimensional_Analysis.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="Quantities.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.Units"></a><a class="link" href="Units.html" title="Units">Units</a> 29</h2></div></div></div> 30<div class="toc"><dl class="toc"> 31<dt><span class="section"><a href="Units.html#boost_units.Units.base_units">Base Units</a></span></dt> 32<dt><span class="section"><a href="Units.html#boost_units.Units.scaled_base_units">Scaled Base Units</a></span></dt> 33<dt><span class="section"><a href="Units.html#boost_units.Units.scaled_units">Scaled Units</a></span></dt> 34</dl></div> 35<p> 36 We define a <span class="bold"><strong>unit</strong></span> as a set of base units each 37 of which can be raised to an arbitrary rational exponent. Thus, the SI unit 38 corresponding to the dimension of force is kg m s^-2, where kg, m, and s are 39 base units. We use the notion of a <span class="bold"><strong>unit system</strong></span> 40 such as SI to specify the mapping from a dimension to a particular unit so 41 that instead of specifying the base units explicitly, we can just ask for the 42 representation of a dimension in a particular system. 43 </p> 44<p> 45 Units are, like dimensions, purely compile-time variables with no associated 46 value. Units obey the same algebra as dimensions do; the presence of the unit 47 system serves to ensure that units having identical reduced dimension in different 48 systems (like feet and meters) cannot be inadvertently mixed in computations. 49 </p> 50<p> 51 There are two distinct types of systems that can be envisioned: 52 </p> 53<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 54<li class="listitem"> 55 <span class="bold"><strong>Homogeneous systems</strong></span> : Systems which hold 56 a linearly independent set of base units which can be used to represent 57 many different dimensions. For example, the SI system has seven base dimensions 58 and seven base units corresponding to them. It can represent any unit which 59 uses only those seven base dimensions. Thus it is a homogeneous_system. 60 </li> 61<li class="listitem"> 62 <span class="bold"><strong>Heterogeneous systems</strong></span> : Systems which 63 store the exponents of every base unit involved are termed heterogeneous. 64 Some units can only be represented in this way. For example, area in m 65 ft is intrinsically heterogeneous, because the base units of meters and 66 feet have identical dimensions. As a result, simply storing a dimension 67 and a set of base units does not yield a unique solution. A practical example 68 of the need for heterogeneous units, is an empirical equation used in aviation: 69 H = (r/C)^2 where H is the radar beam height in feet and r is the radar 70 range in nautical miles. In order to enforce dimensional correctness of 71 this equation, the constant, C, must be expressed in nautical miles per 72 foot^(1/2), mixing two distinct base units of length. 73 </li> 74</ul></div> 75<p> 76 Units are implemented by the <span class="underline"><code class="computeroutput"><a class="link" href="../boost/units/unit.html" title="Class template unit">unit</a></code></span> 77 template class defined in <code class="computeroutput"><a class="link" href="Reference.html#header.boost.units.unit_hpp" title="Header <boost/units/unit.hpp>">boost/units/unit.hpp</a></code> 78 : 79 </p> 80<pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">Dim</span><span class="special">,</span><span class="keyword">class</span> <span class="identifier">System</span><span class="special">></span> <span class="keyword">class</span> <span class="identifier">unit</span><span class="special">;</span> 81</pre> 82<p> 83 In addition to supporting the compile-time dimensional analysis operations, 84 the +, -, *, and / runtime operators are provided for <span class="underline"><code class="computeroutput"><a class="link" href="../boost/units/unit.html" title="Class template unit">unit</a></code></span> variables. Because the 85 dimension associated with powers and roots must be computed at compile-time, 86 it is not possible to provide overloads for <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">pow</span></code> that 87 function correctly for <span class="underline"><code class="computeroutput"><a class="link" href="../boost/units/unit.html" title="Class template unit">unit</a></code></span>s. 88 These operations are supported through free functions <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> 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> that are templated 89 on integer and <span class="underline"><code class="computeroutput"><a class="link" href="../boost/units/static_rational.html" title="Class template static_rational">static_rational</a></code></span> 90 values and can take as an argument any type for which the utility classes 91 <span class="underline"><code class="computeroutput"><a class="link" href="../boost/units/power_typeof_helper.html" title="Struct template power_typeof_helper">power_typeof_helper</a></code></span> 92 and <span class="underline"><code class="computeroutput"><a class="link" href="../boost/units/root_typeof_helper.html" title="Struct template root_typeof_helper">root_typeof_helper</a></code></span> 93 have been defined. 94 </p> 95<div class="section"> 96<div class="titlepage"><div><div><h3 class="title"> 97<a name="boost_units.Units.base_units"></a><a class="link" href="Units.html#boost_units.Units.base_units" title="Base Units">Base Units</a> 98</h3></div></div></div> 99<p> 100 Base units are defined much like base dimensions. 101 </p> 102<pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">Derived</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Dimensions</span><span class="special">,</span> <span class="keyword">long</span> <span class="identifier">N</span><span class="special">></span> <span class="keyword">struct</span> <span class="identifier">base_unit</span> <span class="special">{</span> <span class="special">...</span> <span class="special">};</span> 103</pre> 104<p> 105 Again negative ordinals are reserved. 106 </p> 107<p> 108 As an example, in the following we will implement a subset of the SI unit 109 system based on the fundamental dimensions given above, demonstrating all 110 steps necessary for a completely functional system. First, we simply define 111 a unit system that includes type definitions for commonly used units: 112 </p> 113<p> 114</p> 115<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">meter_base_unit</span> <span class="special">:</span> <span class="identifier">base_unit</span><span class="special"><</span><span class="identifier">meter_base_unit</span><span class="special">,</span> <span class="identifier">length_dimension</span><span class="special">,</span> <span class="number">1</span><span class="special">></span> <span class="special">{</span> <span class="special">};</span> 116<span class="keyword">struct</span> <span class="identifier">kilogram_base_unit</span> <span class="special">:</span> <span class="identifier">base_unit</span><span class="special"><</span><span class="identifier">kilogram_base_unit</span><span class="special">,</span> <span class="identifier">mass_dimension</span><span class="special">,</span> <span class="number">2</span><span class="special">></span> <span class="special">{</span> <span class="special">};</span> 117<span class="keyword">struct</span> <span class="identifier">second_base_unit</span> <span class="special">:</span> <span class="identifier">base_unit</span><span class="special"><</span><span class="identifier">second_base_unit</span><span class="special">,</span> <span class="identifier">time_dimension</span><span class="special">,</span> <span class="number">3</span><span class="special">></span> <span class="special">{</span> <span class="special">};</span> 118 119<span class="keyword">typedef</span> <span class="identifier">make_system</span><span class="special"><</span> 120 <span class="identifier">meter_base_unit</span><span class="special">,</span> 121 <span class="identifier">kilogram_base_unit</span><span class="special">,</span> 122 <span class="identifier">second_base_unit</span><span class="special">>::</span><span class="identifier">type</span> <span class="identifier">mks_system</span><span class="special">;</span> 123 124<span class="comment">/// unit typedefs</span> 125<span class="keyword">typedef</span> <span class="identifier">unit</span><span class="special"><</span><span class="identifier">dimensionless_type</span><span class="special">,</span><span class="identifier">mks_system</span><span class="special">></span> <span class="identifier">dimensionless</span><span class="special">;</span> 126 127<span class="keyword">typedef</span> <span class="identifier">unit</span><span class="special"><</span><span class="identifier">length_dimension</span><span class="special">,</span><span class="identifier">mks_system</span><span class="special">></span> <span class="identifier">length</span><span class="special">;</span> 128<span class="keyword">typedef</span> <span class="identifier">unit</span><span class="special"><</span><span class="identifier">mass_dimension</span><span class="special">,</span><span class="identifier">mks_system</span><span class="special">></span> <span class="identifier">mass</span><span class="special">;</span> 129<span class="keyword">typedef</span> <span class="identifier">unit</span><span class="special"><</span><span class="identifier">time_dimension</span><span class="special">,</span><span class="identifier">mks_system</span><span class="special">></span> <span class="identifier">time</span><span class="special">;</span> 130 131<span class="keyword">typedef</span> <span class="identifier">unit</span><span class="special"><</span><span class="identifier">area_dimension</span><span class="special">,</span><span class="identifier">mks_system</span><span class="special">></span> <span class="identifier">area</span><span class="special">;</span> 132<span class="keyword">typedef</span> <span class="identifier">unit</span><span class="special"><</span><span class="identifier">energy_dimension</span><span class="special">,</span><span class="identifier">mks_system</span><span class="special">></span> <span class="identifier">energy</span><span class="special">;</span> 133</pre> 134<p> 135 </p> 136<p> 137 The macro <span class="underline"><code class="computeroutput"><a class="link" href="../BOOST_UNI_1_3_44_10_2_40_1.html" title="Macro BOOST_UNITS_STATIC_CONSTANT">BOOST_UNITS_STATIC_CONSTANT</a></code></span> 138 is provided in <code class="computeroutput"><a class="link" href="Reference.html#header.boost.units.static_constant_hpp" title="Header <boost/units/static_constant.hpp>">boost/units/static_constant.hpp</a></code> 139 to facilitate ODR- and thread-safe constant definition in header files. We 140 then define some constants for the supported units to simplify variable definitions: 141 </p> 142<p> 143</p> 144<pre class="programlisting"><span class="comment">/// unit constants </span> 145<span class="identifier">BOOST_UNITS_STATIC_CONSTANT</span><span class="special">(</span><span class="identifier">meter</span><span class="special">,</span><span class="identifier">length</span><span class="special">);</span> 146<span class="identifier">BOOST_UNITS_STATIC_CONSTANT</span><span class="special">(</span><span class="identifier">meters</span><span class="special">,</span><span class="identifier">length</span><span class="special">);</span> 147<span class="identifier">BOOST_UNITS_STATIC_CONSTANT</span><span class="special">(</span><span class="identifier">kilogram</span><span class="special">,</span><span class="identifier">mass</span><span class="special">);</span> 148<span class="identifier">BOOST_UNITS_STATIC_CONSTANT</span><span class="special">(</span><span class="identifier">kilograms</span><span class="special">,</span><span class="identifier">mass</span><span class="special">);</span> 149<span class="identifier">BOOST_UNITS_STATIC_CONSTANT</span><span class="special">(</span><span class="identifier">second</span><span class="special">,</span><span class="identifier">time</span><span class="special">);</span> 150<span class="identifier">BOOST_UNITS_STATIC_CONSTANT</span><span class="special">(</span><span class="identifier">seconds</span><span class="special">,</span><span class="identifier">time</span><span class="special">);</span> 151 152<span class="identifier">BOOST_UNITS_STATIC_CONSTANT</span><span class="special">(</span><span class="identifier">square_meter</span><span class="special">,</span><span class="identifier">area</span><span class="special">);</span> 153<span class="identifier">BOOST_UNITS_STATIC_CONSTANT</span><span class="special">(</span><span class="identifier">square_meters</span><span class="special">,</span><span class="identifier">area</span><span class="special">);</span> 154<span class="identifier">BOOST_UNITS_STATIC_CONSTANT</span><span class="special">(</span><span class="identifier">joule</span><span class="special">,</span><span class="identifier">energy</span><span class="special">);</span> 155<span class="identifier">BOOST_UNITS_STATIC_CONSTANT</span><span class="special">(</span><span class="identifier">joules</span><span class="special">,</span><span class="identifier">energy</span><span class="special">);</span> 156</pre> 157<p> 158 </p> 159<p> 160 If support for textual output of units is desired, we can also specialize 161 the <span class="underline"><code class="computeroutput"><a class="link" href="../boost/units/base_unit_info.html" title="Struct template base_unit_info">base_unit_info</a></code></span> 162 class for each fundamental dimension tag: 163 </p> 164<p> 165</p> 166<pre class="programlisting"><span class="keyword">template</span><span class="special"><></span> <span class="keyword">struct</span> <span class="identifier">base_unit_info</span><span class="special"><</span><span class="identifier">test</span><span class="special">::</span><span class="identifier">meter_base_unit</span><span class="special">></span> 167<span class="special">{</span> 168 <span class="keyword">static</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">name</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="string">"meter"</span><span class="special">;</span> <span class="special">}</span> 169 <span class="keyword">static</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">symbol</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="string">"m"</span><span class="special">;</span> <span class="special">}</span> 170<span class="special">};</span> 171</pre> 172<p> 173 </p> 174<p> 175 and similarly for <code class="computeroutput"><span class="identifier">kilogram_base_unit</span></code> 176 and <code class="computeroutput"><span class="identifier">second_base_unit</span></code>. A future 177 version of the library will provide a more flexible system allowing for internationalization 178 through a facet/locale-type mechanism. The <code class="computeroutput"><span class="identifier">name</span><span class="special">()</span></code> and <code class="computeroutput"><span class="identifier">symbol</span><span class="special">()</span></code> methods of <span class="underline"><code class="computeroutput"><a class="link" href="../boost/units/base_unit_info.html" title="Struct template base_unit_info">base_unit_info</a></code></span> 179 provide full and short names for the base unit. With these definitions, we 180 have the rudimentary beginnings of our unit system, which can be used to 181 determine reduced dimensions for arbitrary unit calculations. 182 </p> 183</div> 184<div class="section"> 185<div class="titlepage"><div><div><h3 class="title"> 186<a name="boost_units.Units.scaled_base_units"></a><a class="link" href="Units.html#boost_units.Units.scaled_base_units" title="Scaled Base Units">Scaled Base Units</a> 187</h3></div></div></div> 188<p> 189 Now, it is also possible to define a base unit as being a multiple of another 190 base unit. For example, the way that <code class="computeroutput"><span class="identifier">kilogram_base_unit</span></code> 191 is actually defined by the library is along the following lines 192 </p> 193<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">gram_base_unit</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">gram_base_unit</span><span class="special">,</span> <span class="identifier">mass_dimension</span><span class="special">,</span> <span class="number">1</span><span class="special">></span> <span class="special">{};</span> 194<span class="keyword">typedef</span> <span class="identifier">scaled_base_unit</span><span class="special"><</span><span class="identifier">gram_base_unit</span><span class="special">,</span> <span class="identifier">scale</span><span class="special"><</span><span class="number">10</span><span class="special">,</span> <span class="identifier">static_rational</span><span class="special"><</span><span class="number">3</span><span class="special">></span> <span class="special">></span> <span class="special">></span> <span class="identifier">kilogram_base_unit</span><span class="special">;</span> 195</pre> 196<p> 197 This basically defines a kilogram as being 10^3 times a gram. 198 </p> 199<p> 200 There are several advantages to this approach. 201 </p> 202<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 203<li class="listitem"> 204 It reflects the real meaning of these units better than treating them 205 as independent units. 206 </li> 207<li class="listitem"> 208 If a conversion is defined between grams or kilograms and some other 209 units, it will automatically work for both kilograms and grams, with 210 only one specialization. 211 </li> 212<li class="listitem"> 213 Similarly, if the symbol for grams is defined as "g", then 214 the symbol for kilograms will be "kg" without any extra effort. 215 </li> 216</ul></div> 217</div> 218<div class="section"> 219<div class="titlepage"><div><div><h3 class="title"> 220<a name="boost_units.Units.scaled_units"></a><a class="link" href="Units.html#boost_units.Units.scaled_units" title="Scaled Units">Scaled Units</a> 221</h3></div></div></div> 222<p> 223 We can also scale a <span class="underline"><code class="computeroutput"><a class="link" href="../boost/units/unit.html" title="Class template unit">unit</a></code></span> 224 as a whole, rather than scaling the individual base units which comprise 225 it. For this purpose, we use the metafunction <span class="underline"><code class="computeroutput"><a class="link" href="../boost/units/make_scaled_unit.html" title="Struct template make_scaled_unit">make_scaled_unit</a></code></span>. 226 The main motivation for this feature is the metric prefixes defined in <code class="computeroutput"><a class="link" href="Reference.html#header.boost.units.systems.si.prefixes_hpp" title="Header <boost/units/systems/si/prefixes.hpp>">boost/units/systems/si/prefixes.hpp</a></code>. 227 </p> 228<p> 229 A simple example of its usage would be. 230 </p> 231<pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">make_scaled_unit</span><span class="special"><</span><span class="identifier">si</span><span class="special">::</span><span class="identifier">time</span><span class="special">,</span> <span class="identifier">scale</span><span class="special"><</span><span class="number">10</span><span class="special">,</span> <span class="identifier">static_rational</span><span class="special"><-</span><span class="number">9</span><span class="special">></span> <span class="special">></span> <span class="special">>::</span><span class="identifier">type</span> <span class="identifier">nanosecond</span><span class="special">;</span> 232</pre> 233<p> 234 nanosecond is a specialization of <span class="underline"><code class="computeroutput"><a class="link" href="../boost/units/unit.html" title="Class template unit">unit</a></code></span>, 235 and can be used in a quantity normally. 236 </p> 237<pre class="programlisting"><span class="identifier">quantity</span><span class="special"><</span><span class="identifier">nanosecond</span><span class="special">></span> <span class="identifier">t</span><span class="special">(</span><span class="number">1.0</span> <span class="special">*</span> <span class="identifier">si</span><span class="special">::</span><span class="identifier">seconds</span><span class="special">);</span> 238<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">t</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> <span class="comment">// prints 1e9 ns</span> 239</pre> 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="Dimensional_Analysis.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="Quantities.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> 254</div> 255</body> 256</html> 257
