bdlb_transparentless

Detailed Description

Outline

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

Purpose

Provide a transparent less-than predicate.

Classes

• bdlb::TransparentLess: a transparent less-than predicate.

See also

bsl_map, bsl_set

Description

This component provides a struct, bdlb::TransparentLess, that defines a functor that can be used as transparent less-than comparator for heterogeneous lookup.

Usage

This section illustrates intended use of this component.

Example 1: Basic Use of bdlb::TransparentLess

Suppose we need a container to store set of unique bsl::strings objects. We use bsl::set for our container, which uses bsl::less as default comparator. bsl::less is suitable if we want to search an entry using a bsl::string object as a key. However, if we were to try and search using a bsl::string_view object the code would not compile, even though the comparison operator between bsl::string and bsl::string_view exists. 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::TransparentLess as a comparator for the standard container set, in this case to allow a bsl::set<bsl::string> to be searched with a bsl::string_view.

First, we create several C-strings:

const char *newYork          = "NY";
const char *losAngeles       = "LA";
const char *cityWithLongName = "The abbreviation of really really long "
                               "name of the city. The name is so long "
                               "that even its abbreviation definitely "
                               "exceeds Small String Optimization limit";
const char *sanFrancisco     = "SF";

Next, we create several allocators to precisely control memory allocation:

bslma::TestAllocator         ca("container", veryVeryVeryVerbose);
bslma::TestAllocator         sa("strings",   veryVeryVeryVerbose);

And set one of them as default:

bslma::TestAllocator         da("default",   veryVeryVeryVerbose);
bslma::DefaultAllocatorGuard dag(&da);

Then, we create two containers, one with default comparator and another using bdlb::TransparentLess as a comparator:

bsl::set<bsl::string>                        defaultSet(&ca);
bsl::set<bsl::string, bdlb::TransparentLess> userSet(&ca);

Now, we fill the containers with the strings:

bsl::string newYorkStr         (newYork,           &sa);
bsl::string losAngelesStr      (losAngeles,        &sa);
bsl::string cityWithLongNameStr(cityWithLongName,  &sa);
bsl::string sanFranciscoStr    (sanFrancisco,      &sa);
 
defaultSet.insert(newYorkStr         );
defaultSet.insert(losAngelesStr      );
defaultSet.insert(cityWithLongNameStr);
 
userSet.insert(newYorkStr         );
userSet.insert(losAngelesStr      );
userSet.insert(cityWithLongNameStr);

Finally, we observe that the container created with TransparentLess container (userSet) allows to use string_view object as a key and does not make any implicit conversions:

bsl::string_view newYorkStrView         (newYork         );
bsl::string_view cityWithLongNameStrView(cityWithLongName);
bsl::string_view sanFranciscoStrView    (sanFrancisco    );
 
assert(userSet.end() != userSet.find(newYorkStrView         ));
assert(userSet.end() != userSet.find(cityWithLongNameStrView));
assert(userSet.end() == userSet.find(sanFranciscoStrView    ));
 
assert(0 == da.numBytesTotal());
 
assert(userSet.end() != userSet.find(newYork         ));
assert(userSet.end() != userSet.find(cityWithLongName));
assert(userSet.end() == userSet.find(sanFrancisco    ));
 
assert(0 == da.numBytesTotal());

While the container using the default comparator implicitly converts C-strings to bsl::string objects:

assert(defaultSet.end() != defaultSet.find(newYork         ));
assert(defaultSet.end() != defaultSet.find(cityWithLongName));
assert(defaultSet.end() == defaultSet.find(sanFrancisco    ));
 
assert(0 < da.numBytesTotal());