bslmf_referencewrapper

Detailed Description

Provide a copyable, assignable object wrapper for references.

Outline

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

Purpose

Provide a copyable, assignable object wrapper for references.

Classes

• bsl::reference_wrapper: copyable, rebindable reference proxy

Canonical Header

bsl_functional.h

Description

This component provides bsl::reference_wrapper, a copyable, rebindable proxy for a reference to an object or function. As a reference_wrapper is an object it can be stored in a place that cannot normally hold a reference, such as an array or a Standard Library container. A reference_wrapper is implicitly convertible to its contained reference type so that it can be passed to functions that take such a reference. Unlike a native C++ reference, which is immutably bound to its target at initialization, a reference_wrapper may be rebound to refer to a different target by assignment from another reference_wrapper object.

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 provides only a partial implementation of the standard class template before C++11, omitting support for use as a function object. Further, the C++ Standard Library uses std::reference_wrapper as a special vocabulary type for several factory functions such as std::bind, std::make_pair, and std::make_tuple to embed true references in the created objects. The bsl library does not implement those functions, but uses the std implementations directly. Hence, those features are not available with our C++03 implementation.

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.

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 <class 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);

Functions
	bsl::reference_wrapper< T >::reference_wrapper (T &object)
T &	bsl::reference_wrapper< T >::get () const
	bsl::reference_wrapper< T >::operator T& () const

Function Documentation

get()

template<class T >

T & bsl::reference_wrapper< T >::get ( ) const

inline

Return a reference to the object that *this represents.

operator T&()

template<class T >

bsl::reference_wrapper< T >::operator T& ( ) const

inline

Return a reference to the object that *this represents.

reference_wrapper()

template<class T >

bsl::reference_wrapper< T >::reference_wrapper ( T &  object )

inline

Create a reference wrapper representing the specified object.