bslstl_referencewrapper

Macros
#define	BSLSTL_REFRENCEWRAPPER_IS_ALIASED

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage
    • Example 1: Sorted References

Purpose

Provide copyable, assignable object wrapper for references.

Classes

• bsl::reference_wrapper: class object to hold a reference to an object

Canonical header: bsl_functional.h

Description

This component provides bsl::reference_wrapper, a reduced implementation of the standard C++2011 template of the same name, which simply wraps a reference into a copyable, assignable object to allow it to be stored in a place that cannot normally hold a reference, such as a standard container. Because a reference wrapper is convertible to its contained reference type, it can be passed to functions that take such a reference.

This component also provides the (free) helper functions bsl::ref and bsl::cref that may be used to generate reference_wrapper objects more concisely than with the constructor.

NOTE: This component is a partial implementation of the standard class, omitting support for use as a function object, and is in any case of limited usefulness in a pure C++98 environment.

Usage

This section illustrates intended use of this component.

Example 1: Sorted References

Let us suppose that we wish to handle objects that will be passed to a comparison function expecting references to the objects. Let us suppose further that these objects are large enough that we would not wish to move them around bodily as they are sorted. Note that plausible examples of uses for this component are limited in freestanding C++98.

First, let us define the large-object type:

struct Canary {
    static const int s_size = 1000;
    Canary *d_values[s_size];
    Canary();
};
 
Canary::Canary()
{
     for (int i = 0; i < s_size; ++i) {
         d_values[i] = this;
     }
}

Next, we define the comparison function:

bool operator<(Canary const& a, Canary const& b)
{
    return a.d_values[0] < b.d_values[0];
}

Finally, we define a generic function to sort two items:

template <typename T>
void sortTwoItems(T& a, T& b)
{
    if (b < a) {
        T tmp(a);
        a = b;
        b = tmp;
    }
}

We can call sortTwoItems on wrappers representing Canary objects without need to move actual, large Canary objects about. In the call to sortTwoItems, below, the operator= used in it is that of bsl::reference_wrapper<Canary>, but the operator< used is the one declared for Canary& arguments. All of the conversions needed are applied implicitly:

Canary canaries[2];
bsl::reference_wrapper<Canary> canaryA = bsl::ref(canaries[1]);
bsl::reference_wrapper<Canary> canaryB = bsl::ref(canaries[0]);
sortTwoItems(canaryA, canaryB);
 
assert(&canaryA.get() == canaries);
assert(&canaryB.get() == canaries + 1);

Macro Definition Documentation

BSLSTL_REFRENCEWRAPPER_IS_ALIASED

#define BSLSTL_REFRENCEWRAPPER_IS_ALIASED