Component bslalg_containerbase [Package bslalg]

Provide a wrapper for STL allocators, respecting bslma semantics. More...

Namespaces
namespace	bslma
namespace	bslalg

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage
    • Example 1: Creating a Fixed-Size Array with bslalg::ContainerBase

Purpose:

Provide a wrapper for STL allocators, respecting bslma semantics.

Classes:

bslalg::ContainerBase

proxy class for STL-style containers

See also:

Component bslma_stdallocator

Description:

This component provides a single, mechanism class, bslalg::ContainerBase, that can used as a common base class for all STL-style containers. A container should derive from this class to take advantage of empty-base optimization when a non-'bslma' allocator is used.

Usage:

This section illustrates intended use of this component.

Example 1: Creating a Fixed-Size Array with bslalg::ContainerBase:

Suppose we would like to implement a fixed-size array that allocates memory on the heap at construction.

First, we define the interface of the container, MyFixedSizeArray, that derives from ContainerBase. The implementation is elided for brevity:

  template <class VALUE, class ALLOCATOR>
  class MyFixedSizeArray : private bslalg::ContainerBase<ALLOCATOR>
      // This class implements a container that contains a fixed number of
      // elements of the parameterized type 'VALUE' using the parameterized
      // 'ALLOCATOR' to supply memory.  The number of elements is specified
      // on construction.
  {

Notice that to use this component, a class should derive from ContainerBase in order to take advantage of empty-base optimization.

      // DATA
      VALUE     *d_array;  // head pointer to the array of elements
      const int  d_size;   // (fixed) number of elements in 'd_array'

    public:
      // CREATORS
      MyFixedSizeArray(int size, const ALLOCATOR& allocator = ALLOCATOR());
          // Create a 'MyFixedSizeArray' object having the specified 'size'
          // elements, and using the specified 'allocator' to supply memory.

      MyFixedSizeArray(const MyFixedSizeArray& original,
                       const ALLOCATOR&        allocator = ALLOCATOR());
          // Create a 'MyFixedSizeArray' object having same number of
          // elements as that of the specified 'original', the same value of
          // each element as that of corresponding element in 'original', and
          // using the specified 'allocator' to supply memory.

      ~MyFixedSizeArray();
          // Destroy this object.

      // MANIPULATORS
      VALUE& operator[](int i);
          // Return the reference of the specified 'i'th element of this
          // object.  The behavior is undefined unless 'i < size()'.

      // ACCESSORS
      int size() const;
          // Return the number of elements contained in this object.
  };

Finally, assuming we have a STL compliant allocator named Allocator, we can create a MyFixedSizeArray object and populate it with data.

  MyFixedSizeArray<int, Allocator<int> > fixedArray(3);
  fixedArray[0] = 1;
  fixedArray[1] = 2;
  fixedArray[2] = 3;

  assert(fixedArray[0] == 1);
  assert(fixedArray[1] == 2);
  assert(fixedArray[2] == 3);