bslstl_randomaccessiterator

Macros
#define	bslstl_RandomAccessIterator   bslstl::RandomAccessIterator
	This alias is defined for backward compatibility.

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

bslstl_iterator, bslstl_forwarditerator, 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
    //! MyFixedSizeArray() = default;
        // Create a 'MyFixedSizeArray' object having the parameterized
        // 'SIZE' number of elements of the parameterized type 'VALUE'.
 
    //! MyFixedSizeArray(const MyFixedSizeArray& original) = default;
        // 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'.
 
    //! ~MyFixedSizeArray() = default;
        // 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);

Macro Definition Documentation

bslstl_RandomAccessIterator

#define bslstl_RandomAccessIterator   bslstl::RandomAccessIterator