Component bsltf_stdtestallocator [Package bsltf]

Provide a minimal standard compliant allocator. More...

Namespaces
namespace	bsltf

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage
    • Example 1: Testing The Support for STL-Compliant Allocator

Purpose:

Provide a minimal standard compliant allocator.

Classes:

bsltf::StdTestAllocatorConfiguration	namespace to configure allocator
bsltf::StdTestAllocatorConfigurationGuard	configuration scoped guard
bsltf::StdTestAllocator	standard compliant allocator

Description:

This component provides an allocator, StdTestAllocator, that defines the minimal interface to comply with section 20.1.5 ([lib.allocator.requirements]) of the C++03 standard. This type can be used to verify that constructs designed to support a standard-compliant allocator access the allocator only through the standard-defined interface.

StdTestAllocator delegates its operations to a static bslma::Allocator (delegate allocator) that can be configured by the utilities provided in the namespace StdTestAllocatorConfiguration. StdTestAllocatorConfigurationGuard provides a scoped guard to enable temporary replacement of the delegate allocator.

Usage:

This section illustrates intended use of this component.

Example 1: Testing The Support for STL-Compliant Allocator:

In this example we will verify that a type supports the use of a STL-compliant allocator.

First we define a simple container type intended to be used with a C++03 standard compliant allocator:

  template <class TYPE, class ALLOCATOR>
  class MyContainer {
      // This container type is parameterized on a standard allocator type
      // and contains a single object, always initialized, which can be
      // replaced and accessed.

      // DATA MEMBERS
      ALLOCATOR  d_allocator;  // allocator used to supply memory (held, not
                               // owned)

      TYPE      *d_object_p;   // pointer to the contained object

    public:
      // CONSTRUCTORS
      MyContainer(const TYPE& object);
          // Create an container containing the specified 'object', using the
          // parameterized 'ALLOCATOR' to supply memory.

      ~MyContainer();
          // Destroy this container.

      // MANIPULATORS
      TYPE& object();
          // Return a reference providing modifiable access to the object
          // contained in this container.

      // ACCESSORS
      const TYPE& object() const;
          // Return a reference providing non-modifiable access to the object
          // contained in this container.
  };

Then, we define the member functions of MyContainer:

  // CREATORS
  template <class TYPE, class ALLOCATOR>
  MyContainer<TYPE, ALLOCATOR>::MyContainer(const TYPE& object)
  {
      d_object_p = d_allocator.allocate(1);
      d_allocator.construct(d_object_p, object);
  }

  template <class TYPE, class ALLOCATOR>
  MyContainer<TYPE, ALLOCATOR>::~MyContainer()
  {
      d_allocator.destroy(d_object_p);
      d_allocator.deallocate(d_object_p);
  }

  // MANIPULATORS
  template <class TYPE, class ALLOCATOR>
  TYPE& MyContainer<TYPE, ALLOCATOR>::object()
  {
      return *d_object_p;
  }

  // ACCESSORS
  template <class TYPE, class ALLOCATOR>
  const TYPE& MyContainer<TYPE, ALLOCATOR>::object() const
  {
      return *d_object_p;
  }

Now, we use StdTestAllocator to implement a simple test for MyContainer to verify it correctly uses a parameterized allocator using only the C++03 standard methods:

  bslma_TestAllocator oa("object", veryVeryVeryVerbose);
  StdTestAllocatorConfigurationGuard stag(&oa);
  {
      typedef MyContainer<int, StdTestAllocator<int> > Obj;

      Obj mX(2); const Obj& X = mX;
      assert(sizeof(int) == oa.numBytesInUse());

      assert(X.object() == 2);

      mX.object() = -10;
      assert(X.object() == -10);
  }

  assert(0 == oa.numBytesInUse());