[Boost-commit] svn:boost r73084 - sandbox/conversion/libs/conversion_ext/doc

Subject: [Boost-commit] svn:boost r73084 - sandbox/conversion/libs/conversion_ext/doc
From: gordon_at_[hidden]
Date: 2011-07-13 18:37:36

Author: gordon.woodhull
Date: 2011-07-13 18:37:36 EDT (Wed, 13 Jul 2011)
New Revision: 73084
URL: http://svn.boost.org/trac/boost/changeset/73084

Log:
minor copy edits
Text files modified: 
   sandbox/conversion/libs/conversion_ext/doc/conversion.qbk |    64 ++++++++++++++++++++--------------------
   1 files changed, 32 insertions(+), 32 deletions(-)

Modified: sandbox/conversion/libs/conversion_ext/doc/conversion.qbk
==============================================================================
--- sandbox/conversion/libs/conversion_ext/doc/conversion.qbk	(original)
+++ sandbox/conversion/libs/conversion_ext/doc/conversion.qbk	2011-07-13 18:37:36 EDT (Wed, 13 Jul 2011)
@@ -94,9 +94,9 @@
 [section Scope]
 [/==================]
 
-[*Boost.Conversion] manages with generic extrinsic conversion between unrelated types. These conversion can be seen as implicit or explicit conversions ([@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2380.pdf [*N2380 - Explicit Conversion Operator Draft Working Paper (revision 2)]]).
+[*Boost.Conversion] manages generic extrinsic conversion between unrelated types. These conversion can be seen as implicit or explicit conversions ([@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2380.pdf [*N2380 - Explicit Conversion Operator Draft Working Paper (revision 2)]]).
 
-The conversion operator can not be overloaded with a free function on C++. In the past, there were some request to been able to overload the `static_cast` operator [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2200.pdf [*N2200 - Operator Overloading]]. The author of this library thinks that the language would be more uniform if this extrinsic overload would be possible. The new extrinsic conversion operators could take the following form 
+The conversion operator can not be overloaded with a free function in C++. In the past, there were requests to be able to overload the `static_cast` operator [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2200.pdf [*N2200 - Operator Overloading]]. The author of this library thinks that the language would be more uniform if this extrinsic overload would be possible. The new extrinsic conversion operators could take the following form 
 
   operator Target(const Source& val);
 
@@ -106,20 +106,20 @@
 
   Target& operator=(Target&, Source const&);
 
-[*Boost.Conversion] tries to provide a library emulation for this missing feature and shows some needed workarounds that are needed to take care of the current C++ semantics. 
+[*Boost.Conversion] provides a library emulation for this missing feature and shows some workarounds needed to take care of current C++ semantics. 
 
-In order to provide the needed functionality, two type traits are mandatory `is_constructible` and `is_assignable`. The library provide a first implementation of these type traits that works on compilers providing some specific features. The idea is that these type traits should be added to [*Boost.TypeTraits].
+In order to provide the needed functionality, two type traits are mandatory: `is_constructible` and `is_assignable`. The library provides a first implementation of these type traits that works on compilers providing some specific features. The idea is that these type traits should be added to [*Boost.TypeTraits].
 
-When we don't have an automatic way to detect these traits, the library provide specialization for some std and boost types. If accepted the library should provide the specializations for all the standard types and optionally for all the Boost types.
+When we don't have an automatic way to detect these traits, the library provides specializations for some std and boost types. If accepted the library will provide specializations for all the standard types and optionally for all the Boost types.
 
-User working with compilers not supporting the definition of these traits, or users that need to make their code portable, will need to specialize these traits by hand.  
+Users working with compilers not supporting the definition of these traits, or users that need to make their code portable, will need to specialize these traits by hand.  
 
 [endsect]
 
 
 [section Motivation]
 
-I've needed recently to convert from `boost::chrono::time_point<Clock, Duration>` to `boost::posix_time::ptime` and from  `boost::chrono::duration<Rep, Period>` to `boost::posix_time::time_duration`. This kind of conversions are needed quite often when you use code from two different libraries that have implemented the same concept using of course different representations and have hard coded the library interface to its own implementation. Well this is a normal situation we can't avoid. Life is life.
+I've needed recently to convert from `boost::chrono::time_point<Clock, Duration>` to `boost::posix_time::ptime` and from  `boost::chrono::duration<Rep, Period>` to `boost::posix_time::time_duration`. These kinds of conversions are needed quite often when you use code from two different libraries that have each implemented the same concept using a different representation, and hard-coded the library interface to its own implementation. Well, this is a normal situation we can't avoid. Life is life.
 
 Quite often we need to convert unrelated types `Source` and `Target`. As these classes are unrelated, neither of them offers conversion operators to the other. Usually we get it by defining a specific function such as
 
@@ -134,7 +134,7 @@
     template <typename Clock, typename Duration>
     posix_time::ptime convert_to_posix_time_ptime(const chrono::time_point<Clock, Duration>& from);
 
-Imagine now that you need to convert a `std::pair<Source, Source>` to a `std::pair<Target, Target>`. The standard defines conversions of pairs if the related types are C++ convertible:
+Imagine now that you need to convert a `std::pair<Source, Source>` to a `std::pair<Target, Target>`. The standard defines conversion of two pair types if the related types are C++ convertible:
 
     template <typename T1, typename T2>
     struct pair {
@@ -151,7 +151,7 @@
 
 As the types `Target` and `Source` are not C++ convertible other than using a specific function, we need to use a workaround.
 
-Well we can again define a specific function
+We can again define a specific function
 
     std::pair<Target,Target> ConvertToPairOfTarget(std::pair<Source,Source>& v) {
         return std::make_pair(ConvertToTarget(v.fisrt), ConvertToTarget(v.second));
@@ -178,7 +178,7 @@
 
     Target  convert_to(Source& v) {return ConvertToTarget(v);}
 
-Note that the preceding overloadings don't really work, as C++ doesn't use the result type on overload resolution.
+Note that the preceding overloadings don't really work, as C++ doesn't use the result type on overload resolution. The library uses a customization point that takes into account the result type.
 
 In my case I needed
 
@@ -204,7 +204,7 @@
 
 using the `ConvertToPair` function.
 
-What about converting `std::pair<Source,std::pair<Source,Source> >` to `std::pair<Target,std::pair<Target,Target> >`? The issue now is that `convert_to(std::make_pair<to, std::make_pair<to,to> >)` does not compiles because the conversion of `std::pair` is named `ConvertToPair`. So we need to specialize the function `convert_to` for pairs.
+What about converting `std::pair<Source,std::pair<Source,Source> >` to `std::pair<Target,std::pair<Target,Target> >`? The issue now is that `convert_to(std::make_pair<to, std::make_pair<to,to> >)` does not compile because the conversion of `std::pair` is named `ConvertToPair`. So we need to specialize the function `convert_to` for pairs.
 
 
     template <typename T1, typename T2, typename S1, typename S2)
@@ -213,7 +213,7 @@
         return std::pair<T1,T2>(convert_to<T1>(from.first), convert_to<T2>(from.second));
     }
 
-There is still a last point. The preceding design works well with unrelated classes, but what about classes that already define some kind of conversion, using a constructor or a conversion operator. Do we need to make specialization for these conversion? The answer is no. We need to define the default implementation of `convert_to` function to just return the explicit conversion.
+There is still a last point. The preceding design works well with unrelated classes, but what about classes that already define conversion via a constructor or a conversion operator - do we need to specialize these conversions? The answer is no. We need to define the default implementation of the `convert_to` function to just return the explicit conversion.
 
     template < typename Target, typename Source>
     Target convert_to(const Source& from)
@@ -221,7 +221,7 @@
         return Target(from);
     }
 
-As noted above these overloadings don't work, and the library uses a customization point that takes in account the result type.
+As noted above these overloadings don't work, and the library uses a customization point that takes into account the result type.
 
 What have we learned? Classes or algorithms relying on a conversion can be made more generic by relaying in a function that explicitly states this conversion. Thus, instead of requiring
 
@@ -252,9 +252,9 @@
 
     to = convert_to<Target>(from);
 
-The rationale is that if there was not a copy constructor from a `Source` seems reasonable to think that there will not be an assignment operator. So in most of the cases, once we have specialized the __convert_to function we recover a reasonable implementation for the __assign_to function.
+The rationale is that if there was not a copy constructor from a `Source` seems reasonable to think that there will not be an assignment operator. So in most cases, once we have specialized the __convert_to function we achieve a reasonable implementation for the __assign_to function.
 
-When doing multiple assignments we use to do
+When doing multiple assignments we commonly do
 
     a = b = c;
 
@@ -262,15 +262,15 @@
 
     assign_to(a, assign_to(b, c));
 
-and if we find this not really readable we can try with the make assigner to `mat' free function.
+and if we find this less than readable we can try with the "make assigner to" `mat' free function.
 
     mat(a) = mat(b) = c;
 
-The behavior of `mat` recall the `tie` function of [*Boost.Tuple], but instead of allowing multiple assignments, allows a single `assign_to` call.
+The behavior of `mat` recalls the `tie` function of [*Boost.Tuple], but instead of invoking multiple assignments, it invokes a single `assign_to` call.
 
 So one of the advantages of using this common functions is uniformity. The other is that now we are able to find all the explicit conversions to one type, as we can do with explicit casts.
 
-The library takes in account some of the features provided by the [*Boost.Convert] library, as no-throw conversions, conversions with fallback, ...
+The library takes in account some of the features suggested by the [*Boost.Convert] library and its review, such as no-throw conversions, conversions with fallback, ...
 
 [endsect]
 
@@ -283,14 +283,14 @@
 
 * a generic __implicit_convert_to function which can be customized by the user to make implicit conversion between unrelated types.
 * a generic __explicit_convert_to function which can be customized by the user to make explicit conversion between unrelated types.
-* a generic __convert_to function which is equivalent __explicit_convert_to or that behaves as a functor factory if its argument is a fusion actor.
+* a generic __convert_to function (or __explicit_convert_to) for performing conversions, that behaves as a functor factory if its argument is a fusion actor.
 * a generic __assign_to function which can be customized by the user to make explicit assignments between unrelated types.
 * a generic __try_convert_to function which can be customized by the user to make explicit optional conversion between unrelated types.
 * a generic __try_assign_to function which can be customized by the user to make explicit optional assignments between unrelated types.
-* a generic __convert_to_or_fallback function which can be customized by the user to make explicit conversion between unrelated types relying on a fallback when the conversion fails.
+* a generic __convert_to_or_fallback function which can be customized by the user to make explicit conversion between unrelated types, relying on a fallback when the conversion fails.
 
-* a generic __mat function returning a `assignable_to` wrapper which replace assignments by a calls to __assign_to. 
-* a generic __mcf function returning a `convertible_from` wrapper which replace the implicit conversion operators by a calls to __implicit_convert_to.
+* a generic __mat function returning a `assignable_to` wrapper which implements assignment by a calls to __assign_to. 
+* a generic __mcf function returning a `convertible_from` wrapper which implements the implicit conversion operators by calls to __implicit_convert_to.
 * a __convertible_to wrapper that acts as a implicit converter when passing parameters to a function.
 
 [/* a generic `convert_to_via` function which convert a type `From` to another `To` using a temporary one `Via`.]
@@ -434,7 +434,7 @@
 [section Using extrinsic conversions and assignments]
 [/====================================]
 
-When you need to make a extrinsic explicit conversion you need to include the file `boost/conversion/convert_to.hpp` and just use the __convert_to function.
+When you need to make a extrinsic explicit conversion, simply include the file `boost/conversion/convert_to.hpp` and use the __convert_to function.
 
 [EVEN_CPP]
 
@@ -448,16 +448,16 @@
 
   return Target(source);
 
-When the extrinsic conversion must be stored in a variable you could use __assign_to instead. 
-By default __assign_to(target,source) calls to the assignment operator if `is_assignable<Target,Source>`, 
+When the extrinsic conversion must be stored in a variable you can use __assign_to instead. 
+By default if the trait `is_assignable<Target,Source>` returns true, __assign_to(target,source) calls the assignment operator, 
 
   target=source;
 
-otherwise it do 
+otherwise it does
 
   target=convert_to<Target>(source);
 
-when `Source` is extrinsic convertible to `Target`.
+when `Source` is extrinsically convertible to `Target`.
 
 For example we can implement a function that swaps two convertible types as follows:
 
@@ -471,7 +471,7 @@
   x= 3
 
 [note 
-The name __convert_to could also be convert and __assign_to be assign, but I find them more coherent with the other names used by the library. If the Boost community agree on better names globally I will adopt them. 
+The name __convert_to could also be `convert` and __assign_to `assign`, but I find the current names more coherent with the other names used by the library. If the Boost community agree on better names globally I will adopt them. 
 ]
 
 ['See the source file [@../../example/swap.cpp example/swap.cpp]]
@@ -517,18 +517,18 @@
     std::pair<int,int> pint(0,1);
     std::pair<double,double> pdouble=convert_to<std::pair<double,double> >(pint);
 
-Do not forget to include these files when you use a generic class or algorithm using the generic __convert_to or __assign_to, otherwise your program should not compile. E.g. if you want to convert a pair of `chrono::time_point<>` to a pair of `posix_time::ptime` do not forget to include in addition to the `boost/conversion/std/pair.hpp` the file `boost/conversion/boost/chrono_posix_time.hpp`
+Do not forget to include these files when you use a generic class or algorithm using the generic __convert_to or __assign_to, otherwise your program will not compile. E.g. if you want to convert a pair of `chrono::time_point<>` to a pair of `posix_time::ptime` do not forget to include both `boost/conversion/std/pair.hpp` and `boost/conversion/boost/chrono_posix_time.hpp`
 
 [endsect]
 
-[section Handling with invalid conversions]
+[section Handling invalid conversions]
 [/====================================]
 
 The expected behavior of __convert_to is to throw an exception when the conversion is not possible. If an action must be taken on failure we need to use a try-catch
 
 [NO_THROW_CPP_TRY_CATCH_WAY]
 
-Sometimes the user could prefer a no-throw behavior. The library provides another way to get the same with the __try_convert_to function which returns an optional initialized when the conversion succeeds. 
+Sometimes the user could prefer no-throw behavior. The library provides a way to get this behavior with the __try_convert_to function, which returns an optional initialized when the conversion succeeds. 
 
 [NO_THROW_CPP_TRY_CONVERT_WAY]
 
@@ -545,7 +545,7 @@
 
 [endsect]
 
-[section Handling with invalid conversions via a fallback]
+[section Handling invalid conversions via a fallback]
 [/====================================]
 
 In some cases the conversion failure can be ignored and the result replaced with a fallback value. There are some ways to manage with that