bdlb_caselessstringviewless.h

Go to the documentation of this file.

/// @file bdlb_caselessstringviewless.h
///
/// The content of this file has been pre-processed for Doxygen.
///
 
 
// bdlb_caselessstringviewless.h                                      -*-C++-*-
#ifndef INCLUDED_BDLB_CASELESSSTRINGVIEWLESS
#define INCLUDED_BDLB_CASELESSSTRINGVIEWLESS
 
#include <bsls_ident.h>
BSLS_IDENT("$Id: $")
 
/// @defgroup bdlb_caselessstringviewless bdlb_caselessstringviewless
/// @brief  Provide a case-insensitive less-than predicate for string views.
/// @addtogroup bdl
/// @{
/// @addtogroup bdlb
/// @{
/// @addtogroup bdlb_caselessstringviewless
/// @{
///
/// <h1> Outline </h1>
/// * <a href="#bdlb_caselessstringviewless-purpose"> Purpose</a>
/// * <a href="#bdlb_caselessstringviewless-classes"> Classes </a>
/// * <a href="#bdlb_caselessstringviewless-description"> Description </a>
///   * <a href="#bdlb_caselessstringviewless-usage"> Usage </a>
///     * <a href="#bdlb_caselessstringviewless-example-1-basic-use-of-bdlb-caselessstringviewless"> Example 1: Basic Use of bdlb::CaselessStringViewLess </a>
///
/// # Purpose {#bdlb_caselessstringviewless-purpose}
/// Provide a case-insensitive less-than predicate for string views.
///
/// # Classes {#bdlb_caselessstringviewless-classes}
///
/// -  bdlb::CaselessStringViewLess: a case-insensitive less for @ref string_view s.
///
/// @see  bsl_map, bsl_set
///
/// # Description {#bdlb_caselessstringviewless-description}
/// This component provides a `struct`,
/// `bdlb::CaselessStringViewLess`, that defines a functor that compares two
/// string views using a case-insensitive string comparison.  This
/// lexicographical ordering makes `CaselessStringViewLess` suitable for
/// supporting `bsl::string`s or `bsl::string_view`s as keys in case-insensitive
/// ordered associative containers.
///
/// Note that using this component to compare keys in a container is less
/// efficient than converting them all to the same case prior to insertion and
/// then just doing straight string compares.
///
/// ## Usage {#bdlb_caselessstringviewless-usage}
///
///
/// This section illustrates intended use of this component.
///
/// ### Example 1: Basic Use of bdlb::CaselessStringViewLess {#bdlb_caselessstringviewless-example-1-basic-use-of-bdlb-caselessstringviewless}
///
///
/// Suppose we need a container to store set of unique strings.  The following
/// code illustrates how to use `bdlb::CaselessStringViewLess` as a comparator
/// for the standard container `set`, to create a set of unique case-insensitive
/// string values.
///
/// First, we create several strings:
/// @code
/// const bsl::string newYork        = "NY";
/// const bsl::string losAngeles     = "LA";
/// const bsl::string newJersey      = "NJ";
/// const bsl::string sanFrancisco   = "SF";
/// const bsl::string anotherNewYork = "ny";
/// @endcode
/// Next, we create two containers, one with default comparator and another
/// using `bdlb::CstringLess` as a comparator:
/// @code
/// bsl::set<bsl::string>                               caseSensitiveSet;
/// bsl::set<bsl::string, bdlb::CaselessStringViewLess> caseInsensitiveSet;
/// @endcode
/// Then, we fill containers with the same contents:
/// @code
/// caseSensitiveSet.insert(newYork);
/// caseSensitiveSet.insert(losAngeles);
/// caseSensitiveSet.insert(newJersey);
/// caseSensitiveSet.insert(sanFrancisco);
/// caseSensitiveSet.insert(anotherNewYork);
///
/// caseInsensitiveSet.insert(newYork);
/// caseInsensitiveSet.insert(losAngeles);
/// caseInsensitiveSet.insert(newJersey);
/// caseInsensitiveSet.insert(sanFrancisco);
/// caseInsensitiveSet.insert(anotherNewYork);
/// @endcode
/// Next, we observe that the container created with `CaselessStringViewLess`
/// (`caseInsensitiveSet`) contains the correct number of unique string values
/// (4), while the container using the default comparator does not:
/// @code
/// assert(5 == caseSensitiveSet.size());
/// assert(4 == caseInsensitiveSet.size());
/// @endcode
/// Now, we observe the members of the case-sensitive set:
/// @code
/// assert( caseSensitiveSet.count("NY"));
/// assert(!caseSensitiveSet.count("nY"));
/// assert(!caseSensitiveSet.count("Ny"));
/// assert( caseSensitiveSet.count("ny"));
///
/// assert( caseSensitiveSet.count("SF"));
/// assert(!caseSensitiveSet.count("sF"));
/// assert(!caseSensitiveSet.count("Sf"));
/// assert(!caseSensitiveSet.count("sf"));
/// @endcode
/// Finally, we observe that we can do case-insensitive access to
/// `caseInsensiveSet`:
/// @code
/// assert( caseInsensitiveSet.count("NY"));
/// assert( caseInsensitiveSet.count("nY"));
/// assert( caseInsensitiveSet.count("Ny"));
/// assert( caseInsensitiveSet.count("ny"));
///
/// assert( caseInsensitiveSet.count("LA"));
/// assert( caseInsensitiveSet.count("lA"));
/// assert( caseInsensitiveSet.count("La"));
/// assert( caseInsensitiveSet.count("la"));
///
/// assert( caseInsensitiveSet.count("nj"));
/// assert( caseInsensitiveSet.count("nJ"));
/// assert( caseInsensitiveSet.count("Nj"));
/// assert( caseInsensitiveSet.count("NJ"));
///
/// assert( caseInsensitiveSet.count("sf"));
/// assert( caseInsensitiveSet.count("sF"));
/// assert( caseInsensitiveSet.count("Sf"));
/// assert( caseInsensitiveSet.count("SF"));
///
/// assert(!caseInsensitiveSet.count("GA"));
/// assert(!caseInsensitiveSet.count("gA"));
/// assert(!caseInsensitiveSet.count("Ga"));
/// assert(!caseInsensitiveSet.count("ga"));
/// @endcode
/// @}
/** @} */
/** @} */
 
/** @addtogroup bdl
 * @{
 */
/** @addtogroup bdlb
 * @{
 */
/** @addtogroup bdlb_caselessstringviewless
 * @{
 */
 
#include <bdlscm_version.h>
 
#include <bdlb_stringviewutil.h>
 
#include <bslmf_istriviallycopyable.h>
#include <bslmf_istriviallydefaultconstructible.h>
#include <bslmf_nestedtraitdeclaration.h>
 
#include <bsls_assert.h>
 
#include <bsl_algorithm.h>
#include <bsl_cstddef.h>
#include <bsl_string_view.h>
 
 
namespace bdlb {
 
                        // =============================
                        // struct CaselessStringViewLess
                        // =============================
 
/// This `struct` defines an ordering on string views, enabling them for use
/// as keys in the standard associative containers such as `bsl::map` and `bsl::set`.  
/// 
/// \note Note that   this class is an empty POD type.
///
/// See @ref bdlb_caselessstringviewless 
struct CaselessStringViewLess {
 
    // PUBLIC TYPES
    typedef bsl::string_view first_argument_type;
    typedef bsl::string_view second_argument_type;
    typedef bool             result_type;
 
    /// Type alias indicating this is a transparent hash functor.
    typedef void             is_transparent;
 
    // TRAITS
    BSLMF_NESTED_TRAIT_DECLARATION(CaselessStringViewLess,
                                   bsl::is_trivially_copyable);
    BSLMF_NESTED_TRAIT_DECLARATION(CaselessStringViewLess,
                                   bsl::is_trivially_default_constructible);
 
    // CREATORS
 
    /// Create a `CaselessStringViewLess` object.
     CaselessStringViewLess() = default;
 
    /// Create a `CaselessStringViewLess` object.  
    /// \note Note that  as
    /// `CaselessStringViewLess` is an empty (stateless) type, this
    /// operation has no observable effect.
     CaselessStringViewLess(const CaselessStringViewLess& original) =
                                                                    default;
 
    /// Destroy this object.
     ~CaselessStringViewLess() = default;
 
    // MANIPULATORS
 
    /// Assign to this object the value of the specified `rhs` object, and
    /// return a reference providing modifiable access to this object.  
    /// 
    /// \note Note that   as `CaselessStringViewLess` is an empty (stateless) type, this
    /// operation has no observable effect.
     CaselessStringViewLess& operator=(const CaselessStringViewLess& rhs) =
                                                                    default;
 
    // ACCESSORS
 
    /// Return `true` if the specified `lhs` is lexicographically ordered
    /// before the specified `rhs`, and `false` otherwise.
    bool operator()(bsl::string_view lhs, bsl::string_view rhs) const;
};
 
// ============================================================================
//                           INLINE DEFINITIONS
// ============================================================================
 
                        // -----------------------------
                        // struct CaselessStringViewLess
                        // -----------------------------
 
// ACCESSORS
inline
bool CaselessStringViewLess::operator()(bsl::string_view lhs,
                                        bsl::string_view rhs) const
{
    return bdlb::StringViewUtil::lowerCaseCmp(lhs, rhs) < 0;
}
 
}  // close package namespace
 
 
#endif
 
// ----------------------------------------------------------------------------
// Copyright 2021 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 ----------------------------------
 
/** @} */
/** @} */
/** @} */