Component bsls_nullptr [Package bsls]

Provide a distinct type for null pointer literals. More...

Namespaces
namespace	bsls
namespace	bsl

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Limitations
  • Usage

Purpose:

Provide a distinct type for null pointer literals.

Classes:

bsl::nullptr_t

type for function parameter to match null pointer literals

Description:

This component provides bsl::nullptr_t as a limited emulation of the C++11 type, std::nullptr_t, which can be used as a function parameter type to create an overload set where null pointer literals are handled specially. Note that this component will be deprecated, and ultimately removed, once BDE code can assume support for a C++11 compiler. On a platform that supports the language feature, a fully-conforming typedef is supplied rather than using the emulation layer.

Limitations:

This component provides a simple emulation of the C++11 facility, which cannot be expressed with a pure library solution. As such it comes with a number of limitations. The most obvious is that C++11 provides a new null pointer literal, nullptr, which is not emulated by this component. The new null pointer literal is an object of a new type, expressed by the alias nullptr_t, which this component emulates. However, as this is a library-only emulation, it does not have any preference in the overloading rules, so will be an equal-rank ambiguous match. For example, given the following overload set, a call to myFunction with a null pointer literal would be ambiguous:

  void myFunction(void *p);
  void myFunction(bsl::nullptr_t);

  int main() {
     myFunction(0);  // ERROR, ambiguous function call
  }

However, if the pointer-argument is a pointer whose type is deduced from the function call, then no pointer type can be deduced from the null pointer and this component becomes necessary.

  template<typename T>
  void myFunction(T *p);
  void myFunction(bsl::nullptr_t);

  int main() {
     myFunction(0);  // call the 'bsl::nullptr_t' method
  }

Null pointer values can be created in C++11 by creating objects of type std::nullptr_t, and then used to initialize pointer and pointer-to-member objects:

  std::nullptr_t nullLiteral = std::nullptr_t();
  int *pI = nullLiteral;

The type of a bsl::nullptr_t object cannot be used in such assignments or initializations, unless compiled on a platform that natively supports this C++11 language feature.

Usage:

This section illustrates intended use of this component.

Example 1: Constructing a "smart pointer"

• - - - - - - - - - - - - - - - - - - - - First we define a smart pointer class template, as a guard to destroy a managed object as the smart pointer leaves scope. This class will have a constructor template taking a pointer to a type potentially derived from the parameterized type of the smart pointer, and also a deletion-policy function. By capturing the most-derived type through type-deduction when the smart pointer is constructed, we can ensure the correct destructor is called, even if the destructor of the base class has not been declared as virtual. However, relying on type-deduction means we cannot pass a null pointer to this constructor, as it is not possible to deduce what type a null pointer is supposed to refer to, therefore we must use a special null pointer type, such as bsls::nullptr_t. Note that in real code we would allocate and reclaim memory using a user-specified allocator, but defining such protocols in this low level component would further distract from the nullptr usage in this example.

    template<class TARGET_TYPE>
    class ScopedPointer {
        // This class template is a guard to manage a dynamically created
        // object of the parameterized 'TARGET_TYPE'.
  
      private:
        typedef void DeleterFn(TARGET_TYPE *);  // deleter type
  
        // DATA
        TARGET_TYPE *d_target_p;    // wrapped pointer
        DeleterFn   *d_deleter_fn;  // deleter function
  
        template<class SOURCE_TYPE>
        static void defaultDeleteFn(TARGET_TYPE *ptr);
            // Destroy the specified '*ptr' by calling 'delete' on the pointer
            // cast to the parameterized 'SOURCE_TYPE*'.  It is an error to
            // instantiate this template with a 'SOURCE_TYPE' that is not
            // derived from (and cv-compatible with) 'TARGET_TYPE'.
  
       private:
        // NOT IMPLEMENTED
        ScopedPointer(const ScopedPointer&);
        ScopedPointer& operator=(const ScopedPointer&);
            // Objects of this type cannot be copied.
  
      public:
        template<class SOURCE_TYPE>
        ScopedPointer(SOURCE_TYPE *pointer,
                      DeleterFn   *fn = &defaultDeleteFn<SOURCE_TYPE>);
            // Create a 'ScopedPointer' object owning the specified 'pointer'
            // and using the specified 'fn' to destroy the owned pointer when
            // this object is destroyed.
  
        ScopedPointer(bsl::nullptr_t = 0);
            // Create an empty 'ScopedPointer' object that does not own a
            // pointer.
  
        ~ScopedPointer();
            // Destroy this 'ScopedPointer' object and the target object
            // that it owns, using the stored deleter function.
  
        // Further methods appropriate to a smart pointer, such as
        // 'operator*' and 'operator->' elided from this example.
    };
  

  Then we provide a definition for each of the methods.

    template<class TARGET_TYPE>
    template<class SOURCE_TYPE>
    void ScopedPointer<TARGET_TYPE>::defaultDeleteFn(TARGET_TYPE *ptr)
    {
        delete static_cast<SOURCE_TYPE *>(ptr);
    }
  
    template<class TARGET_TYPE>
    template<class SOURCE_TYPE>
    inline
    ScopedPointer<TARGET_TYPE>::ScopedPointer(SOURCE_TYPE *pointer,
                                              DeleterFn   *fn)
    : d_target_p(pointer)
    , d_deleter_fn(fn)
    {
    }
  
    template<class TARGET_TYPE>
    inline
    ScopedPointer<TARGET_TYPE>::ScopedPointer(bsl::nullptr_t)
    : d_target_p(0)
    , d_deleter_fn(0)
    {
    }
  
    template<class TARGET_TYPE>
    inline
    ScopedPointer<TARGET_TYPE>::~ScopedPointer()
    {
        if (d_deleter_fn) {
            d_deleter_fn(d_target_p);
        }
    }
  

  Finally, we can construct a ScopedPointer with a null pointer literal, that would otherwise be non-deducible, using our bsl::nullptr_t overload.

    void testScopedPointer()
    {
        ScopedPointer<int> x(0);
    }