[Boost-commit] svn:boost r81717 - trunk/libs/tti/doc

Subject: [Boost-commit] svn:boost r81717 - trunk/libs/tti/doc
From: eldiener_at_[hidden]
Date: 2012-12-05 00:03:36

Author: eldiener
Date: 2012-12-05 00:03:35 EST (Wed, 05 Dec 2012)
New Revision: 81717
URL: http://svn.boost.org/trac/boost/changeset/81717

Log:
Updated has type documentation.
Text files modified: 
   trunk/libs/tti/doc/tti_detail.qbk          |    88 ++++++++++++++--------------            
   trunk/libs/tti/doc/tti_detail_has_type.qbk |   121 +++++++++++++++++++++++++++++++-------- 
   2 files changed, 140 insertions(+), 69 deletions(-)

Modified: trunk/libs/tti/doc/tti_detail.qbk
==============================================================================
--- trunk/libs/tti/doc/tti_detail.qbk	(original)
+++ trunk/libs/tti/doc/tti_detail.qbk	2012-12-05 00:03:35 EST (Wed, 05 Dec 2012)
@@ -52,21 +52,21 @@
     [
     `has_type_'name'`
     
-    class T = enclosing type
+    class TTI_T = enclosing type
     ]
     [[headerref boost/tti/has_type.hpp `has_type.hpp`]]
   ]
   [
-    [Type with check]
+    [Type with lambda expression]
     [
     [macroref BOOST_TTI_HAS_TYPE](name)
     ]
     [
     `has_type_'name'`
     
-    class T = enclosing type
+    class TTI_T = enclosing type
     
-    class U = type to check against
+    class TTI_U = lambda expression invoked with the inner type and returning a boolean constant
     ]
     [[headerref boost/tti/has_type.hpp `has_type.hpp`]]
   ]
@@ -78,7 +78,7 @@
     [
     `has_template_'name'`
     
-    class T = enclosing type
+    class TTI_T = enclosing type
     
     All of the template parameters must be template type parameters ( 'class' or 'typename' parameters )
     ]
@@ -92,7 +92,7 @@
     [
     `has_template_'name'`
     
-    class T = enclosing type
+    class TTI_T = enclosing type
     
     All of the template parameters must be template type parameters ( 'class' or 'typename' parameters )
     ]
@@ -106,7 +106,7 @@
     [
     `has_template_'name'`
     
-    class T = enclosing type
+    class TTI_T = enclosing type
     ]
     [[headerref boost/tti/has_template.hpp `has_template.hpp`]]
   ]
@@ -118,7 +118,7 @@
     [
     `has_template_'name'`
     
-    class T = enclosing type
+    class TTI_T = enclosing type
     ]
     [[headerref boost/tti/has_template.hpp `has_template.hpp`]]
   ]
@@ -130,12 +130,12 @@
     [
     `has_member_data_'name'`
     
-    class T = enclosing type 
-                  OR 
-              pointer to member data ( 'MemberData_Type Enclosing_Type::*' )
+    class TTI_T = enclosing type 
+                      OR 
+                  pointer to member data ( 'MemberData_Type Enclosing_Type::*' )
     
-    class R = (optional) data type
-              If the first parameter is the pointer to member data this must not be specified.
+    class TTI_R = (optional) data type
+                  If the first parameter is the pointer to member data this must not be specified.
     ]
     [[headerref boost/tti/has_member_data.hpp `has_member_data.hpp`]]
   ]
@@ -147,22 +147,22 @@
     [
     `has_member_function_'name'`
     
-    class T   = enclosing type 
-                    OR 
-                pointer to member function 
-                ( 'Return_Type Enclosing_Type::* ( Zero or more comma-separated parameter types )' )
-    
-    class R   = (optional) return type if the first parameter is the enclosing type.
-                If the first parameter is the pointer to member function this must not be specified.
-    
-    class FS  = (optional) function parameter types as a Boost MPL forward sequence.
-                If the first parameter is the pointer to member function this must not be specified.
-                If there are no function parameters this does not have to be specified.
-                Defaults to boost::mpl::vector<>.
-    
-    class TAG = (optional) Boost `function_types` tag type.
-                If the first parameter is the pointer to member function this must not be specified.
-                Defaults to `boost::function_types::null_tag`.
+    class TTI_T   = enclosing type 
+                        OR 
+                    pointer to member function 
+                    ( 'Return_Type Enclosing_Type::* ( Zero or more comma-separated parameter types )' )
+    
+    class TTI_R   = (optional) return type if the first parameter is the enclosing type.
+                    If the first parameter is the pointer to member function this must not be specified.
+    
+    class TTI_FS  = (optional) function parameter types as a Boost MPL forward sequence.
+                    If the first parameter is the pointer to member function this must not be specified.
+                    If there are no function parameters this does not have to be specified.
+                    Defaults to boost::mpl::vector<>.
+    
+    class TTI_TAG = (optional) Boost `function_types` tag type.
+                    If the first parameter is the pointer to member function this must not be specified.
+                    Defaults to `boost::function_types::null_tag`.
     ]
     [[headerref boost/tti/has_member_function.hpp `has_member_function.hpp`]]
   ]
@@ -174,9 +174,9 @@
     [
     `has_static_member_data_'name'`
     
-    class T = enclosing type
+    class TTI_T = enclosing type
     
-    class Type = data type
+    class TTI_Type = data type
     ]
     [[headerref boost/tti/has_static_member_data.hpp `has_static_member_data.hpp`]]
   ]
@@ -188,20 +188,20 @@
     [
     `has_static_member_function_'name'`
     
-    class T   = enclosing type
+    class TTI_T   = enclosing type
     
-    class R   = return type 
-                    OR 
-                function type ( 'Return_Type (Zero or more comma-separated parameter types)' )
-    
-    class FS  = (optional) function parameter types as a Boost MPL forward sequence.
-                If the second parameter is the function type this must not be specified.
-                If there are no function parameters, this does not have to be specified.
-                Defaults to boost::mpl::vector<>.
-    
-    class TAG = (optional) Boost `function_types` tag type.
-                If the second parameter is the function type this must not be specified.
-                Defaults to `boost::function_types::null_tag`.
+    class TTI_R   = return type 
+                        OR 
+                    function type ( 'Return_Type (Zero or more comma-separated parameter types)' )
+    
+    class TTI_FS  = (optional) function parameter types as a Boost MPL forward sequence.
+                    If the second parameter is the function type this must not be specified.
+                    If there are no function parameters, this does not have to be specified.
+                    Defaults to boost::mpl::vector<>.
+    
+    class TTI_TAG = (optional) Boost `function_types` tag type.
+                    If the second parameter is the function type this must not be specified.
+                    Defaults to `boost::function_types::null_tag`.
     ]
     [[headerref boost/tti/has_static_member_function.hpp `has_static_member_function.hpp`]]
   ]

Modified: trunk/libs/tti/doc/tti_detail_has_type.qbk
==============================================================================
--- trunk/libs/tti/doc/tti_detail_has_type.qbk	(original)
+++ trunk/libs/tti/doc/tti_detail_has_type.qbk	2012-12-05 00:03:35 EST (Wed, 05 Dec 2012)
@@ -1,5 +1,5 @@
 [/ 
-  (C) Copyright Edward Diener 2011
+  (C) Copyright Edward Diener 2011,2012
   Use, modification and distribution are subject to 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).
@@ -10,27 +10,31 @@
 The TTI macro [macroref BOOST_TTI_HAS_TYPE] introspects
 a nested type of a class.
 
-BOOST_TTI_HAS_TYPE takes a single parameter which is the name of 
+The BOOST_TTI_HAS_TYPE macro takes a single parameter which is the name of 
 an inner type whose existence the programmer wants to check. The 
 macro generates a metafunction called 'has_type_'name_of_inner_type'. 
-The purpose of the macro is to check for the existence by name of an 
-inner type and, optionally, check whether that inner type is equivalent 
-to a particular type. This latter functionality is normally only 
-used to check whether or not the inner type is a typedef for
-another type, since an inner user-defined type declares its
-own type by its name.
-
-The metafunction can be invoked by passing it the enclosing type 
-to introspect. Optionally a second type can be passed to the 
-metafunction, whose purpose is to check that if the inner type 
-exists it is of the same type as this second type.
+
+The main purpose of the generated metafunction is to check for the existence by 
+name of the inner type. The metafunction can also be used to invoke an MPL lambda 
+expression which is passed the inner type. One of the most common usages of the added 
+functionality is to check whether or not the inner type is a typedef for another type.
+
+The metafunction is invoked by passing it the enclosing type 
+to introspect. A second type may be passed to the 
+metafunction, an MPL lambda expression taking the inner type 
+and returning a boolean constant.
 
 The metafunction returns a single type called 'type', which is a 
 boost::mpl::bool_. As a convenience the metafunction 
 returns the value of this type directly as a compile time bool constant 
-called 'value'. This is true or false depending on whether the inner 
-type exists or not and, if a second optional type is passed, whether .
-the second type is the same as the type which exists.
+called 'value'. This value is true or false depending on whether the inner 
+type exists or not. 
+
+If a second optional type is passed, this type must be an MPL lambda expression 
+and the expression will be invoked only if the inner type exists. In that case the 
+metafunction returns true or false depending on whether the lambda expression returns 
+true or false. If the inner type does not exist, the lambda expression, even if 
+specified, is never invoked and the metafunction returns false.
 
 [heading Generating the metafunction]
 
@@ -44,11 +48,11 @@
 [heading Invoking the metafunction]
 
 You invoke the metafunction by instantiating the template with an enclosing 
-type to introspect and, optionally, a type which the inner type must match.
+type to introspect and, optionally, an MPL lambda expression.
 A return value called 'value' is a compile time bool constant.
 
   has_type_AType<Enclosing_Type>::value
-  has_type_AType<Enclosing_Type,Another_Type>::value
+  has_type_AType<Enclosing_Type,ALambdaExpression>::value
   
 [heading Examples]
 
@@ -75,24 +79,85 @@
    };
    
 Finally we invoke our metafunction and return our value.
-This all happens at compile time, and can be used by 
-programmers doing compile time template metaprogramming.
-  
+
  has_type_MyTypeDef<Top>::value;  // true
  has_type_MyTypeDef<Top2>::value; // false
- has_type_MyTypeDef<Top,int>::value; // true
- has_type_MyTypeDef<Top,long>::value; // false
 
  has_type_AType<Top>::value;  // true
  has_type_AType<Top2>::value; // false
  
  has_type_ATypeDef<Top>::value;  // false
  has_type_ATypeDef<Top2>::value; // true
- has_type_ATypeDef<Top2,int>::value; // false
- has_type_ATypeDef<Top2,long>::value; // true
 
  has_type_MyType<Top>::value;  // false
  has_type_MyType<Top2>::value; // true
+ 
+[heading Examples - using lambda expressions]
+
+We can further invoke our metafunction with a second type, 
+which is an MPL lambda expression. 
+
+An MPL lambda expression, an extremely useful technique in 
+template metaprogramming, allows us to pass a metafunction to 
+other metafunctions. The metafunction we pass can be in the form
+of a placeholder expression or a metafunction class. In our case
+the metafunction passed to our has_type_'name_of_inner_type'
+metafunction as a lambda expression must return a boolean constant 
+expression.
+
+[heading Example - using a lambda expression with a placeholder expression]
+
+We will first illustrate the use of a lambda expression in the 
+form of a placeholder expression being passed as the second template
+parameter to our has_type_'name_of_inner_type' metafunction.
+A popular and simple placeholder expression we can use is 
+'boost::is_same<_1,SomeType>' to check if the inner type found is a 
+particular type. This is particularly useful when the inner type 
+is a typedef for some other type.
+
+First we include some more header files and a using declaration
+for convenience.
+
+ #include <boost/mpl/placeholders.hpp
+ #include <boost/type_traits/is_same.hpp
+ using namespace boost::mpl::placeholders;
+
+Next we invoke our metafunction:
+
+ has_type_MyTypeDef<Top,boost::is_same<_1,int> >::value; // true
+ has_type_MyTypeDef<Top,boost::is_same<_1,long> >::value; // false
+
+ has_type_ATypeDef<Top2,boost::is_same<_1,int> >::value; // false
+ has_type_ATypeDef<Top2,boost::is_same<_1,long> >::value; // true
+
+[heading Example - using a lambda expression with a metafunction class]
+
+We will next illustrate the use of a lambda expression in the 
+form of a metafunction class being passed as the second template
+parameter to our has_type_'name_of_inner_type' metafunction.
+
+A metafunction class is a type which has a nested class template
+called 'apply'. For our metafunction class example we will check if the
+inner type is a built-in integer type. First let us write out 
+metafunction class:
+
+ #include <boost/type_traits/is_integral.hpp>
+
+ class OurMetafunctionClass
+   {
+   template<class T> struct apply :
+       boost::is_integral<T>
+       {
+       };
+   };
+   
+Now we can invoke our metafunction:
+
+ has_type_MyTypeDef<Top,OurMetafunctionClass>::value; // true
+ has_type_AType<Top,OurMetafunctionClass>::value; // false
+
+ has_type_ATypeDef<Top2,OurMetafunctionClass>::value; // true
+ has_type_MyType<Top2,OurMetafunctionClass>::value; // true
 
 [heading Metafunction re-use]
 
@@ -105,4 +170,10 @@
 metafunction for introspecting any enclosing type, having 
 any inner type, for that name.
 
+Furthermore since we have only encoded the name of the inner 
+type for which we are introspecting, we can not only introspect
+for that inner type by name but add different lambda expressions 
+to inspect that inner type for whatever we want to find out about 
+it using the same metafunction.
+
 [endsect]