bdlb_pairutil

Detailed Description

Provide support functions for bsl::pair.

Outline

• Purpose
• Classes
• Description
  • Usage
    • Example 1: Basic Usage of tie Function
    • Example 2: Adapting bsl Container For Ranges

Purpose

Provide support functions for bsl::pair.

Classes

• bdlb::PairUtil: namespace for functions working with bsl::pair

Description

This component provides the class bdlb::PairUtil, which has the following tools for working with bsl::pair:

• tie: function that is intended to be used in place of bsl::tie when the right-hand side of the assignment is a bsl::pair
• adaptForRanges: function that adapt bsl containers whose value type is a bsl::pair type to work with range adaptors
• stdPairRefAdaptor: function object that takes a bsl::pair by reference and returns a std::pair where each element is a reference to the corresponding member of the bsl::pair

Usage

This section illustrates intended use of this component.

Example 1: Basic Usage of tie Function

Suppose we need to implement a function that takes a bsl::map and stores into out-parameters the key and value corresponding to the first entry in the map. Using bsl::maps container interface, we can obtain a reference to a bsl::pair of the key and value. We can then use bdlb::PairUtil::tie to assign from both the key and value in a single expression:

/// Load into the specified `key` and the specified `value` the key and
/// value for the first entry in the specified `map` and return `true`,
/// or else fail by storing 0 and an empty string and return `false`
/// when `map` is empty.
bool getFirst(int                              *key,
              bsl::string                      *value,
              const bsl::map<int, bsl::string>& map)
{
    if (map.empty()) {
        *key = 0;
        value->clear();
        return false;                                              // RETURN
    }
    bdlb::PairUtil::tie(*key, *value) = *map.begin();
    return true;
}
 
void usageExample()
{
    bsl::map<int, bsl::string> map;
    map[30782530] = "bbi10";
 
    int         uuid;
    bsl::string username;
 
    bool result = getFirst(&uuid, &username, map);
    assert(result);
    assert(30782530 == uuid);
    assert("bbi10"  == username);
}

Example 2: Adapting bsl Container For Ranges

Let's assume that we have a bsl::map storing employee indexes and their names, and we want to get a list of employee names:

 bsl::map<int, bsl::string_view> employees{{1, "John Dow"},
                                           {2, "Jane Dow"},
                                           {3, "James Dow"}};

However, if we were to try and access the names using bsl::views::values we would see a compilation error:

auto names = employees | bsl::views::values; // does not compile auto namesIt = names.begin(); assert("John Dow" == *namesIt);

This fails to because bsl::pair, unlike the std::pair, does not model the tuple-like concept, which is a requirement of the bsl::views::values. This problem can be resolved using the bdlb::PairUtil::adaptForRanges function on the container:

 auto names = employees | bdlb::PairUtil::adaptForRanges
                                                       | bsl::views::values;
 auto namesIt = names.begin();
 assert("John Dow" == *namesIt);

And of course this function allows you to create chains of adaptors using a pipeline operator:

 const auto startsWithJa = [](bsl::string_view name) -> bool
 {
     return name.starts_with("Ja");
 };
 
 auto jaNames = employees | bdlb::PairUtil::adaptForRanges
                                         | bsl::views::values
                                         | bsl::views::filter(startsWithJa);
 assert(bsl::ranges::equal(jaNames,
                           bsl::vector<bsl::string_view>{"Jane Dow",
                                                         "James Dow"}));