bslmf.h

Go to the documentation of this file.

/// @file bslmf.h
///
///
/// @defgroup bslmf Package bslmf
/// @brief  Basic Standard Library Meta-Functions (bslmf)
/// @addtogroup bsl
/// @{
/// @addtogroup bslmf
/// @{
/// * <a href="#bslmf-purpose"> Purpose</a>
/// * <a href="#bslmf-mnemonic"> Mnemonic </a>
/// * <a href="#bslmf-description"> Description </a>
///   * <a href="#bslmf-hierarchical-synopsis"> Hierarchical Synopsis </a>
///   * <a href="#bslmf-component-synopsis"> Component Synopsis </a>
///
/// # Purpose {#bslmf-purpose}
/// Provide meta-function versions of useful coding constructs.
///
/// # Mnemonic {#bslmf-mnemonic}
/// Basic Standard Library Meta-Functions (bslmf)
///
/// # Description {#bslmf-description}
/// The 'bslmf' package provides meta-function equivalents of certain
/// useful coding constructs.  A meta-function is a template-based, compile-time
/// construct that behaves like a (runtime) function in that it "evaluates"
/// arguments and does something different based on the input it is passed (in the
/// case of templates, the input it is instantiated with).  'bslmf' provides
/// metafunctions to evaluate (at compile time) constructs such as the following:
/// an 'if'-statement equivalent, whether a (template) argument is a fundamental
/// type, whether an argument is an 'enum' type, whether two arguments have the
/// same type, and more.
///
/// The "return value" of that function is generally a compile-time constant under
/// the form of a nested 'enum' 'VALUE', or in some cases a nested 'Type', or
/// both.  For instance, in order to evaluate whether two types are the same, one
/// could write a meta-function predicate (evaluating to 0 or 1) as follows:
/// @code
///  template <class U, class V>
///  struct IsSame {
///      // This 'struct' provides a meta function parameterized by two types 'U'
///      // and 'V', that takes 'VALUE == 0' unless 'U' and 'V' are the same type,
///      // in which case it takes 'VALUE == 1'.
///
///      // PUBLIC TYPES
///      enum { VALUE = 0 };
///      typedef bslmf_MetaInt<VALUE>  Type;
///  };
///
///  // SPECIALIZATIONS
///  template <class T>
///  struct IsSame<T, T> {
///      // This specialization of the 'IsSame' meta function is parameterized by
///      // a single type 'T' and is selected if the two parameters of 'IsSame',
///      // 'U' and 'V', are both equal to 'T'.  It takes 'VALUE == 1'.
///
///      // PUBLIC TYPES
///      enum { VALUE = 1 };
///      typedef bslmf_MetaInt<VALUE>  Type;
///  };
/// @endcode
/// Note the use of a 'bslmf_MetaInt' nested type usually employed for function
/// dispatching.  See the @ref bslmf_issame  component-level documentation for a more
/// thorough usage example.
///
/// Other meta-functions don't have a 'VALUE', but apply some type of
/// transformation (e.g., removing top-level 'const' qualifiers, decaying array
/// and function types to pointer types).  Those usually have a nested 'Type'.
///
/// ## Hierarchical Synopsis {#bslmf-hierarchical-synopsis}
///
/// The 'bslmf' package currently has 100 components having 21 levels of physical
/// dependency.  The list below shows the hierarchical ordering of the components.
/// The order of components within each level is not architecturally significant,
/// just alphabetical.
/// @code
///  21. bslmf_isnothrowswappable
///
///  20. bslmf_isswappable
///      bslmf_unwraprefdecay
///
///  19. bslmf_forwardingreftype
///      bslmf_forwardingtype
///      bslmf_invokeresult
///      bslmf_unwrapreference
///      bslmf_util
///
///  18. bslmf_movableref
///      bslmf_referencewrapper
///
///  17. bslmf_isbitwisemoveable
///      bslmf_iscopyconstructible
///      bslmf_isnothrowmoveconstructible
///
///  16. bslmf_isbitwisecopyable
///
///  15. bslmf_haspointersemantics
///      bslmf_isbitwiseequalitycomparable
///      bslmf_istriviallycopyable
///      bslmf_istriviallydefaultconstructible
///      bslmf_matcharithmetictype
///      bslmf_usesallocatorargt
///
///  14. bslmf_detectnestedtrait
///      bslmf_isenum
///
///  13. bslmf_isaccessiblebaseof
///      bslmf_isconvertibletoany
///      bslmf_nestedtraitdeclaration
///      bslmf_usesallocator
///
///  12. bslmf_isconvertible
///
///  11. bslmf_isfundamental
///
///  10. bslmf_isarithmetic
///
///   9. bslmf_isintegral
///      bslmf_ismemberpointer
///
///   8. bslmf_addcv
///      bslmf_ismemberobjectpointer
///
///   7. bslmf_addconst
///      bslmf_addvolatile
///      bslmf_decay
///      bslmf_isempty
///      bslmf_ismemberfunctionpointer
///      bslmf_ispolymorphic
///      bslmf_removepointer
///
///   6. bslmf_isclass
///      bslmf_isfloatingpoint
///      bslmf_isfunction
///      bslmf_ispointer
///      bslmf_isvoid
///      bslmf_memberfunctionpointertraits
///      bslmf_memberpointertraits
///      bslmf_removecvq
///      bslmf_removecvref
///
///   5. bslmf_addpointer
///      bslmf_addreference
///      bslmf_conjunction
///      bslmf_disjunction
///      bslmf_functionpointertraits
///      bslmf_if                                           !DEPRECATED!
///      bslmf_makeintegersequence
///      bslmf_matchanytype
///      bslmf_metaint                                      !DEPRECATED!
///      bslmf_negation
///      bslmf_removecv
///      bslmf_selecttrait
///
///   4. bslmf_addlvaluereference
///      bslmf_addrvaluereference
///      bslmf_arraytopointer
///      bslmf_conditional
///      bslmf_enableif
///      bslmf_floatingtypestructuraltraits
///      bslmf_integersequence
///      bslmf_isconst
///      bslmf_isreference
///      bslmf_isvolatile
///      bslmf_nthparameter
///      bslmf_removeconst
///      bslmf_removeextent
///      bslmf_removereference
///      bslmf_removevolatile
///      bslmf_resulttype
///      bslmf_switch
///      bslmf_tag
///      bslmf_typeidentity
///      bslmf_typelist
///
///   3. bslmf_assert
///      bslmf_isarray
///      bslmf_islvaluereference
///      bslmf_ispair
///      bslmf_isreferencewrapper
///      bslmf_isrvaluereference
///      bslmf_issame
///      bslmf_istransparentpredicate
///      bslmf_nil
///
///   2. bslmf_allocatorargt
///      bslmf_booleantestable
///      bslmf_containercompatiblerange
///      bslmf_integralconstant
///      bslmf_voidtype
///
///   1. bslmf_conjunction_cpp03                                         !PRIVATE!
///      bslmf_disjunction_cpp03                                         !PRIVATE!
///      bslmf_functionpointertraits_cpp03                               !PRIVATE!
///      bslmf_invokeresult_cpp03                                        !PRIVATE!
///      bslmf_nthparameter_cpp03                                        !PRIVATE!
/// @endcode
///
/// ## Component Synopsis {#bslmf-component-synopsis}
///
///  @ref bslmf_addconst :
///       Provide a meta-function for adding a top-level `const`-qualifier.
/// 
///  @ref bslmf_addcv :
///       Provide a meta-function for adding top-level cv-qualifiers.
/// 
///  @ref bslmf_addlvaluereference :
///       Provide a compile-time type transformation to lvalue reference.
/// 
///  @ref bslmf_addpointer :
///       Provide meta-function to transform a type to pointer to that type.
/// 
///  @ref bslmf_addreference :
///       Provide a meta-function for adding "reference-ness" to a type.
/// 
///  @ref bslmf_addrvaluereference :
///       Provide a compile-time type transformation to rvalue reference.
/// 
///  @ref bslmf_addvolatile :
///       Provide a meta-function for adding a `volatile`-qualifier.
/// 
///  @ref bslmf_allocatorargt :
///       Provide a tag type to precede allocator arguments.
/// 
///  @ref bslmf_arraytopointer :
///       Provide a meta-function to convert array types to pointer types.
/// 
///  @ref bslmf_assert :
///       Provide a compile-time assertion facility.
/// 
///  @ref bslmf_booleantestable :
///       Provide an exposition-only concept `boolean-testable`.
/// 
///  @ref bslmf_conditional :
///       Provide a compile-time conditional type selector.
/// 
///  @ref bslmf_conjunction :
///       Provide the logical conjunction (AND) for type traits.
/// 
///  @ref bslmf_conjunction_cpp03 :                                          !PRIVATE!
///       Provide C++03 implementation for bslmf_conjunction.h
/// 
///  @ref bslmf_containercompatiblerange :
///       Provide a concept for the Standard `container-compatible-range`.
/// 
///  @ref bslmf_decay :
///       Convert a type to the type used for pass-by-value.
/// 
///  @ref bslmf_detectnestedtrait :
///       Provide a facility for defining traits and detecting legacy traits.
/// 
///  @ref bslmf_disjunction :
///       Provide the logical disjunction (OR) for type traits.
/// 
///  @ref bslmf_disjunction_cpp03 :                                          !PRIVATE!
///       Provide C++03 implementation for bslmf_disjunction.h
/// 
///  @ref bslmf_enableif :
///       Provide a utility to set up SFINAE conditions in type deduction.
/// 
///  @ref bslmf_floatingtypestructuraltraits :
///       Provide traits to describe floating point type structure.
/// 
///  @ref bslmf_forwardingreftype :
///       Provide a meta-function for determining a forwarding type.
/// 
///  @ref bslmf_forwardingtype :
///       Provide a meta-function for determining an optimal forwarding type.
/// 
///  @ref bslmf_functionpointertraits :
///       Provide a meta-function for determining function pointer traits.
/// 
///  @ref bslmf_functionpointertraits_cpp03 :                                !PRIVATE!
///       Provide C++03 implementation for bslmf_functionpointertraits.h
/// 
///  @ref bslmf_haspointersemantics :
///       Provide a type trait for pointer semantics.
/// 
///  'bslmf_if':                                            !DEPRECATED!
///       Provide a compile-time `if/else` (conditional) meta-function.
/// 
///  @ref bslmf_integersequence :
///       Provide a template parameter pack of integers.
/// 
///  @ref bslmf_integralconstant :
///       Provide a mapping from integral constants to unique types.
/// 
///  @ref bslmf_invokeresult :
///       Determine the result type of an invocable expression.
/// 
///  @ref bslmf_invokeresult_cpp03 :                                         !PRIVATE!
///       Provide C++03 implementation for bslmf_invokeresult.h
/// 
///  @ref bslmf_isaccessiblebaseof :
///       Provide a compile-time check for derived classes.
/// 
///  @ref bslmf_isarithmetic :
///       Provide a compile-time check for determining arithmetic types.
/// 
///  @ref bslmf_isarray :
///       Provide a compile-time check for array types.
/// 
///  @ref bslmf_isbitwisecopyable :
///       Provide a meta-function for determining bitwise copyable types.
/// 
///  @ref bslmf_isbitwiseequalitycomparable :
///       Provide a type trait for bitwise equality.
/// 
///  @ref bslmf_isbitwisemoveable :
///       Provide a primitive type trait for bitwise moveable classes.
/// 
///  @ref bslmf_isclass :
///       Provide a compile-time check for determining class types.
/// 
///  @ref bslmf_isconst :
///       Provide a compile-time check for `const`-qualified types.
/// 
///  @ref bslmf_isconvertible :
///       Provide a compile-time check for type conversion.
/// 
///  @ref bslmf_isconvertibletoany :
///       Provide a compile-time check for types convertible to any type.
/// 
///  @ref bslmf_iscopyconstructible :
///       Provide a meta-function to report if a type is copy constructible.
/// 
///  @ref bslmf_isempty :
///       Provide a compile-time check for detecting an empty class type.
/// 
///  @ref bslmf_isenum :
///       Provide compile-time check for determining enumerated types.
/// 
///  @ref bslmf_isfloatingpoint :
///       Provide a compile-time check for floating-point types.
/// 
///  @ref bslmf_isfunction :
///       Provide a compile-time check for determining function types.
/// 
///  @ref bslmf_isfundamental :
///       Provide a compile-time check for determining fundamental types.
/// 
///  @ref bslmf_isintegral :
///       Provide a compile-time check for integral types.
/// 
///  @ref bslmf_islvaluereference :
///       Provide a compile-time check for lvalue reference types.
/// 
///  @ref bslmf_ismemberfunctionpointer :
///       Provide a compile-time check for member function pointer types.
/// 
///  @ref bslmf_ismemberobjectpointer :
///       Provide a compile-time check for member object pointer types.
/// 
///  @ref bslmf_ismemberpointer :
///       Provide a compile-time check for non-static member pointer types.
/// 
///  @ref bslmf_isnothrowmoveconstructible :
///       Provide metafunction to identify no-throw move-constructible types.
/// 
///  @ref bslmf_isnothrowswappable :
///       Provide metafunction to identify nothrow swappable types.
/// 
///  @ref bslmf_ispair :
///       Provide a compile-time check for the bsl::pair type.
/// 
///  @ref bslmf_ispointer :
///       Provide a compile-time check for pointer types.
/// 
///  @ref bslmf_ispolymorphic :
///       Provide a compile-time check for determining polymorphic types.
/// 
///  @ref bslmf_isreference :
///       Provide a meta-function to test reference types.
/// 
///  @ref bslmf_isreferencewrapper :
///       Provide a trait to detect reference-wrapper specializations.
/// 
///  @ref bslmf_isrvaluereference :
///       Provide a compile-time check for rvalue reference types.
/// 
///  @ref bslmf_issame :
///       Provide a meta-function for testing if two types are the same.
/// 
///  @ref bslmf_isswappable :
///       Provide metafunction to identify swappable types.
/// 
///  @ref bslmf_istransparentpredicate :
///       Support detection of whether a predicate functor is transparent.
/// 
///  @ref bslmf_istriviallycopyable :
///       Provide a meta-function for determining trivially copyable types.
/// 
///  @ref bslmf_istriviallydefaultconstructible :
///       Provide a compile-time check for trivially default-constructible.
/// 
///  @ref bslmf_isvoid :
///       Provide a compile-time check for `void` types.
/// 
///  @ref bslmf_isvolatile :
///       Provide a compile-time check for `volatile`-qualified types.
/// 
///  @ref bslmf_makeintegersequence :
///       Provide a template parameter pack of integers.
/// 
///  @ref bslmf_matchanytype :
///       Provide a generic type to which any type can be converted.
/// 
///  @ref bslmf_matcharithmetictype :
///       Provide a class supporting "do-the-right-thing clause" dispatch.
/// 
///  @ref bslmf_memberfunctionpointertraits :
///       Provide meta-functions to detect member function pointer traits.
/// 
///  @ref bslmf_memberpointertraits :
///       Provide meta-function to detect pointer to member traits.
/// 
///  @ref bslmf_metaint :                                       !DEPRECATED!
///       Provide a meta-function to map integral constants to unique types.
/// 
///  @ref bslmf_movableref :
///       Provide a vocabulary type to enable move semantics.
/// 
///  @ref bslmf_negation :
///       Provide the logical negation (NOT) for type traits.
/// 
///  @ref bslmf_nestedtraitdeclaration :
///       Provide a nested declaration to associate a class with a trait.
/// 
///  'bslmf_nil':
///       Provide a nil type.
/// 
///  @ref bslmf_nthparameter :
///       Metafunction to return the Nth type parameter in a parameter pack
/// 
///  @ref bslmf_nthparameter_cpp03 :                                         !PRIVATE!
///       Provide C++03 implementation for bslmf_nthparameter.h
/// 
///  @ref bslmf_referencewrapper :
///       Provide copyable, assignable object wrapper for references.
/// 
///  @ref bslmf_removeconst :
///       Provide a meta-function for removing top-level `const`-qualifier.
/// 
///  @ref bslmf_removecv :
///       Provide a meta-function for removing top-level cv-qualifiers.
/// 
///  @ref bslmf_removecvq :
///       Provide a meta-function for removing `const`/`volatile` qualifiers.
/// 
///  @ref bslmf_removecvref :
///       Provide a meta-func for removing reference-ness and cv-qualifiers.
/// 
///  @ref bslmf_removeextent :
///       Provide a metafunction to return an array type's element type.
/// 
///  @ref bslmf_removepointer :
///       Provide a meta-function to transform pointer type to referent type.
/// 
///  @ref bslmf_removereference :
///       Provide a meta-function for stripping reference-ness from types.
/// 
///  @ref bslmf_removevolatile :
///       Provide a meta-function for removing `volatile`-qualifier.
/// 
///  @ref bslmf_resulttype :
///       Provide access to `result_type` or `ResultType` nested type.
/// 
///  @ref bslmf_selecttrait :
///       Provide clean compile-time dispatch based on multiple traits
/// 
///  @ref bslmf_switch :
///       Provide a compile-time `switch` meta-function.
/// 
///  'bslmf_tag':
///       Provide an integral-constant-to-type conversion.
/// 
///  @ref bslmf_typeidentity :
///       Provide a template metafunction that returns its argument.
/// 
///  @ref bslmf_typelist :
///       Provide a typelist component.
/// 
///  @ref bslmf_unwraprefdecay :
///       Provide a meta-function to decay and unwrap reference wrappers.
/// 
///  @ref bslmf_unwrapreference :
///       Provide a meta-function to unwrap reference wrappers.
/// 
///  @ref bslmf_usesallocator :
///       Provide a meta-function to determine if a type uses an allocator.
/// 
///  @ref bslmf_usesallocatorargt :
///       Provide a metafunction for @ref allocator_arg_t  construction
/// 
///  @ref bslmf_util :
///       Provide low-level functions on `bslmf` types.
/// 
///  @ref bslmf_voidtype :
///       Provide a helper for implementing SFINAE-based metafunctions.
///
/// @}
/** @} */