[Boost-commit] svn:boost r46149 - sandbox/units/libs/units/doc

From: steven_at_[hidden]
Date: 2008-06-04 22:21:02

Author: steven_watanabe
Date: 2008-06-04 22:21:02 EDT (Wed, 04 Jun 2008)
New Revision: 46149
URL: http://svn.boost.org/trac/boost/changeset/46149

Log:
Deal with scaled units
Text files modified: 
   sandbox/units/libs/units/doc/units.qbk |    51 +++++++++++++++++++++++++++++++++++---- 
   1 files changed, 45 insertions(+), 6 deletions(-)

Modified: sandbox/units/libs/units/doc/units.qbk
==============================================================================
--- sandbox/units/libs/units/doc/units.qbk	(original)
+++ sandbox/units/libs/units/doc/units.qbk	2008-06-04 22:21:02 EDT (Wed, 04 Jun 2008)
@@ -28,6 +28,7 @@
 [def __base_unit [classref boost::units::base_unit base_unit]]
 [def __base_dimension [classref boost::units::base_dimension base_dimension]]
 [def __scaled_base_unit [classref boost::units::scaled_base_unit base_unit]]
+[def __make_scaled_unit [classref boost::units::make_scaled_unit make_scaled_unit]]
 
 [def __unary_plus_typeof_helper [classref boost::units::unary_plus_typeof_helper unary_plus_typeof_helper]]
 [def __unary_minus_typeof_helper [classref boost::units::unary_minus_typeof_helper unary_minus_typeof_helper]]
@@ -284,6 +285,8 @@
 free functions [___pow] and [___root] that are templated on integer and [___static_rational] values and can take as an argument 
 any type for which the utility classes [___power_typeof_helper] and [___root_typeof_helper] have been defined.
 
+[section Base Units]
+
 Base units are defined much like base dimensions.
 
     template<class Derived, class Dimensions, long N> struct base_unit { ... };
@@ -315,6 +318,48 @@
 
 [endsect]
 
+[section Scaled Base Units]
+
+Now, it is also possible to define a base unit as being a multiple of
+another base unit.  For example, the way that `kilogram_base_unit` is
+actually defined by the library is along the following lines
+
+    struct gram_base_unit : boost::units::base_unit<gram_base_unit, mass_dimension, 1> {};
+    typedef scaled_base_unit<gram_base_unit, scale<10, static_rational<3> > > kilogram_base_unit;
+
+This basically defines a kilogram as being 10^3 times a gram.
+
+There are several advantages to this approach.
+
+* It reflects the real meaning of these units better than treating them as independent units.
+* If a conversion is defined between grams or kilograms and some other units,
+  it will automatically work for both kilograms and grams, with only one specialization.
+* Similarly, if the symbol for grams is defined as "g", then the symbol for kilograms
+  will be "kg" without any extra effort.
+
+[endsect]
+
+[section Scaled Units]
+
+We can also scale a [___unit] as a whole, rather than scaling the individual
+base units which comprise it.  For this purpose, we use the metafunction
+[___make_scaled_unit].  The main motivation for this feature is the metric
+prefixes defined in [headerref boost/units/systems/si/prefixes.hpp].
+
+A simple example of its usage would be.
+
+    typedef make_scaled_unit<si::time, scale<10, static_rational<-9> > >::type nanosecond;
+
+nanosecond is a specialization of [___unit], and can be
+used in a quantity normally.
+
+    quantity<nanosecond> t(1.0 * si::seconds);
+    std::cout << t << std::endl;    // prints 1e9 ns
+
+[endsect]
+
+[endsect]
+
 [section:Quantities Quantities]
 
 A *quantity* is defined as a value of an arbitrary value type that is associated with a specific unit. For example,
@@ -448,12 +493,6 @@
 
 [endsect]
 
-[section:Scaled_Units Scaled Units]
-
-Need to discuss scaled units and prefixes here since they are mentioned in the next section...
-
-[endsect]
-
 [section:Examples Examples]
 
 [section:DimensionExample Dimension Example]