bslmf_istransparentpredicate.h

Go to the documentation of this file.

/// @file bslmf_istransparentpredicate.h
///
/// The content of this file has been pre-processed for Doxygen.
///
 
 
// bslmf_istransparentpredicate.h                                     -*-C++-*-
#ifndef INCLUDED_BSLMF_ISTRANSPARENTPREDICATE
#define INCLUDED_BSLMF_ISTRANSPARENTPREDICATE
 
#include <bsls_ident.h>
BSLS_IDENT("$Id: $")
 
/// @defgroup bslmf_istransparentpredicate bslmf_istransparentpredicate
/// @brief  Support detection of whether a predicate functor is transparent.
/// @addtogroup bsl
/// @{
/// @addtogroup bslmf
/// @{
/// @addtogroup bslmf_istransparentpredicate
/// @{
///
/// <h1> Outline </h1>
/// * <a href="#bslmf_istransparentpredicate-purpose"> Purpose</a>
/// * <a href="#bslmf_istransparentpredicate-classes"> Classes </a>
/// * <a href="#bslmf_istransparentpredicate-description"> Description </a>
///   * <a href="#bslmf_istransparentpredicate-usage"> Usage </a>
///     * <a href="#bslmf_istransparentpredicate-example-1-specifying-behavior-of-comparator"> Example 1: Specifying Behavior Of Comparator </a>
///
/// # Purpose {#bslmf_istransparentpredicate-purpose}
/// Support detection of whether a predicate functor is transparent.
///
/// # Classes {#bslmf_istransparentpredicate-classes}
///
/// -  bslmf::IsTransparentPredicate: Detects `is_transparent`
///
/// @see  bslstl_map, bslstl_set
///
/// # Description {#bslmf_istransparentpredicate-description}
/// This component provides a metafunction,
/// `bslmf::IsTransparentPredicate`, that can be used to detect whether a
/// comparator is transparent (supports heterogeneous comparisons).  If the
/// comparator has a nested type named `is_transparent`, the template inherits
/// from `true_type`, otherwise it inherits from `false_type`.
///
/// ## Usage {#bslmf_istransparentpredicate-usage}
///
///
/// This section illustrates intended use of this component.
///
/// ### Example 1: Specifying Behavior Of Comparator {#bslmf_istransparentpredicate-example-1-specifying-behavior-of-comparator}
///
///
/// In this example, we demonstrate the use of `IsTransparentPredicate` to
/// determine different comparator's behavior.  Our goal is to create an
/// overload of an associative container's method that participates in overload
/// resolution only if the comparator is transparent, otherwise we fall back on
/// a default behavior.
///
/// First, we define simple container, `Vector`, that is used as a foundation
/// for our associative container:
/// @code
/// template <class TYPE>
/// class Vector {
///     // DATA
///     const TYPE * d_begin_p;   // pointer to the beginning
///     const TYPE * d_end_p;     // pointer to the end
///
///   public:
///     // CREATORS
///     Vector(const TYPE *first, const TYPE *last)
///         // Construct an object that references the specified 'first' and
///         // 'last' items in the sequence.
///     : d_begin_p(first)
///     , d_end_p(last)
///     {
///     }
///
///     // ACCESSORS
///     const TYPE *begin() const
///         // Return a reference providing non-modifiable access to the first
///         // object in the underlying sequence.
///     {
///         return d_begin_p;
///     }
///
///     const TYPE *end() const
///         // Return a reference providing non-modifiable access to the last
///         // object in the underlying sequence.
///     {
///         return d_end_p;
///     }
/// };
/// @endcode
/// Then we define simple type, `String`, that is used as a key.  Note that we
/// have comparison operators that allow to compare both two `String` objects
/// and `String` object with character sequence.
/// @code
/// class String {
///     // CLASS DATA
///     static int  s_numObjectsCreated;  // total number of created instances
///
///     // DATA
///     const char *d_data_p;             // reference to a string
///
///   public:
///     // CLASS METHODS
///     static int numObjectsCreated()
///         // Return the total number of created instances of class 'String'.
///     {
///         return s_numObjectsCreated;
///     }
///
///     // CREATORS
///     String()
///         // Construct an empty string
///     : d_data_p("")
///     {
///         ++s_numObjectsCreated;
///     }
///
///     String(const char *data)  // IMPLICIT
///         // Construct a string that references the specified 'data'.  The
///         // behavior is undefined unless 'data' points to a null-terminated
///         // string.
///     : d_data_p(data)
///     {
///         ++s_numObjectsCreated;
///     }
///
///     // FREE FUNCTIONS
///     friend bool operator<(const String& lhs, const String& rhs)
///         // Return 'true' if the value of the specified 'lhs' string is
///         // lexicographically less than that of the specified 'rhs' string,
///         // and 'false' otherwise.
///     {
///         const char *lhsData = lhs.d_data_p;
///         const char *rhsData = rhs.d_data_p;
///         while (true) {
///             if (*lhsData < *rhsData) {
///                 return true;                                      // RETURN
///             }
///             else if (*lhsData > *rhsData || *lhsData == '\0') {
///                 return false;                                     // RETURN
///             }
///             ++lhsData;
///             ++rhsData;
///         }
///     }
///
///     friend bool operator<(const String& lhs, const char *rhs)
///         // Return 'true' if the value of the specified 'lhs' string is
///         // lexicographically less than the specified 'rhs' character
///         // sequence, and 'false' otherwise.
///     {
///         const char *lhsData = lhs.d_data_p;
///         while (true) {
///             if (*lhsData < *rhs) {
///                 return true;                                      // RETURN
///             }
///             else if (*lhsData > *rhs || *lhsData == '\0') {
///                 return false;                                     // RETURN
///             }
///             ++lhsData;
///             ++rhs;
///         }
///     }
///
///     friend bool operator<(const char *lhs, const String& rhs)
///         // Return 'true' if the specified 'lhs' character sequence is
///         // lexicographically less than the value of the specified 'rhs'
///         // string, and 'false' otherwise.
///     {
///         const char *rhsData = rhs.d_data_p;
///         while (true) {
///             if (*lhs < *rhsData) {
///                 return true;                                      // RETURN
///             }
///             else if (*lhs > *rhsData || *lhs == '\0') {
///                 return false;                                     // RETURN
///             }
///             ++lhs;
///             ++rhsData;
///         }
///     }
/// };
///
/// int String::s_numObjectsCreated = 0;
/// @endcode
/// Next we define our associative container.  Note that we use
/// `IsTransparentPredicate` for a method with `enable_if` in the return type.
/// This adds our function template into the function overload resolution set if
/// and only if the comparison function object is considered transparent, using
/// a technique known as "SFINAE".
/// @code
/// template <class t_COMPARATOR>
/// class FlatStringSet {
///
///     // DATA
///     t_COMPARATOR   d_comparator;  // comparison object
///     Vector<String> d_data;        // stores the data
///
///   public:
///     // TYPES
///     typedef const String * const_iterator;
///
///     // CREATORS
///     template <class INPUT_ITERATOR>
///     FlatStringSet(INPUT_ITERATOR    first,
///                   INPUT_ITERATOR    last,
///                   const t_COMPARATOR& comparator = t_COMPARATOR());
///         // Create a set, and insert each 'String' object in the sequence
///         // starting at the specified 'first' element, and ending
///         // immediately before the specified 'last' element, ignoring those
///         // keys having a value equivalent to that which appears earlier in
///         // the sequence.  Optionally specify a 'comparator' used to order
///         // keys contained in this object.  If 'comparator' is not supplied,
///         // a default-constructed object of the (template parameter) type
///         // 't_COMPARATOR' is used.  This operation has 'O[N]' complexity,
///         // where 'N' is the number of elements between 'first' and 'last'.
///         // The (template parameter) type 'INPUT_ITERATOR' shall meet the
///         // requirements of an input iterator defined in the C++11 standard
///         // [24.2.3] providing access to values of a type convertible to
///         // 'String', and 'String' must be 'emplace-constructible' from '*i'
///         // into this set, where 'i' is a dereferenceable iterator in the
///         // range '[first .. last)'.  The behavior is undefined unless
///         // 'first' and 'last' refer to a sequence of valid values where
///         // 'first' is at a position at or before 'last', the range is
///         // ordered according to 't_COMPARATOR', and there are no duplicates
///         // in the range.
///
///     // ACCESSORS
///     const_iterator begin() const;
///         // Return an iterator providing non-modifiable access to the first
///         // 'String' object in the ordered sequence of 'String' objects
///         // maintained by this set, or the 'end' iterator if this set is
///         // empty.
///
///     const_iterator end() const;
///         // Return an iterator providing non-modifiable access to the
///         // past-the-end element in the ordered sequence of 'String' objects
///         // maintained by this set.
///
///     const_iterator find(const String& key) const
///         // Return an iterator to the element that compares equal to the
///         // specified 'key' if such an element exists, and an end iterator
///         // otherwise.
///         //
///         // Note: implemented inline due to Sun CC compilation error.
///     {
///         for (const_iterator first = begin(); first != end(); ++first) {
///             if (d_comparator(key, *first)) {
///                 return end();                                     // RETURN
///             }
///             if (!d_comparator(*first, key)) {
///                 return first;                                     // RETURN
///             }
///         }
///         return end();
///     }
///
///     template <class t_KEY>
///     typename bsl::enable_if<IsTransparentPredicate<t_COMPARATOR,
///                                                    t_KEY>::value,
///                             const_iterator>::type
///     find(const t_KEY& key) const
///         // Return an iterator to the element that compares equal to the
///         // specified 'key' if such an element exists, and an end iterator
///         // otherwise.
///         //
///         // Note: implemented inline due to Sun CC compilation error.
///     {
///         for (const_iterator first = begin(); first != end(); ++first) {
///             if (d_comparator(key, *first)) {
///                 return end();                                     // RETURN
///             }
///             if (!d_comparator(*first, key)) {
///                 return first;                                     // RETURN
///             }
///         }
///         return end();
///     }
///
///     int size() const;
///         // Return the number of elements in this container.
/// };
///
/// // CREATORS
/// template <class t_COMPARATOR>
/// template <class INPUT_ITERATOR>
/// FlatStringSet<t_COMPARATOR>::FlatStringSet(INPUT_ITERATOR    first,
///                                          INPUT_ITERATOR    last,
///                                          const t_COMPARATOR& comparator)
/// : d_comparator(comparator),
///   d_data(first, last)
/// {
/// }
///
/// // ACCESSORS
/// template <class t_COMPARATOR>
/// typename FlatStringSet<t_COMPARATOR>::const_iterator
/// FlatStringSet<t_COMPARATOR>::begin() const
/// {
///     return d_data.begin();
/// }
///
/// template <class t_COMPARATOR>
/// typename FlatStringSet<t_COMPARATOR>::const_iterator
/// FlatStringSet<t_COMPARATOR>::end() const
/// {
///     return d_data.end();
/// }
///
/// template <class t_COMPARATOR>
/// int FlatStringSet<t_COMPARATOR>::size() const
/// {
///     return static_cast<int>(end() - begin());
/// }
/// @endcode
/// Then we define two comparators.  These classes are completely identical
/// except that one defines an `is_transparent` type, and the other does not.
/// @code
/// struct TransparentComp
///     // This class can be used as a comparator for containers.  It has a
///     // nested type 'is_transparent', so it is classified as transparent by
///     // the 'bslmf::IsTransparentPredicate' metafunction and can be used for
///     // heterogeneous comparison.
/// {
///     // TYPES
///     typedef void is_transparent;
///
///     // ACCESSORS
///     template <class LHS, class RHS>
///     bool operator()(const LHS& lhs, const RHS& rhs) const
///         // Return 'true' if the specified 'lhs' is less than the specified
///         // 'rhs' and 'false' otherwise.
///     {
///         return lhs < rhs;
///     }
/// };
///
/// struct NonTransparentComp
///     // This class can be used as a comparator for containers.  It has no
///     // nested type 'is_transparent', so it is classified as
///     // non-transparent by the 'bslmf::IsTransparentPredicate' metafunction
///     // and can not be used for heterogeneous comparison.
/// {
///     template <class LHS, class RHS>
///     bool operator()(const LHS& lhs, const RHS& rhs) const
///         // Return 'true' if the specified 'lhs' is less than the specified
///         // 'rhs' and 'false' otherwise.
///     {
///         return lhs < rhs;
///     }
/// };
/// @endcode
/// Next we create an array of `String` objects and two `FlatStringSet` objects,
/// basing on this array and having different comparators, transparent and
/// non-transparent.  Note that creation of `FlatStringSet` object does not
/// increase number of created `String` objects, because it just holds pointers
/// to these objects, but does not copy them.
/// @code
/// int OBJECTS_NUMBER = String::numObjectsCreated();
/// assert(0 == OBJECTS_NUMBER);
///
/// String data[] = { "1", "2", "3", "5" };
/// enum { dataSize = sizeof data / sizeof *data };
///
/// assert(OBJECTS_NUMBER + 4 == String::numObjectsCreated());
/// OBJECTS_NUMBER = String::numObjectsCreated();
///
/// FlatStringSet<NonTransparentComp> nts(data, data + dataSize);
/// FlatStringSet<   TransparentComp>  ts(data, data + dataSize);
///
/// assert(4                  == nts.size()                 );
/// assert(4                  ==  ts.size()                 );
/// assert(OBJECTS_NUMBER     == String::numObjectsCreated());
/// @endcode
/// Then we call `find` method of set, having non-transparent comparator.
/// Explicit creation of temporary `String` object predictably increases the
/// number of created `String` objects.  But using character sequence as a
/// parameter for `find` method increases it too.  Because comparison operator
/// that accepts two `String` objects is used instead of operator that accepts
/// `String` and char sequence, so `String` constructor is called implicitly.
/// @code
/// assert(nts.begin() + 0    == nts.find(String("1"))      );
/// assert(nts.begin() + 1    == nts.find(String("2"))      );
/// assert(nts.begin() + 2    == nts.find(String("3"))      );
/// assert(nts.begin() + 3    == nts.find(String("5"))      );
/// assert(nts.end()          == nts.find(String("6"))      );
///
/// assert(OBJECTS_NUMBER + 5 == String::numObjectsCreated());
/// OBJECTS_NUMBER = String::numObjectsCreated();
///
/// assert(nts.begin() + 0    == nts.find(       "1" )      );
/// assert(nts.begin() + 1    == nts.find(       "2" )      );
/// assert(nts.begin() + 2    == nts.find(       "3" )      );
/// assert(nts.begin() + 3    == nts.find(       "5" )      );
/// assert(nts.end()          == nts.find(       "6" )      );
///
/// assert(OBJECTS_NUMBER + 5 == String::numObjectsCreated());
/// OBJECTS_NUMBER = String::numObjectsCreated();
/// @endcode
/// Finally we call `find` method of set, having transparent comparator.
/// Explicit creation of temporary `String` object still increases the number of
/// created `String` objects.  But using character sequence as a parameter for
/// `find` method does not.  Because comparison operator that accepts `String`
/// and char sequence is available and more appropriate then operator accepting
/// two `String` objects.  So there is no need for implicit constructor
/// invocation.
/// @code
/// assert( ts.begin() + 0    ==  ts.find(String("1"))      );
/// assert( ts.begin() + 1    ==  ts.find(String("2"))      );
/// assert( ts.begin() + 2    ==  ts.find(String("3"))      );
/// assert( ts.begin() + 3    ==  ts.find(String("5"))      );
/// assert( ts.end()          ==  ts.find(String("6"))      );
///
/// assert(OBJECTS_NUMBER + 5 == String::numObjectsCreated());
/// OBJECTS_NUMBER = String::numObjectsCreated();
///
/// assert( ts.begin() + 0    ==  ts.find(        "1" )     );
/// assert( ts.begin() + 1    ==  ts.find(        "2" )     );
/// assert( ts.begin() + 2    ==  ts.find(        "3" )     );
/// assert( ts.begin() + 3    ==  ts.find(        "5" )     );
/// assert( ts.end()          ==  ts.find(        "6" )     );
///
/// assert(OBJECTS_NUMBER     == String::numObjectsCreated());
/// @endcode
/// @}
/** @} */
/** @} */
 
/** @addtogroup bsl
 * @{
 */
/** @addtogroup bslmf
 * @{
 */
/** @addtogroup bslmf_istransparentpredicate
 * @{
 */
 
#include <bslmf_integralconstant.h>
#include <bslmf_voidtype.h>
 
 
namespace bslmf {
 
/// This `struct` template implements a meta-function to determine whether
/// the (template parameter) `t_COMPARATOR` is transparent (has a publicly
/// accessible member that is a type named `is_transparent`).  This generic
/// default template derives from `bsl::false_type`.  Template
/// specializations are provided (below) that derive from `bsl::true_type`.
template <class t_COMPARATOR, class t_KEY, class = void>
struct IsTransparentPredicate : bsl::false_type {
};
 
/// This specialization of `IsTransparentPredicate`, for when the (template
/// parameter) `t_COMPARATOR` is transparent, derives from `bsl::true_type`.
template <class t_COMPARATOR, class t_KEY>
struct IsTransparentPredicate<
    t_COMPARATOR,
    t_KEY,
    BSLMF_VOIDTYPE(typename t_COMPARATOR::is_transparent)> : bsl::true_type {
};
 
}  // close package namespace
 
 
#endif
 
// ----------------------------------------------------------------------------
// Copyright 2019 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 ----------------------------------
 
/** @} */
/** @} */
/** @} */