Component bslalg_arraydestructionprimitives [Package bslalg]

Provide primitive algorithms that destroy arrays. More...

Namespaces
namespace	bslalg

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage
    • Example 1: Destroy Arrays of int and Integer Wrapper Objects

Purpose:

Provide primitive algorithms that destroy arrays.

Classes:

bslalg::ArrayDestructionPrimitives

namespace for array algorithms

See also:

Component bslma_destructionutil, Component bslma_constructionutil

Description:

This component provides utilities to destroy arrays with a uniform interface, but selecting a different implementation according to the traits possessed by the underlying type.

The traits under consideration by this component are:

  Trait                             Note
  -----                             -------------------------------------
   bsl::is_trivially_copyable       Expressed in English as "TYPE has the
                                    bit-wise copyable trait", or "TYPE is
                                    bit-wise copyable", this trait also
                                    implies that destructor calls can be
                                    elided with no effect on observable
                                    behavior.

Usage:

TBD: maybe fix up usage example to show with allocator In this section we show intended use of this component. Note that this component is for use by the bslstl package. Other clients should use the STL algorithms (in header <algorithm> and <memory>).

Example 1: Destroy Arrays of int and Integer Wrapper Objects:

In this example, we will use bslalg::ArrayDestructionPrimitives to destroy both an array of integer scalars and an array of MyInteger objects. Calling the destroy method on an array of integers is a no-op while calling the destroy method on an array of objects of MyInteger class invokes the destructor of each of the objects in the array.

First, we define a MyInteger class that contains an integer value:

  class MyInteger {
      // This class represents an integer value.

      int d_intValue;  // integer value

    public:
      // CREATORS
      MyInteger();
          // Create a 'MyInteger' object having integer value '0'.

      explicit MyInteger(int value);
          // Create a 'MyInteger' object having the specified 'value'.

      ~MyInteger();
          // Destroy this object.

      // ACCESSORS
      int getValue() const;
          // Return the integer value contained in this object.
  };

Then, we create an array of objects, myIntegers, of type MyInteger (note that we bsls::ObjectBuffer to allow us to safely invoke the destructor explicitly):

  bsls::ObjectBuffer<MyInteger> arrayBuffer[5];
  MyInteger *myIntegers = &arrayBuffer[0].object();
  for (int i = 0;i < 5; ++i) {
      new (myIntegers + i) MyInteger(i);
  }

Now, we define a primitive integer array:

  int scalarIntegers[] = { 0, 1, 2, 3, 4 };

Finally, we use the uniform bslalg::ArrayDestructionPrimitives:destroy method to destroy both myIntegers and scalarIntegers:

  bslalg::ArrayDestructionPrimitives::destroy(myIntegers, myIntegers + 5);
  bslalg::ArrayDestructionPrimitives::destroy(scalarIntegers,
                                              scalarIntegers + 5);