Boost logo

Boost-Commit :

Subject: [Boost-commit] svn:boost r60431 - branches/units/autoprefix/boost/units
From: pbristow_at_[hidden]
Date: 2010-03-10 12:15:13


Author: pbristow
Date: 2010-03-10 12:15:12 EST (Wed, 10 Mar 2010)
New Revision: 60431
URL: http://svn.boost.org/trac/boost/changeset/60431

Log:
Added autoprefix and added more comments. \detailed changed to \details to satisfy Doxygen.
Text files modified:
   branches/units/autoprefix/boost/units/cmath.hpp | 10 +-
   branches/units/autoprefix/boost/units/config.hpp | 23 ++++++
   branches/units/autoprefix/boost/units/dim.hpp | 15 +--
   branches/units/autoprefix/boost/units/io.hpp | 137 +++++++++++++++++++++------------------
   branches/units/autoprefix/boost/units/operators.hpp | 9 +-
   branches/units/autoprefix/boost/units/physical_dimensions.hpp | 27 ++++--
   branches/units/autoprefix/boost/units/pow.hpp | 22 +++---
   7 files changed, 140 insertions(+), 103 deletions(-)

Modified: branches/units/autoprefix/boost/units/cmath.hpp
==============================================================================
--- branches/units/autoprefix/boost/units/cmath.hpp (original)
+++ branches/units/autoprefix/boost/units/cmath.hpp 2010-03-10 12:15:12 EST (Wed, 10 Mar 2010)
@@ -2,7 +2,7 @@
 // unit/quantity manipulation and conversion
 //
 // Copyright (C) 2003-2008 Matthias Christian Schabel
-// Copyright (C) 2007-2008 Steven Watanabe
+// Copyright (C) 2007-2010 Steven Watanabe
 //
 // Distributed under the Boost Software License, Version 1.0. (See
 // accompanying file LICENSE_1_0.txt or copy at
@@ -27,10 +27,10 @@
 
 #include <boost/units/systems/si/plane_angle.hpp>
 
-/// \file
+/// \file cmath.hpp
 /// \brief Overloads of functions in \<cmath\> for quantities
 ///
-/// \detailed Only functions for which a dimensionally-correct result type
+/// \details Only functions for which a dimensionally-correct result type
 /// can be determined are overloaded. All functions work with dimensionless
 /// quantities.
 
@@ -38,8 +38,8 @@
 // some <cmath> functions as macros; it is used for all functions even though it
 // isn't necessary -- I didn't want to think :)
 //
-// the form using namespace detail; return(f(x)); is used
-// to enable ADL for UDTs
+// the form \code using namespace detail; return(f(x)); \endcode is used
+// to enable ADL for UDTs.
 
 namespace boost {
 

Modified: branches/units/autoprefix/boost/units/config.hpp
==============================================================================
--- branches/units/autoprefix/boost/units/config.hpp (original)
+++ branches/units/autoprefix/boost/units/config.hpp 2010-03-10 12:15:12 EST (Wed, 10 Mar 2010)
@@ -2,7 +2,7 @@
 // unit/quantity manipulation and conversion
 //
 // Copyright (C) 2003-2008 Matthias Christian Schabel
-// Copyright (C) 2008 Steven Watanabe
+// Copyright (C) 2010 Steven Watanabe
 //
 // Distributed under the Boost Software License, Version 1.0. (See
 // accompanying file LICENSE_1_0.txt or copy at
@@ -85,6 +85,27 @@
     #define BOOST_UNITS_CHECK_LAYOUT_COMPATIBILITY(a, b) ((void)0)
 #endif
 
+// Create a Doxygen main page that will only appear if standalone Doxygen documentation
+// is produced using the Doxywizard GUI using information in the /doc/doxygen/doxyfile.
+
+/*! \mainpage Boost.Units
+
+A C++ library for zero-overhead dimensional analysis and
+unit and quantity manipulation and conversion.
+
+Copyright (C) 2003-2008 Matthias Christian Schabel
+Copyright (C) 2010 Steven Watanabe
+
+Distributed under the Boost Software License, Version 1.0.
+(See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org//LICENSE_1_0.txt)
+
+This is a standalone index produced by the Doxygen Doxywizard GUI using information in the units/doc/doxygen/doxyfile.
+
+A full index that includes the full documentation and tutorial is at
+http://www.boost.org/doc/libs/1_42_0/doc/html//boost_units.html.
+
+*/ // end mainpage
+
 #ifdef BOOST_UNITS_DOXYGEN
 
 /// If defined will trigger a static assertion if quantity<Unit, T>

Modified: branches/units/autoprefix/boost/units/dim.hpp
==============================================================================
--- branches/units/autoprefix/boost/units/dim.hpp (original)
+++ branches/units/autoprefix/boost/units/dim.hpp 2010-03-10 12:15:12 EST (Wed, 10 Mar 2010)
@@ -2,7 +2,7 @@
 // unit/quantity manipulation and conversion
 //
 // Copyright (C) 2003-2008 Matthias Christian Schabel
-// Copyright (C) 2007-2008 Steven Watanabe
+// Copyright (C) 2007-2010 Steven Watanabe
 //
 // Distributed under the Boost Software License, Version 1.0. (See
 // accompanying file LICENSE_1_0.txt or copy at
@@ -21,22 +21,19 @@
 #include <boost/units/static_rational.hpp>
 #include <boost/units/detail/dim_impl.hpp>
 
-/// \file
+/// \file dim.hpp
 /// \brief Handling of fundamental dimension/exponent pairs.
 
 namespace boost {
-
 namespace units {
-
-namespace detail {
-
-struct dim_tag { };
-
+namespace detail
+{
+ struct dim_tag { };
 }
 
 /// \brief Dimension tag/exponent pair for a single fundamental dimension.
 ///
-/// \detailed
+/// \details
 /// The dim class represents a single dimension tag/dimension exponent pair.
 /// That is, @c dim<tag_type,value_type> is a pair where @c tag_type represents the
 /// fundamental dimension being represented and @c value_type represents the

Modified: branches/units/autoprefix/boost/units/io.hpp
==============================================================================
--- branches/units/autoprefix/boost/units/io.hpp (original)
+++ branches/units/autoprefix/boost/units/io.hpp 2010-03-10 12:15:12 EST (Wed, 10 Mar 2010)
@@ -11,6 +11,13 @@
 #ifndef BOOST_UNITS_IO_HPP
 #define BOOST_UNITS_IO_HPP
 
+/// \file
+
+/// \brief Stream Input and output for rationals, units and quantities.
+/// \details Functions and manipulators for output and input of units and quantities.
+/// symbol and name format, and engineering and binary autoprefix.
+/// Serialisation output is also supported.
+
 #include <cassert>
 #include <cmath>
 #include <string>
@@ -49,23 +56,21 @@
 
 namespace units {
 
-// get string representation of arbitrary type
+/// get string representation of arbitrary type.
 template<class T> std::string to_string(const T& t)
 {
- std::stringstream sstr;
-
- sstr << t;
-
+ std::stringstream sstr;
+ sstr << t;
     return sstr.str();
 }
 
-// get string representation of integral-valued @c static_rational
+/// get string representation of integral-valued @c static_rational.
 template<integer_type N> std::string to_string(const static_rational<N>&)
 {
     return to_string(N);
 }
 
-// get string representation of @c static_rational
+/// get string representation of @c static_rational.
 template<integer_type N, integer_type D> std::string to_string(const static_rational<N,D>&)
 {
     return '(' + to_string(N) + '/' + to_string(D) + ')';
@@ -79,40 +84,41 @@
     return os;
 }
 
-/// traits template for unit names
+/// traits template for unit names.
 template<class BaseUnit>
 struct base_unit_info
 {
     /// INTERNAL ONLY
     typedef void base_unit_info_primary_template;
- /// The full name of the unit (returns BaseUnit::name() by default)
+ /// The full name of the unit ( by default)
     static std::string name()
     {
- return(BaseUnit::name());
+ return(BaseUnit::name()); /// \returns BaseUnit::name(), for example "meter"
     }
     
- /// The symbol for the base unit (Returns BaseUnit::symbol() by default)
+ /// The symbol for the base unit.
+
     static std::string symbol()
     {
- return(BaseUnit::symbol());
+ return(BaseUnit::symbol()); /// \returns BaseUnit::symbol(), for example "m"
     }
 };
 
 enum format_mode
-{
- symbol_fmt = 0, // default - reduces unit names to known symbols for both base and derived units
- name_fmt, // output full unit names for base and derived units
- raw_fmt, // output only symbols for base units
- typename_fmt, // output demangled typenames
- fmt_mask = 3
+{ /// \enum format_mode format of output of units, for example "m" or "meter".
+ symbol_fmt = 0, /// default - reduces unit names to known symbols for both base and derived units.
+ name_fmt = 1, /// output full unit names for base and derived units, for example "meter".
+ raw_fmt = 2, /// output only symbols for base units (but not derived units), for example "m".
+ typename_fmt = 3, /// output demangled typenames (useful only for diagnosis).
+ fmt_mask = 3 /// Bits used for format.
 };
 
 enum autoprefix_mode
-{
- autoprefix_none = 0,
- autoprefix_engineering = 4,
- autoprefix_binary = 8,
- autoprefix_mask = 12
+{ /// \enum autoprefix_mode automatic scaling and prefix (controlled by value of quantity) a, if any,
+ autoprefix_none = 0, /// No automatic prefix.
+ autoprefix_engineering = 4, /// Scale and prefix with 10^3 multiples, 1234.5 m output as 1.2345 km.
+ autoprefix_binary = 8, /// Scale and prefix with 2^10 (1024) multiples, 1024 as 1 kb.
+ autoprefix_mask = 12 /// Bits used for autoprefix.
 };
 
 namespace detail {
@@ -151,77 +157,83 @@
 } // namespace detail
 
 inline int get_flags(std::ios_base& ios, int mask)
-{
+{ /// \return flags controlling output.
     return(ios.iword(detail::xalloc_key_holder<true>::value) & mask);
 }
 
 inline void set_flags(std::ios_base& ios, int new_flags, int mask)
-{
+{ /// Set new flags controlling output format.
+ /// \return previous flags.
+
     assert((~mask & new_flags) == 0);
     long& flags = ios.iword(detail::xalloc_key_holder<true>::value);
     flags = (flags & ~mask) | static_cast<long>(new_flags);
 }
 
 inline format_mode get_format(std::ios_base& ios)
-{
+{ /// \return flags controlling output format.
     return(static_cast<format_mode>((get_flags)(ios, fmt_mask)));
 }
 
 inline void set_format(std::ios_base& ios, format_mode new_mode)
-{
- (set_flags)(ios, new_mode, fmt_mask);
+{ /// Set new flags controlling output format.
+ (set_flags)(ios, new_mode, fmt_mask);
 }
 
 inline std::ios_base& typename_format(std::ios_base& ios)
-{
+{ /// Set new flags for type_name output format.
+ /// \return previous format flags.
     (set_format)(ios, typename_fmt);
     return(ios);
 }
 
 inline std::ios_base& raw_format(std::ios_base& ios)
-{
- (set_format)(ios, raw_fmt);
+{ /// set new flag for raw format output, for example "m".
+ (set_format)(ios, raw_fmt); /// \return previous format flags.
     return(ios);
 }
 
 inline std::ios_base& symbol_format(std::ios_base& ios)
-{
- (set_format)(ios, symbol_fmt);
+{ // set new format flag for symbol output, for example "m".
+ (set_format)(ios, symbol_fmt); /// \return previous format flags.
     return(ios);
 }
 
 inline std::ios_base& name_format(std::ios_base& ios)
-{
+{ /// set new format for name output, for example "meter".
     (set_format)(ios, name_fmt);
- return(ios);
+ return(ios); /// \return previous format flags.
 }
 
 inline autoprefix_mode get_autoprefix(std::ios_base& ios)
-{
+{ /// get autoprefix flags for output.
+
     return static_cast<autoprefix_mode>((get_flags)(ios, autoprefix_mask));
 }
 
 inline void set_autoprefix(std::ios_base& ios, autoprefix_mode new_mode)
-{
+{ /// Get format for output.
     (set_flags)(ios, new_mode, autoprefix_mask);
 }
 
 inline std::ios_base& no_prefix(std::ios_base& ios)
-{
+{ /// Clear autoprefix flags.
+
     (set_autoprefix)(ios, autoprefix_none);
- return ios;
+ return ios; /// \return previous prefix flags.
 }
 
 inline std::ios_base& engineering_prefix(std::ios_base& ios)
-{
+{ /// Set flag for engineering prefix, so 1234.5 m displays as "1.2345 km".
+
     (set_autoprefix)(ios, autoprefix_engineering);
- return ios;
+ return ios; /// \return previous prefix flags.
 }
 
 inline std::ios_base& binary_prefix(std::ios_base& ios)
-{
+{ /// Set flag for binary prefix, so 1024 byte displays as "1 Kib".
     (set_autoprefix)(ios, autoprefix_binary);
- return ios;
+ return ios; /// \return previous prefix flags.
 }
 
 namespace detail {
@@ -229,13 +241,13 @@
 template<integer_type N, integer_type D>
 inline std::string exponent_string(const static_rational<N,D>& r)
 {
- return '^' + to_string(r);
+ return '^' + to_string(r); ///\return exponent string like "^1/2".
 }
 
 template<>
 inline std::string exponent_string(const static_rational<1>&)
 {
- return "";
+ return ""; ///\return empty exponent string for integer rational like 2.
 }
 
 template<class T>
@@ -250,7 +262,7 @@
     return base_unit_info<typename T::tag_type>::name() + exponent_string(typename T::value_type());
 }
 
-// stringify with symbols
+// stringify with symbols.
 template<int N>
 struct symbol_string_impl
 {
@@ -288,7 +300,7 @@
         static void value(std::string& str)
         {
             // better shorthand for dimensionless?
- str += "dimensionless";
+ str += "dimensionless"; /// \return appended "dimensionless".
         }
     };
 };
@@ -317,7 +329,7 @@
     };
 };
 
-// stringify with names
+// stringify with names.
 template<int N>
 struct name_string_impl
 {
@@ -456,7 +468,7 @@
     return(str);
 }
 
-// this overload catches scaled units that have a single base unit
+// This overload catches scaled units that have a single base unit
 // raised to the first power. It causes si::nano * si::meters to not
 // put parentheses around the meters. i.e. nm rather than n(m)
 /// INTERNAL ONLY
@@ -472,7 +484,7 @@
     return(str);
 }
 
-// this overload is necessary to disambiguate.
+// This overload is necessary to disambiguate.
 // it catches units that are unscaled and have a single
 // base unit raised to the first power. It is treated the
 // same as any other unscaled unit.
@@ -486,8 +498,7 @@
     return(str);
 }
 
-
-// this overload catches scaled units that have a single scaled base unit
+// This overload catches scaled units that have a single scaled base unit
 // raised to the first power. It moves that scaling on the base unit
 // to the unit level scaling and recurses. By doing this we make sure that
 // si::milli * si::kilograms will print g rather than mkg.
@@ -626,7 +637,7 @@
     os << s;
 }
 
-// code for automatically applying the appropriate prefixes.
+// For automatically applying the appropriate prefixes.
 
 template<class End, class Prev, class T, class F, class TooLarge>
 void find_matching_scale_impl(End, End, Prev, T, F, TooLarge l)
@@ -746,7 +757,7 @@
     detail::find_matching_scale<Prefixes>(q.value(), detail::print_scaled<Unit>(os), default_);
 }
 
-// handle units like si::kilograms that have a scale embedded in the
+// Handle units like si::kilograms that have a scale embedded in the
 // base unit. This overload is disabled if the scaled base unit has
 // a user-defined string representation.
 template<class Prefixes, class CharT, class Traits, class Dimension, class BaseUnit, class BaseScale, class Scale, class T>
@@ -862,12 +873,12 @@
     return detail::to_string_impl(unit<Dimension,System>(), detail::format_name_impl());
 }
 
-/// Print an @c unit as a list of base units and exponents
+/// Print a @c unit as a list of base units and their exponents.
 ///
-/// for @c symbol_format this gives e.g. "m s^-1" or "J"
-/// for @c name_format this gives e.g. "meter second^-1" or "joule"
-/// for @c raw_format this gives e.g. "m s^-1" or "meter kilogram^2 second^-2"
-/// for @c typename_format this gives the typename itself (currently demangled only on GCC)
+/// for @c symbol_format outputs e.g. "m s^-1" or "J".
+/// for @c name_format outputs e.g. "meter second^-1" or "joule".
+/// for @c raw_format outputs e.g. "m s^-1" or "meter kilogram^2 second^-2".
+/// for @c typename_format outputs the typename itself (currently demangled only on GCC).
 template<class Char, class Traits, class Dimension, class System>
 inline std::basic_ostream<Char, Traits>& operator<<(std::basic_ostream<Char, Traits>& os, const unit<Dimension, System>& u)
 {
@@ -895,10 +906,12 @@
     return(os);
 }
 
-/// Print a @c quantity. Prints the value followed by the unit
-/// If the engineering_prefix, or binary_prefix is set, tries
-/// to scale the value appropriately.
+/// \brief Print a @c quantity.
+/// \details Prints the value followed by the unit.
+/// If the engineering_prefix, or binary_prefix is set,
+/// tries to scale the value appropriately.
 /// For example, it might print 12.345 km instead of 12345 m.
+/// (Note does @b not attempt to automatically scale scalars like double, float...)
 template<class Char, class Traits, class Unit, class T>
 inline std::basic_ostream<Char, Traits>& operator<<(std::basic_ostream<Char, Traits>& os, const quantity<Unit, T>& q)
 {

Modified: branches/units/autoprefix/boost/units/operators.hpp
==============================================================================
--- branches/units/autoprefix/boost/units/operators.hpp (original)
+++ branches/units/autoprefix/boost/units/operators.hpp 2010-03-10 12:15:12 EST (Wed, 10 Mar 2010)
@@ -16,24 +16,23 @@
 
 #include <boost/units/config.hpp>
 
-/// \file
+/// \file operators.hpp
 /// \brief Compile time operators and typeof helper classes.
 ///
-/// \detailed
+/// \details
 /// These operators declare the compile-time operators needed to support dimensional
-/// analysis algebra. They require the use of Boost.Typeof.
+/// analysis algebra. They require the use of Boost.Typeof, emulation or native.
 /// Typeof helper classes define result type for heterogeneous operators on value types.
 /// These must be defined through specialization for powers and roots.
 
 namespace boost {
-
 namespace units {
 
 #if BOOST_UNITS_HAS_TYPEOF
 
 #ifndef BOOST_UNITS_DOXYGEN
 
-// to avoid need for default constructor and eliminate divide by zero errors
+// to avoid need for default constructor and eliminate divide by zero errors.
 namespace typeof_ {
 
 /// INTERNAL ONLY

Modified: branches/units/autoprefix/boost/units/physical_dimensions.hpp
==============================================================================
--- branches/units/autoprefix/boost/units/physical_dimensions.hpp (original)
+++ branches/units/autoprefix/boost/units/physical_dimensions.hpp 2010-03-10 12:15:12 EST (Wed, 10 Mar 2010)
@@ -2,7 +2,7 @@
 // unit/quantity manipulation and conversion
 //
 // Copyright (C) 2003-2008 Matthias Christian Schabel
-// Copyright (C) 2007-2008 Steven Watanabe
+// Copyright (C) 2007-2010 Steven Watanabe
 //
 // Distributed under the Boost Software License, Version 1.0. (See
 // accompanying file LICENSE_1_0.txt or copy at
@@ -11,25 +11,32 @@
 #ifndef BOOST_UNITS_PHYSICAL_UNITS_HPP
 #define BOOST_UNITS_PHYSICAL_UNITS_HPP
 
-/// \file Includes all of the physical_dimension headers.
-///
-/// \brief Physical dimensions according to the SI system
-///
-/// \detail This header includes all physical dimension headers for both base
-/// derived dimensions. Base dimensions are extended to include plane and
-/// solid angle for convenience.
+/// \file
+
+/// \brief Physical dimensions according to the SI system.
 ///
+/// \details This header includes all physical dimension headers for both base
+/// derived dimensions.
+
+/// Base dimensions are extended to include plane and solid angle as separate dimensions
+/// to reduce the risk of confusion between the dimensions.
+
+// Include all of the physical_dimension headers.
 
+// SI seven fundamental dimensions.
 #include <boost/units/physical_dimensions/amount.hpp>
 #include <boost/units/physical_dimensions/current.hpp>
 #include <boost/units/physical_dimensions/length.hpp>
 #include <boost/units/physical_dimensions/luminous_intensity.hpp>
 #include <boost/units/physical_dimensions/mass.hpp>
-#include <boost/units/physical_dimensions/plane_angle.hpp>
-#include <boost/units/physical_dimensions/solid_angle.hpp>
 #include <boost/units/physical_dimensions/temperature.hpp>
 #include <boost/units/physical_dimensions/time.hpp>
 
+// Base dimensions are extended to include plane and solid angle for convenience.
+#include <boost/units/physical_dimensions/plane_angle.hpp>
+#include <boost/units/physical_dimensions/solid_angle.hpp>
+
+// Derived dimensions.
 #include <boost/units/physical_dimensions/absorbed_dose.hpp>
 #include <boost/units/physical_dimensions/acceleration.hpp>
 #include <boost/units/physical_dimensions/action.hpp>

Modified: branches/units/autoprefix/boost/units/pow.hpp
==============================================================================
--- branches/units/autoprefix/boost/units/pow.hpp (original)
+++ branches/units/autoprefix/boost/units/pow.hpp 2010-03-10 12:15:12 EST (Wed, 10 Mar 2010)
@@ -2,7 +2,7 @@
 // unit/quantity manipulation and conversion
 //
 // Copyright (C) 2003-2008 Matthias Christian Schabel
-// Copyright (C) 2008 Steven Watanabe
+// Copyright (C) 2010 Steven Watanabe
 //
 // Distributed under the Boost Software License, Version 1.0. (See
 // accompanying file LICENSE_1_0.txt or copy at
@@ -18,14 +18,14 @@
 #include <boost/units/static_rational.hpp>
 #include <boost/units/detail/static_rational_power.hpp>
 
-/// \file
-/// \brief Raise values to exponents known at compile-time
+/// \file pow.hpp
+/// \brief Raise values to exponents known at compile-time.
 
 namespace boost {
 
 namespace units {
 
-/// raise a value to a @c static_rational power
+/// raise a value to a @c static_rational power.
 template<class Rat,class Y>
 inline typename power_typeof_helper<Y,Rat>::type
 pow(const Y& x)
@@ -33,7 +33,7 @@
     return power_typeof_helper<Y,Rat>::value(x);
 }
 
-/// raise a value to an integer power
+/// raise a value to an integer power.
 template<long N,class Y>
 inline typename power_typeof_helper<Y,static_rational<N> >::type
 pow(const Y& x)
@@ -43,7 +43,7 @@
 
 #ifndef BOOST_UNITS_DOXYGEN
 
-/// raise @c T to a @c static_rational power
+/// raise @c T to a @c static_rational power.
 template<class T, long N,long D>
 struct power_typeof_helper<T, static_rational<N,D> >
 {
@@ -57,11 +57,11 @@
     }
 };
 
-/// raise @c float to a @c static_rational power
+/// raise @c float to a @c static_rational power.
 template<long N,long D>
 struct power_typeof_helper<float, static_rational<N,D> >
 {
- // N.B. pathscale doesn't accept inheritence for some reason.
+ // N.B. pathscale doesn't accept inheritance for some reason.
     typedef power_typeof_helper<double, static_rational<N,D> > base;
     typedef typename base::type type;
     static type value(const double& x)
@@ -72,7 +72,7 @@
 
 #endif
 
-/// take the @c static_rational root of a value
+/// take the @c static_rational root of a value.
 template<class Rat,class Y>
 typename root_typeof_helper<Y,Rat>::type
 root(const Y& x)
@@ -80,7 +80,7 @@
     return root_typeof_helper<Y,Rat>::value(x);
 }
 
-/// take the integer root of a value
+/// take the integer root of a value.
 template<long N,class Y>
 typename root_typeof_helper<Y,static_rational<N> >::type
 root(const Y& x)
@@ -94,7 +94,7 @@
 template<class T, long N,long D>
 struct root_typeof_helper<T,static_rational<N,D> >
 {
- // N.B. pathscale doesn't accept inheritence for some reason.
+ // N.B. pathscale doesn't accept inheritance for some reason.
     typedef power_typeof_helper<T, static_rational<D,N> > base;
     typedef typename base::type type;
     static type value(const T& x)


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