boost/program_options/eof_iterator.hpp

0001 // Copyright Vladimir Prus 2004.
0002 // Distributed under the Boost Software License, Version 1.0.
0003 // (See accompanying file LICENSE_1_0.txt
0004 // or copy at http://www.boost.org/LICENSE_1_0.txt)
0005
0006 #ifndef BOOST_EOF_ITERATOR_VP_2004_03_12
0007 #define BOOST_EOF_ITERATOR_VP_2004_03_12
0008
0009 #include <boost/iterator/iterator_facade.hpp>
0010
0011 namespace boost {
0012
0013     /** The 'eof_iterator' class is useful for constructing forward iterators
0014         in cases where iterator extract data from some source and it's easy
0015         to detect 'eof' \-- i.e. the situation where there's no data. One
0016         apparent example is reading lines from a file.
0017
0018         Implementing such iterators using 'iterator_facade' directly would
0019         require to create class with three core operation, a couple of
0020         constructors. When using 'eof_iterator', the derived class should define
0021         only one method to get new value, plus a couple of constructors.
0022
0023         The basic idea is that iterator has 'eof' bit. Two iterators are equal
0024         only if both have their 'eof' bits set. The 'get' method either obtains
0025         the new value or sets the 'eof' bit.
0026
0027         Specifically, derived class should define:
0028
0029         1. A default constructor, which creates iterator with 'eof' bit set. The
0030         constructor body should call 'found_eof' method defined here.
0031         2. Some other constructor. It should initialize some 'data pointer' used
0032         in iterator operation and then call 'get'.
0033         3. The 'get' method. It should operate this way:
0034             - look at some 'data pointer' to see if new element is available;
0035               if not, it should call 'found_eof'.
0036             - extract new element and store it at location returned by the 'value'
0037                method.
0038             - advance the data pointer.
0039
0040         Essentially, the 'get' method has the functionality of both 'increment'
0041         and 'dereference'. It's very good for the cases where data extraction
0042         implicitly moves data pointer, like for stream operation.
0043     */
0044     template<class Derived, class ValueType>
0045     class eof_iterator : public iterator_facade<Derived, const ValueType,
0046                                                 forward_traversal_tag>
0047     {
0048     public:
0049         eof_iterator()
0050         : m_at_eof(false)
0051         {}
0052
0053     protected: // interface for derived
0054
0055         /** Returns the reference which should be used by derived
0056             class to store the next value. */
0057         ValueType& value()
0058         {
0059             return m_value;
0060         }
0061
0062         /** Should be called by derived class to indicate that it can't
0063             produce next element. */
0064         void found_eof()
0065         {
0066             m_at_eof = true;
0067         }
0068
0069
0070     private: // iterator core operations
0071 #ifdef __DCC__
0072         friend class boost::iterator_core_access;
0073 #else
0074         friend class iterator_core_access;
0075 #endif
0076
0077         void increment()
0078         {
0079             static_cast<Derived&>(*this).get();
0080         }
0081
0082         bool equal(const eof_iterator& other) const
0083         {
0084             if (m_at_eof && other.m_at_eof)
0085                 return true;
0086             else
0087                 return false;
0088         }
0089
0090         const ValueType& dereference() const
0091         {
0092             return m_value;
0093         }
0094
0095         bool m_at_eof;
0096         ValueType m_value;
0097     };
0098 }
0099
0100 #endif
0101