units.qbk

Boost provides free peer-reviewed portable C++ source libraries. We emphasize libraries that work

giving the following output :

[conversion_output_1]

A few more explicit unit system conversions :

[conversion_snippet_5]

which produces the following output:

[conversion_output_2]

[endsect]

[section:UDTExample User Defined Types]

([@../../libs/units/example/quaternion.cpp quaternion.cpp])

This example demonstrates the use of `boost::math::quaternion` as a value type for  [___quantity] and the converse.
For the first case, we first define specializations of [___power_typeof_helper] and [___root_typeof_helper] for 
powers and roots, respectively:

[import ../example/quaternion.cpp]

[quaternion_class_snippet_1a]

[quaternion_class_snippet_1b]

We can now declare a [___quantity] of a `quaternion` :

[quaternion_snippet_1]

so that all operations that are defined in the `quaternion` class behave correctly. If rational
powers were defined for this class, it would be possible to compute rational powers and roots with
no additional changes. 

[quaternion_output_1]

Now, if for some reason we preferred the [___quantity] to be the value type of the `quaternion` class we would have :

[quaternion_snippet_2]

Here, the unary plus and minus and addition and subtraction operators function correctly. Unfortunately, 
the multiplication and division operations fail because `quaternion` implements them in terms of the `*=` and 
`/=` operators, respectively, which are incapable of representing the heterogeneous unit algebra needed for 
quantities (an identical problem 
occurs with `std::complex<T>`, for the same reason). In order to compute rational powers and roots, we need to 
specialize [___power_typeof_helper] and [___root_typeof_helper] as follows:

[quaternion_class_snippet_2a]

[quaternion_class_snippet_2b]

giving:

[quaternion_output_2]

[endsect]

[section:ComplexExample Complex Example]

([@../../libs/units/example/complex.cpp complex.cpp])

This example demonstrates how to implement a replacement `complex` class that functions correctly both as a 
quantity value type and as a quantity container class, including heterogeneous multiplication and division 
operations and rational powers and roots. Naturally, heterogeneous operations are only supported on
compilers that implement `typeof`. The primary differences are that binary operations are not implemented
using the `op=` operators and use the utility classes [___add_typeof_helper], [___subtract_typeof_helper], 
[___multiply_typeof_helper], and [___divide_typeof_helper]. In addition, [___power_typeof_helper] and
[___root_typeof_helper] are defined for both cases :

[import ../example/complex.cpp]

[complex_class_snippet_1]

With this replacement `complex` class, we can declare a complex variable :

[complex_snippet_1]   

to get the correct behavior for all cases supported by [___quantity] with a `complex` value type :

[complex_output_1]

and, similarly, `complex` with a [___quantity] value type 

[complex_snippet_2]

gives

[complex_output_2]

[endsect]

[section:PerformanceExample Performance Example]

([@../../libs/units/example/performance.cpp performance.cpp])

This example provides an ad hoc performance test to verify that zero runtime overhead 
is incurred when using [___quantity] in place of `double`. Note that performance 
optimization and testing is not trivial, so some care must be taken in profiling. It 
is also critical to have a compiler capable of optimizing the many template instantiations
and inline calls effectively to achieve maximal performance. Zero overhead for this test
has been verified using gcc 4.0.1, and icc 9.0, 10.0, and 10.1 on Mac OS 10.4 and 10.5, and
using msvc 8.0 on Windows XP.

[endsect]

[section:RadarBeamHeightExample Radar Beam Height]

([@../../libs/units/example/radar_beam_height.cpp radar_beam_height.cpp])

[import ../example/radar_beam_height.cpp]

This example demonstrates the implementation of two non-SI units of length, the 
nautical mile :

[radar_beam_height_class_snippet_1]

and the imperial foot :

[radar_beam_height_class_snippet_2]

These units include conversions between themselves and the meter. Three functions
for computing radar beam height from radar range and the local earth radius are 
defined. The first takes arguments in one system and returns a value in the same 
system :

[radar_beam_height_function_snippet_1]

The second is similar, but is templated on return type, so that the arguments are
converted to the return unit system internally :

[radar_beam_height_function_snippet_2]

Finally, the third function is an empirical approximation that is only valid for
radar ranges specified in nautical miles, returning beam height in feet. This 
function uses the heterogeneous unit of nautical miles per square root of feet to
ensure dimensional correctness :

[radar_beam_height_function_snippet_3]

With these, we can compute radar beam height in various unit systems :

[radar_beam_height_snippet_1]

giving

[radar_beam_height_output]

[endsect]

[section:HeterogeneousUnitExample Heterogeneous Unit Example]

([@../../libs/units/example/heterogeneous_unit.cpp heterogeneous_unit.cpp])

[import ../example/heterogeneous_unit.cpp]

Mixed units and mixed unit conversions.

This code:

[heterogeneous_unit_snippet_1]

gives

[heterogeneous_unit_output_1]

Arbitrary conversions also work:

[heterogeneous_unit_snippet_2]

yielding

[heterogeneous_unit_output_2]

[endsect]

[section:AbsoluteRelativeTemperatureExample Absolute and Relative Temperature Example]

([@../../libs/units/example/temperature.cpp temperature.cpp])

[import ../example/temperature.cpp]

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 using the [___absolute] wrapper class.

First we define a system using the predefined fahrenheit base unit:

[temperature_snippet_1]

Now we can create some quantities:

[temperature_snippet_3]

Note the use of [___absolute] to wrap a unit. The resulting output is:

[temperature_output_1]

[endsect]

[section:RuntimeConversionFactorExample Runtime Conversion Factor Example]

([@../../libs/units/example/runtime_conversion_factor.cpp runtime_conversion_factor.cpp])

[import ../example/runtime_conversion_factor.cpp]

The Boost.Units library does not require that the conversion factors be compile time constants,
as is demonstrated in this example:

[runtime_conversion_factor_snippet_1]

[endsect]

[section:UnitsWithNonbaseDimensions Units with Non-base Dimensions]

([@../../libs/units/example/non_base_dimension.cpp non_base_dimension.cpp])

[import ../example/non_base_dimension.cpp]

It is also possible to define base units that have derived rather than base dimensions:

[non_base_dimension_snippet_1]

[endsect]

[section:OutputForCompositeUnits Output for Composite Units]

([@../../libs/units/example/composite_output.cpp composite_output.cpp])

[import ../example/composite_output.cpp]

If a unit has a special name and/or symbol, the free functions `name_string` and
`symbol_string` can be overloaded directly. 

[composite_output_snippet_1]

In this case, any unit that reduces 
to the overloaded unit will be output with the replacement symbol. 

Special names and symbols for the SI and CGS unit systems are found in 
[headerref boost/units/systems/si/io.hpp] and [headerref boost/units/systems/cgs/io.hpp], 
respectively. If these headers are not included, the output will simply follow
default rules using the appropriate fundamental dimensions. 
Note that neither of these functions is defined for quantities 
because doing so would require making assumptions on how the corresponding value
type should be formatted.

Three `ostream` formatters, `symbol_format`, `name_format`, and `typename_format`
are provided for convenience. These select the textual representation of units 
provided by `symbol_string` or `name_string` in the first two cases, while the
latter returns a demangled typename for debugging purposes. Formatting of scaled
unit is also done correctly.

[endsect]

[section:ConversionFactor Conversion Factor]

This code demonstrates the use of the `conversion_factor` free function to determine
the scale factor between two units.

([@../../libs/units/example/conversion_factor.cpp conversion_factor.cpp])

[import ../example/conversion_factor.cpp]

[conversion_factor_snippet_1]

Produces

[conversion_factor_output]

[endsect]

[section:RuntimeUnits Runtime Units]

([@../../libs/units/example/runtime_unit.cpp runtime_unit.cpp])

[import ../example/runtime_unit.cpp]

This example shows how to implement an interface that
allow different units at runtime while still maintaining
type safety for internal calculations.

[runtime_unit_snippet_1]

[endsect]

[section:lambda Interoperability with Boost.Lambda]

([@../../libs/units/example/lambda.cpp lambda.cpp])

[import ../example/lambda.cpp]

The header [headerref boost/units/lambda.hpp] provides overloads
and specializations needed to make Boost.Units usable with the
Boost.Lambda library.

[lambda_snippet_1]

[endsect]

[endsect]

[section:Utilities Utilities]

Relatively complete SI and CGS unit systems are provided in [headerref boost/units/systems/si.hpp] and
[headerref boost/units/systems/cgs.hpp], respectively. 

[section:Metaprogramming_Classes Metaprogramming Classes]

    template<long N> struct ordinal<N>;

    template<typename T,typename V> struct get_tag< dim<T,V> >;
    template<typename T,typename V> struct get_value< dim<T,V> >;
    template<class S,class DT> struct get_system_tag_of_dim<S,DT>;
    template<typename Seq> struct make_dimension_list<Seq>;
    template<class DT> struct fundamental_dimension<DT>;
    template<class DT1,int E1,...> struct composite_dimension<DT1,E1,...>;

    template<class Dim,class System> struct get_dimension< unit<Dim,System> >;
    template<class Unit,class Y> struct get_dimension< quantity<Unit,Y> >;
    template<class Dim,class System> struct get_system< unit<Dim,System> >;
    template<class Unit,class Y> struct get_system quantity<Unit,Y> >;

    struct dimensionless_type;
    template<class System> struct dimensionless_unit<System>;
    template<class System,class Y> struct dimensionless_quantity<System,Y>;

    struct implicitly_convertible;
    struct trivial_conversion;
    template<class T,class S1,class S2> struct base_unit_converter<T,S1,S2>;

    template<class Q1,class Q2> class conversion_helper<Q1,Q2>;

[endsect]

[section:Metaprogramming_Predicates Metaprogramming Predicates]

    template<typename T,typename V> struct is_dim< dim<T,V> >;
    template<typename T,typename V> struct is_empty_dim< dim<T,V> >;

    template<typename Seq> struct is_dimension_list<Seq>;

    template<class S> struct is_system< homogeneous_system<S> >;
    template<class S> struct is_system< heterogeneous_system<S> >;
    template<class S> struct is_homogeneous_system< homogeneous_system<S> >;