|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r67507 - in sandbox/tti: boost/tti libs/tti/doc
From: eldiener_at_[hidden]
Date: 2010-12-30 16:54:51
Author: eldiener
Date: 2010-12-30 16:54:36 EST (Thu, 30 Dec 2010)
New Revision: 67507
URL: http://svn.boost.org/trac/boost/changeset/67507
Log:
Added documentation and support for tti::has_template
Added:
sandbox/tti/boost/tti/TTIntrospectionTemplate.hpp (contents, props changed)
sandbox/tti/libs/tti/doc/TTIMetafunctions.qbk (contents, props changed)
sandbox/tti/libs/tti/doc/TTINestedType.qbk (contents, props changed)
Text files modified:
sandbox/tti/boost/tti/TTIntrospection.hpp | 91 ++++++++++++++-------------
sandbox/tti/boost/tti/TTIntrospectionVM.hpp | 4
sandbox/tti/libs/tti/doc/Jamfile.v2 | 1
sandbox/tti/libs/tti/doc/TTIDetail.qbk | 129 ++++++++++++++++++++++++++++++++++++++++
sandbox/tti/libs/tti/doc/TTIFunctionality.qbk | 46 +++++++-------
sandbox/tti/libs/tti/doc/TTIIntroduction.qbk | 10 +-
sandbox/tti/libs/tti/doc/TTITerminology.qbk | 8 +-
sandbox/tti/libs/tti/doc/TypeTraitsIntrospection.qbk | 2
8 files changed, 213 insertions(+), 78 deletions(-)
Modified: sandbox/tti/boost/tti/TTIntrospection.hpp
==============================================================================
--- sandbox/tti/boost/tti/TTIntrospection.hpp (original)
+++ sandbox/tti/boost/tti/TTIntrospection.hpp 2010-12-30 16:54:36 EST (Thu, 30 Dec 2010)
@@ -20,6 +20,7 @@
#include <boost/type_traits/detail/yes_no_type.hpp>
#include <boost/type_traits/is_same.hpp>
#include <boost/type_traits/remove_const.hpp>
+#include "TTIntrospectionTemplate.hpp"
#include "detail/TTIntrospectionDetail.hpp"
/*
@@ -720,12 +721,12 @@
/// A metafunction which checks whether a type exists within an enclosing type.
/**
- This metafunction takes all its types as metafunctions whose typedef 'type' member is the actual type used.
+ This metafunction takes all its types as nullary metafunctions whose typedef 'type' member is the actual type used.
The metafunction types and return:
HasType = Template class generated from the TTI_HAS_TYPE ( or TTI_TRAIT_HAS_TYPE ) macro.<br />
- T = The enclosing type as a metafunction.
+ T = The enclosing type as a nullary metafunction.
returns = 'value' is true if the type exists within the enclosing type,
otherwise 'value' is false.
@@ -750,12 +751,12 @@
/// A metafunction whose typedef 'type' is either the internal type or an unspecified type.
/**
- This metafunction takes all its types as metafunctions whose typedef 'type' member is the actual type used.
+ This metafunction takes all its types as nullary metafunctions whose typedef 'type' member is the actual type used.
The metafunction types and return:
MemberType = Template class generated from the TTI_MEMBER_TYPE ( or TTI_TRAIT_MEMBER_TYPE ) macro.<br />
- T = The enclosing type as a metafunction.
+ T = The enclosing type as a nullary metafunction.
returns = 'type' is the inner type of the 'name' in TTI_MEMBER_TYPE ( or TTI_TRAIT_MEMBER_TYPE )
if the inner type exists within the enclosing type,
@@ -782,17 +783,44 @@
{
};
+/// A metafunction which checks whether a type of a particular signature exists within an enclosing type.
+/**
+
+ This metafunction takes all its types as nullary metafunctions whose typedef 'type' member is the actual type used.
+
+ The metafunction types and return:
+
+ HasTypeCheckTypedef = Template class generated from the TTI_HAS_TYPE_CHECK_TYPEDEF ( or TTI_TRAIT_HAS_TYPE_CHECK_TYPEDEF ) macro.<br />
+ T = The enclosing type as a nullary metafunction.<br />
+ U = The type of the enclosed type as a nullary metafunction.
+
+ returns = 'value' is true if the type exists within the enclosing type,
+ with the correct type signature,
+ otherwise 'value' is false.
+
+*/
+ template
+ <
+ template<class,class> class HasTypeCheckTypedef,
+ class T,
+ class U
+ >
+ struct mf_has_type_check_typedef :
+ public mf_has_static_data<HasTypeCheckTypedef,T,U>
+ {
+ };
+
/// A metafunction which checks whether a member function exists within an enclosing type.
/**
- This metafunction takes all its types as metafunctions whose typedef 'type' member is the actual type used.
+ This metafunction takes all its types as nullary metafunctions whose typedef 'type' member is the actual type used.
The metafunction types and return:
HasMember = Template class generated from the TTI_HAS_MEMBER ( or TTI_TRAIT_HAS_MEMBER ) macro.<br />
- T = The enclosing type as a metafunction.<br />
- R = The return type of the member function as a metafunction.<br />
- P... = The parameter types of the member function, each as a metafunction.<br />
+ T = The enclosing type as a nullary metafunction.<br />
+ R = The return type of the member function as a nullary metafunction.<br />
+ P... = The parameter types of the member function, each as a nullary metafunction.<br />
There can be up to TTI_MAX_PARAMETERS number of parameters. The default is 10.
returns = 'value' is true if the member function exists within the enclosing type,
@@ -828,13 +856,13 @@
/// A metafunction which checks whether a member data exists within an enclosing type.
/**
- This metafunction takes all its types as metafunctions whose typedef 'type' member is the actual type used.
+ This metafunction takes all its types as nullary metafunctions whose typedef 'type' member is the actual type used.
The metafunction types and return:
HasMember = Template class generated from the TTI_HAS_MEMBER ( or TTI_TRAIT_HAS_MEMBER ) macro.<br />
- T = The enclosing type as a metafunction.<br />
- R = The type of the member data as a metafunction.
+ T = The enclosing type as a nullary metafunction.<br />
+ R = The type of the member data as a nullary metafunction.
returns = 'value' is true if the member data exists within the enclosing type,
otherwise 'value' is false.
@@ -867,14 +895,14 @@
/// A metafunction which checks whether a static member function exists within an enclosing type.
/**
- This metafunction takes all its types as metafunctions whose typedef 'type' member is the actual type used.
+ This metafunction takes all its types as nullary metafunctions whose typedef 'type' member is the actual type used.
The metafunction types and return:
HasStatic Member = Template class generated from the TTI_HAS_STATIC_MEMBER ( or TTI_TRAIT_HAS_STATIC_MEMBER ) macro.<br />
- T = The enclosing type as a metafunction.<br />
- R = The return type of the static member function as a metafunction.<br />
- P... = The parameter types of the static member function, each as a metafunction.<br />
+ T = The enclosing type as a nullary metafunction.<br />
+ R = The return type of the static member function as a nullary metafunction.<br />
+ P... = The parameter types of the static member function, each as a nullary metafunction.<br />
There can be up to TTI_MAX_PARAMETERS number of parameters. The default is 10.
returns = 'value' is true if the static member function exists within the enclosing type,
@@ -910,13 +938,13 @@
/// A metafunction which checks whether a static member data exists within an enclosing type.
/**
- This metafunction takes all its types as metafunctions whose typedef 'type' member is the actual type used.
+ This metafunction takes all its types as nullary metafunctions whose typedef 'type' member is the actual type used.
The metafunction types and return:
HasStaticMember = Template class generated from the TTI_HAS_STATIC_MEMBER ( or TTI_TRAIT_HAS_STATIC_MEMBER ) macro.<br />
- T = The enclosing type as a metafunction.<br />
- R = The type of the static member data as a metafunction.
+ T = The enclosing type as a nullary metafunction.<br />
+ R = The type of the static member data as a nullary metafunction.
returns = 'value' is true if the member data exists within the enclosing type,
otherwise 'value' is false.
@@ -940,33 +968,6 @@
{
};
-/// A metafunction which checks whether a type of a particular signature exists within an enclosing type.
-/**
-
- This metafunction takes all its types as metafunctions whose typedef 'type' member is the actual type used.
-
- The metafunction types and return:
-
- HasTypeCheckTypedef = Template class generated from the TTI_HAS_TYPE_CHECK_TYPEDEF ( or TTI_TRAIT_HAS_TYPE_CHECK_TYPEDEF ) macro.<br />
- T = The enclosing type as a metafunction.<br />
- U = The type of the enclosed type as a metafunction.
-
- returns = 'value' is true if the type exists within the enclosing type,
- with the correct type signature,
- otherwise 'value' is false.
-
-*/
- template
- <
- template<class,class> class HasTypeCheckTypedef,
- class T,
- class U
- >
- struct mf_has_type_check_typedef :
- public mf_has_static_data<HasTypeCheckTypedef,T,U>
- {
- };
-
}
#endif // TT_INTROSPECTION_HPP
Added: sandbox/tti/boost/tti/TTIntrospectionTemplate.hpp
==============================================================================
--- (empty file)
+++ sandbox/tti/boost/tti/TTIntrospectionTemplate.hpp 2010-12-30 16:54:36 EST (Thu, 30 Dec 2010)
@@ -0,0 +1,52 @@
+#if !defined(TT_INTROSPECTION_TEMPLATE_HPP)
+#define TT_INTROSPECTION_TEMPLATE_HPP
+
+#include "detail/TTIntrospectionDetail.hpp"
+
+/*
+
+ The succeeding comments in this file are in doxygen format.
+
+*/
+
+/** \file
+*/
+
+namespace tti
+ {
+
+/// A metafunction which checks whether a class template exists within an enclosing type.
+/**
+
+ This metafunction takes all its types as nullary metafunctions whose typedef 'type' member is the actual type used.
+
+ The metafunction types and return:
+
+ HasTemplate = Template class generated from either TTI_HAS_TEMPLATE ( or TTI_TRAIT_HAS_TEMPLATE )
+ or TTI_HAS_TEMPLATE_CHECK_PARAMS ( or TTI_TRAIT_HAS_TEMPLATE_CHECK_PARAMS )
+ or TTI_VM_HAS_TEMPLATE_CHECK_PARAMS ( or TTI_VM_TRAIT_HAS_TEMPLATE_CHECK_PARAMS ) macros.<br />
+ T = The enclosing type as a nullary metafunction.
+
+ returns = 'value' is true if the template exists within the enclosing type,
+ otherwise 'value' is false.
+
+*/
+ template
+ <
+ template<class> class HasTemplate,
+ class T
+ >
+ struct mf_has_template :
+ tti::detail::eval
+ <
+ HasTemplate
+ <
+ T
+ >
+ >
+ {
+ };
+
+ }
+
+#endif // TT_INTROSPECTION_TEMPLATE_HPP
Modified: sandbox/tti/boost/tti/TTIntrospectionVM.hpp
==============================================================================
--- sandbox/tti/boost/tti/TTIntrospectionVM.hpp (original)
+++ sandbox/tti/boost/tti/TTIntrospectionVM.hpp 2010-12-30 16:54:36 EST (Thu, 30 Dec 2010)
@@ -3,9 +3,11 @@
#include <boost/config.hpp>
#include <boost/mpl/has_xxx.hpp>
-#include <boost/preprocessor/cat.hpp>
+#include <boost/mpl/identity.hpp>
#include <boost/preprocessor/arithmetic/add.hpp>
+#include <boost/preprocessor/cat.hpp>
#include <boost/variadic_macro_data/VariadicMacroData.hpp>
+#include "TTIntrospectionTemplate.hpp"
#include "detail/TTIntrospectionDetail.hpp"
/*
Modified: sandbox/tti/libs/tti/doc/Jamfile.v2
==============================================================================
--- sandbox/tti/libs/tti/doc/Jamfile.v2 (original)
+++ sandbox/tti/libs/tti/doc/Jamfile.v2 2010-12-30 16:54:36 EST (Thu, 30 Dec 2010)
@@ -15,6 +15,7 @@
:
$(here)/../../../boost/tti/TTIntrospection.hpp
$(here)/../../../boost/tti/TTIntrospectionVM.hpp
+ $(here)/../../../boost/tti/TTIntrospectionTemplate.hpp
:
<doxygen:param>PROJECT_NAME="TTI"
<doxygen:param>PROJECT_NUMBER=1
Modified: sandbox/tti/libs/tti/doc/TTIDetail.qbk
==============================================================================
--- sandbox/tti/libs/tti/doc/TTIDetail.qbk (original)
+++ sandbox/tti/libs/tti/doc/TTIDetail.qbk 2010-12-30 16:54:36 EST (Thu, 30 Dec 2010)
@@ -1,3 +1,132 @@
[section:tti_detail Macros]
+The TTI library uses macros to create metafunctions, in the top-level tti namespace,
+for introspecting an inner element by name. Each macro for a particular type of inner
+element has two forms, the simple one where the first macro parameter designating the
+'name' of the inner element is used to create the name of the metafunction, and the
+slightly more complicated one where the first macro parameter, called 'trait', designates
+the name of the metafunction and the second macro parameter designates the 'name' to be queried.
+Other than that difference, the two forms of the macro produce the exact same results.
+All of the querying macros create a metafunction whose boolean 'value' specifies
+whether or not the inner element exists.
+
+A table of these macros is given, with the inner element whose
+existence the metaprogrammer is querying. A more detailed explanation can be found
+in the reference section. In the Template column only the name generated by the simple form
+of the template is given since the name generated by the more complicated form is always tti::trait
+where 'trait' is the first parameter to the corresponding macro.
+
+[table:tbmacros TTI Macros
+ [
+ [Inner Element]
+ [Macro]
+ [Template]
+ ]
+ [
+ [Type]
+ [
+ TTI\_HAS\_TYPE(name)[br]
+ TTI\_TRAIT\_HAS\_TYPE(trait,name)
+ ]
+ [
+ tti::has\_type\_'name'[br]
+ class T = enclosing type
+ ]
+ ]
+ [
+ [Type with check]
+ [
+ TTI\_HAS\_TYPE\_CHECK\_TYPEDEF(name)[br]
+ TTI\_TRAIT\_HAS\_TYPE\_CHECK\_TYPEDEF(trait,name)
+ ]
+ [
+ tti::has\_type\_check\_typedef\_'name'[br]
+ class T = enclosing type,class U = type to check against
+ ]
+ ]
+ [
+ [Class Template]
+ [
+ TTI\_HAS\_TEMPLATE(name)[br]
+ TTI\_TRAIT\_HAS\_TEMPLATE(trait,name)
+ ]
+ [
+ tti::has\_template\_'name'[br]
+ class T = enclosing type
+ ]
+ ]
+ [
+ [Class Template with params]
+ [
+ TTI\_HAS\_TEMPLATE\_CHECK\_PARAMS(name,ppSeq[footnote A Boost PP data sequence with each comma separated portion of the template parameters as its own sequence element.])[br]
+ TTI\_TRAIT\_HAS\_TEMPLATE\_CHECK\_PARAMS(trait,name,ppSeq)
+ ]
+ [
+ tti::has\_template\_check\_params\_'name'[br]
+ class T = enclosing type
+ ]
+ ]
+ [
+ [Class Template with params using variadic macros[footnote Header file is TTIntrospectionVM.hpp.]]
+ [
+ TTI\_VM\_HAS\_TEMPLATE\_CHECK\_PARAMS(name,...[footnote The template parameters as variadic data.])[br]
+ TTI\_VM\_TRAIT\_HAS\_TEMPLATE\_CHECK\_PARAMS(trait,name,...)
+ ]
+ [
+ tti::has\_template\_check\_params\_'name'[br]
+ class T = enclosing type
+ ]
+ ]
+ [
+ [Data or function member]
+ [
+ TTI\_HAS\_MEMBER(name)[br]
+ TTI\_TRAIT\_HAS\_MEMBER(trait,name)
+ ]
+ [
+ tti::has\_member\_'name'[br]
+ class T = pointer to data or function member
+ ]
+ ]
+ [
+ [Static data or static function member]
+ [
+ TTI\_HAS\_STATIC\_MEMBER(name)[br]
+ TTI\_TRAIT\_HAS\_STATIC\_MEMBER(trait,name)
+ ]
+ [
+ tti::has\_static\_member\_'name'[br]
+ class T = enclosing type,class Type = data or function type
+ ]
+ ]
+]
+
+There is one other macro which creates a metafunction which does not query
+for the existence of an inner element type, but is very useful nonetheless.
+Instead the metafunction created returns the nested type if it exists, else
+it returns an unspecified type.
+
+[table:tbmacronested TTI Nested Type Macro
+ [
+ [Inner Element]
+ [Macro]
+ [Template]
+ ]
+ [
+ [Type]
+ [
+ TTI\_MEMBER\_TYPE(name)[br]
+ TTI\_TRAIT\_MEMBER\_TYPE(trait,name)
+ ]
+ [
+ tti::member\_type\_'name'[br]
+ class T = enclosing type
+ ]
+ ]
+]
+
+The usefulness of this macro, and its corresponding metafunction, will be shown
+in the next section when I explain the problem of nested types and how TTI solves
+it.
+
[endsect]
Modified: sandbox/tti/libs/tti/doc/TTIFunctionality.qbk
==============================================================================
--- sandbox/tti/libs/tti/doc/TTIFunctionality.qbk (original)
+++ sandbox/tti/libs/tti/doc/TTIFunctionality.qbk 2010-12-30 16:54:36 EST (Thu, 30 Dec 2010)
@@ -7,10 +7,10 @@
# Does it have a nested type with a particular name which is a typedef for a particular type ?
# Does it have a nested class template with a particular name ?
# Does it have a nested class template with a particular name and a particular signature ?
-# Does it have a function member with a particular name and a particular signature ?
-# Does it have a data member with a particular name and of a particular type ?
-# Does it have a static function member with a particular name and a particular signature ?
-# Does it have a static data member with a particular name and of a particular type ?
+# Does it have a member function with a particular name and a particular signature ?
+# Does it have a member data with a particular name and of a particular type ?
+# Does it have a static member function with a particular name and a particular signature ?
+# Does it have a static member data with a particular name and of a particular type ?
These are the compile-time questions which the TTI library answers.
@@ -18,33 +18,33 @@
a particular name. In order to do this using template metaprogramming, macros are used
so that the name of the inner element can be passed to the macro. The macro will then
generate an appropriate metafunction, which the template metaprogrammer can then use to
-query the information that is needed. The name itself is always passed to the macro as a
-macro parameter, but other macro parameters may be needed also in some cases.
+query the information that is needed. The name itself of the inner element is always passed
+to the macro as a macro parameter, but other macro parameters may be needed also in some cases.
All of the macros start with the prefix TTI_, create their metafunctions in the top-level
tti namespace, and come in two forms:
-# In the simplest form the 'name' is used directly to generate the name of the metafunction.
- The 'name' is appended to the name of the macro, with the TTI_ prefix removed, a final
- underscore added, and the macro part of the name in lower case. As an example, for the macro
- TTI_HAS_TYPE(MyType) the name of the metafunction is 'tti::has_type_MyType' and it will look
- for an inner type called 'MyType'.
+# In the simplest form the 'name' of the inner element is used directly to generate the name
+ of the metafunction as well as serving as the 'name' to introspect. The 'name' is appended
+ to the name of the macro, with the TTI_ prefix removed, a final underscore added, and the
+ macro part of the name in lower case. As an example, for the macro TTI_HAS_TYPE(MyType) the
+ name of the metafunction is 'tti::has_type_MyType' and it will look for an inner type
+ called 'MyType'.
# In the slightly more complicated form the macro starts with TTI\_TRAIT\_ and a 'trait' name is
- passed as the first parameter, with the 'name' as the second parameter. The 'trait' serves
- only to completely name the metafunction in the tti namespace. As an example, for the macro
- TTI_TRAIT_HAS_TYPE(MyTrait,MyType) the name of the metafunction is 'tti::MyTrait' and it will
+ passed as the first parameter, with the 'name' of the inner element as the second parameter.
+ The 'trait' serves only to completely name the metafunction in the tti namespace. As an example,
+ for the macro TTI_TRAIT_HAS_TYPE(MyTrait,MyType) the name of the metafunction is 'tti::MyTrait' and it will
look for an inner type called 'MyType'.
-It is imporant to realize two things. First that any given metafunction generated, when introspecting
-a particular inner element, can be reused for any combination of template parameters which involve the
-same type of inner element. Second that once a metafunction is generated, attempting to generate another
-metafunction of the same name will create ODR violations since two C++ constructs with the same name/type
-in the same namespace will have been created. This second possibility has much less chance of occurence
-if you use the simple form of each macro and just reuse the metafunction if you are querying for two
-entities of the same name in different enclosing types or possibly in the same enclosing type but with
-different signatures.
+[important Any given metafunction generated, when introspecting a particular inner element, can be reused
+for any combination of template parameters which involve the same type of inner element. Once a metafunction
+is generated, attempting to generate another metafunction of the same name will create ODR violations since
+two C++ constructs with the same name/type in the same namespace will have been created. This latter
+possibility has much less chance of occurence if you use the simple form of each macro and just reuse
+the metafunction if you are querying for two entities of the same name in different enclosing types, or in
+the same enclosing type but with different signatures.]
-[section:tti_reason Reason for Library]
+[section:tti_reason Why the TTI Library ?]
In the Boost Type Traits library there is compile time functionality for
querying information about a C++ type. This information is very useful
Modified: sandbox/tti/libs/tti/doc/TTIIntroduction.qbk
==============================================================================
--- sandbox/tti/libs/tti/doc/TTIIntroduction.qbk (original)
+++ sandbox/tti/libs/tti/doc/TTIIntroduction.qbk 2010-12-30 16:54:36 EST (Thu, 30 Dec 2010)
@@ -9,8 +9,8 @@
The name of the library is chosen because the library offers
compile time functionality on a type, as does the Boost Type Traits library,
-and because the functionality the library offers is the ability to introspect,
-or query, a type about the existence of a specific element.
+and because the functionality the library offers is the ability to introspect
+a type about the existence of a specific element.
I use the word "introspect" in a very broad sense here. Normally language
introspection means asking for information to be initially returned by name.
@@ -25,14 +25,14 @@
subsequently invoked to determine whether or not the
element exists within the type.
# Provide corresponding metafunctions which can operate
- on each of the metafunctions generated by the set of
- macros. These secondary metafunctions provide
+ on each of the macro metafunctions generated.
+ These secondary metafunctions provide
the same set of introspection as the primary ones but
allow nested types, which do not actually have to exist,
to be passed in template parameters without producing
a compiler error.
-The library is a header only library.
+The library is a header only library.
There are two separate headers in the library,
divided depending on whether or not the library
Added: sandbox/tti/libs/tti/doc/TTIMetafunctions.qbk
==============================================================================
--- (empty file)
+++ sandbox/tti/libs/tti/doc/TTIMetafunctions.qbk 2010-12-30 16:54:36 EST (Thu, 30 Dec 2010)
@@ -0,0 +1,101 @@
+[section:tti_metafunctions Metafunctions]
+
+A table of these metafunctions is given, based on the inner element whose
+existence the metaprogrammer is querying. A more detailed explanation can be found
+in the reference section. All of the metafunctions are in the tti top-level namespace,
+all have a particular name, and all begin with the prefix 'mf_' so as not to conflict with
+the macro metafunctions in the library.
+
+[table:tbmetafunctions TTI Metafunctions
+ [
+ [Inner Element]
+ [Template]
+ [Parameters]
+ [Macro Equivalent]
+ ]
+ [
+ [Type]
+ [tti::mf_has_type]
+ [
+ template<class> class HasType = generated macro metafunction[br]
+ class T = enclosing type nullary metafunction
+ ]
+ [TTI_HAS_TYPE (TTI_TRAIT_HAS_TYPE)]
+ ]
+ [
+ [Type with check]
+ [tti::mf_has_type_check_typedef]
+ [
+ template<class,class> class HasTypeCheckTypedef = generated macro metafunction[br]
+ class T = enclosing type nullary metafunction[br]
+ class U = type to check against nullary metafunction
+ ]
+ [TTI_HAS_TYPE_CHECK_TYPEDEF (TTI_TRAIT_HAS_TYPE_CHECK_TYPEDEF)]
+ ]
+ [
+ [Member data]
+ [tti::mf_has_member_data]
+ [
+ template<class> class HasMember = generated macro metafunction[br]
+ class T = enclosing type nullary metafunction[br]
+ class R = type of member data nullary Metafunction
+ ]
+ [TTI_HAS_MEMBER (TTI_TRAIT_HAS_MEMBER)]
+ ]
+ [
+ [Member function]
+ [tti::mf_has_member_function]
+ [
+ template<class> class HasMember = generated macro metafunction[br]
+ class T = enclosing type nullary metafunction[br]
+ class R = return value nullary metafunction[br]
+ class Types... = parameter types as nullary metafunctions
+ ]
+ [TTI_HAS_MEMBER (TTI_TRAIT_HAS_MEMBER)]
+ ]
+ [
+ [Static data]
+ [tti::mf_has_static_data]
+ [
+ template<class,class> class HasStaticMember = generated macro metafunction[br]
+ class T = enclosing type nullary metafunction[br]
+ class R = type of static data nullary metafunction
+ ]
+ [TTI_HAS_STATIC_MEMBER (TTI_TRAIT_HAS_STATIC_MEMBER)]
+ ]
+ [
+ [Static function]
+ [tti::mf_has_static_function]
+ [
+ template<class,class> class HasStaticMember = generated macro metafunction[br]
+ class T = enclosing type nullary metafunction[br]
+ class R = return value nullary metafunction[br]
+ class Types... = parameter types as nullary metafunctions
+ ]
+ [TTI_HAS_STATIC_MEMBER (TTI_TRAIT_HAS_STATIC_MEMBER)]
+ ]
+]
+
+Just as there is the macro TTI_MEMBER_TYPE (TTI_TRAIT_MEMBER_TYPE) for creating
+a macro metafunction which returns a nested type if it exists, else an unspecified
+type, there is also the equivalent metafunction.
+
+[table:tbmetanested TTI Nested Type Metafunction
+ [
+ [Inner Element]
+ [Template]
+ [Parameters]
+ [Macro Equivalent]
+ ]
+ [
+ [Type]
+ [tti::mf_member_type]
+ [
+ template<class> class MemberType = generated macro metafunction[br]
+ class T = enclosing type nullary metafunction
+ ]
+ [TTI_MEMBER_TYPE (TTI_TRAIT_MEMBER_TYPE)]
+ ]
+]
+
+[endsect]
Added: sandbox/tti/libs/tti/doc/TTINestedType.qbk
==============================================================================
--- (empty file)
+++ sandbox/tti/libs/tti/doc/TTINestedType.qbk 2010-12-30 16:54:36 EST (Thu, 30 Dec 2010)
@@ -0,0 +1,71 @@
+[section:tti_nested_type Nested Types]
+
+[heading The Problem]
+
+The goal of the TTI library is never to produce a compiler error by just
+using the functionality in the library, whether it is invoking its function-like macros
+or instantiating the metafunctions created by them. In this sense The TTI library macros
+for querying an enclosing type for an inner element work very well, except in one general case.
+That general case is the crux of the discussion regarding nested types which follows,
+and explains the reason for the separate group of TTI metafunctions which mirror the
+functionality of the macros and their generated metafunctions.
+
+The metafunctions generated by the TTI macros all work with types, whether in specifying
+an enclosing type or in specifying the type of some inner element. The C++ notation for
+a nested type, given an enclosing type 'E' and an inner type 'I', is 'E::I'. If either the
+enclosing type 'E' does not exist, or the inner type 'I' does not exist within 'E', the expression
+'E::I' will give a compiler error if we attempt to use it in our template instantiation
+of one of TTI's macro metafunctions. We want to be able to query for the existence of inner
+elements to an enclosing type without producing compiler errors. Of course if we absolutely
+know what types we have and that a nested type exists we can always use an expression like
+E::I without error, or even E::I::AnotherInnerType as we drill down further into nested types.
+But this is often not the case when doing template programming since the type being
+passed to us at compile-time in a class or function template is chosen at instantiation
+time.
+
+One solution to this is afforded by the library itself. Given an enclosing type 'E'
+which we know must exist, either because it is a top-level type we know about or
+it is passed to us in some template as a 'class E' or 'typename E', and given an inner type
+named 'I' whose existence we would like ascertain, we can use a TTI_HAS_TYPE(I) macro and it's related
+tti::has_type_I metafunction to determine if the nested type 'I' exists. This solution is perfectly valid
+and, with Boost MPL's selection metafunctions, we can do compile-time selection to generate the
+correct template code.
+
+However this does not scale that well syntactically if we need to drill down further from a
+top-level enclosing type to a deeply nested type. We are going to be generating a great deal
+of boost::mpl::if_ and/or boost::mpl::eval_if type selection statements to get to some
+final condition where we know we can generate the compile-time code which we want.
+
+[heading The Solution]
+
+The TTI library offers a better solution in the form of a set of constructs which work with
+nested types without producing a compiler error if the nested type does not exist, but still
+are able to do the querying for inner elements that our TTI macro metafunctions do.
+
+We have already seen one of those constructs, the macro TTI_MEMBER_TYPE
+( and equivalent TTI_TRAIT_MEMBER_TYPE ), which generates a metafunction based on the name
+of an inner type. But instead of telling us whether that inner type exists it instead returns
+a typedef 'type' which is that inner type if it exists, else it is an unspecified type if it
+does not. In this way we have created a metafunction, very similar in functionality to
+boost::mpl::identity, but which still returns some marker 'type' if our nested type is invalid.
+
+The remaining metafunctions in the TTI library use this concept of a nested type which does
+not exist not producing a compiler error to query the same things that our macro metafunctions
+do, but without having to use the notation 'E::I' to express a nested type.
+
+For each of these metafunctions the first class template parameter is its corresponding macro metafunction
+template and the remaining parameter are 'types', which always consists first of the enclosing type and then
+possibly other types which make up the signature of whatever inner element we are querying. The most important
+thing to understand about these 'types' is that they are passed in the form of a nullary metafunction
+whose typedef 'type' is the actual type. This lets us pass not only the result of
+TTI_MEMBER_TYPE ( TTI_TRAIT_MEMBER_TYPE ) as one of the 'types', which may not actually exist, but also
+the result of its equivalent metafunction, tti::mf_member_type ( explained later ). For a type not
+generated by either the TTI_MEMBER_TYPE ( TTI_TRAIT_MEMBER_TYPE ) macro metafunction or tti::mf_member_type
+metafunction, and therefore exists in our scope, we can use boost::mpl::identity to create our
+nullary metafunction.
+
+[tip The header file <boost/mpl/identity.hpp> is included by the TTI main header file TTIntrospection.hpp
+so you need not manually include it in order to use boost::mpl::identity to wrap a known type as a nullary
+metafunction for the TTI metafunctions.]
+
+[endsect]
Modified: sandbox/tti/libs/tti/doc/TTITerminology.qbk
==============================================================================
--- sandbox/tti/libs/tti/doc/TTITerminology.qbk (original)
+++ sandbox/tti/libs/tti/doc/TTITerminology.qbk 2010-12-30 16:54:36 EST (Thu, 30 Dec 2010)
@@ -1,16 +1,16 @@
[section:tti_terminology Terminology]
The term "enclosing type" refers to the type which is being introspected.
-This type is always a user-defined class, struct, or union.
+This type is always a class, struct, or union.
The term "inner xxx", where xxx is some element of the enclosing type,
refers to either a type, template, function, or data within the enclosing
-type. The term "inner element" also refers to these entities.
+type. The term "inner element" also refers to any one of these entities in general.
I use the term "nested type" to refer to a type within another type.
-I use the term "function member" or "data member" to refer to non-static
+I use the term "member function" or "member data" to refer to non-static
functions or data that are part of the enclosing type.
-I use the term "static function" or "static data" to refer to static
+I use the term "static member function" or "static member data" to refer to static
functions or data that are part of the enclosing type.
I use the term "class template member" to refer to a class template
nested within the enclosing type.
Modified: sandbox/tti/libs/tti/doc/TypeTraitsIntrospection.qbk
==============================================================================
--- sandbox/tti/libs/tti/doc/TypeTraitsIntrospection.qbk (original)
+++ sandbox/tti/libs/tti/doc/TypeTraitsIntrospection.qbk 2010-12-30 16:54:36 EST (Thu, 30 Dec 2010)
@@ -14,6 +14,8 @@
[include TTITerminology.qbk]
[include TTIFunctionality.qbk]
[include TTIDetail.qbk]
+[include TTINestedType.qbk]
+[include TTIMetafunctions.qbk]
[include TTIReference.qbk]
[include TTIHistory.qbk]
[include TTIAcknowledgements.qbk]
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