Component bslstl_forwarditerator [Package bslstl]

Provide a template to create STL-compliant forward iterators. More...

Namespaces
namespace	bslstl

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage

Purpose:

Provide a template to create STL-compliant forward iterators.

Classes:

bslstl::ForwardIterator

forward iterator template

Canonical Header:

bsl_iterator.h

See also:

Component bslstl_iterator, Component bslstl_bidirectionaliterator, Component bslstl_randomaccessiterator

Description:

This component provides an iterator adaptor that, given an implementation class defining a core set of iterator functionality, adapts it to provide an STL-compliant forward iterator interface. The set of requirements for a forward iterator is found in "Table 106: Forward iterator requirements", under the tag "[forward.iterators]". (Note that this reference is sourced in N3092, a C++0x working paper; the actual table number may vary in the actual standard.) Include bsl_iterator.h to use this component.

Usage:

Given the following "iterator-like" implementation class:

  template <class T>
  class my_IteratorImp {
    public:
      // CREATORS
      my_IteratorImp();
      my_IteratorImp(const my_IteratorImp&);
      ~my_IteratorImp();

      // An additional value-constructor should be supplied that can be
      // called by the unspecified container type, providing access to the
      // container's internal data structure that is to be iterated over.
      // This would typically be called by 'begin' and 'end'.

      // MANIPULATORS
      my_IteratorImp& operator=(const my_IteratorImp&);

      void operator++();

      // ACCESSORS
      T& operator*() const;
  };

  template <class T>
  bool operator==(const my_IteratorImp<T>& lhs,
                  const my_IteratorImp<T>& rhs);

simply add the following two typedefs to any container class that provides my_IteratorImp<T> access, and the container will have STL-compliant forward iterators:

  typedef bslstl::ForwardIterator<T, my_IteratorImp<T> > iterator;
  typedef bslstl::ForwardIterator<const T, my_IteratorImp<T> >
                                                              const_iterator;

Note that the implementation for const_iterator is my_IteratorImp<T> and not my_IteratorImp<const T>, rather the const is added to the return value of operator* by way of conversion to the first template argument.