|
|
Boost-Commit : |
From: steven_at_[hidden]
Date: 2007-07-27 14:28:52
Author: steven_watanabe
Date: 2007-07-27 14:28:50 EDT (Fri, 27 Jul 2007)
New Revision: 7566
URL: http://svn.boost.org/trac/boost/changeset/7566
Log:
Updated examples augmented FAQ
Text files modified:
sandbox/units/libs/units/doc/units.qbk | 114 +++++++++++++++++++--------------------
sandbox/units/libs/units/example/unit_example_16.cpp | 10 ---
sandbox/units/libs/units/example/unit_example_18.cpp | 12 +++-
sandbox/units/libs/units/example/unit_example_20.cpp | 8 ++
sandbox/units/libs/units/example/unit_example_5.cpp | 55 +++++++++---------
sandbox/units/libs/units/example/unit_example_8.cpp | 10 ---
6 files changed, 99 insertions(+), 110 deletions(-)
Modified: sandbox/units/libs/units/doc/units.qbk
==============================================================================
--- sandbox/units/libs/units/doc/units.qbk (original)
+++ sandbox/units/libs/units/doc/units.qbk 2007-07-27 14:28:50 EDT (Fri, 27 Jul 2007)
@@ -21,9 +21,10 @@
[def __static_rational [classref boost::units::static_rational static_rational]]
[def __make_dimension_list [classref boost::units::make_dimension_list make_dimension_list]]
[def __unit [classref boost::units::unit unit]]
-[def __base_unit_info [classref boost::units::base_unit_info unit_info]]
+[def __base_unit_info [classref boost::units::base_unit_info base_unit_info]]
[def __quantity [classref boost::units::quantity quantity]]
[def __conversion_helper [classref boost::units::conversion_helper conversion_helper]]
+[def __absolute [classref boost::units::absolute absolute]]
[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]]
@@ -402,8 +403,8 @@
([@../examples/unit_example_1.cpp unit_example_1.cpp])
By using MPL metafunctions and the template specializations for operations on composite dimensions
-defined in [headerref boost/units/dimension.hpp],
-it is possible to perform compile time arithmetic according to the dimensional analysis rules described above
+defined in [headerref boost/units/dimension.hpp], it is possible to perform compile time arithmetic
+according to the dimensional analysis rules described [link boost_units.Dimensional_Analysis above]
to produce new composite dimensions :
[import ../example/unit_example_1.cpp]
@@ -563,11 +564,7 @@
greater-than, and greater-or-equal-to. Support for rational powers and roots can be added by overloading
the [___power_dimof_helper] and [___root_typeof_helper] classes. Here we implement a user-defined `measurement`
class that models a numerical measurement with an associated measurement error and the appropriate algebra and
-demonstrates its use as a quantity value type; the full code is found in [@../examples/measurement.hpp measurement.hpp]:
-
-[import ../example/measurement.hpp]
-
-[measurement_snippet_1]
+demonstrates its use as a quantity value type; the full code is found in [@../examples/measurement.hpp measurement.hpp].
Then, defining some `measurement` [___quantity] variables
@@ -577,10 +574,7 @@
[unit_example_4_output_13]
-If we implement the overloaded helper classes for rational powers and roots :
-
-[measurement_snippet_2]
-
+If we implement the overloaded helper classes for rational powers and roots
then we can also compute rational powers of measurement quantities :
[unit_example_4_output_14]
@@ -593,7 +587,7 @@
([@../examples/unit_example_5.cpp unit_example_5.cpp])
-This example demonstrates [___quantity_cast] and the various allowed conversions between SI and CGS units. Defining some
+This example demonstrates the various allowed conversions between SI and CGS units. Defining some
quantities
[import ../example/unit_example_5.cpp]
@@ -601,11 +595,9 @@
[unit_example_5_snippet_1]
illustrates implicit conversion of quantities of different value types where implicit conversion
-of the value types themselves is allowed. [___quantity_cast] allows explicit conversions for three cases:
-
-* construction of a quantity from a raw value :
-
-[unit_example_5_snippet_2]
+of the value types themselves is allowed. N.B. The conversion from double to int is treated
+as an explicit conversion because there is no way to emulate the exact behavior of the built-in
+conversion. Explicit constructors allow conversions for two cases:
* explicit casting of a [___quantity] to a different `value_type` :
@@ -619,7 +611,7 @@
[unit_example_5_output_1]
-Explicit unit system conversion is allowed in the [___quantity] constructor :
+A few more explicit unit system conversions :
[unit_example_5_snippet_5]
@@ -628,11 +620,11 @@
[unit_example_5_output_2]
While the library default is to enable only those unit conversions for which the conversion of every
-fundamental dimension present in a quantity is specifically enabled as implicit, it is possible to
+base unit present in a quantity is specifically enabled as implicit, it is possible to
supersede this behavior and enable all implicit conversions by defining the preprocessor
constant [___BOOST_UNITS_ENABLE_IMPLICIT_UNIT_CONVERSIONS]. This allows us to do things like the following:
-[unit_example_5_snippet_3]
+[unit_example_5_snippet_6]
which produces the following output:
@@ -913,8 +905,26 @@
([@../example/unit_example_18.cpp unit_example_18.cpp])
+[import ../example/units_example_18.cpp]
+
Mixed units and mixed unit conversions.
+First a look at the output:
+
+[unit_example_18_snippet_1]
+
+printing
+
+[unit_example_18_output_1]
+
+Arbitrary conversions also work:
+
+[unit_example_18_snippet_2]
+
+yielding
+
+[unit_example_18_output_2]
+
[endsect]
[section:Example_19 Example 19]
@@ -936,37 +946,25 @@
[import ../example/unit_example_20.cpp]
-This example shows a method for implementing absolute temperatures and relative temperature differences in Fahrenheit
+This example demonstrates using of absolute temperatures and relative temperature differences in Fahrenheit
and converting between these and the Kelvin temperature scale. This issue touches on some surprisingly deep mathematical
concepts (see [@http://en.wikipedia.org/wiki/Affine_space Wikipedia] for a basic review), but for our purposes here, we
will simply observe that it is important to be able to differentiate between an absolute temperature measurement and a
-measurement of temperature difference. This is accomplished by defining two wrapper classes :
-
-[unit_example_20_class_snippet_1]
+measurement of temperature difference. This is accomplished by using the [___absolute] wrapper class.
-that implement the correct algebra for points and vectors in 1D. We then define a unit system for Fahrenheit temperature and
-associated classes :
-
-[unit_example_20_class_snippet_2]
-
-Finally, we manually define __conversion_helper for converting absolute temperatures and temperature differences in Fahrenheit
-to Kelvin and specify that these conversions may be done implicitly to demonstrate fine-grained control over implicit unit
-conversions :
-
-[unit_example_20_class_snippet_3]
-
-Note that the absolute conversion includes both scale and offset, while relative conversion only includes scale. With this, we
-can define Fahrenheit temperatures :
+First we define a system using the predefined fahrenheit base unit:
[unit_example_20_snippet_1]
-and convert them to SI :
+For convenience we make conversions implicit:
[unit_example_20_snippet_2]
-resulting in the expected values :
+Now we can create some quantities:
+
+[unit_example_20_snippet_3]
-[unit_example_20_output]
+Note the use of [___absolute] to wrap a unit.
[endsect]
@@ -1084,23 +1082,6 @@
[endsect]
-[section:Namespace_Boost Why is everything in the boost namespace?]
-
-Boost.Units (formerly `mcs::units`) was originally written as an example of generic programming for dimensional analysis for the
-Boost mailing list. There is also significant interest in development of a Boost Units library,
-and this library represents my vision for how it could be done cleanly. Andrew Little has an extensive
-project that was recently reviewed and rejected by Boost that demonstrates his (very different)
-take on the idea
-[@http://quan.sourceforge.net here]. There are also a number of additional units projects
-of varying degrees of completion in the
-[@http://boost-consulting.com/vault/index.php?&direction=0&order=&directory=Units Boost Vault]
-and the
-[@http://boost-consulting.com/vault/index.php?&direction=0&order=&directory=Units Boost Files]
-page on Yahoo! Groups (accessing the latter may require registration). As of February 6, 2007, `mcs::units`
-has been officially submitted for public review for inclusion into Boost.
-
-[endsect]
-
[section:Angle_Are_Units Angles are treated as units]
If you don't like this, you can just ignore the angle units and
@@ -1117,13 +1098,28 @@
What should this print? If only heterogeneous
systems are available it would print 3.14159+ rad
-Why? Well, asin would return a quantity<dimensionless>
+Why? Well, `asin` would return a `quantity<dimensionless>`
effectively losing the information that degrees
are being used. In order to propogate this extra information
we need homogeneous systems.
[endsect]
+[section:NoConstructorFromValueType Why can't I construct a quantity directly from the value type?]
+
+This only breaks generic code--which ought to break anyway. The only
+literal value that ought to be converted to a quantity by generic code
+is zero, which can be handled by the default constructor.
+
+[endsect]
+
+[section:ExplicitConversions Why are conversions explicit by default?]
+
+Safety. Implicit conversions are dangerous and should
+not occur without a good reason.
+
+[endsect]
+
[endsect]
[section:Acknowledgements Acknowledgements]
Modified: sandbox/units/libs/units/example/unit_example_16.cpp
==============================================================================
--- sandbox/units/libs/units/example/unit_example_16.cpp (original)
+++ sandbox/units/libs/units/example/unit_example_16.cpp 2007-07-27 14:28:50 EDT (Fri, 27 Jul 2007)
@@ -49,11 +49,6 @@
//[unit_example_16_class_snippet_1
namespace nautical {
-/// placeholder class defining nautical unit system
-//struct system_tag : public ordinal<100> { };
-
-//typedef homogeneous_system<system_tag> system;
-
struct length_base_unit : base_unit<length_base_unit, length_dimension, 1>
{
static std::string name() { return "nautical mile"; }
@@ -86,11 +81,6 @@
//[unit_example_16_class_snippet_2
namespace imperial {
-///// placeholder class defining imperial unit system
-//struct system_tag : public ordinal<101> { };
-//
-//typedef homogeneous_system<system_tag> system;
-
struct length_base_unit : base_unit<length_base_unit, length_dimension, 2>
{
static std::string name() { return "foot"; }
Modified: sandbox/units/libs/units/example/unit_example_18.cpp
==============================================================================
--- sandbox/units/libs/units/example/unit_example_18.cpp (original)
+++ sandbox/units/libs/units/example/unit_example_18.cpp 2007-07-27 14:28:50 EDT (Fri, 27 Jul 2007)
@@ -19,6 +19,7 @@
Output:
@verbatim
+//[unit_example_18_output_1
1.5 m
1 g
1.5 m g
@@ -29,8 +30,11 @@
1 cm kg s^-2
1 cm m^-1 kg s^-2
+//]
+//[unit_example_18_output_2
0.015 m^2
+//]
@endverbatim
**/
@@ -46,8 +50,6 @@
#include <boost/units/detail/utility.hpp>
#include <boost/units/systems/cgs.hpp>
#include <boost/units/systems/si.hpp>
-//#include <boost/units/systems/conversions/convert_cgs_to_si.hpp>
-//#include <boost/units/systems/conversions/convert_si_to_cgs.hpp>
using namespace boost::units;
@@ -55,6 +57,7 @@
{
std::stringstream sstream1, sstream2;
+ //[unit_example_18_snippet_1
quantity<SI::length> L(1.5*SI::meter);
quantity<CGS::mass> M(1.0*CGS::gram);
@@ -71,11 +74,14 @@
sstream1 << 1.0*CGS::centimeter*SI::kilogram/pow<2>(SI::second) << std::endl
<< 1.0*CGS::centimeter*SI::kilogram/pow<2>(SI::second)/SI::meter << std::endl
<< std::endl;
-
+ //]
+
+ //unit_example_18_snippet_2
quantity<SI::area> A(1.5*SI::meter*CGS::centimeter);
sstream1 << A << std::endl
<< std::endl;
+ //]
sstream2 << "1.5 m" << std::endl
<< "1 g" << std::endl
Modified: sandbox/units/libs/units/example/unit_example_20.cpp
==============================================================================
--- sandbox/units/libs/units/example/unit_example_20.cpp (original)
+++ sandbox/units/libs/units/example/unit_example_20.cpp 2007-07-27 14:28:50 EDT (Fri, 27 Jul 2007)
@@ -54,15 +54,18 @@
namespace fahrenheit {
+//[unit_example_20_snippet_1
typedef make_system<fahrenheit_base_unit>::type system;
typedef unit<temperature_dimension,system> temperature;
BOOST_UNITS_STATIC_CONSTANT(degree,temperature);
BOOST_UNITS_STATIC_CONSTANT(degrees,temperature);
+//]
} // fahrenheit
+//[unit_example_20_snippet_2
template<>
struct is_implicitly_convertible< unit<temperature_dimension,fahrenheit::system>,
unit<temperature_dimension,SI::system> > :
@@ -74,6 +77,7 @@
absolute< unit<temperature_dimension,SI::system> > > :
public mpl::true_
{ };
+//]
} // namespace units
@@ -83,6 +87,7 @@
{
std::stringstream sstream1, sstream2;
+ //[unit_example_20_snippet_3
quantity<absolute<fahrenheit::temperature> > T1p(32.0*absolute<fahrenheit::temperature>());
quantity<fahrenheit::temperature> T1v(32.0*fahrenheit::degrees);
@@ -90,7 +95,8 @@
quantity<absolute<SI::temperature> > T3p = T1p;
quantity<SI::temperature> T2v(T1v);
quantity<SI::temperature> T3v = T1v;
-
+ //]
+
typedef conversion_helper<quantity<absolute<fahrenheit::temperature> >,
quantity<absolute<SI::temperature> > > absolute_conv_type;
typedef conversion_helper<quantity<fahrenheit::temperature,double>,
Modified: sandbox/units/libs/units/example/unit_example_5.cpp
==============================================================================
--- sandbox/units/libs/units/example/unit_example_5.cpp (original)
+++ sandbox/units/libs/units/example/unit_example_5.cpp 2007-07-27 14:28:50 EDT (Fri, 27 Jul 2007)
@@ -22,9 +22,11 @@
//[unit_example_5_output_1
L1 = 2 m
L2 = 2 m
-L3 = 5 m
-L4 = 4 m
-L5 = 200 cm
+L3 = 2 m
+L4 = 200 cm
+L5 = 5 m
+L6 = 4 m
+L7 = 200 cm
//]
//[unit_example_5_output_2
@@ -64,8 +66,6 @@
#include <boost/units/io.hpp>
#include <boost/units/systems/cgs.hpp>
#include <boost/units/systems/si.hpp>
-//#include <boost/units/systems/conversions/convert_cgs_to_si.hpp>
-//#include <boost/units/systems/conversions/convert_si_to_cgs.hpp>
using namespace boost::units;
@@ -82,32 +82,27 @@
quantity<SI::length,int> L2(quantity<SI::length,double>(2.5*SI::meters));
//]
- //[unit_example_5_snippet_2
- //deprecated
- //quantity<SI::length,int> L3 = quantity_cast< quantity<SI::length,int> >(2.5);
- //]
-
//[unit_example_5_snippet_3
- //deprecated
- //quantity<SI::length,int> L4 = quantity_cast<quantity<SI::length,int> >(L1);
+ quantity<SI::length,int> L3 = static_cast<quantity<SI::length,int> >(L1);
//]
//[unit_example_5_snippet_4
- //deprecated
- //quantity<CGS::length> L5 = quantity_cast<quantity<CGS::length> >(L1);
+ quantity<CGS::length> L4 = static_cast<quantity<CGS::length> >(L1);
//]
- quantity<SI::length,int> L3(4*SI::meters),
- L4(5*SI::meters);
- quantity<CGS::length> L5(L1);
+ quantity<SI::length,int> L5(4*SI::meters),
+ L6(5*SI::meters);
+ quantity<CGS::length> L7(L1);
- swap(L3,L4);
+ swap(L5,L6);
sstream1 << "L1 = " << L1 << std::endl
<< "L2 = " << L2 << std::endl
<< "L3 = " << L3 << std::endl
<< "L4 = " << L4 << std::endl
<< "L5 = " << L5 << std::endl
+ << "L6 = " << L6 << std::endl
+ << "L7 = " << L7 << std::endl
<< std::endl;
}
@@ -147,27 +142,29 @@
<< "implicit conversions enabled"
<< std::endl;
+ //[unit_example_5_snippet_6
quantity<SI::volume> vs(1.0*pow<3>(SI::meter));
quantity<CGS::volume> vc;
vc = vs;
-
- sstream1 << "volume (m^3) = " << vs << std::endl
- << "volume (cm^3) = " << vc << std::endl
- << std::endl;
quantity<SI::energy> es(1.0*SI::joule);
quantity<CGS::energy> ec;
ec = es;
+ quantity<SI::velocity> v1 = 2.0*SI::meters/SI::second,
+ v2 = 2.0*CGS::centimeters/CGS::second;
+ //]
+
+ sstream1 << "volume (m^3) = " << vs << std::endl
+ << "volume (cm^3) = " << vc << std::endl
+ << std::endl;
+
sstream1 << "energy (joules) = " << es << std::endl
<< "energy (ergs) = " << ec << std::endl
<< std::endl;
- quantity<SI::velocity> v1 = 2.0*SI::meters/SI::second,
- v2 = 2.0*CGS::centimeters/CGS::second;
-
sstream1 << "velocity (2 m/s) = " << v1 << std::endl
<< "velocity (2 cm/s) = " << v2 << std::endl
<< std::endl;
@@ -175,9 +172,11 @@
sstream2 << "L1 = 2 m" << std::endl;
sstream2 << "L2 = 2 m" << std::endl;
- sstream2 << "L3 = 5 m" << std::endl;
- sstream2 << "L4 = 4 m" << std::endl;
- sstream2 << "L5 = 200 cm" << std::endl;
+ sstream2 << "L3 = 2 m" << std::endl;
+ sstream2 << "L4 = 200 cm" << std::endl;
+ sstream2 << "L5 = 5 m" << std::endl;
+ sstream2 << "L6 = 4 m" << std::endl;
+ sstream2 << "L7 = 200 cm" << std::endl;
sstream2 << std::endl;
sstream2 << "volume (m^3) = 1 m^3" << std::endl;
sstream2 << "volume (cm^3) = " << 1e6 << " cm^3" << std::endl;
Modified: sandbox/units/libs/units/example/unit_example_8.cpp
==============================================================================
--- sandbox/units/libs/units/example/unit_example_8.cpp (original)
+++ sandbox/units/libs/units/example/unit_example_8.cpp 2007-07-27 14:28:50 EDT (Fri, 27 Jul 2007)
@@ -76,11 +76,7 @@
typedef boost::math::quaternion<typename power_dimof_helper<Y,static_rational<N,D> >::type> type;
static type value(const boost::math::quaternion<Y>& x)
- {
- //const static_rational<N,D> rat;
-
- //const typename divide_typeof_helper<Y,Y>::type m = Y(rat.numerator())/Y(rat.denominator());
-
+ {
return boost::math::pow(x,static_cast<int>(N));
}
};
@@ -96,10 +92,6 @@
static type value(const boost::math::quaternion<Y>& x)
{
- //const static_rational<N,D> rat;
-
- //const typename divide_typeof_helper<Y,Y>::type m = Y(rat.denominator())/Y(rat.numerator());
-
return boost::math::pow(x,static_cast<int>(D));
}
};
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk