doc/html/boost_units/Quick_Start.html

   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=US-ASCII">
   5 <title>Quick Start</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&#160;43.&#160;Boost.Units 1.1.0">
  10 <link rel="prev" href="../boost_units.html" title="Chapter&#160;43.&#160;Boost.Units 1.1.0">
  11 <link rel="next" href="Dimensional_Analysis.html" title="Dimensional Analysis">
  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="../boost_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="Dimensional_Analysis.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.Quick_Start"></a><a class="link" href="Quick_Start.html" title="Quick Start">Quick Start</a>
  29 </h2></div></div></div>
  30 <p>
  31       Before discussing the basics of the library, we first define a few terms that
  32       will be used frequently in the following :
  33     </p>
  34 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
  35 <li class="listitem">
  36           <span class="bold"><strong>Base dimension</strong></span> : A base dimension is loosely
  37           defined as a measurable entity of interest; in conventional dimensional
  38           analysis, base dimensions include length ([L]), mass ([M]), time ([T]),
  39           etc... but there is no specific restriction on what base dimensions can
  40           be used. Base dimensions are essentially a tag type and provide no dimensional
  41           analysis functionality themselves.
  42         </li>
  43 <li class="listitem">
  44           <span class="bold"><strong>Dimension</strong></span> : A collection of zero or more
  45           base dimensions, each potentially raised to a different rational power.
  46           For example, length = [L]^1, area = [L]^2, velocity = [L]^1/[T]^1, and
  47           energy = [M]^1 [L]^2/[T]^2 are all dimensions.
  48         </li>
  49 <li class="listitem">
  50           <span class="bold"><strong>Base unit</strong></span> : A base unit represents a specific
  51           measure of a dimension. For example, while length is an abstract measure
  52           of distance, the meter is a concrete base unit of distance. Conversions
  53           are defined using base units. Much like base dimensions, base units are
  54           a tag type used solely to define units and do not support dimensional analysis
  55           algebra.
  56         </li>
  57 <li class="listitem">
  58           <span class="bold"><strong>Unit</strong></span> : A set of base units raised to rational
  59           exponents, e.g. m^1, kg^1, m^1/s^2.
  60         </li>
  61 <li class="listitem">
  62           <span class="bold"><strong>System</strong></span> : A unit system is a collection
  63           of base units representing all the measurable entities of interest for
  64           a specific problem. For example, the SI unit system defines seven base
  65           units : length ([L]) in meters, mass ([M]) in kilograms, time ([T]) in
  66           seconds, current ([I]) in amperes, temperature ([theta]) in kelvin, amount
  67           ([N]) in moles, and luminous intensity ([J]) in candelas. All measurable
  68           entities within the SI system can be represented as products of various
  69           integer or rational powers of these seven base units.
  70         </li>
  71 <li class="listitem">
  72           <span class="bold"><strong>Quantity</strong></span> : A quantity represents a concrete
  73           amount of a unit. Thus, while the meter is the base unit of length in the
  74           SI system, 5.5 meters is a quantity of length in that system.
  75         </li>
  76 </ul></div>
  77 <p>
  78       To begin, we present two short tutorials. <a href="../../../libs/units/tutorial/tutorial_1.cpp" target="_top">Tutorial1</a>
  79       demonstrates the use of <a href="http://en.wikipedia.org/wiki/SI_units" target="_top">SI</a>
  80       units. After including the appropriate system headers and the headers for the
  81       various SI units we will need (all SI units can be included with <code class="computeroutput"><a class="link" href="Reference.html#header.boost.units.systems.si_hpp" title="Header &lt;boost/units/systems/si.hpp&gt;">boost/units/systems/si.hpp</a></code>) and
  82       for quantity I/O (<code class="computeroutput"><a class="link" href="Reference.html#header.boost.units.io_hpp" title="Header &lt;boost/units/io.hpp&gt;">boost/units/io.hpp</a></code>),
  83       we define a function that computes the work, in joules, done by exerting a
  84       force in newtons over a specified distance in meters and outputs the result
  85       to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span></code>. The <span class="underline"><code class="computeroutput"><a class="link" href="../boost/units/quantity.html" title="Class template quantity">quantity</a></code></span> class accepts
  86       a second template parameter as its value type; this parameter defaults to
  87       <code class="computeroutput"><span class="keyword">double</span></code> if not otherwise specified.
  88       To demonstrate the ease of using user-defined types in dimensional calculations,
  89       we also present code for computing the complex impedance using <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">complex</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span></code>
  90       as the value type :
  91     </p>
  92 <p>
  93 </p>
  94 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">complex</span><span class="special">&gt;</span>
  95 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
  96
  97 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">typeof</span><span class="special">/</span><span class="identifier">std</span><span class="special">/</span><span class="identifier">complex</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
  98
  99 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">units</span><span class="special">/</span><span class="identifier">systems</span><span class="special">/</span><span class="identifier">si</span><span class="special">/</span><span class="identifier">energy</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 100 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">units</span><span class="special">/</span><span class="identifier">systems</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="identifier">hpp</span><span class="special">&gt;</span>
 101 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">units</span><span class="special">/</span><span class="identifier">systems</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="identifier">hpp</span><span class="special">&gt;</span>
 102 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">units</span><span class="special">/</span><span class="identifier">systems</span><span class="special">/</span><span class="identifier">si</span><span class="special">/</span><span class="identifier">electric_potential</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 103 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">units</span><span class="special">/</span><span class="identifier">systems</span><span class="special">/</span><span class="identifier">si</span><span class="special">/</span><span class="identifier">current</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 104 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">units</span><span class="special">/</span><span class="identifier">systems</span><span class="special">/</span><span class="identifier">si</span><span class="special">/</span><span class="identifier">resistance</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 105 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">units</span><span class="special">/</span><span class="identifier">systems</span><span class="special">/</span><span class="identifier">si</span><span class="special">/</span><span class="identifier">io</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 106
 107 <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">units</span><span class="special">;</span>
 108 <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">units</span><span class="special">::</span><span class="identifier">si</span><span class="special">;</span>
 109
 110 <span class="identifier">quantity</span><span class="special">&lt;</span><span class="identifier">energy</span><span class="special">&gt;</span>
 111 <span class="identifier">work</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">quantity</span><span class="special">&lt;</span><span class="identifier">force</span><span class="special">&gt;&amp;</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">quantity</span><span class="special">&lt;</span><span class="identifier">length</span><span class="special">&gt;&amp;</span> <span class="identifier">dx</span><span class="special">)</span>
 112 <span class="special">{</span>
 113     <span class="keyword">return</span> <span class="identifier">F</span> <span class="special">*</span> <span class="identifier">dx</span><span class="special">;</span> <span class="comment">// Defines the relation: work = force * distance.</span>
 114 <span class="special">}</span>
 115
 116 <span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
 117 <span class="special">{</span>
 118     <span class="comment">/// Test calculation of work.</span>
 119     <span class="identifier">quantity</span><span class="special">&lt;</span><span class="identifier">force</span><span class="special">&gt;</span>     <span class="identifier">F</span><span class="special">(</span><span class="number">2.0</span> <span class="special">*</span> <span class="identifier">newton</span><span class="special">);</span> <span class="comment">// Define a quantity of force.</span>
 120     <span class="identifier">quantity</span><span class="special">&lt;</span><span class="identifier">length</span><span class="special">&gt;</span>    <span class="identifier">dx</span><span class="special">(</span><span class="number">2.0</span> <span class="special">*</span> <span class="identifier">meter</span><span class="special">);</span> <span class="comment">// and a distance,</span>
 121     <span class="identifier">quantity</span><span class="special">&lt;</span><span class="identifier">energy</span><span class="special">&gt;</span>    <span class="identifier">E</span><span class="special">(</span><span class="identifier">work</span><span class="special">(</span><span class="identifier">F</span><span class="special">,</span><span class="identifier">dx</span><span class="special">));</span>  <span class="comment">// and calculate the work done.</span>
 122
 123     <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"F  = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">F</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span>
 124               <span class="special">&lt;&lt;</span> <span class="string">"dx = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">dx</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span>
 125               <span class="special">&lt;&lt;</span> <span class="string">"E  = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">E</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span>
 126               <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 127
 128     <span class="comment">/// Test and check complex quantities.</span>
 129     <span class="keyword">typedef</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">complex</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span> <span class="identifier">complex_type</span><span class="special">;</span> <span class="comment">// double real and imaginary parts.</span>
 130
 131     <span class="comment">// Define some complex electrical quantities.</span>
 132     <span class="identifier">quantity</span><span class="special">&lt;</span><span class="identifier">electric_potential</span><span class="special">,</span> <span class="identifier">complex_type</span><span class="special">&gt;</span> <span class="identifier">v</span> <span class="special">=</span> <span class="identifier">complex_type</span><span class="special">(</span><span class="number">12.5</span><span class="special">,</span> <span class="number">0.0</span><span class="special">)</span> <span class="special">*</span> <span class="identifier">volts</span><span class="special">;</span>
 133     <span class="identifier">quantity</span><span class="special">&lt;</span><span class="identifier">current</span><span class="special">,</span> <span class="identifier">complex_type</span><span class="special">&gt;</span>            <span class="identifier">i</span> <span class="special">=</span> <span class="identifier">complex_type</span><span class="special">(</span><span class="number">3.0</span><span class="special">,</span> <span class="number">4.0</span><span class="special">)</span> <span class="special">*</span> <span class="identifier">amperes</span><span class="special">;</span>
 134     <span class="identifier">quantity</span><span class="special">&lt;</span><span class="identifier">resistance</span><span class="special">,</span> <span class="identifier">complex_type</span><span class="special">&gt;</span>         <span class="identifier">z</span> <span class="special">=</span> <span class="identifier">complex_type</span><span class="special">(</span><span class="number">1.5</span><span class="special">,</span> <span class="special">-</span><span class="number">2.0</span><span class="special">)</span> <span class="special">*</span> <span class="identifier">ohms</span><span class="special">;</span>
 135
 136     <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"V   = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">v</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span>
 137               <span class="special">&lt;&lt;</span> <span class="string">"I   = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">i</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span>
 138               <span class="special">&lt;&lt;</span> <span class="string">"Z   = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">z</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span>
 139               <span class="comment">// Calculate from Ohm's law voltage = current * resistance.</span>
 140               <span class="special">&lt;&lt;</span> <span class="string">"I * Z = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">i</span> <span class="special">*</span> <span class="identifier">z</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span>
 141               <span class="comment">// Check defined V is equal to calculated.</span>
 142               <span class="special">&lt;&lt;</span> <span class="string">"I * Z == V? "</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">boolalpha</span> <span class="special">&lt;&lt;</span> <span class="special">(</span><span class="identifier">i</span> <span class="special">*</span> <span class="identifier">z</span> <span class="special">==</span> <span class="identifier">v</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span>
 143               <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 144     <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
 145 <span class="special">}</span>
 146 </pre>
 147 <p>
 148     </p>
 149 <p>
 150       The intent and function of the above code should be obvious; the output produced
 151       is :
 152     </p>
 153 <p>
 154 </p>
 155 <pre class="programlisting"><span class="identifier">F</span>  <span class="special">=</span> <span class="number">2</span> <span class="identifier">N</span>
 156 <span class="identifier">dx</span> <span class="special">=</span> <span class="number">2</span> <span class="identifier">m</span>
 157 <span class="identifier">E</span>  <span class="special">=</span> <span class="number">4</span> <span class="identifier">J</span>
 158
 159 <span class="identifier">V</span>   <span class="special">=</span> <span class="special">(</span><span class="number">12.5</span><span class="special">,</span><span class="number">0</span><span class="special">)</span> <span class="identifier">V</span>
 160 <span class="identifier">I</span>   <span class="special">=</span> <span class="special">(</span><span class="number">3</span><span class="special">,</span><span class="number">4</span><span class="special">)</span> <span class="identifier">A</span>
 161 <span class="identifier">Z</span>   <span class="special">=</span> <span class="special">(</span><span class="number">1.5</span><span class="special">,-</span><span class="number">2</span><span class="special">)</span> <span class="identifier">Ohm</span>
 162 <span class="identifier">I</span><span class="special">*</span><span class="identifier">Z</span> <span class="special">=</span> <span class="special">(</span><span class="number">12.5</span><span class="special">,</span><span class="number">0</span><span class="special">)</span> <span class="identifier">V</span>
 163 <span class="identifier">I</span><span class="special">*</span><span class="identifier">Z</span> <span class="special">==</span> <span class="identifier">V</span><span class="special">?</span> <span class="keyword">true</span>
 164 </pre>
 165 <p>
 166     </p>
 167 <p>
 168       While this library attempts to make simple dimensional computations easy to
 169       code, it is in no way tied to any particular unit system (SI or otherwise).
 170       Instead, it provides a highly flexible compile-time system for dimensional
 171       analysis, supporting arbitrary collections of base dimensions, rational powers
 172       of units, and explicit quantity conversions. It accomplishes all of this via
 173       template metaprogramming techniques. With modern optimizing compilers, this
 174       results in zero runtime overhead for quantity computations relative to the
 175       same code without unit checking.
 176     </p>
 177 </div>
 178 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 179 <td align="left"></td>
 180 <td align="right"><div class="copyright-footer">Copyright &#169; 2003-2008 Matthias Christian Schabel<br>Copyright &#169; 2007-2010 Steven
 181       Watanabe<p>
 182         Distributed under the Boost Software License, Version 1.0. (See accompanying
 183         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>)
 184       </p>
 185 </div></td>
 186 </tr></table>
 187 <hr>
 188 <div class="spirit-nav">
 189 <a accesskey="p" href="../boost_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="Dimensional_Analysis.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
 190 </div>
 191 </body>
 192 </html>