tti/doc/tti_functionality.qbk

[section:tti_functionality General Functionality]

The elements about which a template metaprogrammer might be interested in finding 
out at compile time about a type are:

* Does it have a nested type with a particular name ?
* 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 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.

All of the questions above attempt to find an answer about an inner element with 
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 
introspect 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 also be needed in some cases.

All of the macros start with the prefix BOOST\_TTI\_, create their metafunctions in a  
namespace called 'boost::tti', and come in two forms: 

# 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. To generate the name of 
  the metafunction the 'name' is appended to the name of the macro, with the BOOST\_TTI\_ prefix removed, 
  a final underscore added, and the macro part of the name in lower case. As an example, for the 
  macro BOOST\_TTI\_HAS\_TYPE(MyType) the name of the metafunction is 'boost::tti::has_type_MyType' and it will 
  look for an inner type called 'MyType'.
# In the slightly more complicated form, which I call the complex form, the macro starts with 
  BOOST\_TTI\_TRAIT\_ and a 'trait' name is passed as the first parameter, with the 'name' of the inner 
  element as the second parameter. The 'trait' name serves only to completely name the metafunction in 
  the boost::tti namespace. As an example, for the macro BOOST\_TTI\_TRAIT\_HAS\_TYPE(MyTrait,MyType) the name of 
  the metafunction is 'boost::tti::MyTrait' and it will look for an inner type called 'MyType'. Every
  macro has a corresponding complex form.
  
[important When introspecting a particular inner element any given macro metafunction generated 
can be reused with any combination of template parameters which involve the same type of inner element. 
Furthermore once a macro metafunction is generated, attempting to generate another macro 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 macro metafunction. You can even do this if you are introspecting for two 
entities of the same name in different enclosing types, or in the same enclosing type but with different 
signatures, as with overloaded member functions.]
  
Once either of these two macro forms are used for a particular type of inner element, the 
corresponding macro metafunction has the exact same functionality. 

In the succeeding documentation all macro metafunctions will be referred by their simple form 
name, but remember that the complex form name can always alternatively be used.
  
[endsect]