BDE 4.14.0 Production release
Loading...
Searching...
No Matches
bslstl_randomaccessiterator

Macros

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

Detailed Description

Outline

Purpose

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

Classes

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:

MyArrayIterator<VALUE> > iterator;
typedef bslstl::RandomAccessIterator<const VALUE,
MyArrayIterator<VALUE> >
const_iterator;
Definition bslstl_randomaccessiterator.h:280

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