bslmf_addpointer.h

Go to the documentation of this file.

/// @file bslmf_addpointer.h
///
/// The content of this file has been pre-processed for Doxygen.
///
 
 
// bslmf_addpointer.h                                                 -*-C++-*-
#ifndef INCLUDED_BSLMF_ADDPOINTER
#define INCLUDED_BSLMF_ADDPOINTER
 
#include <bsls_ident.h>
BSLS_IDENT("$Id: $")
 
/// @defgroup bslmf_addpointer bslmf_addpointer
/// @brief  Provide meta-function to transform a type to pointer to that type.
/// @addtogroup bsl
/// @{
/// @addtogroup bslmf
/// @{
/// @addtogroup bslmf_addpointer
/// @{
///
/// <h1> Outline </h1>
/// * <a href="#bslmf_addpointer-purpose"> Purpose</a>
/// * <a href="#bslmf_addpointer-classes"> Classes </a>
/// * <a href="#bslmf_addpointer-description"> Description </a>
///   * <a href="#bslmf_addpointer-usage"> Usage </a>
///     * <a href="#bslmf_addpointer-example-1-transform-type-to-pointer-type-to-that-type"> Example 1: Transform Type to Pointer Type to that Type </a>
///
/// # Purpose {#bslmf_addpointer-purpose}
/// Provide meta-function to transform a type to pointer to that type.
///
/// # Classes {#bslmf_addpointer-classes}
///
/// -  bsl::add_pointer: meta-function to transform a type to a pointer type
/// -  bsl::add_pointer_t: alias to the return type of the `bsl::add_pointer`
///
/// @see  bslmf_removepointer
///
/// # Description {#bslmf_addpointer-description}
/// This component defines a meta-function, `bsl::add_pointer`,
/// that may be used to transform a type to a pointer to that type.
///
/// `bsl::add_pointer` meets the requirements of the @ref add_pointer  template
/// defined in the C++11 standard [meta.trans.ptr].
///
/// ## Usage {#bslmf_addpointer-usage}
///
///
/// In this section we show intended use of this component.
///
/// ### Example 1: Transform Type to Pointer Type to that Type {#bslmf_addpointer-example-1-transform-type-to-pointer-type-to-that-type}
///
///
/// Suppose that we want to transform a type to a pointer type to that type.
///
/// First, we create two `typedef`s -- a pointer type (`MyPtrType`) and the type
/// pointed to by the pointer type (`MyType`):
/// @code
/// typedef int   MyType;
/// typedef int * MyPtrType;
/// @endcode
/// Now, we transform `MyType` to a pointer type using `bsl::add_pointer` and
/// verify that the resulting type is the same as `MyPtrType`:
/// @code
/// assert((bsl::is_same<bsl::add_pointer<MyType>::type, MyPtrType>::value));
/// @endcode
/// Finally, if the current compiler supports alias templates C++11 feature, we
/// transform `MyType` to a pointer type using `bsl::add_pointer_t` and verify
/// that the resulting type is the same as `MyPtrType`:
/// @code
/// #ifdef BSLS_COMPILERFEATURES_SUPPORT_ALIAS_TEMPLATES
///   assert((bsl::is_same<bsl::add_pointer_t<MyType>, MyPtrType>::value));
/// #endif
/// @endcode
/// Note, that the `bsl::add_pointer_t` avoids the `::type` suffix and
/// `typename` prefix when we want to use the result of the `bsl::add_pointer`
/// meta-function in templates.
/// @}
/** @} */
/** @} */
 
/** @addtogroup bsl
 * @{
 */
/** @addtogroup bslmf
 * @{
 */
/** @addtogroup bslmf_addpointer
 * @{
 */
 
#include <bslscm_version.h>
 
#include <bsls_compilerfeatures.h>
#include <bsls_platform.h>
 
#include <stddef.h>
 
#ifndef BDE_DONT_ALLOW_TRANSITIVE_INCLUDES
#include <bslmf_removereference.h>
#endif // BDE_DONT_ALLOW_TRANSITIVE_INCLUDES
 
 
namespace bslmf {
 
/// This utility `struct` is a private implementation detail that hosts an
/// overloaded pair of functions that, through SFINAE, can determine whether
/// it is legal to form a pointer to a specified `t_TYPE`.
///
/// See @ref bslmf_addpointer 
struct AddPointer_Compute {
 
    struct LargeResult {
        char d_dummy[99];
    };
 
    template <class t_TYPE>
    static LargeResult canFormPointer(t_TYPE *);
 
    template <class t_TYPE>
    static char canFormPointer(...);
};
 
/// For the majority of types, it is perfectly reasonable to form the type
/// `t_TYPE *`.
///
/// See @ref bslmf_addpointer 
template <class t_TYPE,
          size_t = sizeof(AddPointer_Compute::canFormPointer<t_TYPE>(0))>
struct AddPointer_Impl {
 
    typedef t_TYPE *type;  // A pointer to the original 't_TYPE'.
};
 
/// For special cases, such as references and "abominable" functions, it is
/// not legal to form a pointer, and this parital specialization will be
/// chosen by the computed default template parameter.
template <class t_TYPE>
struct AddPointer_Impl<t_TYPE, 1u> {
 
    typedef t_TYPE type;  // Do not modify the type if a pointer is not valid.
};
 
#if defined(BSLS_PLATFORM_CMP_IBM)
template <class t_TYPE>
struct AddPointer_Impl<t_TYPE[], 1u> {
    // IBM miscomputes the SFINAE condition for arrays of unknown bound, so we
    // provide an additional partial specialization for this platform.
 
    typedef t_TYPE (*type)[];     // A pointer to the original 't_TYPE[]'.
};
#endif
 
}  // close package namespace
 
 
namespace bsl {
 
                         // ==================
                         // struct add_pointer
                         // ==================
 
/// This `struct` template implements the @ref add_pointer  meta-function
/// defined in the C++11 standard [meta.trans.ptr], providing an alias,
/// `type`, that returns the result.  If the (template parameter) `t_TYPE`
/// is not a reference type, then `type` is an alias to a pointer type that
/// points to `t_TYPE`; otherwise, `type` is an alias to a pointer type that
/// points to the type referred to by the reference `t_TYPE`, unless it is
/// not legal to form such a pointer type, in which case `type` is an alias
/// for `t_TYPE`.
///
/// See @ref bslmf_addpointer 
template <class t_TYPE>
struct add_pointer {
 
    /// This `typedef` is an alias to a pointer type that points to the
    /// (template parameter) `t_TYPE` if it is not a reference type;
    /// otherwise, this `typedef` is an alias to a pointer type that points
    /// to the type referred to by the reference `t_TYPE`.
    typedef typename BloombergLP::bslmf::AddPointer_Impl<t_TYPE>::type type;
};
 
/// If we can form a reference to `t_TYPE`, then we can also form a pointer
/// to it.  In particular, we know that it is not `void` (which should still
/// work) or an "abominable" function type with a trailing cv-qualifier. 
/// 
/// \note Note that   this partial specialization is necessary to avoid falling into
/// degenerate (non-compiling) cases in the implementation meta-program.
template <class t_TYPE>
struct add_pointer<t_TYPE&> {
 
    typedef t_TYPE * type;
};
 
#if defined(BSLS_COMPILERFEATURES_SUPPORT_RVALUE_REFERENCES)
/// If we can form a reference to `t_TYPE`, then we can also form a pointer
/// to it.  In particular, we know that it is not `void` (which should still
/// work) or an "abominable" function type with a trailing cv-qualifier. 
/// 
/// \note Note that   this partial specialization is necessary to avoid falling into
/// degenerate (non-compiling) cases in the implementation meta-program.
template <class t_TYPE>
struct add_pointer<t_TYPE&&> {
 
    typedef t_TYPE * type;
};
#endif
 
#ifdef BSLS_COMPILERFEATURES_SUPPORT_ALIAS_TEMPLATES
 
//ALIASES
 
/// @ref add_pointer_t  is an alias to the return type of the `bsl::add_pointer`
/// meta-function.  Note, that the @ref remove_pointer_t  avoids the `::type`
/// suffix and `typename` prefix when we want to use the result of the
/// meta-function in templates.
template <class t_TYPE>
using add_pointer_t = typename add_pointer<t_TYPE>::type;
 
#endif  // BSLS_COMPILERFEATURES_SUPPORT_ALIAS_TEMPLATES
 
}  // close namespace bsl
 
#endif
 
// ----------------------------------------------------------------------------
// Copyright 2017 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 ----------------------------------
 
/** @} */
/** @} */
/** @} */