bslmf_nestedtraitdeclaration.h

Go to the documentation of this file.

/// @file bslmf_nestedtraitdeclaration.h
///
/// The content of this file has been pre-processed for Doxygen.
///
 
 
// bslmf_nestedtraitdeclaration.h                                     -*-C++-*-
#ifndef INCLUDED_BSLMF_NESTEDTRAITDECLARATION
#define INCLUDED_BSLMF_NESTEDTRAITDECLARATION
 
#include <bsls_ident.h>
BSLS_IDENT("$Id: $")
 
/// @defgroup bslmf_nestedtraitdeclaration bslmf_nestedtraitdeclaration
/// @brief  Provide a nested declaration to associate a class with a trait.
/// @addtogroup bsl
/// @{
/// @addtogroup bslmf
/// @{
/// @addtogroup bslmf_nestedtraitdeclaration
/// @{
///
/// <h1> Outline </h1>
/// * <a href="#bslmf_nestedtraitdeclaration-purpose"> Purpose</a>
/// * <a href="#bslmf_nestedtraitdeclaration-macros"> Macros </a>
/// * <a href="#bslmf_nestedtraitdeclaration-description"> Description </a>
///   * <a href="#bslmf_nestedtraitdeclaration-relationship-with-c-11-style-type-traits"> Relationship with "C++11-style" Type Traits </a>
///   * <a href="#bslmf_nestedtraitdeclaration-usage"> Usage </a>
///     * <a href="#bslmf_nestedtraitdeclaration-example-1-testing-a-type-for-a-custom-trait"> Example 1: Testing a Type for a Custom Trait </a>
///
/// # Purpose {#bslmf_nestedtraitdeclaration-purpose}
/// Provide a nested declaration to associate a class with a trait.
///
/// # Macros {#bslmf_nestedtraitdeclaration-macros}
///
/// -  BSLMF_NESTED_TRAIT_DECLARATION: macro that associates a trait with a class
/// -  BSLMF_NESTED_TRAIT_DECLARATION_IF: conditional macro to associates a trait
///
/// @see  bslmf_detectnestedtrait
///
/// # Description {#bslmf_nestedtraitdeclaration-description}
/// This component defines a pair of macros,
/// `BSLMF_NESTED_TRAIT_DECLARATION` and `BSLMF_NESTED_TRAIT_DECLARATION_IF`,
/// that can be used in association with the facilities provided by
/// @ref bslmf_detectnestedtrait  to declare that a given class has a given trait.
///
/// Traits provide a mechanism for convenient compile-time discovery of
/// information about a class, which is useful in particular for providing
/// efficient specializations of generalized containers and algorithms without
/// having to rely on knowledge of specific target classes.
///
/// The primary public interface of this component consists of two macros that
/// provide a facility for declaring that a given class has a given trait.
/// These macros embed the association between the type and the trait inside the
/// class definition itself, hence the term "nested trait declaration".
///
/// Note that the term "nested" is not meant to imply that this facility
/// declares a nested type within the class namespace, only that the trait
/// declaration appears as one of the public declarations that make up the class
/// definition.  For example, we could declare that a class, `xyza::Foo`, has
/// the trait `abcd::BarTrait` in the following way:
/// @code
/// namespace xyza {
///
/// class Foo {
///     // ... various implementation details ...
///
///   public:
///     // TRAITS
///     BSLMF_NESTED_TRAIT_DECLARATION(Foo, abcd::BarTrait);
///
///     // ... the rest of the public interface ...
/// };
///
/// }  // close namespace xyza
/// @endcode
/// Two flavors of macro are provided: one for declaring unconditionally that a
/// class has a trait, and another for declaring that the class has a trait if
/// and only if a given compile-time expression evaluates to `true`.
///
/// ## Relationship with "C++11-style" Type Traits {#bslmf_nestedtraitdeclaration-relationship-with-c-11-style-type-traits}
///
///
/// Traits declared using this component are not automatically compatible
/// mechanisms designed to detect "C++11-style" traits.  For a full discussion
/// of the relationship between nested traits and "C++11-style" traits, as well
/// as best practices for defining, associating, and detecting traits, see the
/// component documentation for @ref bslmf_detectnestedtrait .
///
/// ## Usage {#bslmf_nestedtraitdeclaration-usage}
///
///
/// This section illustrates the intended use of this component.
///
/// ### Example 1: Testing a Type for a Custom Trait {#bslmf_nestedtraitdeclaration-example-1-testing-a-type-for-a-custom-trait}
///
///
/// When writing generic infrastructure code, we often need to choose among
/// multiple code paths based on the capabilities of the types on which we are
/// operating.  If those capabilities are reflected in a type's public
/// interface, we may be able to use techniques such as SFINAE to choose the
/// appropriate code path.  However, SFINAE cannot detect all of a type's
/// capabilities.  In particular, SFINAE cannot detect constructors, memory
/// allocation, thread-safety characteristics, and so on.  Functions that depend
/// on these capabilities must use another technique to determine the correct
/// code path to use for a given type.  We can solve this sort of problem by
/// associating types with custom traits that indicate what capabilities are
/// provided by a given type.
///
/// First, assume that a compatible trait, `abcd::RequiresLockTrait`, has been
/// defined that indicates that a type's methods must not be called unless a
/// known lock is first acquired:
/// @code
/// namespace abcd { template <class t_TYPE> struct RequiresLockTrait; }
/// @endcode
/// The implementation of `abcd::RequiresLockTrait` is not shown.
///
/// Then, in package `xyza`, we declare a type, `DoesNotRequireLockType`, that
/// can be used without acquiring the lock:
/// @code
/// namespace xyza {
///
/// class DoesNotRequireLockType {
///     // ...
///
///   public:
///     // CREATORS
///     DoesNotRequireLockType();
///         // ...
/// };
/// @endcode
/// Next, we declare a type, `RequiresLockType`, that does require the lock.  We
/// use the `BSLMF_NESTED_TRAIT_DECLARATION` macro to associate the type with
/// the `abcd::RequiresLockTrait` trait:
/// @code
/// class RequiresLockType {
///     // ...
///
///   public:
///     // TRAITS
///     BSLMF_NESTED_TRAIT_DECLARATION(RequiresLockType,
///                                    abcd::RequiresLockTrait);
///
///     // CREATORS
///     RequiresLockType();
///         // ...
///
/// };
/// @endcode
/// Notice that the macro declaration is performed within the scope of the class
/// declaration, and must be done with public scope.
///
/// Now, we declare a templatized container type, `Container`, that is
/// parameterized on some `ELEMENT` type.  If `ELEMENT` requires a lock, then a
/// `Container` of `ELEMENT`s will require a lock as well.  This can be
/// expressed using the `BSLMF_NESTED_TRAIT_DECLARATION_IF` macro, by providing
/// `abcd::RequiresLockTrait<ELEMENT>::value` as the condition for associating
/// the trait with `Container`.
/// @code
/// template <class ELEMENT>
/// struct Container {
///     // ...
///
///   public:
///     // TRAITS
///     BSLMF_NESTED_TRAIT_DECLARATION_IF(Container, abcd::RequiresLockTrait,
///                                   abcd::RequiresLockTrait<ELEMENT>::value);
///
///     // ...
/// };
///
/// } // close package namespace
/// @endcode
/// Finally, code interacting with `xyza::DoesNotRequireLockType`,
/// `xyza::RequiresLockType` or `xyza::Container` objects will be able to choose
/// the appropriate code path by checking for the `abcd::RequiresLockTrait`
/// trait.  See @ref bslmf_detectnestedtrait  for an example of how generic code
/// would use such a trait.
/// @}
/** @} */
/** @} */
 
/** @addtogroup bsl
 * @{
 */
/** @addtogroup bslmf
 * @{
 */
/** @addtogroup bslmf_nestedtraitdeclaration
 * @{
 */
 
#include <bslscm_version.h>
 
 
 
namespace bslmf {
 
                        // ============================
                        // class NestedTraitDeclaration
                        // ============================
 
/// Class `t_TYPE` will be convertible to
/// `NestedTraitDeclaration<t_TYPE,t_TRAIT,true>` if `t_TRAIT` is associated
/// with `t_TYPE` using the `BSLMF_NESTED_TRAIT_DECLARATION` macro.  Nested
/// trait detection depends on `t_COND` being true.  If `t_COND` is false,
/// the nested trait detection will not see the conversion it is looking for
/// and will not associate `t_TRAIT` with `t_TYPE`.  This feature is used by
/// `BSLMF_NESTED_TRAIT_DECLARATION_IF` to turn a trait on or off depending
/// on a compile-time condition (usually another trait).
///
/// See @ref bslmf_nestedtraitdeclaration 
template <class t_TYPE, template <class t_T> class t_TRAIT, bool t_COND = true>
class NestedTraitDeclaration {
 
  public:
    // PUBLIC TYPES
    typedef NestedTraitDeclaration Type;
 
    // CREATORS
     NestedTraitDeclaration();
     NestedTraitDeclaration(const  NestedTraitDeclaration&);
     NestedTraitDeclaration& operator=(const  NestedTraitDeclaration&);
     ~NestedTraitDeclaration();
};
 
                    // ====================================
                    // macro BSLMF_NESTED_TRAIT_DECLARATION
                    // ====================================
 
#define BSLMF_NESTED_TRAIT_DECLARATION(t_TYPE, t_TRAIT)                       \
    operator BloombergLP::bslmf::NestedTraitDeclaration<t_TYPE, t_TRAIT>()    \
        const                                                                 \
    {                                                                         \
        return BloombergLP::bslmf::NestedTraitDeclaration<t_TYPE, t_TRAIT>(); \
    }
 
#ifdef __CDT_PARSER__
// Work around an Eclise CDT bug where it fails to parse the conditional trait
// declaration.  See internal DRQS 47839133.
#define BSLMF_NESTED_TRAIT_DECLARATION_IF(t_TYPE, t_TRAIT, t_COND)
#else
#define BSLMF_NESTED_TRAIT_DECLARATION_IF(t_TYPE, t_TRAIT, t_COND)            \
    operator BloombergLP::bslmf::                                             \
        NestedTraitDeclaration<t_TYPE, t_TRAIT, t_COND>() const               \
    {                                                                         \
        return BloombergLP::bslmf::                                           \
            NestedTraitDeclaration<t_TYPE, t_TRAIT, t_COND>();                \
    }
#endif
 
}  // close package namespace
 
 
 
#endif // ! defined(INCLUDED_BSLMF_NESTEDTRAITDECLARATION)
 
// ----------------------------------------------------------------------------
// Copyright 2013 Bloomberg Finance L.P.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// ----------------------------- END-OF-FILE ----------------------------------
 
/** @} */
/** @} */
/** @} */