bslalg_swaputil

Typedefs
typedef bslalg::SwapUtil	bslalg_SwapUtil
	This alias is defined for backward compatibility.

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage
    • Example 1: Using bslalg::SwapUtil::swap

Purpose

Provide a simple to use swap algorithm.

Classes

• bslalg::SwapUtil: namespace for the swap utility function.

See also

bsl_algorithm

Description

This component provides a namespace for a utility function that swaps the value of two objects of the same type. Using this utility is intended to be a simpler alternative to using the standard swap algorithm directly. The standard swap algorithm is provided in the bsl namespace in a generic form and overloaded for specific classes in the namespaces of those classes. When the swap algorithm is used, its specific implementation is supposed to be found by Argument Dependent Lookup (ADL). Finding the proper swap function with ADL requires bringing the bsl::swap into the current scope with the using directive and then calling a swap function without the namespace qualification. The swap utility static function provided by this component relieves the end-user from a need to remember those details of the proper usage of the swap algorithm.

Usage

This section illustrates intended use of this component.

Example 1: Using bslalg::SwapUtil::swap

In this example we define a type Container and use bslalg::SwapUtil to both implement a user-defined swap for Container, and swap two container objects.

We start by defining a class Container in the xyz namespace. Further we assume that Container has some expensive-to-copy data, so we provide a custom swap algorithm to efficiently swap the data between a two objects this class by defining a swap method and a swap free function.

namespace xyz {
 
class Container {
  private:
    int d_expensiveData;
 
  public:
    void swap(Container& other);
        // Swap the value of 'this' object with the value of the specified
        // 'other' object.  This method provides the no-throw
        // exception-safety guarantee.
};
 
void swap(Container& a, Container& b);
    // Swap the values of the specified 'a' and 'b' objects.  This function
    // provides the no-throw exception-safety guarantee.

Note that the free function swap is overloaded in the namespace of the class Container, which is xyz.

Next, we implemented the swap method using the bslalg::SwapUtil::swap to swap the individual data elements:

inline
void Container::swap(Container& other)
{
    bslalg::SwapUtil::swap(&d_expensiveData, &other.d_expensiveData);
 
    // Equivalent to:
    // using bsl::swap;
    // swap(d_expensiveData, other.d_expensiveData);
}

Notice that calling bslalg::SwapUtil::swap is equivalent to making the bsl::swap available in the current scope by doing using bsl::swap and making a subsequent call to an unqualified swap function.

Then, we implement the swap free function:

inline
void swap(Container& a, Container& b)
{
    a.swap(b);
}
 
}  // close namespace xyz

Finally we can use bslalg::SwapUtil::swap to swap two objects of class xyz::Container:

xyz::Container c1, c2;
 
bslalg::SwapUtil::swap(&c1, &c2);

The above code correctly calls the xyz::swap overload for the Container class.

Typedef Documentation

bslalg_SwapUtil

typedef bslalg::SwapUtil bslalg_SwapUtil