Boost logo

Boost-Commit :

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]


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