bslstl_iterator Component

Provide basic iterator traits, adaptors, and utilities. More...

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:: Component bslstl_forwarditerator, Component bslstl_bidirectionaliterator, Component 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:

  template <class VALUE, int SIZE>
  class MyFixedSizeArray
      // 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.
  {
      // 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
          // Create a 'MyFixedSizeArray' object having the parameterized
          // 'SIZE' elements of the parameterized type 'VALUE'.

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

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

Component bslstl_iterator [Package bslstl]

Component bslstl_iterator
[Package bslstl]