bslstl_iterator

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage
    • Example 1: Using Iterators to Traverse a Container

Purpose

Provide basic iterator traits, adaptors, and utilities.

Classes

• bsl::iterator_traits: information about iterator associated types
• bsl::reverse_iterator: bring in std::reverse_iterator
• bsl::distance: global function to calculate iterator distance

Canonical header: bsl_iterator.h

See also

bslstl_forwarditerator, bslstl_bidirectionaliterator, bslstl_randomaccessiterator, C++ Standard

Description

This component is for internal use only. Please include <bsl_iterator.h> directly. This component provides the facilities of the iterators library from the C++ Standard, including iterator primitives (24.4), iterator adaptors (24.5), and stream iterators (24.6).

Usage

In this section we show intended use of this component.

Example 1: Using Iterators to Traverse a Container

In this example, we will use the bsl::iterator and bsl::reverse_iterator to traverse an iterable container type.

Suppose that we have an iterable container template type MyFixedSizeArray. An instantiation of MyFixedSizeArray represents an array having fixed number of elements, which is a parameter passed to the class constructor during construction. A traversal of MyFixedSizeArray can be accomplished using basic iterators (pointers) as well as reverse iterators.

First, we create a elided definition of the template container class, MyFixedSizeArray, which provides mutable and constant iterators of template type bsl::iterator and reverse_iterator :

/// This is a container that contains a fixed number of elements.  The
/// number of elements is specified upon construction and can not be
/// changed afterwards.
template <class VALUE, int SIZE>
class MyFixedSizeArray
{
    // DATA
    VALUE d_array[SIZE];  // storage of the container
 
  public:
    // PUBLIC TYPES
    typedef VALUE value_type;

Here, we define mutable and constant iterators and reverse iterators:

    typedef VALUE                                 *iterator;
    typedef VALUE const                           *const_iterator;
    typedef bsl::reverse_iterator<iterator>        reverse_iterator;
    typedef bsl::reverse_iterator<const_iterator>  const_reverse_iterator;
 
    // CREATORS
    //! MyFixedSizeArray() = default;
        // Create a `MyFixedSizeArray` object having the parameterized
        // `SIZE` 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 `rhs`, and the same value of
        // each element as that of corresponding element in `rhs`.
 
    //! ~MyFixedSizeArray() = default;
        // Destroy this object.

Now, we define the begin and end methods to return basic iterators (VALUE* and const VALUE*), and the rbegin and rend methods to return reverse iterators (bsl::reverse_iterator<VALUE*> and bsl::reverse_iterator<const VALUE*>) type:

    // MANIPULATORS
    iterator begin();
        // Return the basic iterator providing modifiable access to the
        // first valid element of this object.
 
    iterator end();
        // Return the basic iterator providing modifiable access to the
        // position one after the last valid element of this object.
 
    reverse_iterator rbegin();
        // Return the reverse iterator providing modifiable access to the
        // last valid element of this object.
 
    reverse_iterator rend();
        // Return the reverse iterator providing modifiable access to the
        // position one before the first valid element of this object.
 
    VALUE& operator[](int i);
        // Return the reference providing modifiable access of the
        // specified `i`th element of this object.
 
    // ACCESSORS
    const_iterator begin() const;
        // Return the basic iterator providing non-modifiable access to the
        // first valid element of this object.
 
    const_iterator end() const;
        // Return the basic iterator providing non-modifiable access to the
        // position one after the last valid element of this object.
 
    const_reverse_iterator rbegin() const;
        // Return the reverse iterator providing non-modifiable access to
        // the last valid element of this object.
 
    const_reverse_iterator rend() const;
        // Return the reverse iterator providing non-modifiable access to
        // the position one before the first valid element of this object.
 
    int size() const;
        // Return the number of elements contained in this object.
 
    const VALUE& operator[](int i) const;
        // Return the reference providing non-modifiable access of the
        // specified `i`th element of this object.
};
 
// ...

Then, we create a MyFixedSizeArray and initialize its elements:

// Create a fixed array having five elements.
 
MyFixedSizeArray<int, 5> fixedArray;
 
// Initialize the values of each element in the fixed array.
 
for (int i = 0; i < fixedArray.size(); ++i) {
    fixedArray[i] = i + 1;
}

Next, we generate reverse iterators using the rbegin and rend methods of the fixed array object:

MyFixedSizeArray<int, 5>::reverse_iterator rstart  = fixedArray.rbegin();
MyFixedSizeArray<int, 5>::reverse_iterator rfinish = fixedArray.rend();

Now, we note that we could have acquired the iterators and container size by calling the appropriate free functions:

assert(rstart  == bsl::rbegin(fixedArray));
assert(rfinish == bsl::rend(  fixedArray));
 
assert(fixedArray.size() == bsl::size(fixedArray));
assert(rfinish - rstart  == bsl::ssize(fixedArray));

Finally, we traverse the fixed array again in reverse order using the two generated reverse iterators:

printf("Traverse array using reverse iterator:\n");
while (rstart != rfinish) {
    printf("\tElement: %d\n", *rstart);
    ++rstart;
}

The preceding loop produces the following output on stdout:

Traverse array using reverse iterator:
     Element: 5
     Element: 4
     Element: 3
     Element: 2
     Element: 1