Component bdlat_arrayiterators [Package bdlat]

Provide iterator support for bdlat_ArrayFunction-conformant types. More...

Namespaces
namespace	bdlat_ArrayIterators

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Thread Safety
  • Usage

Purpose:

Provide iterator support for bdlat_ArrayFunction-conformant types.

Classes:

bdlat_ArrayIterators::BackInsertIterator

class for appending to arrays

See also:

Component bdlat_arrayfunctions

Description:

This component provides a namespace bdlat_ArrayIterators that contains definitions for the bdlat_ArrayIterators::BackInsertIterator class template and the backInserter convenience function. Additional iterator types may be added in the future.

BackInsertIterator<ARRAY_TYPE> is an iterator type which, when used in an expression like "*i++ = v", appends the value v to the end of the ARRAY_TYPE object used to construct the iterator, i. It meets the requirements of an STL output iterator and it can be instantiated for any type that meets the requirements described in bdlat_arrayfunctions. BackInsertIterator is similar to the standard bsl::back_insert_iterator class template, which works for STL sequence containers.

The backInserter function template takes a parameter of type pointer-to-'ARRAY_TYPE', where ARRAY_TYPE is a type that conforms to the interface described in the bdlat_arrayfunctions component, and returns an object of type BackInsertIterator<ARRAY_TYPE>. It is a convenience function for creating a BackInsertIterator without declaring its exact type. The backInserter function is similar to the standard bsl::back_inserter template function, which works for STL sequence containers. In fact, backInserter is specialized for bsl::vector so that it returns an bsl::back_insert_iterator, just like bsl::back_inserter does.

Thread Safety:

A BackInsertIterator contains a pointer to an array object and multiple backInsertIterator objects may point to the same array object. It is safe to access or modify two BackInsertIterator objects simultaneously, each from a separate thread, if they each refer to a different array object. It is safe to access a single BackInsertIterator object simultaneously from two or more separate threads, provided no other thread is simultaneously modifying the iterator or its referenced array. It is not safe to access or modify a BackInsertIterator object in one thread while another thread modifies the same iterator, its referenced array object, or another iterator referring to the same array.

Usage:

To use the facilities in this component, you must of course include the header file:

  #include <bdlat_arrayiterators.h>

The main use of the facilities in this component is for creating generic algorithms. The following generic function appends a few integers to the end of an object of type ARRAY that adheres to the bdlat_ArrayFunctions interface. It starts by creating a BackInsertIterator:

  template <typename ARRAY>
  void appendSome(ARRAY *arrayObj)
  {
      bdlat_ArrayIterators::BackInsertIterator<ARRAY> it(arrayObj);

Now, using the "*i++ = v" idiom, append the numbers 5 and 4 to the array object:

      *it++ = 5;
      *it++ = 4;

Alternatively, one can use the iterator in a standard algorithm. For example, the following code appends the numbers 3, 2, and 1 to the array object:

      const int VALUES[] = { 3, 2, 1 };
      const int NUM_VALUES = sizeof(VALUES) / sizeof(VALUES[0]);
      bsl::copy(VALUES, VALUES + NUM_VALUES, it);
  }

An alternative implementation of appendSome would use backInserter to create an iterator without declaring its exact type. Note that, in this case, we do not create a variable it, but simply pass the iterator to a standard algorithm:

  template <typename ARRAY>
  void appendSome2(ARRAY *arrayObj)
  {
      const int VALUES[] = { 5, 4, 3, 2, 1 };
      const int NUM_VALUES = sizeof(VALUES) / sizeof(VALUES[0]);
      bsl::copy(VALUES, VALUES + NUM_VALUES,
                bdlat_ArrayIterators::backInserter(arrayObj));
  }

In our main program, we need to construct an array that adheres to the bdlat_arrayfunctions interface:

  #include <vector>

  int main()
  {
      typedef bsl::vector<int> my_IntArrayType;

The result of calling appendSome is that the elements 5, 4, 3, 2 and 1 are appended to the array:

      my_IntArrayType array1;
      appendSome(&array1);
      assert(5 == array1[0]);
      assert(4 == array1[1]);
      assert(3 == array1[2]);
      assert(2 == array1[3]);
      assert(1 == array1[4]);

The result of calling appendSome2 is the same:

      my_IntArrayType array2;
      appendSome2(&array2);
      assert(array2 == array1);

      return 0;
  }