Component bslstl_randomaccessiterator [Package bslstl]

Provide a template to create STL-compliant random access iterators. More...

Namespaces
namespace	bslstl

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage
    • Example 1: Defining a Standard Compliant Random Access Iterator

Purpose:

Provide a template to create STL-compliant random access iterators.

Classes:

bslstl::RandomAccessIterator

random-access iterator template

Canonical Header:

bsl_iterator.h

See also:

Component bslstl_iterator, Component bslstl_forwarditerator, Component bslstl_bidirectionaliterator

Description:

This component provides an iterator adaptor that, given an implementation class defining a core set of iterator functionality specified in the class level documentation, adapts it to provide an STL-compliant random access iterator interface. bslstl::RandomAccessIterator meets the requirements of a random access iterator described in the C++11 standard [24.2.7] under the tag "[random.access.iterators]". Include bsl_iterator.h to use this component.

Usage:

In this section we show intended use of this component.

Example 1: Defining a Standard Compliant Random Access Iterator:

Suppose we want to create a standard compliant random access iterator for a container.

First, we define an iterator, MyArrayIterator, that meets the requirements of the IMP_ITER template parameter of RandomAccessIterator class (see class level documentation), but does not meet the full set of requirements for a random access iterator as defined by the C++ standard. Note that the following shows only the public interface required. Private members and additional methods that may be needed to implement this class are elided in this example:

  template <class VALUE>
  class MyArrayIterator {
      // This class implements the minimal requirements to implement a random
      // access iterator using 'bslstl::RandomAccessIterator'.

    public:
      // CREATORS
      MyArrayIterator();
          // Create a 'MyArrayIterator' object that does not refer to any
          // value.

      MyArrayIterator(const MyArrayIterator& original);
          // Create a 'MyArrayIterator' object having the same value
          // as the specified 'original' object.

      ~MyArrayIterator();
          // Destroy this object;

      // MANIPULATORS
      MyArrayIterator& operator=(const MyArrayIterator& rhs);
          // Assign to this object the value of the specified 'rhs' object,
          // and return a reference providing modifiable access to this
          // object.

      void operator++();
          // Increment this object to refer to the next element in an array.

      void operator--();
          // Decrement this object to refer to the previous element in an
          // array.

      void operator+=(std::ptrdiff_t n);
          // Move this object forward by the specified 'n' elements in the
          // array.

      void operator-=(std::ptrdiff_t n);
          // Move this object backward by the specified 'n' elements in the
          // array.

      // ACCESSORS
      VALUE& operator*() const;
          // Return a reference providing modifiable access to the value (of
          // the parameterized 'VALUE' type) of the element referred to by
          // this object.
  };

  template <class VALUE>
  bool operator==(const MyArrayIterator<VALUE>&,
                  const MyArrayIterator<VALUE>&);
  template <class VALUE>
  bool operator<(const MyArrayIterator<VALUE>&,
                 const MyArrayIterator<VALUE>&);
  template <class VALUE>
  std::ptrdiff_t operator-(const MyArrayIterator<VALUE>&,
                           const MyArrayIterator<VALUE>&);

Notice that MyArrayIterator does not implement a complete standard compliant random access iterator. It is missing methods such as operator+ and operator[].

Then, we define the interface for our container class template, MyFixedSizeArray. The implementation of the interface is elided for brevity:

  template <class VALUE, int SIZE>
  class MyFixedSizeArray {
      // This class implements a container that contains the parameterized
      // 'SIZE' number of elements of the parameterized 'VALUE' type.

      // DATA
      VALUE d_array[SIZE];   // storage of the container

    public:
      // PUBLIC TYPES
      typedef VALUE value_type;

Now, we use RandomAccessIterator to create a standard compliant iterator for this container:

      typedef bslstl::RandomAccessIterator<VALUE,
                                           MyArrayIterator<VALUE> > iterator;
      typedef bslstl::RandomAccessIterator<const VALUE,
                                           MyArrayIterator<VALUE> >
                                                              const_iterator;

Notice that the implementation for const_iterator is MyArrayIterator<VALUE> and not MyArrayIterator<const VALUE>.

Next, we continue defining the rest of the class.

      // CREATORS
          // Create a 'MyFixedSizeArray' object having the parameterized
          // 'SIZE' number of elements of the parameterized type 'VALUE'.

          // 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'.

          // Destroy this object.

      // MANIPULATORS
      iterator begin();
          // Return a random access iterator providing modifiable access to
          // the first valid element of this object.

      iterator end();
          // Return a random access iterator providing modifiable access to
          // the last valid element of this object.

      VALUE& operator[](std::ptrdiff_t position);
          // Return a reference providing modifiable access to the element at
          // the specified 'position'.

      // ACCESSORS
      const_iterator begin() const;
          // Return a random access iterator providing non-modifiable access
          // to the first valid element of this object.

      const_iterator end() const;
          // Return a random access iterator providing non-modifiable access
          // to the last valid element of this object.

      const VALUE& operator[](std::ptrdiff_t position) const;
          // Return a reference providing non-modifiable access to the
          // specified 'i'th element in this object.
  };

Then, we create a MyFixedSizeArray and initialize its elements:

  MyFixedSizeArray<int, 5> fixedArray;
  fixedArray[0] = 3;
  fixedArray[1] = 2;
  fixedArray[2] = 5;
  fixedArray[3] = 4;
  fixedArray[4] = 1;

Finally, to show that MyFixedSizeArray::iterator can be used as a random access iterator, we invoke a function that takes random iterators as parameters, such as std::sort, on the begin and end iterators and verify the results:

  std::sort(fixedArray.begin(), fixedArray.end());

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