Component bslmf_util [Package bslmf]

Provide low-level functions on bslmf types. More...

Namespaces
namespace	bslmf

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • bslmf::Util::forward
  • bslmf::Util::forwardAsReference
  • bslmf::Util::moveIfSupported
  • Usage
  • Example 1: Using bslmf::Util::forward
  • Example 2: Using bslmf::Util::forwardAsReference
  • Example 3: Using bslmf::Util::moveIfSupported

Purpose:

Provide low-level functions on bslmf types.

Classes:

bslmf::Util

utility class providing low-level functionality

Description:

This component defines a utility struct, bslmf::Util, that serves as a namespace for a suite of functions that supply low-level functionality for implementing portable generic facilities such as might be found in the C++ standard library.

bslmf::Util::forward:

The function forward emulates the C++ standard utility function std::forward with the addition that on compilers that don't support r-value references (i.e., C++03) a bslmf::MovableRef<t_T> is forwarded as a bslmf::MovableRef<t_T>. This operation is typically used via BSLS_COMPILERFEATURES_FORWARD (along with BSLS_COMPILERFEATURES_FORWARD_REF) when forwarding arguments in a generic context. See Usage.

bslmf::Util::forwardAsReference:

The function forwardAsReference, like forward, emulates the C++ standard utility function std::forward with the difference that on compilers that don't support r-value references (C++03) a bslmf::MovableRef<t_T> is forwarded as const t_T& (instead of bslmf::MovableRef<t_T>). This operation is intended to be used when forwarding a MovableRef<t_T> where that MovableRef is being supplied to a function that does not support move emulation, but will support true C++11 r-value references (e.g., bdlf::BindUtil::bind).

bslmf::Util::moveIfSupported:

The function moveIfSupported emulates the C++ standard utility function std::move with the addition that on compilers that don't support r-value references (i.e., C++03) an l-value reference is returned instead. This operation is intended to be used when moving an object to a function that does not support move emulation, but will support true C++11 r-value references (e.g., bdlf::BindUtil::bind).

Usage:

This section illustrates intended use of this component.

Example 1: Using bslmf::Util::forward:

Clients should generally not use bslmf::Util::forward directly, instead it should be used via BSLS_COMPILERFEATURES_FORWARD in conjunction with BSLS_COMPILERFEATURES_FORWARD_REF. Here we show a simple function using BSLS_COMPILERFEATURES_FORWARD:

  template <class RESULT_TYPE>
  struct FactoryUtil {

     template <class ARG_TYPE>
     RESULT_TYPE create(BSLS_COMPILERFEATURES_FORWARD_REF(ARG_TYPE) arg) {
       return RESULT_TYPE(BSLS_COMPILERFEATURES_FORWARD(ARG_TYPE, arg));
     }
  };

Notice that bslmf::Util::forward is only used in conjunction with BSLS_COMPILERFEATURES_FORWARD_REF because, in the example above, if the create function's parameter type was 'ARG_TYPE&& ' then it is a C++11-only(!) forwarding reference, and we would simply use the standard std::forward. Alternatively, if the parameter type was MovableRef<ARG_TYPE> then arg is not a forwarding-reference to be forwarded (certainly not in C++03).

Example 2: Using bslmf::Util::forwardAsReference:

Suppose we had a template facility, MyBindUtil::bind that does not support bslmf::MovableRef, but will accept true r-value references (on supported compilers). Here we use forwardAsReference to forward a supplied bslmf::MovableRef as a true r-value reference (on supporting compilers), and a const reference otherwise. Note that the definitions of MyFunction and MyBindUtil are elided and meant to represent bsl::function and bdlf::BindUtil::bind respectively:

  void doSomething(bslmf::MovableRef<Foo> value)
  {
    MyFunction f = MyBindUtil::bind(
                                bslmf::Util::forwardAsReference<Foo>(value));

    //...
  }

Note that because MyBindUtil::bind does not support MovableRef, without forwardAsReference the call to bind might either fail to compile, or worse, bind the MyFunction instance to a reference to value (rather a new object moved-from value) on C++03 platforms.

Example 3: Using bslmf::Util::moveIfSupported:

Suppose we had a template facility, MyBindUtil::bind that does not support bslmf::MovableRef, but will accept true r-value references (on supported compilers). Here we use moveIfSupported to move a supplied value if the compiler suppots r-value references, and copy it otherwise. Note that the definitions of MyFunction and MyBindUtil are elided and meant to represent bsl::function and bdlf::BindUtil::bind respectively:

  void doSomething2(Foo value)
  {
      MyFunction f = MyBindUtil::bind(bslmf::Util::moveIfSupported(value));

      //...
  }

Note that because MyBindUtil::bind does not support MovableRef, without moveIfSupported the call to bind might either fail to compile, or worse, bind the MyFunction instance to a reference to value (rather a new object moved-from value) on C++03 platforms.