From bbd235a4b2e7b1fe1c54ac77d70334d95b0c3500 Mon Sep 17 00:00:00 2001
From: Alexander Nasonov <alnsn@yandex.ru>
Date: Tue, 13 Jun 2006 21:00:06 +0000
Subject: [PATCH] Documentation for promotion traits.

[SVN r34296]
---
 doc/type_traits.qbk | 124 +++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 122 insertions(+), 2 deletions(-)

diff --git a/doc/type_traits.qbk b/doc/type_traits.qbk
index 59d96bb..6fa5f65 100644
--- a/doc/type_traits.qbk
+++ b/doc/type_traits.qbk
@@ -1,7 +1,8 @@
 [library Boost.TypeTraits
-    [copyright 2000 2005 Adobe Systems Inc, David Abrahams, Steve Cleary, 
+    [copyright 2000 2006 Adobe Systems Inc, David Abrahams, Steve Cleary, 
     Beman Dawes, Aleksey Gurtovoy, Howard Hinnant, Jesse Jones, Mat Marcus, 
-    Itay Maman, John Maddock, Thorsten Ottosen, Robert Ramey and Jeremy Siek]
+    Itay Maman, John Maddock, Alexander Nasonov, Thorsten Ottosen,
+    Robert Ramey and Jeremy Siek]
     [purpose Meta-programming support library]
     [license
         Distributed under the Boost Software License, Version 1.0.
@@ -93,6 +94,10 @@
 
 [def __function_traits [link boost_typetraits.function_traits function_traits]]
 
+[def __promote [link boost_typetraits.promote promote]]
+[def __integral_promotion [link boost_typetraits.integral_promotion integral_promotion]]
+[def __floating_point_promotion [link boost_typetraits.floating_point_promotion floating_point_promotion]]
+
 [section:intro Introduction]
 
 The Boost type-traits library contains a 
@@ -617,6 +622,15 @@ result of applying the transformation to the template argument `T`.
    template <class T>
    struct __add_volatile;
 
+   template <class T>
+   struct __floating_point_promotion;
+
+   template <class T>
+   struct __integral_promotion;
+
+   template <class T>
+   struct __promote;
+
    template <class T>
    struct __remove_all_extents;
 
@@ -1017,6 +1031,21 @@ different types
 
 [endsect]
 
+[section:to_double Convert Numeric Types and Enums to double]
+
+Demonstrates a conversion of
+[@../../libs/numeric/conversion/doc/definitions.html#numtypes Numeric Types]
+and enum types to double:
+
+    template<class T>
+    inline double to_double(T const& value)
+    {
+        typedef typename boost::promote<T>::type promoted;
+        return boost::numeric::converter<double,promoted>::convert(value);
+    }
+
+[endsect]
+
 [endsect]
 
 [section:reference Alphabetical Reference]
@@ -1271,6 +1300,36 @@ expression that evaluates to /0/.]
 
 [endsect]
 
+[section:floating_point_promotion floating_point_promotion]
+
+   template <class T>
+   struct floating_point_promotion
+   {
+      typedef __below type;
+   };
+  
+__type If floating point promotion can be applied to an rvalue of type `T`,
+then applies floating point promotion to `T` and keeps cv-qualifiers of `T`,
+otherwise leaves `T` unchanged.
+
+__std_ref 4.6.
+
+__header ` #include <boost/type_traits/floating_point_promotion.hpp>` or ` #include <boost/type_traits.hpp>`
+
+[table Examples
+
+[ [Expression] [Result Type]]
+
+[[`floating_point_promotion<float const>::type`][`double const`]]
+
+[[`floating_point_promotion<float&>::type`][`float&`]]
+
+[[`floating_point_promotion<short>::type`][`short`]]
+
+]
+
+[endsect]
+
 [section:function_traits function_traits]
 [def __argN '''arg<replaceable>N</replaceable>_type''']
 
@@ -1582,6 +1641,36 @@ one of these.
 
 [endsect]
 
+[section:integral_promotion integral_promotion]
+
+   template <class T>
+   struct integral_promotion
+   {
+      typedef __below type;
+   };
+  
+__type If integral promotion can be applied to an rvalue of type `T`, then
+applies integral promotion to `T` and keeps cv-qualifiers of `T`,
+otherwise leaves `T` unchanged.
+
+__std_ref 4.5 except 4.5/3 (integral bit-field).
+
+__header ` #include <boost/type_traits/integral_promotion.hpp>` or ` #include <boost/type_traits.hpp>`
+
+[table Examples
+
+[ [Expression] [Result Type]]
+
+[[`integral_promotion<short const>::type`][`int const`]]
+
+[[`integral_promotion<short&>::type`][`short&`]]
+
+[[`integral_promotion<enum std::float_round_style>::type`][`int`]]
+
+]
+
+[endsect]
+
 [section:is_abstract is_abstract]
    template <class T>
    struct is_abstract : public __tof {};
@@ -2520,6 +2609,37 @@ at the top level in this case.]
 
 [endsect]
 
+[section:promote promote]
+
+   template <class T>
+   struct promote
+   {
+      typedef __below type;
+   };
+  
+__type If integral or floating point promotion can be applied to an rvalue
+of type `T`, then applies integral and floating point promotions to `T` and
+keeps cv-qualifiers of `T`, otherwise leaves `T` unchanged. See also
+__integral_promotion and __floating_point_promotion.
+
+__std_ref 4.5 except 4.5/3 (integral bit-field) and 4.6.
+
+__header ` #include <boost/type_traits/promote.hpp>` or ` #include <boost/type_traits.hpp>`
+
+[table Examples
+
+[ [Expression] [Result Type]]
+
+[[`promote<short volatile>::type`][`int volatile`]]
+
+[[`promote<float const>::type`][`double const`]]
+
+[[`promote<short&>::type`][`short&`]]
+
+]
+
+[endsect]
+
 [section:rank rank]
    template <class T>
    struct rank : public __integral_constant<std::size_t, RANK(T)> {};