bdlb_transparentstringhash

Detailed Description

Provide a transparent hash functor.

Outline

• Purpose
• Classes
• Description
  • Usage
    • Example 1: Basic Use of bdlb::TransparentStringHash

Purpose

Provide a transparent hash functor.

Classes

• bdlb::TransparentStringHash: a transparent hash functor for strings

See also

bsl_unordered_map, bsl_unordered_set

Description

This component provides a struct, bdlb::TransparentStringHash, that defines a functor to generate a hash code for different 'string-like' types and can be used as transparent hash functor for heterogeneous lookup.

Usage

This section illustrates intended use of this component.

Example 1: Basic Use of bdlb::TransparentStringHash

Suppose we need a container to store set of bsl::string unique objects. bsl::unordered_set is designed exactly for this purpose. But imagine that we want to use bsl::string_view objects for search operations within our container. bsl::unordered_set uses bsl::hash as default hash functor. The problem is that even though the hash function for bsl::string_view exists, compiler tries to convert bsl::string_view objects to the bsl::string since bsl::hash is parameterized by bsl::string. And compilation fails, because there is no such implicit conversion. In addition, implicit conversions where they are available, may lead to additional memory allocation for temporary objects. The following code illustrates how to use bdlb::TransparentStringHash as a hash functor for the standard container unordered_set, in this case to allow a bsl::unordered_set<bsl::string> to be searched with a bsl::string_view.

First, we define a transparent equality predicate, that is required by the bsl::unordered_set along with the transparent hash:

                 // =============================
                 // struct TestTransparentEqualTo
                 // =============================
 
/// This `struct` defines an equality of objects of different types,
/// enabling them for use for heterogeneous comparison in the standard
/// associative containers such as `bsl::unordered_map`.  Note that this
/// class is an empty POD type.
struct TestTransparentEqualTo {
 
    // TYPES
 
    /// Type alias indicating this is a transparent comparator.
    typedef void is_transparent;
 
    // ACCESSORS
 
    /// Return `true` if the specified `lhs` is equal to the specified
    /// `rhs` and `false` otherwise.
    template <class LHS, class RHS>
    bool operator()(const LHS& lhs, const RHS& rhs) const
    {
        return lhs == rhs;
    }
};

Note that this struct is defined only to avoid cycle dependencies between BDE components. In real code for these purposes it is recommended to use bdlb::TransparentEqualTo.

Then, we create a container that uses bdlb::TransparentStringHash. We use the transparent comparator defined above to avoid implicit conversions:

typedef bsl::unordered_set<bsl::string,
                           bdlb::TransparentStringHash,
                           TestTransparentEqualTo> TransparentHashSet;
 
TransparentHashSet transparentSet;

Now, we fill the container with the strings:

transparentSet.insert("NY");
transparentSet.insert("LA");

Finally, we observe that the container allows to use bsl::string_view objects as a key and does not make any implicit conversions:

bsl::string_view  newYork       ("NY");
bsl::string_view  losAngeles    ("LA");
const char       *sanFrancisco = "SF";
 
assert(transparentSet.end() != transparentSet.find(newYork     ));
assert(transparentSet.end() != transparentSet.find(losAngeles  ));
assert(transparentSet.end() == transparentSet.find(sanFrancisco));