diff --git a/development/boost/iterator_categories.hpp b/development/boost/iterator_categories.hpp deleted file mode 100644 index 138a5be..0000000 --- a/development/boost/iterator_categories.hpp +++ /dev/null @@ -1,159 +0,0 @@ -#ifndef BOOST_ITERATOR_CATEGORIES_HPP -#define BOOST_ITERATOR_CATEGORIES_HPP - -#include -#include -#include -#include -#include - -namespace boost { - - // Return Type Categories - struct readable_iterator_tag { }; - struct writable_iterator_tag { }; - struct swappable_iterator_tag { }; - struct mutable_lvalue_iterator_tag : - virtual public writable_iterator_tag, - virtual public readable_iterator_tag { }; - struct constant_lvalue_iterator_tag : - virtual public readable_iterator_tag { }; - - // Traversal Categories - struct forward_traversal_tag { }; - struct bidirectional_traversal_tag : public forward_traversal_tag { }; - struct random_access_traversal_tag : public bidirectional_traversal_tag { }; - - struct error_iterator_tag { }; - - // Inherit from iterator_base if your iterator defines its own - // return_category and traversal_category. Otherwise, the "old style" - // iterator category will be mapped to the return_category and - // traversal_category. - struct new_iterator_base { }; - - namespace detail { - - struct return_category_from_nested_type { - template struct bind { - typedef typename Iterator::return_category type; - }; - }; - - struct traversal_category_from_nested_type { - template struct bind { - typedef typename Iterator::traversal_category type; - }; - }; - - template - struct choose_lvalue_return { - typedef typename ct_if::value, - boost::constant_lvalue_iterator_tag, - boost::mutable_lvalue_iterator_tag>::type type; - }; - - - template - struct iter_category_to_return { - typedef typename ct_if< - is_convertible::value, - typename choose_lvalue_return::type, - typename ct_if< - is_convertible::value, - boost::readable_iterator_tag, - typename ct_if< - is_convertible::value, - boost::writable_iterator_tag, - boost::error_iterator_tag - >::type - >::type - >::type type; - }; - - template - struct iter_category_to_traversal { - typedef typename ct_if< - is_convertible::value, - random_access_traversal_tag, - typename ct_if< - is_convertible::value, - bidirectional_traversal_tag, - forward_traversal_tag - >::type - >::type type; - }; - - struct return_category_from_old_traits { - template class bind { - typedef boost::detail::iterator_traits OldTraits; - typedef typename OldTraits::iterator_category Cat; - typedef typename OldTraits::value_type value_type; - public: - typedef iter_category_to_return::type type; - }; - }; - - struct traversal_category_from_old_traits { - template class bind { - typedef boost::detail::iterator_traits OldTraits; - typedef typename OldTraits::iterator_category Cat; - public: - typedef iter_category_to_traversal::type type; - }; - }; - - template - class choose_return_category { - typedef typename ct_if::value, - return_category_from_nested_type, - return_category_from_old_traits>::type Choice; - public: - typedef typename Choice:: template bind::type type; - }; - - template - class choose_traversal_category { - typedef typename ct_if::value, - traversal_category_from_nested_type, - traversal_category_from_old_traits>::type Choice; - public: - typedef typename Choice:: template bind::type type; - }; - - } // namespace detail - - template - struct return_category { - typedef typename detail::choose_return_category::type type; - }; - - - template - struct traversal_category { - typedef typename detail::choose_traversal_category::type type; - }; - -#if !defined(BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION) - - template - struct return_category - { - typedef typename ct_if::value, - constant_lvalue_iterator_tag, - mutable_lvalue_iterator_tag>::type type; - }; - - template - struct traversal_category - { - typedef random_access_traversal_tag type; - }; - -#endif - -} // namespace boost - -#endif // BOOST_ITERATOR_CATEGORIES_HPP diff --git a/development/boost/iterator_concepts.hpp b/development/boost/iterator_concepts.hpp deleted file mode 100644 index a30ff17..0000000 --- a/development/boost/iterator_concepts.hpp +++ /dev/null @@ -1,172 +0,0 @@ -#ifndef BOOST_ITERATOR_CONCEPTS_HPP -#define BOOST_ITERATOR_CONCEPTS_HPP - -#include -#include -#include -#include - -namespace boost_concepts { - // Used a different namespace here (instead of "boost") so that the - // concept descriptions do not take for granted the names in - // namespace boost. - - - //=========================================================================== - // Iterator Access Concepts - - template - class ReadableIteratorConcept { - public: - typedef typename std::iterator_traits::value_type value_type; - typedef typename std::iterator_traits::reference reference; - typedef typename boost::return_category::type return_category; - - void constraints() { - boost::function_requires< boost::SGIAssignableConcept >(); - boost::function_requires< boost::EqualityComparableConcept >(); - boost::function_requires< - boost::DefaultConstructibleConcept >(); - - BOOST_STATIC_ASSERT((boost::is_convertible::value)); - - reference r = *i; // or perhaps read(x) - value_type v(r); - boost::ignore_unused_variable_warning(v); - } - Iterator i; - }; - - template - class WritableIteratorConcept { - public: - typedef typename boost::return_category::type return_category; - - void constraints() { - boost::function_requires< boost::SGIAssignableConcept >(); - boost::function_requires< boost::EqualityComparableConcept >(); - boost::function_requires< - boost::DefaultConstructibleConcept >(); - - BOOST_STATIC_ASSERT((boost::is_convertible::value)); - - *i = v; // a good alternative could be something like write(x, v) - } - ValueType v; - Iterator i; - }; - - template - class ConstantLvalueIteratorConcept { - public: - typedef typename std::iterator_traits::value_type value_type; - typedef typename std::iterator_traits::reference reference; - typedef typename boost::return_category::type return_category; - - void constraints() { - boost::function_requires< ReadableIteratorConcept >(); - - BOOST_STATIC_ASSERT((boost::is_convertible::value)); - - BOOST_STATIC_ASSERT((boost::is_same::value)); - - reference v = *i; - boost::ignore_unused_variable_warning(v); - } - Iterator i; - }; - - template - class MutableLvalueIteratorConcept { - public: - typedef typename std::iterator_traits::value_type value_type; - typedef typename std::iterator_traits::reference reference; - typedef typename boost::return_category::type return_category; - - void constraints() { - boost::function_requires< ReadableIteratorConcept >(); - boost::function_requires< - WritableIteratorConcept >(); - - BOOST_STATIC_ASSERT((boost::is_convertible::value)); - - BOOST_STATIC_ASSERT((boost::is_same::value)); - - reference v = *i; - boost::ignore_unused_variable_warning(v); - } - Iterator i; - }; - - //=========================================================================== - // Iterator Traversal Concepts - - template - class ForwardIteratorConcept { - public: - typedef typename boost::traversal_category::type traversal_category; - - void constraints() { - boost::function_requires< boost::SGIAssignableConcept >(); - boost::function_requires< boost::EqualityComparableConcept >(); - boost::function_requires< - boost::DefaultConstructibleConcept >(); - - BOOST_STATIC_ASSERT((boost::is_convertible::value)); - ++i; - (void)i++; - } - Iterator i; - }; - - template - class BidirectionalIteratorConcept { - public: - typedef typename boost::traversal_category::type traversal_category; - - void constraints() { - boost::function_requires< ForwardIteratorConcept >(); - - BOOST_STATIC_ASSERT((boost::is_convertible::value)); - - --i; - (void)i--; - } - Iterator i; - }; - - template - class RandomAccessIteratorConcept { - public: - typedef typename boost::traversal_category::type traversal_category; - typedef typename std::iterator_traits::difference_type - difference_type; - - void constraints() { - boost::function_requires< BidirectionalIteratorConcept >(); - - BOOST_STATIC_ASSERT((boost::is_convertible::value)); - - i += n; - i = i + n; - i = n + i; - i -= n; - i = i - n; - n = i - j; - } - difference_type n; - Iterator i, j; - }; - -} // namespace boost_concepts - - -#endif // BOOST_ITERATOR_CONCEPTS_HPP diff --git a/development/libs/iterator/concept_tests.cpp b/development/libs/iterator/concept_tests.cpp deleted file mode 100644 index f75f311..0000000 --- a/development/libs/iterator/concept_tests.cpp +++ /dev/null @@ -1,73 +0,0 @@ -#include -#include - -struct new_iterator - : public boost::iterator, - public boost::new_iterator_base -{ - typedef boost::random_access_traversal_tag traversal_category; - typedef boost::mutable_lvalue_iterator_tag return_category; - - int& operator*() const { return *m_x; } - new_iterator& operator++() { return *this; } - new_iterator operator++(int) { return *this; } - new_iterator& operator--() { return *this; } - new_iterator operator--(int) { return *this; } - new_iterator& operator+=(std::ptrdiff_t) { return *this; } - new_iterator operator+(std::ptrdiff_t) { return *this; } - new_iterator& operator-=(std::ptrdiff_t) { return *this; } - std::ptrdiff_t operator-(const new_iterator&) const { return 0; } - new_iterator operator-(std::ptrdiff_t) const { return *this; } - bool operator==(const new_iterator&) const { return false; } - bool operator!=(const new_iterator&) const { return false; } - bool operator<(const new_iterator&) const { return false; } - int* m_x; -}; -new_iterator operator+(std::ptrdiff_t, new_iterator x) { return x; } - -struct old_iterator - : public boost::iterator -{ - int& operator*() const { return *m_x; } - old_iterator& operator++() { return *this; } - old_iterator operator++(int) { return *this; } - old_iterator& operator--() { return *this; } - old_iterator operator--(int) { return *this; } - old_iterator& operator+=(std::ptrdiff_t) { return *this; } - old_iterator operator+(std::ptrdiff_t) { return *this; } - old_iterator& operator-=(std::ptrdiff_t) { return *this; } - old_iterator operator-(std::ptrdiff_t) const { return *this; } - std::ptrdiff_t operator-(const old_iterator&) const { return 0; } - bool operator==(const old_iterator&) const { return false; } - bool operator!=(const old_iterator&) const { return false; } - bool operator<(const old_iterator&) const { return false; } - int* m_x; -}; -old_iterator operator+(std::ptrdiff_t, old_iterator x) { return x; } - -int -main() -{ -#if !defined(BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION) - boost::function_requires< - boost_concepts::MutableLvalueIteratorConcept >(); - boost::function_requires< - boost_concepts::RandomAccessIteratorConcept >(); - - boost::function_requires< - boost_concepts::ConstantLvalueIteratorConcept >(); - boost::function_requires< - boost_concepts::RandomAccessIteratorConcept >(); -#endif - - boost::function_requires< - boost_concepts::MutableLvalueIteratorConcept >(); - boost::function_requires< - boost_concepts::RandomAccessIteratorConcept >(); - - boost::function_requires< - boost_concepts::MutableLvalueIteratorConcept >(); - boost::function_requires< - boost_concepts::RandomAccessIteratorConcept >(); - return 0; -} diff --git a/development/libs/iterator/iterator_categories.htm b/development/libs/iterator/iterator_categories.htm deleted file mode 100644 index 83c29e5..0000000 --- a/development/libs/iterator/iterator_categories.htm +++ /dev/null @@ -1,160 +0,0 @@ - - - - Boost Iterator Traits - - - -C++ Boost -
- -

Boost Iterator Category Traits

-Header boost/iterator_categories.hpp - -

-The boost::traversal_category and -boost::return_category traits classes provides access to the -category tags for iterators that model the Boost Iterator Concepts, which are a -replacement for the iterator requirements in the C++ standard. The -other associated types of the Boost iterator concepts are accessed -through the std::iterator_traits class. - -

    -
  • traversal_category<Iter>::type   Can the iterator go forward, backward, etc.? -
  • return_category<Iter>::type   Is the iterator read or write only? - Is the dereferenced type an lvalue? -
- -

-An important feature of the boost::traversal_category and -boost::return_category classes is that they are backwards -compatible, i.e., they automatically work for iterators for which -there are valid definitions of std::iterator_traits. The old -iterator_category is mapped to the appropriate traversal and -return categories. - -

-When creating a new iterator type that is meant to work with -boost::traversal_category and -boost::return_category, you can either create a -specialization of these classes for your iterator type, or you can -provide all the necessary associated types as nested typedefs. In -this case, your iterator class will need to inherit from -new_iterator_base to let the category traits know -that it will be able to find typedefs for traversal_category -and return_category in you iterator class. - - -Each of the new iterator requirements will need a category tag. - -

-namespace boost {
-
-  // Return Type Categories
-  struct readable_iterator_tag { };
-  struct writable_iterator_tag { };
-  struct swappable_iterator_tag { };
-  struct mutable_lvalue_iterator_tag : virtual public writable_iterator_tag,
-    virtual public readable_iterator_tag { };
-  struct constant_lvalue_iterator_tag : public readable_iterator_tag { };
-
-  // Traversal Categories
-  struct forward_traversal_tag { };
-  struct bidirectional_traversal_tag : public forward_traversal_tag { };
-  struct random_access_traversal_tag : public bidirectional_traversal_tag { };
-
-}
-
- -

-The following is pseudo-code for the iterator category traits classes. - -

-namespace boost {
-
-  // Inherit from iterator_base if your iterator defines its own
-  // return_category and traversal_category. Otherwise, the "old style"
-  // iterator category will be mapped to the return_category and
-  // traversal_category.
-  struct new_iterator_base { };
-
-  template <typename Iterator>
-  struct return_category
-  {
-    // Pseudo-code
-    if (Iterator inherits from new_iterator_base) {
-      typedef typename Iterator::return_category type;
-    } else {
-      typedef std::iterator_traits<Iterator> OldTraits;
-      typedef typename OldTraits::iterator_category Cat;
-      if (Cat inherits from std::forward_iterator_tag)
-	if (is-const(T))
-	  typedef boost::constant_lvalue_iterator_tag type;
-	else
-	  typedef boost::mutable_lvalue_iterator_tag type;
-      else if (Cat inherits from std::input_iterator_tag)
-	typedef boost::readable_iterator_tag type;
-      else if (Cat inherits from std::output_iterator_tag)
-	typedef boost::writable_iterator_tag type;
-    }
-  };
-
-  template <typename T>
-  struct return_category<T*>
-  {
-    // Pseudo-code
-    if (is-const(T))
-      typedef boost::constant_lvalue_iterator_tag type;
-    else
-      typedef boost::mutable_lvalue_iterator_tag type;
-  };
-
-  template <typename Iterator>
-  struct traversal_category
-  {
-    // Pseudo-code
-    if (Iterator inherits from new_iterator_base) {
-      typedef typename Iterator::traversal_category type;
-    } else {
-      typedef std::iterator_traits<Iterator> OldTraits;
-      typedef typename OldTraits::iterator_category Cat;
-
-      if (Cat inherits from std::random_access_iterator_tag)
-	typedef boost::random_access_traversal_tag type;
-      else if (Cat inherits from std::bidirectional_iterator_tag)
-	typedef boost::bidirectional_traversal_tag type;
-      else if (Cat inherits from std::forward_iterator_tag)
-	typedef boost::forward_traversal_tag type;
-    }
-  };
-
-  template <typename T>
-  struct traversal_category<T*>
-  {
-    typedef boost::random_access_traversal_tag type;
-  };
-
-}
-
- -
-
jeremy siek
- - -Last modified: Mon Mar 19 12:59:30 EST 2001 - - - diff --git a/development/libs/iterator/iterator_concepts.fig b/development/libs/iterator/iterator_concepts.fig deleted file mode 100644 index 198205e..0000000 --- a/development/libs/iterator/iterator_concepts.fig +++ /dev/null @@ -1,37 +0,0 @@ -#FIG 3.2 -Landscape -Center -Inches -Letter -100.00 -Single --2 -1200 2 -6 150 2325 4275 4350 -2 1 0 1 0 7 100 0 -1 4.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 1725 4050 1725 3450 -2 1 0 1 0 7 100 0 -1 4.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 1725 3150 1725 2550 -4 0 0 100 0 19 18 0.0000 4 210 3180 375 2550 ForwardTraversalIterator\001 -4 0 0 100 0 19 18 0.0000 4 210 3765 225 3450 BidirectionalTraversalIterator\001 -4 0 0 100 0 19 18 0.0000 4 210 4125 150 4350 RandomAccessTraversalIterator\001 --6 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 4800 3600 4800 2400 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 6900 3000 5400 2400 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 6900 3000 7500 2400 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 6900 3000 9075 2475 -4 0 0 100 0 19 18 0.0000 4 210 2040 6600 2400 WritableIterator\001 -4 0 0 100 0 19 18 0.0000 4 210 2145 3900 2400 ReadableIterator\001 -4 0 0 50 0 19 18 0.0000 4 210 2835 5700 3300 MutableLvalueIterator\001 -4 0 0 50 0 19 18 0.0000 4 270 2355 9075 2400 SwappableIterator\001 -4 0 0 50 0 19 18 0.0000 4 210 2970 3825 3900 ConstantLvalueIterator\001 diff --git a/development/libs/iterator/iterator_concepts.gif b/development/libs/iterator/iterator_concepts.gif deleted file mode 100644 index bac35c7..0000000 Binary files a/development/libs/iterator/iterator_concepts.gif and /dev/null differ diff --git a/development/libs/iterator/iterator_concepts.htm b/development/libs/iterator/iterator_concepts.htm deleted file mode 100644 index f2f8dcd..0000000 --- a/development/libs/iterator/iterator_concepts.htm +++ /dev/null @@ -1,663 +0,0 @@ - - - - -Iterator Concepts - -C++ Boost - -
- - -

Iterator Concepts

- -

The standard iterator categories and requirements are flawed because -they use a single hierarchy of requirements to address two orthogonal -issues: iterator traversal and dereference return -type. The current iterator requirement hierarchy is mainly -geared towards iterator traversal (hence the category names), while -requirements that address dereference return type sneak in at various -places. - -

-The iterator requirements should be separated into two hierarchies. -One set of concepts handles the return type semantics: -

- -The other set of concepts handles iterator traversal: - - - -The current Input Iterator and Output Iterator requirements will -continue to be used as is. Note that Input Iterator implies Readable -Iterator and Output Iterator implies Writable Iterator. - -

-Note: we considered defining a Single-Pass Iterator, which could be -combined with Readable or Writable Iterator to replace the Input and -Output Iterator requirements. We rejected this idea because there are -some differences between Input and Output Iterators that make it hard -to merge them: for example Input Iterator requires Equality Comparable -while Output Iterator does not. - - -

-
- - - -
Figure 1: -The iterator concepts and refinement relationships. -
-
-

- - -

Relationship with the standard iterator concepts

- -

-std::Input Iterator implies boost::ReadableIterator. - -

-std::Output Iterator implies boost::Writable Iterator. - -

-std::Forward Iterator refines boost::Forward Iterator and -boost::Constant Lvalue Iterator or boost::Mutable Lvalue Iterator. - -

-std::Bidirectional Iterator refines boost::Bidirectional Iterator and -boost::Constant Lvalue Iterator or boost::Mutable Lvalue Iterator. - -

-std::Random Access Iterator refines boost::Random Access Iterator and -boost::Constant Lvalue Iterator or boost::Mutable Lvalue Iterator. - - -

Notation

- - - - - - - - - - - - - - - - - -
XThe iterator type.
TThe value type of X, i.e., std::iterator_traits<X>::value_type.
x, yAn object of type X.
tAn object of type T.
- -

- -

- - -

-Readable Iterator -

- -A Readable Iterator is an iterator that dereferences to produce an -rvalue that is convertible to the value_type of the -iterator. - -

Associated Types

- - - - - - - - - - - - - - - - - - - - - -
Value typestd::iterator_traits<X>::value_typeThe type of the objects pointed to by the iterator.
Reference typestd::iterator_traits<X>::reference - The return type of dereferencing the iterator. This - type must be convertible to T. -
Return Categorystd::return_category<X>::type - A type convertible to std::readable_iterator_tag -
- -

Refinement of

- -Copy Constructible - -

Valid expressions

- - - - - - - - - - - - - - - -
NameExpressionType requirementsReturn type
Dereference*x std::iterator_traits<X>::reference
Member accessx->mT is a type with a member named m. -If m is a data member, the type of m. -If m is a member function, the return type of m. -
- -

- -

- - -

-Writable Iterator -

- -A Writable Iterator is an iterator that can be used to store a value -using the dereference-assignment expression. - -

Definitions

- -If x is an Writable Iterator of type X, then the -expression *x = a; stores the value a into -x. Note that operator=, like other C++ functions, -may be overloaded; it may, in fact, even be a template function. In -general, then, a may be any of several different types. A -type A belongs to the set of value types of X -if, for an object a of type A, *x = a; is -well-defined and does not require performing any non-trivial -conversions on a. - -

Associated Types

- - - - - - - - - -
Return Categorystd::return_category<X>::type - A type convertible to std::writable_iterator_tag -
- - - -

Refinement of

- -Copy Constructible - -

Valid expressions

- - - - - - - - - - -
NameExpressionReturn type
Dereference assignment*x = aunspecified
- -

- - -

- - -

-Swappable Iterator -

- -A Swappable Iterator is an iterator whose dereferenced values can be -swapped. - -

-Note: the requirements for Swappable Iterator are dependent on the -issues surrounding std::swap() being resolved. Here we assume -that the issue will be resolved by allowing the overload of -std::swap() for user-defined types. - -

-Note: Readable Iterator and Writable Iterator combined implies -Swappable Iterator because of the fully templated -std::swap(). However, Swappable Iterator does not imply -Readable Iterator nor Writable Iterator. - -

Associated Types

- - - - - - - - - -
Return Categorystd::return_category<X>::type - A type convertible to std::swappable_iterator_tag -
- - -

Valid expressions

- -Of the two valid expressions listed below, only one OR the -other is required. If std::iter_swap() is overloaded for -X then std::swap() is not required. If -std::iter_swap() is not overloaded for X then the -default (fully templated) version is used, which will call -std::swap() (this means changing the current requirements for -std::iter_swap()). - -

- - - - - - - - - - - - - - - - - -
NameExpressionReturn type
Iterator Swapstd::iter_swap(x, y)void
Dereference and Swapstd::swap(*x, *y)void
- -

- - -

- - -

-Constant Lvalue Iterator -

- -A Constant Lvalue Iterator is an iterator that dereferences to produce a -const reference to the pointed-to object, i.e., the associated -reference type is const T&. Changing the value -of or destroying an iterator that models Constant Lvalue Iterator does -not invalidate pointers and references previously obtained from that -iterator. - - -

Refinement of

- -Readable Iterator - -

Associated Types

- - - - - - - - - - - - - - - - - -
Reference typestd::iterator_traits<X>::reference - The return type of dereferencing the iterator, which must be - const T&. -
Return Categorystd::return_category<X>::type - A type convertible to std::constant_lvalue_iterator_tag -
- - - -

- -

- - -

-Mutable Lvalue Iterator -

- -A Mutable Lvalue Iterator is an iterator that dereferences to produce a -reference to the pointed-to object. The associated reference -type is T&. Changing the value of or destroying an -iterator that models Mutable Lvalue Iterator does not invalidate -pointers and references previously obtained from that iterator. - -

Refinement of

- -Readable Iterator, -Writable Iterator, -and Swappable Iterator. - - - -

Associated Types

- - - - - - - - - - - - - - - - - -
Reference typestd::iterator_traits<X>::referenceThe return type of dereferencing the iterator, which must be - T&.
Return Categorystd::return_category<X>::type - A type convertible to std::mutable_lvalue_iterator_tag -
- - - -

-

- - -

-Forward Traversal Iterator -

- -The Forward Iterator is an iterator that can be incremented. Also, it -is permissible to make multiple passes through the iterator's range. - -

Refinement of

- -Copy Constructible, -Assignable, -Default Constructible, and -Equality Comparable - - -

Associated types

- - - - - - - - - - - - - - -
Difference Typestd::iterator_traits<X>::difference_type - A signed integral type used for representing distances - between iterators that point into the same range. -
Traversal Categorystd::traversal_category<X>::type - A type convertible to std::forward_traversal_tag -
- -

Valid expressions

- - - - - - - - - - - - - - -
NameExpressionType requirementsReturn type
Preincrement++i X&
Postincrementi++ convertible to const X&
- -

-

- - -

-Bidirectional Traversal Iterator -

- -An iterator that can be incremented and decremented. - -

Refinement of

- -Forward Traversal Iterator - -

Associated types

- - - - - - - -
Traversal Categorystd::traversal_category<X>::type - A type convertible to std::bidirectional_traversal_tag -
- -

Valid expressions

- - - - - - - - - - - - -
NameExpressionType requirementsReturn type
Predecrement--i X&
Postdecrementi-- convertible to const X&
- -

-

- - -

-Random Access Traversal Iterator -

- -An iterator that provides constant-time methods for moving forward and -backward in arbitrary-sized steps. - -

Refinement of

- -Bidirectional Traversal Iterator and -Less Than Comparable where < is a total ordering - -

Associated types

- - - - - - - -
Traversal Categorystd::traversal_category<X>::type - A type convertible to std::random_access_traversal_tag -
- -

Valid expressions

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameExpressionType requirementsReturn type
Iterator additioni += n X&
Iterator additioni + n or n + i X
Iterator subtractioni -= n X&
Iterator subtractioni - n X
Differencei - j std::iterator_traits<X>::difference_type
Element operatori[n]X must also be a model of - Readable Iterator. std::iterator_traits<X>::reference
Element assignmenti[n] = tX must also be a model of - Writable Iterator.unspecified
- -

- -

- - -
Copyright © 2000 -Jeremy Siek, Univ.of Notre Dame (jsiek@lsc.nd.edu) -
- - - diff --git a/doc/access.png b/doc/access.png deleted file mode 100644 index 80011dc..0000000 Binary files a/doc/access.png and /dev/null differ diff --git a/doc/access2old.png b/doc/access2old.png deleted file mode 100644 index 8a87b84..0000000 Binary files a/doc/access2old.png and /dev/null differ diff --git a/doc/counting_iterator.html b/doc/counting_iterator.html deleted file mode 100644 index 6fd0e36..0000000 --- a/doc/counting_iterator.html +++ /dev/null @@ -1,150 +0,0 @@ - - - - - - -Counting Iterator - - - - - - - -
-

Counting Iterator

- --- - - - - - - - - - - - -
Author:David Abrahams, Jeremy Siek, Thomas Witt
Contact:dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de
Organization:Boost Consulting, Indiana University Open Systems -Lab, University of Hanover Institute for Transport -Railway Operation and Construction
Date:2003-08-05
Copyright:Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved
- --- - - - -
abstract:
-

The counting iterator adaptor implements dereference by returning a -reference to the base object. The other operations are implemented by -the base m_iterator, as per the inheritance from -iterator_adaptor.

- -
-template <class Incrementable, class Category = use_default, class Difference = use_default>
-class counting_iterator
-  : public iterator_adaptor<
-        counting_iterator<Incrementable, Category, Difference>
-      , Incrementable
-      , Incrementable
-      , /* see details for category */
-      , Incrementable const&
-      , Incrementable const*
-      , /* distance = Difference or a signed integral type */>
-{
-    friend class iterator_core_access;
- public:
-    counting_iterator();
-    counting_iterator(counting_iterator const& rhs);
-    counting_iterator(Incrementable x);
- private:
-    typename counting_iterator::reference dereference() const
-    {
-        return this->base_reference();
-    }
-  };
-
-
-
[Note: implementers are encouraged to provide an implementation of
-
distance_to and a difference_type that avoids overflows in -the cases when the Incrementable type is a numeric type.]
-
-
-

counting_iterator requirements

-

The Incrementable type must be Default Constructible, Copy -Constructible, and Assignable. The default distance is -an implementation defined signed integegral type.

-

The resulting counting_iterator models Readable Lvalue Iterator.

-

Furthermore, if you wish to create a counting iterator that is a Forward -Traversal Iterator, then the following expressions must be valid:

-
-Incrementable i, j;
-++i         // pre-increment
-i == j      // operator equal
-
-

If you wish to create a counting iterator that is a -Bidirectional Traversal Iterator, then pre-decrement is also required:

-
---i
-
-

If you wish to create a counting iterator that is a Random Access -Traversal Iterator, then these additional expressions are also -required:

-
-counting_iterator::difference_type n;
-i += n
-n = i - j
-i < j
-
-
-
-

counting_iterator operations

-

counting_iterator();

- --- - - - -
Returns:A default constructed instance of counting_iterator.
-

counting_iterator(counting_iterator const& rhs);

- --- - - - -
Returns:An instance of counting_iterator that is a copy of rhs.
-

counting_iterator(Incrementable x);

- --- - - - -
Returns:An instance of counting_iterator with its base -object copy constructed from x.
-
-
-
-
-View document source. -Generated on: 2003-09-14 02:16 UTC. -Generated by Docutils from reStructuredText source. -
- - diff --git a/doc/counting_iterator.rst b/doc/counting_iterator.rst deleted file mode 100644 index 25fb3b3..0000000 --- a/doc/counting_iterator.rst +++ /dev/null @@ -1,23 +0,0 @@ -+++++++++++++++++++ - Counting Iterator -+++++++++++++++++++ - -:Author: David Abrahams, Jeremy Siek, Thomas Witt -:Contact: dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de -:organization: `Boost Consulting`_, Indiana University `Open Systems - Lab`_, University of Hanover `Institute for Transport - Railway Operation and Construction`_ -:date: $Date$ -:copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved - -.. _`Boost Consulting`: http://www.boost-consulting.com -.. _`Open Systems Lab`: http://www.osl.iu.edu -.. _`Institute for Transport Railway Operation and Construction`: http://www.ive.uni-hannover.de - -:abstract: - -.. include:: counting_iterator_abstract.rst - -.. contents:: Table of Contents - -.. include:: counting_iterator_ref.rst diff --git a/doc/counting_iterator_abstract.rst b/doc/counting_iterator_abstract.rst deleted file mode 100644 index 2ac2233..0000000 --- a/doc/counting_iterator_abstract.rst +++ /dev/null @@ -1,5 +0,0 @@ -The counting iterator adaptor implements dereference by returning a -reference to the base object. The other operations are implemented by -the base ``m_iterator``, as per the inheritance from -``iterator_adaptor``. - diff --git a/doc/counting_iterator_ref.rst b/doc/counting_iterator_ref.rst deleted file mode 100644 index fc01011..0000000 --- a/doc/counting_iterator_ref.rst +++ /dev/null @@ -1,85 +0,0 @@ -:: - - template - class counting_iterator - : public iterator_adaptor< - counting_iterator - , Incrementable - , Incrementable - , /* see details for category */ - , Incrementable const& - , Incrementable const* - , /* distance = Difference or a signed integral type */> - { - friend class iterator_core_access; - public: - counting_iterator(); - counting_iterator(counting_iterator const& rhs); - counting_iterator(Incrementable x); - private: - typename counting_iterator::reference dereference() const - { - return this->base_reference(); - } - }; - - -[*Note:* implementers are encouraged to provide an implementation of - ``distance_to`` and a ``difference_type`` that avoids overflows in - the cases when the ``Incrementable`` type is a numeric type.] - -``counting_iterator`` requirements ----------------------------------- - -The ``Incrementable`` type must be Default Constructible, Copy -Constructible, and Assignable. The default distance is -an implementation defined signed integegral type. - -The resulting ``counting_iterator`` models Readable Lvalue Iterator. - -Furthermore, if you wish to create a counting iterator that is a Forward -Traversal Iterator, then the following expressions must be valid: -:: - - Incrementable i, j; - ++i // pre-increment - i == j // operator equal - -If you wish to create a counting iterator that is a -Bidirectional Traversal Iterator, then pre-decrement is also required: -:: - - --i - -If you wish to create a counting iterator that is a Random Access -Traversal Iterator, then these additional expressions are also -required: -:: - - counting_iterator::difference_type n; - i += n - n = i - j - i < j - - - - -``counting_iterator`` operations --------------------------------- - -``counting_iterator();`` - -:Returns: A default constructed instance of ``counting_iterator``. - - -``counting_iterator(counting_iterator const& rhs);`` - -:Returns: An instance of ``counting_iterator`` that is a copy of ``rhs``. - - - -``counting_iterator(Incrementable x);`` - -:Returns: An instance of ``counting_iterator`` with its base - object copy constructed from ``x``. - diff --git a/doc/default.css b/doc/default.css deleted file mode 100644 index 2e1fddb..0000000 --- a/doc/default.css +++ /dev/null @@ -1,188 +0,0 @@ -/* -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:date: $Date$ -:version: $Revision$ -:copyright: This stylesheet has been placed in the public domain. - -Default cascading style sheet for the HTML output of Docutils. -*/ - -.first { - margin-top: 0 } - -.last { - margin-bottom: 0 } - -a.toc-backref { - text-decoration: none ; - color: black } - -dd { - margin-bottom: 0.5em } - -div.abstract { - margin: 2em 5em } - -div.abstract p.topic-title { - font-weight: bold ; - text-align: center } - -div.attention, div.caution, div.danger, div.error, div.hint, -div.important, div.note, div.tip, div.warning { - margin: 2em ; - border: medium outset ; - padding: 1em } - -div.attention p.admonition-title, div.caution p.admonition-title, -div.danger p.admonition-title, div.error p.admonition-title, -div.warning p.admonition-title { - color: red ; - font-weight: bold ; - font-family: sans-serif } - -div.hint p.admonition-title, div.important p.admonition-title, -div.note p.admonition-title, div.tip p.admonition-title { - font-weight: bold ; - font-family: sans-serif } - -div.dedication { - margin: 2em 5em ; - text-align: center ; - font-style: italic } - -div.dedication p.topic-title { - font-weight: bold ; - font-style: normal } - -div.figure { - margin-left: 2em } - -div.footer, div.header { - font-size: smaller } - -div.system-messages { - margin: 5em } - -div.system-messages h1 { - color: red } - -div.system-message { - border: medium outset ; - padding: 1em } - -div.system-message p.system-message-title { - color: red ; - font-weight: bold } - -div.topic { - margin: 2em } - -h1.title { - text-align: center } - -h2.subtitle { - text-align: center } - -hr { - width: 75% } - -ol.simple, ul.simple { - margin-bottom: 1em } - -ol.arabic { - list-style: decimal } - -ol.loweralpha { - list-style: lower-alpha } - -ol.upperalpha { - list-style: upper-alpha } - -ol.lowerroman { - list-style: lower-roman } - -ol.upperroman { - list-style: upper-roman } - -p.caption { - font-style: italic } - -p.credits { - font-style: italic ; - font-size: smaller } - -p.label { - white-space: nowrap } - -p.topic-title { - font-weight: bold } - -pre.address { - margin-bottom: 0 ; - margin-top: 0 ; - font-family: serif ; - font-size: 100% } - -pre.line-block { - font-family: serif ; - font-size: 100% } - -pre.literal-block, pre.doctest-block { - margin-left: 2em ; - margin-right: 2em ; - background-color: #eeeeee } - -span.classifier { - font-family: sans-serif ; - font-style: oblique } - -span.classifier-delimiter { - font-family: sans-serif ; - font-weight: bold } - -span.interpreted { - font-family: sans-serif } - -span.option-argument { - font-style: italic } - -span.pre { - white-space: pre } - -span.problematic { - color: red } - -table { - margin-top: 0.5em ; - margin-bottom: 0.5em } - -table.citation { - border-left: solid thin gray ; - padding-left: 0.5ex } - -table.docinfo { - margin: 2em 4em } - -table.footnote { - border-left: solid thin black ; - padding-left: 0.5ex } - -td, th { - padding-left: 0.5em ; - padding-right: 0.5em ; - vertical-align: top } - -th.docinfo-name, th.field-name { - font-weight: bold ; - text-align: left ; - white-space: nowrap } - -h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { - font-size: 100% } - -tt { - background-color: #eeeeee } - -ul.auto-toc { - list-style-type: none } diff --git a/doc/facade-and-adaptor.html b/doc/facade-and-adaptor.html deleted file mode 100755 index aa0cde4..0000000 --- a/doc/facade-and-adaptor.html +++ /dev/null @@ -1,1854 +0,0 @@ - - - - - - -Iterator Facade and Adaptor - - - - - - - -
-

Iterator Facade and Adaptor

- --- - - - - - - - - - - - - - -
Author:David Abrahams, Jeremy Siek, Thomas Witt
Contact:dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de
Organization:Boost Consulting, Indiana University Open Systems -Lab, University of Hanover Institute for Transport -Railway Operation and Construction
Date:2003-08-05
Number:This document is a revised version of the official N1476=03-0059
Copyright:Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved
- --- - - - -
abstract:We propose a set of class templates that help programmers -build standard-conforming iterators, both from scratch and -by adapting other iterators.
-
-

Table of Contents

- -
-
-

Motivation

-

Iterators play an important role in modern C++ programming. The -iterator is the central abstraction of the algorithms of the Standard -Library, allowing algorithms to be re-used in in a wide variety of -contexts. The C++ Standard Library contains a wide variety of useful -iterators. Every one of the standard containers comes with constant -and mutable iterators 2, and also reverse versions of those -same iterators which traverse the container in the opposite direction. -The Standard also supplies istream_iterator and -ostream_iterator for reading from and writing to streams, -insert_iterator, front_insert_iterator and -back_insert_iterator for inserting elements into containers, and -raw_storage_iterator for initializing raw memory [7].

-

Despite the many iterators supplied by the Standard Library, obvious -and useful iterators are missing, and creating new iterator types is -still a common task for C++ programmers. The literature documents -several of these, for example line_iterator [3] and Constant_iterator -[9]. The iterator abstraction is so powerful that we expect -programmers will always need to invent new iterator types.

-

Although it is easy to create iterators that almost conform to the -standard, the iterator requirements contain subtleties which can make -creating an iterator which actually conforms quite difficult. -Further, the iterator interface is rich, containing many operators -that are technically redundant and tedious to implement. To automate -the repetitive work of constructing iterators, we propose -iterator_facade, an iterator base class template which provides -the rich interface of standard iterators and delegates its -implementation to member functions of the derived class. In addition -to reducing the amount of code necessary to create an iterator, the -iterator_facade also provides compile-time error detection. -Iterator implementation mistakes that often go unnoticed are turned -into compile-time errors because the derived class implementation must -match the expectations of the iterator_facade.

-

A common pattern of iterator construction is the adaptation of one -iterator to form a new one. The functionality of an iterator is -composed of four orthogonal aspects: traversal, indirection, equality -comparison and distance measurement. Adapting an old iterator to -create a new one often saves work because one can reuse one aspect of -functionality while redefining the other. For example, the Standard -provides reverse_iterator, which adapts any Bidirectional Iterator -by inverting its direction of traversal. As with plain iterators, -iterator adaptors defined outside the Standard have become commonplace -in the literature:

-
    -
  • Checked iter[13] adds bounds-checking to an existing iterator.
    • -
  • The iterators of the View Template Library[14], which adapts -containers, are themselves adaptors over the underlying iterators.
    • -
  • Smart iterators [5] adapt an iterator's dereferencing behavior by -applying a function object to the object being referenced and -returning the result.
    • -
  • Custom iterators [4], in which a variety of adaptor types are enumerated.
    • -
  • Compound iterators [1], which access a slice out of a container of containers.
    • -
  • Several iterator adaptors from the MTL [12]. The MTL contains a -strided iterator, where each call to operator++() moves the -iterator ahead by some constant factor, and a scaled iterator, which -multiplies the dereferenced value by some constant.
    • -
- - - - - -
[1]We use the term concept to mean a set of requirements -that a type must satisfy to be used with a particular template -parameter.
- - - - - -
[2]The term mutable iterator refers to iterators over objects that -can be changed by assigning to the dereferenced iterator, while -constant iterator refers to iterators over objects that cannot be -modified.
-

To fulfill the need for constructing adaptors, we propose the -iterator_adaptor class template. Instantiations of -iterator_adaptor serve as a base classes for new iterators, -providing the default behavior of forwarding all operations to the -underlying iterator. The user can selectively replace these features -in the derived iterator class. This proposal also includes a number -of more specialized adaptors, such as the transform_iterator that -applies some user-specified function during the dereference of the -iterator.

-
-
-

Impact on the Standard

-

This proposal is purely an addition to the C++ standard library. -However, note that this proposal relies on the proposal for New -Iterator Concepts.

-
-
-

Design

-
-

Iterator Concepts

-

This proposal is formulated in terms of the new iterator concepts -as proposed in n1477, since user-defined and especially adapted -iterators suffer from the well known categorization problems that are -inherent to the current iterator categories.

-

This proposal does not strictly depend on proposal n1477, as there -is a direct mapping between new and old categories. This proposal -could be reformulated using this mapping if n1477 was not accepted.

-
-
-

Interoperability

-

The question of iterator interoperability is poorly addressed in the -current standard. There are currently two defect reports that are -concerned with interoperability issues.

-

Issue 179 concerns the fact that mutable container iterator types -are only required to be convertible to the corresponding constant -iterator types, but objects of these types are not required to -interoperate in comparison or subtraction expressions. This situation -is tedious in practice and out of line with the way built in types -work. This proposal implements the proposed resolution to issue -179, as most standard library implementations do nowadays. In other -words, if an iterator type A has an implicit or user defined -conversion to an iterator type B, the iterator types are interoperable -and the usual set of operators are available.

-

Issue 280 concerns the current lack of interoperability between -reverse iterator types. The proposed new reverse_iterator template -fixes the issues raised in 280. It provides the desired -interoperability without introducing unwanted overloads.

-
-
-

Iterator Facade

-

While the iterator interface is rich, there is a core subset of the -interface that is necessary for all the functionality. We have -identified the following core behaviors for iterators:

-
    -
  • dereferencing
    • -
  • incrementing
    • -
  • decrementing
    • -
  • equality comparison
    • -
  • random-access motion
    • -
  • distance measurement
    • -
-

In addition to the behaviors listed above, the core interface elements -include the associated types exposed through iterator traits: -value_type, reference, difference_type, and -iterator_category.

-

Iterator facade uses the Curiously Recurring Template Pattern (CRTP) -[Cop95] so that the user can specify the behavior of -iterator_facade in a derived class. Former designs used policy -objects to specify the behavior. iterator_facade does not use policy -objects for several reasons:

-
-
    -
  1. the creation and eventual copying of the policy object may create -overhead that can be avoided with the current approach.
    2. -
  2. The policy object approach does not allow for custom constructors -on the created iterator types, an essential feature if -iterator_facade should be used in other library -implementations.
    3. -
  3. Without the use of CRTP, the standard requirement that an -iterator's operator++ returns the iterator type itself means -that all iterators generated by iterator_facade would be -instantiations of iterator_facade. Cumbersome type generator -metafunctions would be needed to build new parameterized -iterators, and a separate iterator_adaptor layer would be -impossible.
    4. -
-
-
-

Usage

-

The user of iterator_facade derives his iterator class from an -instantiation of iterator_facade which takes the derived iterator -class as the first template parameter. The order of the other -template parameters to iterator_facade have been carefully chosen -to take advantage of useful defaults. For example, when defining a -constant lvalue iterator, the user can pass a const-qualified version -of the iterator's value_type as iterator_facade's Value -parameter and omit the Reference parameter which follows.

-

The derived iterator class must define member functions implementing -the iterator's core behaviors. The following table describes -expressions which are required to be valid depending on the category -of the derived iterator type. These member functions are described -briefly below and in more detail in the iterator facade -requirements.

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - -
ExpressionEffects
i.dereference()Access the value referred to
i.equal(j)Compare for equality with j
i.increment()Advance by one position
i.decrement()Retreat by one position
i.advance(n)Advance by n positions
i.distance_to(j)Measure the distance to j
-
- -

In addition to implementing the core interface functions, an iterator -derived from iterator_facade typically defines several -constructors. To model any of the standard iterator concepts, the -iterator must at least have a copy constructor. Also, if the iterator -type X is meant to be automatically interoperate with another -iterator type Y (as with constant and mutable iterators) then -there must be an implicit conversion from X to Y or from Y -to X (but not both), typically implemented as a conversion -constructor. Finally, if the iterator is to model Forward Traversal -Iterator or a more-refined iterator concept, a default constructor is -required.

-
-
-

Iterator Core Access

-

iterator_facade and the operator implementations need to be able -to access the core member functions in the derived class. Making the -core member functions public would expose an implementation detail to -the user. The design used here ensures that implementation details do -not appear in the public interface of the derived iterator type.

-

Preventing direct access to the core member functions has two -advantages. First, there is no possibility for the user to accidently -use a member function of the iterator when a member of the value_type -was intended. This has been an issue with smart pointer -implementations in the past. The second and main advantage is that -library implementers can freely exchange a hand-rolled iterator -implementation for one based on iterator_facade without fear of -breaking code that was accessing the public core member functions -directly.

-

In a naive implementation, keeping the derived class' core member -functions private would require it to grant friendship to -iterator_facade and each of the seven operators. In order to -reduce the burden of limiting access, iterator_core_access is -provided, a class that acts as a gateway to the core member functions -in the derived iterator class. The author of the derived class only -needs to grant friendship to iterator_core_access to make his core -member functions available to the library.

- - -

iterator_core_access will be typically implemented as an empty -class containing only private static member functions which invoke the -iterator core member functions. There is, however, no need to -standardize the gateway protocol. Note that even if -iterator_core_access used public member functions it would not -open a safety loophole, as every core member function preserves the -invariants of the iterator.

-
-
-

operator[]

-

The indexing operator for a generalized iterator presents special -challenges. A random access iterator's operator[] is only -required to return something convertible to its value_type. -Requiring that it return an lvalue would rule out currently-legal -random-access iterators which hold the referenced value in a data -member (e.g. counting_iterator), because *(p+n) is a reference -into the temporary iterator p+n, which is destroyed when -operator[] returns.

-

Writable iterators built with iterator_facade implement the -semantics required by the preferred resolution to issue 299 and -adopted by proposal n1477: the result of p[n] is a proxy object -containing a copy of p+n, and p[n] = x is equivalent to *(p -+ n) = x. This approach will work properly for any random-access -iterator regardless of the other details of its implementation. A -user who knows more about the implementation of her iterator is free -to implement an operator[] which returns an lvalue in the derived -iterator class; it will hide the one supplied by iterator_facade -from clients of her iterator.

-
-
-

operator->

-

The reference type of a readable iterator (and today's input -iterator) need not in fact be a reference, so long as it is -convertible to the iterator's value_type. When the value_type -is a class, however, it must still be possible to access members -through operator->. Therefore, an iterator whose reference -type is not in fact a reference must return a proxy containing a copy -of the referenced value from its operator->.

-

The return type for operator-> and operator[] is not -explicitly specified. Instead it requires each iterator_facade -instantiation to meet the requirements of its iterator_category.

- - -- - - -
[Cop95][Coplien, 1995] Coplien, J., Curiously Recurring Template -Patterns, C++ Report, February 1995, pp. 24-27.
-
-
-
-

Iterator Adaptor

-

The iterator_adaptor class template adapts some Base 3 -type to create a new iterator. Instantiations of iterator_adaptor -are derived from a corresponding instantiation of iterator_facade -and implement the core behaviors in terms of the Base type. In -essence, iterator_adaptor merely forwards all operations to an -instance of the Base type, which it stores as a member.

- - - - - -
[3]The term "Base" here does not refer to a base class and is -not meant to imply the use of derivation. We have followed the lead -of the standard library, which provides a base() function to access -the underlying iterator object of a reverse_iterator adaptor.
-

The user of iterator_adaptor creates a class derived from an -instantiation of iterator_adaptor and then selectively -redefines some of the core member functions described in the table -above. The Base type need not meet the full requirements for an -iterator. It need only support the operations used by the core -interface functions of iterator_adaptor that have not been -redefined in the user's derived class.

-

Several of the template parameters of iterator_adaptor default to -use_default. This allows the user to make use of a default -parameter even when the user wants to specify a parameter later in the -parameter list. Also, the defaults for the corresponding associated -types are fairly complicated, so metaprogramming is required to -compute them, and use_default can help to simplify the -implementation. Finally, use_default is not left unspecified -because specification helps to highlight that the Reference -template parameter may not always be identical to the iterator's -reference type, and will keep users making mistakes based on that -assumption.

-
-
-

Specialized Adaptors

-

This proposal also contains several examples of specialized adaptors -which were easily implemented using iterator_adaptor:

-
    -
  • indirect_iterator, which iterates over iterators, pointers, -or smart pointers and applies an extra level of dereferencing.
    • -
  • A new reverse_iterator, which inverts the direction of a Base -iterator's motion, while allowing adapted constant and mutable -iterators to interact in the expected ways (unlike those in most -implementations of C++98).
    • -
  • transform_iterator, which applies a user-defined function object -to the underlying values when dereferenced.
    • -
  • projection_iterator, which is similar to transform_iterator -except that when dereferenced it returns a reference instead of -a value.
    • -
  • filter_iterator, which provides a view of an iterator range in -which some elements of the underlying range are skipped.
    • -
-
    -
  • counting_iterator, which adapts any incrementable type -(e.g. integers, iterators) so that incrementing/decrementing the -adapted iterator and dereferencing it produces successive values of -the Base type.
    • -
  • function_output_iterator, which makes it easier to create custom -output iterators.
    • -
-

Based on examples in the Boost library, users have generated many new -adaptors, among them a permutation adaptor which applies some -permutation to a random access iterator, and a strided adaptor, which -adapts a random access iterator by multiplying its unit of motion by a -constant factor. In addition, the Boost Graph Library (BGL) uses -iterator adaptors to adapt other graph libraries, such as LEDA [10] -and Stanford GraphBase [8], to the BGL interface (which requires C++ -Standard compliant iterators).

-
-
-
-

Proposed Text

-
-

Header <iterator_helper> synopsis [lib.iterator.helper.synopsis]

-
-struct use_default;
-
-struct iterator_core_access { /* implementation detail */ };
-
-template <
-    class Derived
-  , class Value
-  , class AccessCategory
-  , class TraversalCategory
-  , class Reference  = Value&
-  , class Difference = ptrdiff_t
->
-class iterator_facade;
-
-template <
-    class Derived
-  , class Base
-  , class Value      = use_default
-  , class Category   = use_default
-  , class Reference  = use_default
-  , class Difference = use_default
->
-class iterator_adaptor;
-
-template <
-    class Iterator
-  , class Value = use_default
-  , class Category = use_default
-  , class Reference = use_default
-  , class Difference = use_default
->
-class indirect_iterator;
-
-template <class Iterator>
-class reverse_iterator;
-
-template <
-    class UnaryFunction
-  , class Iterator
-  , class Reference = use_default
-  , class Value = use_default
->
-class transform_iterator;
-
-template <class Predicate, class Iterator>
-class filter_iterator;
-
-template <
-    class Incrementable
-  , class Category = use_default
-  , class Difference = use_default
->
-class counting_iterator
-
-template <class UnaryFunction>
-class function_output_iterator;
-
-
-
-

Iterator facade [lib.iterator.facade]

-

iterator_facade is a base class template that implements the -interface of standard iterators in terms of a few core functions -and associated types, to be supplied by a derived iterator class.

-
-

Class template iterator_facade

-
-template <
-    class Derived
-  , class Value
-  , class AccessCategory
-  , class TraversalCategory
-  , class Reference  = /* see below */
-  , class Difference = ptrdiff_t
->
-class iterator_facade {
-public:
-    typedef remove_cv<Value>::type value_type;
-    typedef Reference reference;
-    typedef /* see description of operator-> */ pointer;
-    typedef Difference difference_type;
-    typedef iterator_tag<AccessCategory, TraversalCategory> iterator_category;
-
-    reference operator*() const;
-    /* see below */ operator->() const;
-    /* see below */ operator[](difference_type n) const;
-    Derived& operator++();
-    Derived operator++(int);
-    Derived& operator--();
-    Derived operator--(int);
-    Derived& operator+=(difference_type n);
-    Derived& operator-=(difference_type n);
-    Derived operator-(difference_type n) const;
-};
-
-// Comparison operators
-template <class Dr1, class V1, class AC1, class TC1, class R1, class D1,
-          class Dr2, class V2, class AC2, class TC2, class R2, class D2>
-typename enable_if_interoperable<Dr1, Dr2, bool>::type // exposition
-operator ==(iterator_facade<Dr1, V1, AC1, TC1, R1, D1> const& lhs,
-            iterator_facade<Dr2, V2, AC2, TC2, R2, D2> const& rhs);
-
-template <class Dr1, class V1, class AC1, class TC1, class R1, class D1,
-          class Dr2, class V2, class AC2, class TC2, class R2, class D2>
-typename enable_if_interoperable<Dr1, Dr2, bool>::type
-operator !=(iterator_facade<Dr1, V1, AC1, TC1, R1, D1> const& lhs,
-            iterator_facade<Dr2, V2, AC2, TC2, R2, D2> const& rhs);
-
-template <class Dr1, class V1, class AC1, class TC1, class R1, class D1,
-          class Dr2, class V2, class AC2, class TC2, class R2, class D2>
-typename enable_if_interoperable<Dr1, Dr2, bool>::type
-operator <(iterator_facade<Dr1, V1, AC1, TC1, R1, D1> const& lhs,
-           iterator_facade<Dr2, V2, AC2, TC2, R2, D2> const& rhs);
-
-template <class Dr1, class V1, class AC1, class TC1, class R1, class D1,
-          class Dr2, class V2, class AC2, class TC2, class R2, class D2>
-typename enable_if_interoperable<Dr1, Dr2, bool>::type
-operator <=(iterator_facade<Dr1, V1, AC1, TC1, R1, D1> const& lhs,
-            iterator_facade<Dr2, V2, AC2, TC2, R2, D2> const& rhs);
-
-template <class Dr1, class V1, class AC1, class TC1, class R1, class D1,
-          class Dr2, class V2, class AC2, class TC2, class R2, class D2>
-typename enable_if_interoperable<Dr1, Dr2, bool>::type
-operator >(iterator_facade<Dr1, V1, AC1, TC1, R1, D1> const& lhs,
-           iterator_facade<Dr2, V2, AC2, TC2, R2, D2> const& rhs);
-
-template <class Dr1, class V1, class AC1, class TC1, class R1, class D1,
-          class Dr2, class V2, class AC2, class TC2, class R2, class D2>
-typename enable_if_interoperable<Dr1, Dr2, bool>::type
-operator >=(iterator_facade<Dr1, V1, AC1, TC1, R1, D1> const& lhs,
-            iterator_facade<Dr2, V2, AC2, TC2, R2, D2> const& rhs);
-
-template <class Dr1, class V1, class AC1, class TC1, class R1, class D1,
-          class Dr2, class V2, class AC2, class TC2, class R2, class D2>
-typename enable_if_interoperable<Dr1, Dr2, bool>::type
-operator >=(iterator_facade<Dr1, V1, AC1, TC1, R1, D1> const& lhs,
-            iterator_facade<Dr2, V2, AC2, TC2, R2, D2> const& rhs);
-
-// Iterator difference
-template <class Dr1, class V1, class AC1, class TC1, class R1, class D1,
-          class Dr2, class V2, class AC2, class TC2, class R2, class D2>
-typename enable_if_interoperable<Dr1, Dr2, bool>::type
-operator -(iterator_facade<Dr1, V1, AC1, TC1, R1, D1> const& lhs,
-           iterator_facade<Dr2, V2, AC2, TC2, R2, D2> const& rhs);
-
-// Iterator addition
-template <class Derived, class V, class AC, class TC, class R, class D>
-Derived operator+ (iterator_facade<Derived, V, AC, TC, R, D> const&,
-                   typename Derived::difference_type n)
-
-

[Note: The enable_if_interoperable template used above is for exposition -purposes. The member operators should be only be in an overload set -provided the derived types Dr1 and Dr2 are interoperable, by -which we mean they are convertible to each other. The -enable_if_interoperable approach uses SFINAE to take the operators -out of the overload set when the types are not interoperable.]

- -
-

iterator_facade requirements

-

The Derived template parameter must be a class derived from -iterator_facade.

-

The default for the Reference parameter is Value& if the -access category for iterator_facade is implicitly convertible to -writable_iterator_tag, and const Value& otherwise.

-

The following table describes the other requirements on the -Derived parameter. Depending on the resulting iterator's -iterator_category, a subset of the expressions listed in the table -are required to be valid. The operations in the first column must be -accessible to member functions of class iterator_core_access.

-

In the table below, X is the derived iterator type, a is an -object of type X, b and c are objects of type const X, -n is an object of X::difference_type, y is a constant -object of a single pass iterator type interoperable with X, and z -is a constant object of a random access traversal iterator type -interoperable with X.

- ------ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ExpressionReturn TypeAssertion/NoteRequired to implement -Iterator Concept(s)
c.dereference()X::reference Readable Iterator, Writable -Iterator
c.equal(b)convertible to booltrue iff b and c are -equivalent.Single Pass Iterator
c.equal(y)convertible to booltrue iff c and y refer to the -same position. Implements c == y -and c != y.Single Pass Iterator
a.advance(n)unused Random Access Traversal -Iterator
a.increment()unused Incrementable Iterator
a.decrement()unused Bidirectional Traversal -Iterator
c.distance_to(b)convertible to -X::difference_typeequivalent to distance(c, b)Random Access Traversal -Iterator
c.distance_to(z)convertible to -X::difference_typeequivalent to distance(c, z). -Implements c - z, c < z, c -<= z, c > z, and c >= c.Random Access Traversal -Iterator
- -
-
-

iterator_facade operations

-

The operations in this section are described in terms of operations on -the core interface of Derived which may be inaccessible -(i.e. private). The implementation should access these operations -through member functions of class iterator_core_access.

-

reference operator*() const;

- --- - - - -
Returns:static_cast<Derived const*>(this)->dereference()
-

operator->() const; (see below)

- --- - - - -
Returns:

If X::reference is a reference type, returns an object -of type X::pointer equal to:

-
-&static_cast<Derived const*>(this)->dereference()
-
-

Otherwise returns an object of unspecified type such that, given an -object a of type X, a->m is equivalent to (w = *a, -w.m) for some temporary object w of type X::value_type.

-

The type X::pointer is Value* if the access category for -X is implicitly convertible to writable_iterator_tag, and -Value const* otherwise.

-
-

unspecified operator[](difference_type n) const;

- --- - - - -
Returns:an object convertible to X::reference and holding a copy -p of a+n such that, for a constant object v of type -X::value_type, X::reference(a[n] = v) is equivalent -to p = v.
-

Derived& operator++();

- --- - - - -
Effects:
-static_cast<Derived*>(this)->increment();
-return *this;
-
-
- -

Derived operator++(int);

- --- - - - -
Effects:
-Derived tmp(static_cast<Derived const*>(this));
-++*this;
-return tmp;
-
-
-

Derived& operator--();

- --- - - - -
Effects:
-static_cast<Derived*>(this)->decrement();
-return *this;
-
-
-

Derived operator--(int);

- --- - - - -
Effects:
-Derived tmp(static_cast<Derived const*>(this));
---*this;
-return tmp;
-
-
-

Derived& operator+=(difference_type n);

- --- - - - -
Effects:
-static_cast<Derived*>(this)->advance(n);
-return *this;
-
-
-

Derived& operator-=(difference_type n);

- --- - - - -
Effects:
-static_cast<Derived*>(this)->advance(-n);
-return *this;
-
-
-

Derived operator-(difference_type n) const;

- --- - - - - - -
Effects:Derived tmp(static_cast<Derived const*>(this)); -return tmp -= n;
Returns:static_cast<Derived const*>(this)->advance(-n);
-
-
-
-
-

Iterator adaptor [lib.iterator.adaptor]

-

The iterator_adaptor is a base class template derived from an -instantiation of iterator_facade. The core interface functions -expected by iterator_facade are implemented in terms of the -iterator_adaptor's Base template parameter. A class derived -from iterator_adaptor typically redefines some of the core -interface functions to adapt the behavior of the Base type. -Whether the derived class models any of the standard iterator concepts -depends on the operations supported by the Base type and which -core interface functions of iterator_facade are redefined in the -Derived class.

-
-

Class template iterator_adaptor

-
-template <
-    class Derived
-  , class Base
-  , class Value      = use_default
-  , class Category   = use_default
-  , class Reference  = use_default
-  , class Difference = use_default
->
-class iterator_adaptor 
-  : public iterator_facade<Derived, /* see details ...*/>
-{
-    friend class iterator_core_access;
- public:
-    iterator_adaptor();
-    explicit iterator_adaptor(Base iter);
-    Base base() const;
- protected:
-    Base const& base_reference() const;
-    Base& base_reference();
- private: // Core iterator interface for iterator_facade.  
-    typename iterator_adaptor::reference dereference() const;
-
-    template <
-    class OtherDerived, class OtherIterator, class V, class C, class R, class D
-    >   
-    bool equal(iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& x) const;
-
-    void advance(typename iterator_adaptor::difference_type n);
-    void increment();
-    void decrement();
-
-    template <
-        class OtherDerived, class OtherIterator, class V, class C, class R, class D
-    >   
-    typename iterator_adaptor::difference_type distance_to(
-        iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& y) const;
-
- private:
-    Base m_iterator;
-};
-
-
-
-

iterator_adaptor requirements

-

The Derived template parameter must be a derived class of -iterator_adaptor. The Base type must implement the -expressions involving m_iterator in the specifications of those -private member functions of iterator_adaptor that are not -redefined by the Derived class and that are needed to model the -concept corresponding to the iterator_adaptor's category -typedef according to the requirements of iterator_facade. The -rest of the template parameters specify the types for the member -typedefs in iterator_facade. The following pseudo-code -specifies the traits types for iterator_adaptor.

-
-if (Value == use_default)
-    value_type = iterator_traits<Base>::value_type;
-else 
-    value_type = remove_cv<Value>::type;
-
-if (Reference == use_default) {
-    if (Value == use_default)
-        reference = iterator_traits<Base>::reference;
-    else 
-        reference = Value&;
-} else
-    reference = Reference;
-
-if (Distance == use_default)
-    difference_type = iterator_traits<Base>::difference_type;
-else
-    difference_type = Distance;
-
-if (Category == use_default)
-    iterator_category = iterator_tag< 
-        access_category< Base >,
-        traversal_category< Base >
-    >
-else if (Category is an access tag)
-    iterator_category = iterator_tag<
-        Category
-    ...
-
-else if (Category is a traversal tag)
-    ...
-else
-    iterator_category = Category;
-    // Actually the above is wrong.  See the use of
-    // access_category_tag and
-    // new_category_to_access/iter_category_to_access.
-
- -
-
-

iterator_adaptor public operations

-

iterator_adaptor();

- --- - - - - - -
Requires:The Base type must be Default Constructible.
Returns:An instance of iterator_adaptor with -m_iterator default constructed.
-

explicit iterator_adaptor(Base iter);

- --- - - - -
Returns:An instance of iterator_adaptor with -m_iterator copy constructed from iter.
-

Base base() const;

- --- - - - -
Returns:m_iterator
-
-
-

iterator_adaptor protected member functions

-

Base const& base_reference() const;

- --- - - - -
Returns:A const reference to m_iterator.
-

Base& base_reference();

- --- - - - -
Returns:A non-const reference to m_iterator.
-
-
-

iterator_adaptor private member functions

-

typename iterator_adaptor::reference dereference() const;

- --- - - - -
Returns:*m_iterator
-
-template <
-class OtherDerived, class OtherIterator, class V, class C, class R, class D
->   
-bool equal(iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& x) const;
-
- --- - - - -
Returns:m_iterator == x.base()
-

void advance(typename iterator_adaptor::difference_type n);

- --- - - - -
Effects:m_iterator += n;
-

void increment();

- --- - - - -
Effects:++m_iterator;
-

void decrement();

- --- - - - -
Effects:--m_iterator;
-
-template <
-    class OtherDerived, class OtherIterator, class V, class C, class R, class D
->   
-typename iterator_adaptor::difference_type distance_to(
-    iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& y) const;
-
- --- - - - -
Returns:y.base() - m_iterator
-
-
-
-

Specialized adaptors [lib.iterator.special.adaptors]

- -

[Note: The enable_if_convertible<X,Y>::type expression used in -this section is for exposition purposes. The converting constructors -for specialized adaptors should be only be in an overload set provided -that an object of type X is implicitly convertible to an object of -type Y. The enable_if_convertible approach uses SFINAE to -take the constructor out of the overload set when the types are not -implicitly convertible.]

-
-

Indirect iterator

-

The indirect iterator adapts an iterator by applying an extra -dereference inside of operator*(). For example, this iterator -adaptor makes it possible to view a container of pointers -(e.g. list<foo*>) as if it were a container of the pointed-to type -(e.g. list<foo>) .

- -
-

Class template indirect_iterator

-
-template <
-    class Iterator
-  , class Value = use_default
-  , class Category = use_default
-  , class Reference = use_default
-  , class Difference = use_default
->
-class indirect_iterator
-  : public iterator_adaptor</* see discussion */>
-{
-    friend class iterator_core_access;
- public:
-    indirect_iterator();
-    indirect_iterator(Iterator x);
-    template <
-        class Iterator2, class Value2, class Category2
-      , class Reference2, class Difference2
-    >
-    indirect_iterator(
-        indirect_iterator<
-             Iterator2, Value2, Category2, Reference2, Difference2
-        > const& y
-      , typename enable_if_convertible<Iterator2, Iterator>::type* = 0 // exposition
-    );
-private: // as-if specification
-    typename indirect_iterator::reference dereference() const
-    {
-        return **this->base();
-    }
-};
-
-
-
-

indirect_iterator requirements

-

The value_type of the Iterator template parameter should -itself be dereferenceable. The return type of the operator* for -the value_type must be the same type as the Reference template -parameter. The Value template parameter will be the value_type -for the indirect_iterator, unless Value is const. If Value -is const X, then value_type will be non- const X. The -default for Value is

-
-iterator_traits< iterator_traits<Iterator>::value_type >::value_type
-
-

If the default is used for Value, then there must be a valid -specialization of iterator_traits for the value type of the base -iterator.

-

The Reference parameter will be the reference type of the -indirect_iterator. The default is Value&.

-

The Category parameter is the iterator_category type for the -indirect_iterator. The default is -iterator_traits<Iterator>::iterator_category.

-

The indirect iterator will model the most refined standard traversal -concept that is modeled by the Iterator type. The indirect -iterator will model the most refined standard access concept that is -modeled by the value type of Iterator.

-
-
-

indirect_iterator operations

-

indirect_iterator();

- --- - - - - - -
Requires:Iterator must be Default Constructible.
Returns:An instance of indirect_iterator with -a default constructed base object.
-

indirect_iterator(Iterator x);

- --- - - - -
Returns:An instance of indirect_iterator with -the iterator_adaptor subobject copy constructed from x.
-
-template <
-    class Iterator2, class Value2, class Category2
-  , class Reference2, class Difference2
->
-indirect_iterator(
-    indirect_iterator<
-         Iterator2, Value2, Category2, Reference2, Difference2
-    > const& y
-  , typename enable_if_convertible<Iterator2, Iterator>::type* = 0 // exposition
-);
-
- --- - - - - - -
Requires:Iterator2 is implicitly convertible to Iterator.
Returns:An instance of indirect_iterator that is a copy of y.
-
-
-
-

Reverse iterator

- -

The reverse iterator adaptor flips the direction of a base iterator's -motion. Invoking operator++() moves the base iterator backward and -invoking operator--() moves the base iterator forward.

-
-

Class template reverse_iterator

-
-template <class Iterator>
-class reverse_iterator :
-  public iterator_adaptor< reverse_iterator<Iterator>, Iterator >
-{
-  friend class iterator_core_access;
-public:
-  reverse_iterator() {}
-  explicit reverse_iterator(Iterator x) ;
-
-  template<class OtherIterator>
-  reverse_iterator(
-      reverse_iterator<OtherIterator> const& r
-    , typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition
-  );
-
-private: // as-if specification
-  typename reverse_iterator::reference dereference() const { return *prior(this->base()); }
-
-  void increment() { --this->base_reference(); }
-  void decrement() { ++this->base_reference(); }
-
-  void advance(typename reverse_iterator::difference_type n)
-  {
-      this->base_reference() += -n;
-  }
-
-  template <class OtherIterator>
-  typename reverse_iterator::difference_type
-  distance_to(reverse_iterator<OtherIterator> const& y) const
-  {
-      return this->base_reference() - y.base();
-  }
-
-};
-
-
-
-

reverse_iterator requirements

-

The base Iterator must be a model of Bidirectional Traversal -Iterator. The resulting reverse_iterator will be a model of the -most refined standard traversal and access concepts that are modeled -by Iterator.

-

reverse_iterator();

- --- - - - - - -
Requires:Iterator must be Default Constructible.
Returns:An instance of reverse_iterator with a -default constructed base object.
-

explicit reverse_iterator(Iterator x);

- --- - - - -
Returns:An instance of reverse_iterator with a -base object copy constructed from x.
-
-template<class OtherIterator>
-reverse_iterator(
-    reverse_iterator<OtherIterator> const& r
-  , typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition
-);
-
- --- - - - - - -
Requires:OtherIterator is implicitly convertible to Iterator.
Returns:An instance of reverse_iterator that is a copy of r.
-
-
-
-

Transform iterator

-

The transform iterator adapts an iterator by applying some function -object to the result of dereferencing the iterator. In other words, -the operator* of the transform iterator first dereferences the -base iterator, passes the result of this to the function object, and -then returns the result.

-
-

Class template transform_iterator

-
-template <class AdaptableUnaryFunction,
-          class Iterator, 
-          class Reference = use_default, 
-          class Value = use_default>
-class transform_iterator
-  : public iterator_adaptor</* see discussion */>
-{
-  friend class iterator_core_access;
-public:
-  transform_iterator();
-  transform_iterator(Iterator const& x, AdaptableUnaryFunction f);
-
-  template<class OtherIterator, class R2, class V2>
-  transform_iterator(
-        transform_iterator<AdaptableUnaryFunction, OtherIterator, R2, V2> const& t
-      , typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition
-  );
-
-  AdaptableUnaryFunction functor() const;
-private:
-  typename transform_iterator::value_type dereference() const;
-  AdaptableUnaryFunction m_f;
-};
-
-
-
-

transform_iterator requirements

-

The type AdaptableUnaryFunction must be Assignable, Copy -Constructible, and the expression f(x) must be valid where f -is an object of type AdaptableUnaryFunction, x is an object of -type AdaptableUnaryFunction::argument_type, and where the type of -f(x) must be AdaptableUnaryFunction::result_type.

-

The type Iterator must at least model Readable Iterator. The -resulting transform_iterator models the most refined of the -following options that is also modeled by Iterator.

-
-
    -
  • Writable Lvalue Iterator if the result_type of the -AdaptableUnaryFunction is a non-const reference.
    • -
  • Readable Lvalue Iterator if the result_type is a const -reference.
    • -
  • Readable Iterator otherwise.
    • -
-
-

The transform_iterator models the most refined standard traversal -concept that is modeled by Iterator.

-

The value_type of transform_iterator is -remove_reference<result_type>::type. The reference type is -result_type.

-
-
-

transform_iterator public operations

-

transform_iterator();

- --- - - - -
Returns:An instance of transform_iterator with m_f -and m_iterator default constructed.
-

transform_iterator(Iterator const& x, AdaptableUnaryFunction f);

- --- - - - -
Returns:An instance of transform_iterator with m_f -initialized to f and m_iterator initialized to x.
-
-template<class OtherIterator, class R2, class V2>
-transform_iterator(
-      transform_iterator<AdaptableUnaryFunction, OtherIterator, R2, V2> const& t
-    , typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition
-);
-
- --- - - - - - -
Returns:An instance of transform_iterator that is a copy of t.
Requires:OtherIterator is implicitly convertible to Iterator.
-

AdaptableUnaryFunction functor() const;

- --- - - - -
Returns:m_f
-
-
-

transform_iterator private operations

-

typename transform_iterator::value_type dereference() const;

- --- - - - -
Returns:m_f(transform_iterator::dereference());
-
-
-
-

Filter iterator

-

The filter iterator adaptor creates a view of an iterator range in -which some elements of the range are skipped over. A predicate -function object controls which elements are skipped. When the -predicate is applied to an element, if it returns true then the -element is retained and if it returns false then the element is -skipped over. When skipping over elements, it is necessary for the -filter adaptor to know when to stop so as to avoid going past the end -of the underlying range. Therefore the constructor of the filter -iterator takes two iterator parameters: the position for the filtered -iterator and the end of the range.

-
-

Class template filter_iterator

-
-template <class Predicate, class Iterator>
-class filter_iterator
-    : public iterator_adaptor<
-          filter_iterator<Predicate, Iterator>, Iterator
-        , use_default
-        , /* see details */
-      >
-{
- public:
-    filter_iterator();
-    filter_iterator(Predicate f, Iterator x, Iterator end = Iterator());
-    filter_iterator(Iterator x, Iterator end = Iterator());
-    template<class OtherIterator>
-    filter_iterator(
-        filter_iterator<Predicate, OtherIterator> const& t
-        , typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition
-        );
-    Predicate predicate() const;
-    Iterator end() const;
-
- private: // as-if specification
-    void increment()
-    {
-        ++(this->base_reference());
-        satisfy_predicate();
-    }
-
-    void satisfy_predicate()
-    {
-        while (this->base() != this->m_end && !this->m_predicate(*this->base()))
-            ++(this->base_reference());
-    }
-
-    Predicate m_predicate;
-    Iterator m_end;
-};
-
-
-
-
-

filter_iterator requirements

-

The base Iterator parameter must be a model of Readable Iterator -and Single Pass Iterator. The resulting filter_iterator will be a -model of Forward Traversal Iterator if Iterator is, otherwise the -filter_iterator will be a model of Single Pass Iterator. The -access category of the filter_iterator will be the most refined -standard access category that is modeled by Iterator.

- -

The Predicate must be Assignable, Copy Constructible, and the -expression p(x) must be valid where p is an object of type -Predicate, x is an object of type -iterator_traits<Iterator>::value_type, and where the type of -p(x) must be convertible to bool.

-
-
-

filter_iterator operations

-

filter_iterator();

- --- - - - - - -
Requires:Predicate and Iterator must be Default Constructible.
Returns:a filter_iterator whose -predicate is a default constructed Predicate and -whose end is a default constructed Iterator.
-

filter_iterator(Predicate f, Iterator x, Iterator end = Iterator());

- --- - - - -
Returns:A filter_iterator at position x that filters according -to predicate f and that will not increment past end.
-

filter_iterator(Iterator x, Iterator end = Iterator());

- --- - - - - - -
Requires:Predicate must be Default Constructible.
Returns:A filter_iterator at position x that filters -according to a default constructed Predicate -and that will not increment past end.
-
-template <class OtherIterator>
-filter_iterator(
-    filter_iterator<Predicate, OtherIterator> const& t
-    , typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition
-    );``
-
- --- - - - - - -
Requires:OtherIterator is implicitly convertible to Iterator.
Returns:A copy of iterator t.
-

Predicate predicate() const;

- --- - - - -
Returns:A copy of the predicate object used to construct *this.
-

Iterator end() const;

- --- - - - -
Returns:The object end used to construct *this.
-
-
-

Counting iterator

-

The counting iterator adaptor implements dereference by returning a -reference to the base object. The other operations are implemented by -the base m_iterator, as per the inheritance from -iterator_adaptor.

-
-

Class template counting_iterator

-
-template <class Incrementable, class Category = use_default, class Difference = use_default>
-class counting_iterator
-  : public iterator_adaptor<
-        counting_iterator<Incrementable, Category, Difference>
-      , Incrementable
-      , Incrementable
-      , /* see details for category */
-      , Incrementable const&
-      , Incrementable const*
-      , /* distance = Difference or a signed integral type */>
-{
-    friend class iterator_core_access;
- public:
-    counting_iterator();
-    counting_iterator(counting_iterator const& rhs);
-    counting_iterator(Incrementable x);
- private:
-    typename counting_iterator::reference dereference() const
-    {
-        return this->base_reference();
-    }
-  };
-
-
-
[Note: implementers are encouraged to provide an implementation of
-
distance_to and a difference_type that avoids overflows in -the cases when the Incrementable type is a numeric type.]
-
-
-
-
-

counting_iterator requirements

-

The Incrementable type must be Default Constructible, Copy -Constructible, and Assignable. The default distance is -an implementation defined signed integegral type.

-

The resulting counting_iterator models Readable Lvalue Iterator.

-

Furthermore, if you wish to create a counting iterator that is a Forward -Traversal Iterator, then the following expressions must be valid:

-
-Incrementable i, j;
-++i         // pre-increment
-i == j      // operator equal
-
-

If you wish to create a counting iterator that is a -Bidirectional Traversal Iterator, then pre-decrement is also required:

-
---i
-
-

If you wish to create a counting iterator that is a Random Access -Traversal Iterator, then these additional expressions are also -required:

-
-counting_iterator::difference_type n;
-i += n
-n = i - j
-i < j
-
-
-
-

counting_iterator operations

-

counting_iterator();

- --- - - - -
Returns:A default constructed instance of counting_iterator.
-

counting_iterator(counting_iterator const& rhs);

- --- - - - -
Returns:An instance of counting_iterator that is a copy of rhs.
-

counting_iterator(Incrementable x);

- --- - - - -
Returns:An instance of counting_iterator with its base -object copy constructed from x.
-
-
-

Function output iterator

-

The function output iterator adaptor makes it easier to create custom -output iterators. The adaptor takes a unary function and creates a -model of Output Iterator. Each item assigned to the output iterator is -passed as an argument to the unary function. The motivation for this -iterator is that creating a conforming output iterator is non-trivial, -particularly because the proper implementation usually requires a -proxy object.

-
-

Class template function_output_iterator

-
-template <class UnaryFunction>
-class function_output_iterator {
-public:
-  typedef iterator_tag<
-        writable_iterator_tag
-      , incrementable_traversal_tag
-  > iterator_category;
-  typedef void                value_type;
-  typedef void                difference_type;
-  typedef void                pointer;
-  typedef void                reference;
-
-  explicit function_output_iterator(const UnaryFunction& f = UnaryFunction());
-
-  struct output_proxy {
-    output_proxy(UnaryFunction& f);
-    template <class T> output_proxy& operator=(const T& value);
-  };
-  output_proxy operator*();
-  function_output_iterator& operator++();
-  function_output_iterator& operator++(int);
-};
-
-
-
-
-

function_output_iterator requirements

-

The UnaryFunction must be Assignable, Copy Constructible, and the -expression f(x) must be valid, where f is an object of type -UnaryFunction and x is an object of a type accepted by f. -The resulting function_output_iterator is a model of the Writable -and Incrementable Iterator concepts.

-
-
-

function_output_iterator operations

-

explicit function_output_iterator(const UnaryFunction& f = UnaryFunction());

- --- - - - -
Returns:An instance of function_output_iterator with -f stored as a data member.
-

output_proxy operator*();

- --- - - - -
Returns:An instance of output_proxy constructed with -a copy of the unary function f.
-

function_output_iterator& operator++();

- --- - - - -
Returns:*this
-

function_output_iterator& operator++(int);

- --- - - - -
Returns:*this
-
-
-

function_output_iterator::output_proxy operations

-

output_proxy(UnaryFunction& f);

- --- - - - -
Returns:An instance of output_proxy with f stored as -a data member.
-

template <class T> output_proxy& operator=(const T& value);

- --- - - - -
Effects:
-m_f(value); 
-return *this; 
-
-
- -
-
-
-
-
-
-View document source. -Generated on: 2003-09-14 02:16 UTC. -Generated by Docutils from reStructuredText source. -
- - diff --git a/doc/facade-and-adaptor.rst b/doc/facade-and-adaptor.rst deleted file mode 100644 index e06567b..0000000 --- a/doc/facade-and-adaptor.rst +++ /dev/null @@ -1,398 +0,0 @@ -+++++++++++++++++++++++++++++ - Iterator Facade and Adaptor -+++++++++++++++++++++++++++++ - -:Author: David Abrahams, Jeremy Siek, Thomas Witt -:Contact: dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de -:organization: `Boost Consulting`_, Indiana University `Open Systems - Lab`_, University of Hanover `Institute for Transport - Railway Operation and Construction`_ -:date: $Date$ -:Number: **This document is a revised version of the official** N1476=03-0059 -:copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved - -.. _`Boost Consulting`: http://www.boost-consulting.com -.. _`Open Systems Lab`: http://www.osl.iu.edu -.. _`Institute for Transport Railway Operation and Construction`: http://www.ive.uni-hannover.de - -:abstract: We propose a set of class templates that help programmers - build standard-conforming iterators, both from scratch and - by adapting other iterators. - -.. contents:: Table of Contents - -============ - Motivation -============ - -Iterators play an important role in modern C++ programming. The -iterator is the central abstraction of the algorithms of the Standard -Library, allowing algorithms to be re-used in in a wide variety of -contexts. The C++ Standard Library contains a wide variety of useful -iterators. Every one of the standard containers comes with constant -and mutable iterators [#mutable]_, and also reverse versions of those -same iterators which traverse the container in the opposite direction. -The Standard also supplies ``istream_iterator`` and -``ostream_iterator`` for reading from and writing to streams, -``insert_iterator``, ``front_insert_iterator`` and -``back_insert_iterator`` for inserting elements into containers, and -``raw_storage_iterator`` for initializing raw memory [7]. - -Despite the many iterators supplied by the Standard Library, obvious -and useful iterators are missing, and creating new iterator types is -still a common task for C++ programmers. The literature documents -several of these, for example line_iterator [3] and Constant_iterator -[9]. The iterator abstraction is so powerful that we expect -programmers will always need to invent new iterator types. - -Although it is easy to create iterators that *almost* conform to the -standard, the iterator requirements contain subtleties which can make -creating an iterator which *actually* conforms quite difficult. -Further, the iterator interface is rich, containing many operators -that are technically redundant and tedious to implement. To automate -the repetitive work of constructing iterators, we propose -``iterator_facade``, an iterator base class template which provides -the rich interface of standard iterators and delegates its -implementation to member functions of the derived class. In addition -to reducing the amount of code necessary to create an iterator, the -``iterator_facade`` also provides compile-time error detection. -Iterator implementation mistakes that often go unnoticed are turned -into compile-time errors because the derived class implementation must -match the expectations of the ``iterator_facade``. - -A common pattern of iterator construction is the adaptation of one -iterator to form a new one. The functionality of an iterator is -composed of four orthogonal aspects: traversal, indirection, equality -comparison and distance measurement. Adapting an old iterator to -create a new one often saves work because one can reuse one aspect of -functionality while redefining the other. For example, the Standard -provides ``reverse_iterator``, which adapts any Bidirectional Iterator -by inverting its direction of traversal. As with plain iterators, -iterator adaptors defined outside the Standard have become commonplace -in the literature: - -* Checked iter[13] adds bounds-checking to an existing iterator. - -* The iterators of the View Template Library[14], which adapts - containers, are themselves adaptors over the underlying iterators. - -* Smart iterators [5] adapt an iterator's dereferencing behavior by - applying a function object to the object being referenced and - returning the result. - -* Custom iterators [4], in which a variety of adaptor types are enumerated. - -* Compound iterators [1], which access a slice out of a container of containers. - -* Several iterator adaptors from the MTL [12]. The MTL contains a - strided iterator, where each call to ``operator++()`` moves the - iterator ahead by some constant factor, and a scaled iterator, which - multiplies the dereferenced value by some constant. - -.. [#concept] We use the term concept to mean a set of requirements - that a type must satisfy to be used with a particular template - parameter. - -.. [#mutable] The term mutable iterator refers to iterators over objects that - can be changed by assigning to the dereferenced iterator, while - constant iterator refers to iterators over objects that cannot be - modified. - -To fulfill the need for constructing adaptors, we propose the -``iterator_adaptor`` class template. Instantiations of -``iterator_adaptor`` serve as a base classes for new iterators, -providing the default behavior of forwarding all operations to the -underlying iterator. The user can selectively replace these features -in the derived iterator class. This proposal also includes a number -of more specialized adaptors, such as the ``transform_iterator`` that -applies some user-specified function during the dereference of the -iterator. - -======================== - Impact on the Standard -======================== - -This proposal is purely an addition to the C++ standard library. -However, note that this proposal relies on the proposal for New -Iterator Concepts. - -======== - Design -======== - -Iterator Concepts -================= - -This proposal is formulated in terms of the new ``iterator concepts`` -as proposed in `n1477`_, since user-defined and especially adapted -iterators suffer from the well known categorization problems that are -inherent to the current iterator categories. - -.. _`n1477`: http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/papers/2003/n1477.html - -This proposal does not strictly depend on proposal `n1477`_, as there -is a direct mapping between new and old categories. This proposal -could be reformulated using this mapping if `n1477`_ was not accepted. - -Interoperability -================ - -The question of iterator interoperability is poorly addressed in the -current standard. There are currently two defect reports that are -concerned with interoperability issues. - -Issue `179`_ concerns the fact that mutable container iterator types -are only required to be convertible to the corresponding constant -iterator types, but objects of these types are not required to -interoperate in comparison or subtraction expressions. This situation -is tedious in practice and out of line with the way built in types -work. This proposal implements the proposed resolution to issue -`179`_, as most standard library implementations do nowadays. In other -words, if an iterator type A has an implicit or user defined -conversion to an iterator type B, the iterator types are interoperable -and the usual set of operators are available. - -Issue `280`_ concerns the current lack of interoperability between -reverse iterator types. The proposed new reverse_iterator template -fixes the issues raised in 280. It provides the desired -interoperability without introducing unwanted overloads. - -.. _`179`: http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/lwg-defects.html#179 -.. _`280`: http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/lwg-active.html#280 - - -Iterator Facade -=============== - -.. include:: iterator_facade_body.rst - -Iterator Adaptor -================ - -.. include:: iterator_adaptor_body.rst - -Specialized Adaptors -==================== - -This proposal also contains several examples of specialized adaptors -which were easily implemented using ``iterator_adaptor``: - -* ``indirect_iterator``, which iterates over iterators, pointers, - or smart pointers and applies an extra level of dereferencing. - -* A new ``reverse_iterator``, which inverts the direction of a Base - iterator's motion, while allowing adapted constant and mutable - iterators to interact in the expected ways (unlike those in most - implementations of C++98). - -* ``transform_iterator``, which applies a user-defined function object - to the underlying values when dereferenced. - -* ``projection_iterator``, which is similar to ``transform_iterator`` - except that when dereferenced it returns a reference instead of - a value. - -* ``filter_iterator``, which provides a view of an iterator range in - which some elements of the underlying range are skipped. - -.. _counting_iterator: - -* ``counting_iterator``, which adapts any incrementable type - (e.g. integers, iterators) so that incrementing/decrementing the - adapted iterator and dereferencing it produces successive values of - the Base type. - -* ``function_output_iterator``, which makes it easier to create custom - output iterators. - -Based on examples in the Boost library, users have generated many new -adaptors, among them a permutation adaptor which applies some -permutation to a random access iterator, and a strided adaptor, which -adapts a random access iterator by multiplying its unit of motion by a -constant factor. In addition, the Boost Graph Library (BGL) uses -iterator adaptors to adapt other graph libraries, such as LEDA [10] -and Stanford GraphBase [8], to the BGL interface (which requires C++ -Standard compliant iterators). - -=============== - Proposed Text -=============== - - -Header ```` synopsis [lib.iterator.helper.synopsis] -======================================================================= - - -:: - - struct use_default; - - struct iterator_core_access { /* implementation detail */ }; - - template < - class Derived - , class Value - , class AccessCategory - , class TraversalCategory - , class Reference = Value& - , class Difference = ptrdiff_t - > - class iterator_facade; - - template < - class Derived - , class Base - , class Value = use_default - , class Category = use_default - , class Reference = use_default - , class Difference = use_default - > - class iterator_adaptor; - - template < - class Iterator - , class Value = use_default - , class Category = use_default - , class Reference = use_default - , class Difference = use_default - > - class indirect_iterator; - - template - class reverse_iterator; - - template < - class UnaryFunction - , class Iterator - , class Reference = use_default - , class Value = use_default - > - class transform_iterator; - - template - class filter_iterator; - - template < - class Incrementable - , class Category = use_default - , class Difference = use_default - > - class counting_iterator - - template - class function_output_iterator; - - - -Iterator facade [lib.iterator.facade] -===================================== - -.. include:: iterator_facade_abstract.rst - -Class template ``iterator_facade`` ----------------------------------- - -.. include:: iterator_facade_ref.rst - -Iterator adaptor [lib.iterator.adaptor] -======================================= - -.. include:: iterator_adaptor_abstract.rst - -Class template ``iterator_adaptor`` ------------------------------------ - -.. include:: iterator_adaptor_ref.rst - - -Specialized adaptors [lib.iterator.special.adaptors] -==================================================== - -.. The requirements for all of these need to be written *much* more - formally -DWA - - -[*Note:* The ``enable_if_convertible::type`` expression used in -this section is for exposition purposes. The converting constructors -for specialized adaptors should be only be in an overload set provided -that an object of type ``X`` is implicitly convertible to an object of -type ``Y``. The ``enable_if_convertible`` approach uses SFINAE to -take the constructor out of the overload set when the types are not -implicitly convertible.] - - -Indirect iterator ------------------ - -.. include:: indirect_iterator_abstract.rst - -Class template ``indirect_iterator`` -.................................... - -.. include:: indirect_iterator_ref.rst - -Reverse iterator ----------------- - -.. include:: reverse_iterator_abstract.rst - -Class template ``reverse_iterator`` -................................... - -.. include:: reverse_iterator_ref.rst - - -Transform iterator ------------------- - -.. include:: transform_iterator_abstract.rst - -Class template ``transform_iterator`` -..................................... - -.. include:: transform_iterator_ref.rst - - -Filter iterator ---------------- - -.. include:: filter_iterator_abstract.rst - - -Class template ``filter_iterator`` -.................................. - -.. include:: filter_iterator_ref.rst - - -Counting iterator ------------------ - -.. include:: counting_iterator_abstract.rst - -Class template ``counting_iterator`` -.................................... - -.. include:: counting_iterator_ref.rst - - -Function output iterator ------------------------- - -.. include:: function_output_iterator_abstract.rst - -Class template ``function_output_iterator`` -........................................... - -.. include:: function_output_iterator_ref.rst - - - - -.. - LocalWords: Abrahams Siek Witt istream ostream iter MTL strided interoperate - LocalWords: CRTP metafunctions inlining lvalue JGS incrementable BGL LEDA cv - LocalWords: GraphBase struct ptrdiff UnaryFunction const int typename bool pp - LocalWords: lhs rhs SFINAE markup iff tmp OtherDerived OtherIterator DWA foo - LocalWords: dereferenceable subobject AdaptableUnaryFunction impl pre ifdef'd - LocalWords: OtherIncrementable Coplien diff --git a/doc/filter_iterator.html b/doc/filter_iterator.html deleted file mode 100644 index 4133ae5..0000000 --- a/doc/filter_iterator.html +++ /dev/null @@ -1,196 +0,0 @@ - - - - - - -Filter Iterator - - - - - - - -
-

Filter Iterator

- --- - - - - - - - - - - - -
Author:David Abrahams, Jeremy Siek, Thomas Witt
Contact:dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de
Organization:Boost Consulting, Indiana University Open Systems -Lab, University of Hanover Institute for Transport -Railway Operation and Construction
Date:2003-08-05
Copyright:Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved
- --- - - - -
abstract:
-

The filter iterator adaptor creates a view of an iterator range in -which some elements of the range are skipped over. A predicate -function object controls which elements are skipped. When the -predicate is applied to an element, if it returns true then the -element is retained and if it returns false then the element is -skipped over. When skipping over elements, it is necessary for the -filter adaptor to know when to stop so as to avoid going past the end -of the underlying range. Therefore the constructor of the filter -iterator takes two iterator parameters: the position for the filtered -iterator and the end of the range.

- -
-template <class Predicate, class Iterator>
-class filter_iterator
-    : public iterator_adaptor<
-          filter_iterator<Predicate, Iterator>, Iterator
-        , use_default
-        , /* see details */
-      >
-{
- public:
-    filter_iterator();
-    filter_iterator(Predicate f, Iterator x, Iterator end = Iterator());
-    filter_iterator(Iterator x, Iterator end = Iterator());
-    template<class OtherIterator>
-    filter_iterator(
-        filter_iterator<Predicate, OtherIterator> const& t
-        , typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition
-        );
-    Predicate predicate() const;
-    Iterator end() const;
-
- private: // as-if specification
-    void increment()
-    {
-        ++(this->base_reference());
-        satisfy_predicate();
-    }
-
-    void satisfy_predicate()
-    {
-        while (this->base() != this->m_end && !this->m_predicate(*this->base()))
-            ++(this->base_reference());
-    }
-
-    Predicate m_predicate;
-    Iterator m_end;
-};
-
-
-

filter_iterator requirements

-

The base Iterator parameter must be a model of Readable Iterator -and Single Pass Iterator. The resulting filter_iterator will be a -model of Forward Traversal Iterator if Iterator is, otherwise the -filter_iterator will be a model of Single Pass Iterator. The -access category of the filter_iterator will be the most refined -standard access category that is modeled by Iterator.

- -

The Predicate must be Assignable, Copy Constructible, and the -expression p(x) must be valid where p is an object of type -Predicate, x is an object of type -iterator_traits<Iterator>::value_type, and where the type of -p(x) must be convertible to bool.

-
-
-

filter_iterator operations

-

filter_iterator();

- --- - - - - - -
Requires:Predicate and Iterator must be Default Constructible.
Returns:a filter_iterator whose -predicate is a default constructed Predicate and -whose end is a default constructed Iterator.
-

filter_iterator(Predicate f, Iterator x, Iterator end = Iterator());

- --- - - - -
Returns:A filter_iterator at position x that filters according -to predicate f and that will not increment past end.
-

filter_iterator(Iterator x, Iterator end = Iterator());

- --- - - - - - -
Requires:Predicate must be Default Constructible.
Returns:A filter_iterator at position x that filters -according to a default constructed Predicate -and that will not increment past end.
-
-template <class OtherIterator>
-filter_iterator(
-    filter_iterator<Predicate, OtherIterator> const& t
-    , typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition
-    );``
-
- --- - - - - - -
Requires:OtherIterator is implicitly convertible to Iterator.
Returns:A copy of iterator t.
-

Predicate predicate() const;

- --- - - - -
Returns:A copy of the predicate object used to construct *this.
-

Iterator end() const;

- --- - - - -
Returns:The object end used to construct *this.
-
-
-
-
-View document source. -Generated on: 2003-09-14 02:16 UTC. -Generated by Docutils from reStructuredText source. -
- - diff --git a/doc/filter_iterator.rst b/doc/filter_iterator.rst deleted file mode 100644 index acd770e..0000000 --- a/doc/filter_iterator.rst +++ /dev/null @@ -1,23 +0,0 @@ -+++++++++++++++++ - Filter Iterator -+++++++++++++++++ - -:Author: David Abrahams, Jeremy Siek, Thomas Witt -:Contact: dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de -:organization: `Boost Consulting`_, Indiana University `Open Systems - Lab`_, University of Hanover `Institute for Transport - Railway Operation and Construction`_ -:date: $Date$ -:copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved - -.. _`Boost Consulting`: http://www.boost-consulting.com -.. _`Open Systems Lab`: http://www.osl.iu.edu -.. _`Institute for Transport Railway Operation and Construction`: http://www.ive.uni-hannover.de - -:abstract: - -.. include:: filter_iterator_abstract.rst - -.. contents:: Table of Contents - -.. include:: filter_iterator_ref.rst diff --git a/doc/filter_iterator_abstract.rst b/doc/filter_iterator_abstract.rst deleted file mode 100644 index 9517b23..0000000 --- a/doc/filter_iterator_abstract.rst +++ /dev/null @@ -1,10 +0,0 @@ -The filter iterator adaptor creates a view of an iterator range in -which some elements of the range are skipped over. A predicate -function object controls which elements are skipped. When the -predicate is applied to an element, if it returns ``true`` then the -element is retained and if it returns ``false`` then the element is -skipped over. When skipping over elements, it is necessary for the -filter adaptor to know when to stop so as to avoid going past the end -of the underlying range. Therefore the constructor of the filter -iterator takes two iterator parameters: the position for the filtered -iterator and the end of the range. diff --git a/doc/filter_iterator_ref.rst b/doc/filter_iterator_ref.rst deleted file mode 100644 index 29bc166..0000000 --- a/doc/filter_iterator_ref.rst +++ /dev/null @@ -1,108 +0,0 @@ -:: - - template - class filter_iterator - : public iterator_adaptor< - filter_iterator, Iterator - , use_default - , /* see details */ - > - { - public: - filter_iterator(); - filter_iterator(Predicate f, Iterator x, Iterator end = Iterator()); - filter_iterator(Iterator x, Iterator end = Iterator()); - template - filter_iterator( - filter_iterator const& t - , typename enable_if_convertible::type* = 0 // exposition - ); - Predicate predicate() const; - Iterator end() const; - - private: // as-if specification - void increment() - { - ++(this->base_reference()); - satisfy_predicate(); - } - - void satisfy_predicate() - { - while (this->base() != this->m_end && !this->m_predicate(*this->base())) - ++(this->base_reference()); - } - - Predicate m_predicate; - Iterator m_end; - }; - - -``filter_iterator`` requirements --------------------------------- - -The base ``Iterator`` parameter must be a model of Readable Iterator -and Single Pass Iterator. The resulting ``filter_iterator`` will be a -model of Forward Traversal Iterator if ``Iterator`` is, otherwise the -``filter_iterator`` will be a model of Single Pass Iterator. The -access category of the ``filter_iterator`` will be the most refined -standard access category that is modeled by ``Iterator``. - -.. Thomas is going to try implementing filter_iterator so that - it will be bidirectional if the underlying iterator is. -JGS - - -The ``Predicate`` must be Assignable, Copy Constructible, and the -expression ``p(x)`` must be valid where ``p`` is an object of type -``Predicate``, ``x`` is an object of type -``iterator_traits::value_type``, and where the type of -``p(x)`` must be convertible to ``bool``. - - - -``filter_iterator`` operations ------------------------------- - -``filter_iterator();`` - -:Requires: ``Predicate`` and ``Iterator`` must be Default Constructible. -:Returns: a ``filter_iterator`` whose - predicate is a default constructed ``Predicate`` and - whose ``end`` is a default constructed ``Iterator``. - - -``filter_iterator(Predicate f, Iterator x, Iterator end = Iterator());`` - -:Returns: A ``filter_iterator`` at position ``x`` that filters according - to predicate ``f`` and that will not increment past ``end``. - - -``filter_iterator(Iterator x, Iterator end = Iterator());`` - -:Requires: ``Predicate`` must be Default Constructible. -:Returns: A ``filter_iterator`` at position ``x`` that filters - according to a default constructed ``Predicate`` - and that will not increment past ``end``. - - -:: - - template - filter_iterator( - filter_iterator const& t - , typename enable_if_convertible::type* = 0 // exposition - );`` - -:Requires: ``OtherIterator`` is implicitly convertible to ``Iterator``. -:Returns: A copy of iterator ``t``. - - -``Predicate predicate() const;`` - -:Returns: A copy of the predicate object used to construct ``*this``. - - -``Iterator end() const;`` - -:Returns: The object ``end`` used to construct ``*this``. - diff --git a/doc/function_output_iterator.html b/doc/function_output_iterator.html deleted file mode 100644 index 30d4559..0000000 --- a/doc/function_output_iterator.html +++ /dev/null @@ -1,165 +0,0 @@ - - - - - - -Function Output Iterator - - - - - - - -
-

Function Output Iterator

- --- - - - - - - - - - - - -
Author:David Abrahams, Jeremy Siek, Thomas Witt
Contact:dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de
Organization:Boost Consulting, Indiana University Open Systems -Lab, University of Hanover Institute for Transport -Railway Operation and Construction
Date:2003-08-05
Copyright:Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved
- --- - - - -
abstract:
-

The function output iterator adaptor makes it easier to create custom -output iterators. The adaptor takes a unary function and creates a -model of Output Iterator. Each item assigned to the output iterator is -passed as an argument to the unary function. The motivation for this -iterator is that creating a conforming output iterator is non-trivial, -particularly because the proper implementation usually requires a -proxy object.

- -
-template <class UnaryFunction>
-class function_output_iterator {
-public:
-  typedef iterator_tag<
-        writable_iterator_tag
-      , incrementable_traversal_tag
-  > iterator_category;
-  typedef void                value_type;
-  typedef void                difference_type;
-  typedef void                pointer;
-  typedef void                reference;
-
-  explicit function_output_iterator(const UnaryFunction& f = UnaryFunction());
-
-  struct output_proxy {
-    output_proxy(UnaryFunction& f);
-    template <class T> output_proxy& operator=(const T& value);
-  };
-  output_proxy operator*();
-  function_output_iterator& operator++();
-  function_output_iterator& operator++(int);
-};
-
-
-

function_output_iterator requirements

-

The UnaryFunction must be Assignable, Copy Constructible, and the -expression f(x) must be valid, where f is an object of type -UnaryFunction and x is an object of a type accepted by f. -The resulting function_output_iterator is a model of the Writable -and Incrementable Iterator concepts.

-
-
-

function_output_iterator operations

-

explicit function_output_iterator(const UnaryFunction& f = UnaryFunction());

- --- - - - -
Returns:An instance of function_output_iterator with -f stored as a data member.
-

output_proxy operator*();

- --- - - - -
Returns:An instance of output_proxy constructed with -a copy of the unary function f.
-

function_output_iterator& operator++();

- --- - - - -
Returns:*this
-

function_output_iterator& operator++(int);

- --- - - - -
Returns:*this
-
-
-

function_output_iterator::output_proxy operations

-

output_proxy(UnaryFunction& f);

- --- - - - -
Returns:An instance of output_proxy with f stored as -a data member.
-

template <class T> output_proxy& operator=(const T& value);

- --- - - - -
Effects:
-m_f(value); 
-return *this; 
-
-
-
-
-
-
-View document source. -Generated on: 2003-09-14 02:16 UTC. -Generated by Docutils from reStructuredText source. -
- - diff --git a/doc/function_output_iterator.rst b/doc/function_output_iterator.rst deleted file mode 100644 index d1740fb..0000000 --- a/doc/function_output_iterator.rst +++ /dev/null @@ -1,23 +0,0 @@ -++++++++++++++++++++++++++ - Function Output Iterator -++++++++++++++++++++++++++ - -:Author: David Abrahams, Jeremy Siek, Thomas Witt -:Contact: dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de -:organization: `Boost Consulting`_, Indiana University `Open Systems - Lab`_, University of Hanover `Institute for Transport - Railway Operation and Construction`_ -:date: $Date$ -:copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved - -.. _`Boost Consulting`: http://www.boost-consulting.com -.. _`Open Systems Lab`: http://www.osl.iu.edu -.. _`Institute for Transport Railway Operation and Construction`: http://www.ive.uni-hannover.de - -:abstract: - -.. include:: function_output_iterator_abstract.rst - -.. contents:: Table of Contents - -.. include:: function_output_iterator_ref.rst diff --git a/doc/function_output_iterator_abstract.rst b/doc/function_output_iterator_abstract.rst deleted file mode 100644 index 11fb4f1..0000000 --- a/doc/function_output_iterator_abstract.rst +++ /dev/null @@ -1,8 +0,0 @@ -The function output iterator adaptor makes it easier to create custom -output iterators. The adaptor takes a unary function and creates a -model of Output Iterator. Each item assigned to the output iterator is -passed as an argument to the unary function. The motivation for this -iterator is that creating a conforming output iterator is non-trivial, -particularly because the proper implementation usually requires a -proxy object. - diff --git a/doc/function_output_iterator_ref.rst b/doc/function_output_iterator_ref.rst deleted file mode 100644 index 4bb5cf1..0000000 --- a/doc/function_output_iterator_ref.rst +++ /dev/null @@ -1,77 +0,0 @@ -:: - - template - class function_output_iterator { - public: - typedef iterator_tag< - writable_iterator_tag - , incrementable_traversal_tag - > iterator_category; - typedef void value_type; - typedef void difference_type; - typedef void pointer; - typedef void reference; - - explicit function_output_iterator(const UnaryFunction& f = UnaryFunction()); - - struct output_proxy { - output_proxy(UnaryFunction& f); - template output_proxy& operator=(const T& value); - }; - output_proxy operator*(); - function_output_iterator& operator++(); - function_output_iterator& operator++(int); - }; - - -``function_output_iterator`` requirements ------------------------------------------ - -The ``UnaryFunction`` must be Assignable, Copy Constructible, and the -expression ``f(x)`` must be valid, where ``f`` is an object of type -``UnaryFunction`` and ``x`` is an object of a type accepted by ``f``. -The resulting ``function_output_iterator`` is a model of the Writable -and Incrementable Iterator concepts. - - -``function_output_iterator`` operations ---------------------------------------- - -``explicit function_output_iterator(const UnaryFunction& f = UnaryFunction());`` - -:Returns: An instance of ``function_output_iterator`` with - ``f`` stored as a data member. - - -``output_proxy operator*();`` - -:Returns: An instance of ``output_proxy`` constructed with - a copy of the unary function ``f``. - - -``function_output_iterator& operator++();`` - -:Returns: ``*this`` - - -``function_output_iterator& operator++(int);`` - -:Returns: ``*this`` - - -``function_output_iterator::output_proxy`` operations ------------------------------------------------------ - -``output_proxy(UnaryFunction& f);`` - -:Returns: An instance of ``output_proxy`` with ``f`` stored as - a data member. - - -``template output_proxy& operator=(const T& value);`` - -:Effects: - :: - - m_f(value); - return *this; diff --git a/doc/index.html b/doc/index.html deleted file mode 100755 index 37421eb..0000000 --- a/doc/index.html +++ /dev/null @@ -1,188 +0,0 @@ - - - - - - -The Boost Iterator Library Boost - - - - -
-
-View document source. -Generated on: 2003-09-14 02:16 UTC. -Generated by Docutils from reStructuredText source. -
- - diff --git a/doc/index.rst b/doc/index.rst deleted file mode 100755 index 13da6f7..0000000 --- a/doc/index.rst +++ /dev/null @@ -1,226 +0,0 @@ -+++++++++++++++++++++++++++++++++++++++++++++++++ - The Boost Iterator Library |(logo)|__ -+++++++++++++++++++++++++++++++++++++++++++++++++ - -.. |(logo)| image:: ../../../c++boost.gif - :alt: Boost - -__ ../../../index.htm - - -------------------------------------- - - -:Authors: David Abrahams, Jeremy Siek, Thomas Witt -:Contact: dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de -:organizations: `Boost Consulting`_, Indiana University `Open Systems - Lab`_, University of Hanover `Institute for Transport - Railway Operation and Construction`_ -:date: $Date$ -:copyright: Copyright David Abrahams, Jeremy Siek, Thomas Witt 2003. All rights reserved - -.. _`Boost Consulting`: http://www.boost-consulting.com -.. _`Open Systems Lab`: http://www.osl.iu.edu -.. _`Institute for Transport Railway Operation and Construction`: http://www.ive.uni-hannover.de - -:Abstract: The Boost Iterator Library contains two parts. The first - is a system of concepts_ which extend the C++ standard - iterator requirements. The second is a framework - of components for building iterators based on these - extended concepts and includes several useful iterator - adaptors. The extended iterator concepts have - been carefully designed so that new-style iterators will be - compatible with old-style algorithms, though algorithms may - need to be updated if they want to take full advantage of - the new-style iterators. Several components of this - library have been proposed for the C++ standard technical - report. The components of the Boost Iterator Library - replace the older Boost Iterator Adaptor Library. - -.. _concepts: ../../../more/generic_programming.html#concept - -.. contents:: **Table of Contents** - - -------------------------------------- - - -===================== - New-Style Iterators -===================== - -The iterator categories defined in C++98 are extremely limiting -because they bind together two orthogonal concepts: traversal and -element access. For example, because a random access iterator is -required to return a reference (and not a proxy) when dereferenced, -it is impossible to capture the capabilities of -``vector::iterator`` using the C++98 categories. This is the -infamous "``vector`` is not a container, and its iterators -aren't random access iterators", debacle about which Herb Sutter -wrote two papers for the standards comittee (n1185_ and n1211_), -and a `Guru of the Week`__. New-style iterators go well beyond -patching up ``vector``, though: there are lots of other -iterators already in use which can't be adequately represented by -the existing concepts. For details about the new iterator -concepts, see our - -.. _n1185: http://www.gotw.ca/publications/N1185.pdf -.. _n1211: http://www.gotw.ca/publications/N1211.pdf -__ http://www.gotw.ca/gotw/050.htm - - - `Standard Proposal For New-Style Iterators`__ - -__ new-iter-concepts.html - -============================= - Iterator Facade and Adaptor -============================= - -Writing standard-conforming iterators is tricky. In order to ease the -implementation of new iterators, the iterator library provides the -|facade|_ class template, which implements many useful -defaults and compile-time checks designed to help the author iterator -ensure that his iterator is correct. It is common to define a new -iterator which behaves like another iterator, but modifies some aspect -of its behavior. For that purpose, the library supplies the -|adaptor|_ class template, which is specially designed to -take advantage of as much of the underlying iterator's behavior as -possible. - -.. |facade| replace:: ``iterator_facade`` -.. _facade: iterator_facade.html -.. |adaptor| replace:: ``iterator_adaptor`` -.. _adaptor: iterator_adaptor.html - -Both |facade|_ and |adaptor|_ as well as many of -the `specialized adaptors`_ mentioned below have been proposed for -standardization; see our - - `Standard Proposal For Iterator Facade and Adaptor`__ - -for more details. - -__ facade-and-adaptor.html - -====================== - Specialized Adaptors -====================== - -The iterator library supplies a useful suite of standard-conforming -iterator templates based on the Boost `iterator facade and adaptor`_. - -* |counting|_: an iterator over a sequence of consecutive values. - Implements a "lazy sequence" - -* |filter|_: an iterator over the subset of elements of some - sequence which satisfy a given predicate - -* |indirect|_: an iterator over the objects *pointed-to* by the - elements of some sequence. - -* |permutation|_: an iterator over the elements of some random-access - sequence, rearranged according to some sequence of integer indices. - -* |reverse|_: an iterator which traverses the elements of some - bidirectional sequence in reverse. Corrects many of the - shortcomings of C++98's ``std::reverse_iterator``. - -* |transform|_: an iterator over elements which are the result of - applying some functional transformation to the elements of an - underlying sequence. This component also replaces the old - ``projection_iterator_adaptor``. - -.. |counting| replace:: ``counting_iterator`` -.. _counting: counting_iterator.html - -.. |filter| replace:: ``filter_iterator`` -.. _filter: filter_iterator.html - -.. |indirect| replace:: ``indirect_iterator`` -.. _indirect: indirect_iterator.html - -.. |permutation| replace:: ``permutation_iterator`` -.. _permutation: permutation_iterator.html - -.. |reverse| replace:: ``reverse_iterator`` -.. _reverse: reverse_iterator.html - -.. |transform| replace:: ``transform_iterator`` -.. _transform: transform_iterator.html - -==================== - Iterator Utilities -==================== - -Traits ------- - -* |iterator_traits|_: Provides MPL_\ -compatible metafunctions which - retrieve an iterator's traits. Also corrects for the deficiencies - of broken implementations of ``std::iterator_traits``. - -* |interoperable|_: Provides an MPL_\ -compatible metafunction for - testing iterator interoperability - -.. |iterator_traits| replace:: ``iterator_traits.hpp`` -.. _iterator_traits: iterator_traits.html - -.. |interoperable| replace:: ``interoperable.hpp`` -.. _interoperable: interoperable.html - -.. _MPL: ../../mpl/doc/index.html - -Testing and Concept Checking ----------------------------- - -* |iterator_archetypes|_: Add summary here - -* |iterator_concepts|_: Add summary - -.. |iterator_archetypes| replace:: ``iterator_archetypes.hpp`` -.. _iterator_archetypes: iterator_archetypes.html - -.. |iterator_concepts| replace:: ``iterator_concepts.hpp`` -.. _iterator_concepts: iterator_concepts.html - - -======================================================= - Upgrading from the old Boost Iterator Adaptor Library -======================================================= - -Turn your policy class into the body of the iterator - -Use transform_iterator with a true reference type for -projection_iterator. - -========= - History -========= - -In 2000 Dave Abrahams was writing an iterator for a container of -pointers, which would access the pointed-to elements when -dereferenced. Naturally, being a library writer, he decided to -generalize the idea and the Boost Iterator Adaptor library was born. -Dave was inspired by some writings of Andrei Alexandrescu and chose a -policy based design (though he probably didn't capture Andrei's idea -very well - there was only one policy class for all the iterator's -orthogonal properties). Soon Jeremy Siek realized he would need the -library and they worked together to produce a "Boostified" version, -which was reviewed and accepted into the library. They wrote a paper -and made several important revisions of the code. - -Eventually, several shortcomings of the older library began to make -the need for a rewrite apparent. Dave and Jeremy started working at -the Santa Cruz C++ committee meeting in 2002, and had quickly -generated a working prototype. Thomas Witt expressed interest and -became the voice of compile-time checking for the project... - -.. - LocalWords: Abrahams Siek Witt const bool Sutter's WG int UL LI href Lvalue - LocalWords: ReadableIterator WritableIterator SwappableIterator cv pre iter - LocalWords: ConstantLvalueIterator MutableLvalueIterator CopyConstructible TR - LocalWords: ForwardTraversalIterator BidirectionalTraversalIterator lvalue - LocalWords: RandomAccessTraversalIterator dereferenceable Incrementable tmp - LocalWords: incrementable xxx min prev inplace png oldeqnew AccessTag struct - LocalWords: TraversalTag typename lvalues DWA Hmm JGS diff --git a/doc/indirect_iterator.html b/doc/indirect_iterator.html deleted file mode 100644 index 9bbc80b..0000000 --- a/doc/indirect_iterator.html +++ /dev/null @@ -1,169 +0,0 @@ - - - - - - -Indirect Iterator - - - - - - - -
-

Indirect Iterator

- --- - - - - - - - - - - - -
Author:David Abrahams, Jeremy Siek, Thomas Witt
Contact:dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de
Organization:Boost Consulting, Indiana University Open Systems -Lab, University of Hanover Institute for Transport -Railway Operation and Construction
Date:2003-08-05
Copyright:Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved
- --- - - - -
abstract:
-

The indirect iterator adapts an iterator by applying an extra -dereference inside of operator*(). For example, this iterator -adaptor makes it possible to view a container of pointers -(e.g. list<foo*>) as if it were a container of the pointed-to type -(e.g. list<foo>) .

- - -
-template <
-    class Iterator
-  , class Value = use_default
-  , class Category = use_default
-  , class Reference = use_default
-  , class Difference = use_default
->
-class indirect_iterator
-  : public iterator_adaptor</* see discussion */>
-{
-    friend class iterator_core_access;
- public:
-    indirect_iterator();
-    indirect_iterator(Iterator x);
-    template <
-        class Iterator2, class Value2, class Category2
-      , class Reference2, class Difference2
-    >
-    indirect_iterator(
-        indirect_iterator<
-             Iterator2, Value2, Category2, Reference2, Difference2
-        > const& y
-      , typename enable_if_convertible<Iterator2, Iterator>::type* = 0 // exposition
-    );
-private: // as-if specification
-    typename indirect_iterator::reference dereference() const
-    {
-        return **this->base();
-    }
-};
-
-
-

indirect_iterator requirements

-

The value_type of the Iterator template parameter should -itself be dereferenceable. The return type of the operator* for -the value_type must be the same type as the Reference template -parameter. The Value template parameter will be the value_type -for the indirect_iterator, unless Value is const. If Value -is const X, then value_type will be non- const X. The -default for Value is

-
-iterator_traits< iterator_traits<Iterator>::value_type >::value_type
-
-

If the default is used for Value, then there must be a valid -specialization of iterator_traits for the value type of the base -iterator.

-

The Reference parameter will be the reference type of the -indirect_iterator. The default is Value&.

-

The Category parameter is the iterator_category type for the -indirect_iterator. The default is -iterator_traits<Iterator>::iterator_category.

-

The indirect iterator will model the most refined standard traversal -concept that is modeled by the Iterator type. The indirect -iterator will model the most refined standard access concept that is -modeled by the value type of Iterator.

-
-
-

indirect_iterator operations

-

indirect_iterator();

- --- - - - - - -
Requires:Iterator must be Default Constructible.
Returns:An instance of indirect_iterator with -a default constructed base object.
-

indirect_iterator(Iterator x);

- --- - - - -
Returns:An instance of indirect_iterator with -the iterator_adaptor subobject copy constructed from x.
-
-template <
-    class Iterator2, class Value2, class Category2
-  , class Reference2, class Difference2
->
-indirect_iterator(
-    indirect_iterator<
-         Iterator2, Value2, Category2, Reference2, Difference2
-    > const& y
-  , typename enable_if_convertible<Iterator2, Iterator>::type* = 0 // exposition
-);
-
- --- - - - - - -
Requires:Iterator2 is implicitly convertible to Iterator.
Returns:An instance of indirect_iterator that is a copy of y.
-
-
-
-
-View document source. -Generated on: 2003-09-14 02:16 UTC. -Generated by Docutils from reStructuredText source. -
- - diff --git a/doc/indirect_iterator.rst b/doc/indirect_iterator.rst deleted file mode 100644 index 3ea8dcb..0000000 --- a/doc/indirect_iterator.rst +++ /dev/null @@ -1,23 +0,0 @@ -+++++++++++++++++++ - Indirect Iterator -+++++++++++++++++++ - -:Author: David Abrahams, Jeremy Siek, Thomas Witt -:Contact: dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de -:organization: `Boost Consulting`_, Indiana University `Open Systems - Lab`_, University of Hanover `Institute for Transport - Railway Operation and Construction`_ -:date: $Date$ -:copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved - -.. _`Boost Consulting`: http://www.boost-consulting.com -.. _`Open Systems Lab`: http://www.osl.iu.edu -.. _`Institute for Transport Railway Operation and Construction`: http://www.ive.uni-hannover.de - -:abstract: - -.. include:: indirect_iterator_abstract.rst - -.. contents:: Table of Contents - -.. include:: indirect_iterator_ref.rst diff --git a/doc/indirect_iterator_abstract.rst b/doc/indirect_iterator_abstract.rst deleted file mode 100644 index 3b6c2a6..0000000 --- a/doc/indirect_iterator_abstract.rst +++ /dev/null @@ -1,8 +0,0 @@ -The indirect iterator adapts an iterator by applying an *extra* -dereference inside of ``operator*()``. For example, this iterator -adaptor makes it possible to view a container of pointers -(e.g. ``list``) as if it were a container of the pointed-to type -(e.g. ``list``) . - -.. At some point we should add the capability to handle - iterators over smart pointers, which the impl handles. -JGS diff --git a/doc/indirect_iterator_ref.rst b/doc/indirect_iterator_ref.rst deleted file mode 100644 index ebbe2ff..0000000 --- a/doc/indirect_iterator_ref.rst +++ /dev/null @@ -1,96 +0,0 @@ -:: - - template < - class Iterator - , class Value = use_default - , class Category = use_default - , class Reference = use_default - , class Difference = use_default - > - class indirect_iterator - : public iterator_adaptor - { - friend class iterator_core_access; - public: - indirect_iterator(); - indirect_iterator(Iterator x); - template < - class Iterator2, class Value2, class Category2 - , class Reference2, class Difference2 - > - indirect_iterator( - indirect_iterator< - Iterator2, Value2, Category2, Reference2, Difference2 - > const& y - , typename enable_if_convertible::type* = 0 // exposition - ); - private: // as-if specification - typename indirect_iterator::reference dereference() const - { - return **this->base(); - } - }; - -``indirect_iterator`` requirements -.................................. - -The ``value_type`` of the ``Iterator`` template parameter should -itself be dereferenceable. The return type of the ``operator*`` for -the ``value_type`` must be the same type as the ``Reference`` template -parameter. The ``Value`` template parameter will be the ``value_type`` -for the ``indirect_iterator``, unless ``Value`` is const. If ``Value`` -is ``const X``, then ``value_type`` will be *non-* ``const X``. The -default for ``Value`` is - -:: - - iterator_traits< iterator_traits::value_type >::value_type - -If the default is used for ``Value``, then there must be a valid -specialization of ``iterator_traits`` for the value type of the base -iterator. - -The ``Reference`` parameter will be the ``reference`` type of the -``indirect_iterator``. The default is ``Value&``. - -The ``Category`` parameter is the ``iterator_category`` type for the -``indirect_iterator``. The default is -``iterator_traits::iterator_category``. - -The indirect iterator will model the most refined standard traversal -concept that is modeled by the ``Iterator`` type. The indirect -iterator will model the most refined standard access concept that is -modeled by the value type of ``Iterator``. - - -``indirect_iterator`` operations -................................ - -``indirect_iterator();`` - -:Requires: ``Iterator`` must be Default Constructible. -:Returns: An instance of ``indirect_iterator`` with - a default constructed base object. - - -``indirect_iterator(Iterator x);`` - -:Returns: An instance of ``indirect_iterator`` with - the ``iterator_adaptor`` subobject copy constructed from ``x``. - -:: - - template < - class Iterator2, class Value2, class Category2 - , class Reference2, class Difference2 - > - indirect_iterator( - indirect_iterator< - Iterator2, Value2, Category2, Reference2, Difference2 - > const& y - , typename enable_if_convertible::type* = 0 // exposition - ); - -:Requires: ``Iterator2`` is implicitly convertible to ``Iterator``. -:Returns: An instance of ``indirect_iterator`` that is a copy of ``y``. - diff --git a/doc/iterator_adaptor.html b/doc/iterator_adaptor.html deleted file mode 100644 index d34598e..0000000 --- a/doc/iterator_adaptor.html +++ /dev/null @@ -1,335 +0,0 @@ - - - - - - -Iterator Adaptor - - - - - - - -
-

Iterator Adaptor

- --- - - - - - - - - - - - -
Author:David Abrahams, Jeremy Siek, Thomas Witt
Contact:dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de
Organization:Boost Consulting, Indiana University Open Systems -Lab, University of Hanover Institute for Transport -Railway Operation and Construction
Date:2003-08-05
Copyright:Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved
- --- - - - -
abstract:
-

The iterator_adaptor is a base class template derived from an -instantiation of iterator_facade. The core interface functions -expected by iterator_facade are implemented in terms of the -iterator_adaptor's Base template parameter. A class derived -from iterator_adaptor typically redefines some of the core -interface functions to adapt the behavior of the Base type. -Whether the derived class models any of the standard iterator concepts -depends on the operations supported by the Base type and which -core interface functions of iterator_facade are redefined in the -Derived class.

- -
-

Introduction

-

The iterator_adaptor class template adapts some Base 1 -type to create a new iterator. Instantiations of iterator_adaptor -are derived from a corresponding instantiation of iterator_facade -and implement the core behaviors in terms of the Base type. In -essence, iterator_adaptor merely forwards all operations to an -instance of the Base type, which it stores as a member.

- - - - - -
[1]The term "Base" here does not refer to a base class and is -not meant to imply the use of derivation. We have followed the lead -of the standard library, which provides a base() function to access -the underlying iterator object of a reverse_iterator adaptor.
-

The user of iterator_adaptor creates a class derived from an -instantiation of iterator_adaptor and then selectively -redefines some of the core member functions described in the table -above. The Base type need not meet the full requirements for an -iterator. It need only support the operations used by the core -interface functions of iterator_adaptor that have not been -redefined in the user's derived class.

-

Several of the template parameters of iterator_adaptor default to -use_default. This allows the user to make use of a default -parameter even when the user wants to specify a parameter later in the -parameter list. Also, the defaults for the corresponding associated -types are fairly complicated, so metaprogramming is required to -compute them, and use_default can help to simplify the -implementation. Finally, use_default is not left unspecified -because specification helps to highlight that the Reference -template parameter may not always be identical to the iterator's -reference type, and will keep users making mistakes based on that -assumption.

-
-
-

Reference

-
-template <
-    class Derived
-  , class Base
-  , class Value      = use_default
-  , class Category   = use_default
-  , class Reference  = use_default
-  , class Difference = use_default
->
-class iterator_adaptor 
-  : public iterator_facade<Derived, /* see details ...*/>
-{
-    friend class iterator_core_access;
- public:
-    iterator_adaptor();
-    explicit iterator_adaptor(Base iter);
-    Base base() const;
- protected:
-    Base const& base_reference() const;
-    Base& base_reference();
- private: // Core iterator interface for iterator_facade.  
-    typename iterator_adaptor::reference dereference() const;
-
-    template <
-    class OtherDerived, class OtherIterator, class V, class C, class R, class D
-    >   
-    bool equal(iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& x) const;
-
-    void advance(typename iterator_adaptor::difference_type n);
-    void increment();
-    void decrement();
-
-    template <
-        class OtherDerived, class OtherIterator, class V, class C, class R, class D
-    >   
-    typename iterator_adaptor::difference_type distance_to(
-        iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& y) const;
-
- private:
-    Base m_iterator;
-};
-
-
-

iterator_adaptor requirements

-

The Derived template parameter must be a derived class of -iterator_adaptor. The Base type must implement the -expressions involving m_iterator in the specifications of those -private member functions of iterator_adaptor that are not -redefined by the Derived class and that are needed to model the -concept corresponding to the iterator_adaptor's category -typedef according to the requirements of iterator_facade. The -rest of the template parameters specify the types for the member -typedefs in iterator_facade. The following pseudo-code -specifies the traits types for iterator_adaptor.

-
-if (Value == use_default)
-    value_type = iterator_traits<Base>::value_type;
-else 
-    value_type = remove_cv<Value>::type;
-
-if (Reference == use_default) {
-    if (Value == use_default)
-        reference = iterator_traits<Base>::reference;
-    else 
-        reference = Value&;
-} else
-    reference = Reference;
-
-if (Distance == use_default)
-    difference_type = iterator_traits<Base>::difference_type;
-else
-    difference_type = Distance;
-
-if (Category == use_default)
-    iterator_category = iterator_tag< 
-        access_category< Base >,
-        traversal_category< Base >
-    >
-else if (Category is an access tag)
-    iterator_category = iterator_tag<
-        Category
-    ...
-
-else if (Category is a traversal tag)
-    ...
-else
-    iterator_category = Category;
-    // Actually the above is wrong.  See the use of
-    // access_category_tag and
-    // new_category_to_access/iter_category_to_access.
-
- -
-
-

iterator_adaptor public operations

-

iterator_adaptor();

- --- - - - - - -
Requires:The Base type must be Default Constructible.
Returns:An instance of iterator_adaptor with -m_iterator default constructed.
-

explicit iterator_adaptor(Base iter);

- --- - - - -
Returns:An instance of iterator_adaptor with -m_iterator copy constructed from iter.
-

Base base() const;

- --- - - - -
Returns:m_iterator
-
-
-

iterator_adaptor protected member functions

-

Base const& base_reference() const;

- --- - - - -
Returns:A const reference to m_iterator.
-

Base& base_reference();

- --- - - - -
Returns:A non-const reference to m_iterator.
-
-
-

iterator_adaptor private member functions

-

typename iterator_adaptor::reference dereference() const;

- --- - - - -
Returns:*m_iterator
-
-template <
-class OtherDerived, class OtherIterator, class V, class C, class R, class D
->   
-bool equal(iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& x) const;
-
- --- - - - -
Returns:m_iterator == x.base()
-

void advance(typename iterator_adaptor::difference_type n);

- --- - - - -
Effects:m_iterator += n;
-

void increment();

- --- - - - -
Effects:++m_iterator;
-

void decrement();

- --- - - - -
Effects:--m_iterator;
-
-template <
-    class OtherDerived, class OtherIterator, class V, class C, class R, class D
->   
-typename iterator_adaptor::difference_type distance_to(
-    iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& y) const;
-
- --- - - - -
Returns:y.base() - m_iterator
-
-
-
-
-
-View document source. -Generated on: 2003-09-14 02:16 UTC. -Generated by Docutils from reStructuredText source. -
- - diff --git a/doc/iterator_adaptor.rst b/doc/iterator_adaptor.rst deleted file mode 100644 index e64e93a..0000000 --- a/doc/iterator_adaptor.rst +++ /dev/null @@ -1,32 +0,0 @@ -+++++++++++++++++ - Iterator Adaptor -+++++++++++++++++ - -:Author: David Abrahams, Jeremy Siek, Thomas Witt -:Contact: dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de -:organization: `Boost Consulting`_, Indiana University `Open Systems - Lab`_, University of Hanover `Institute for Transport - Railway Operation and Construction`_ -:date: $Date$ -:copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved - -.. _`Boost Consulting`: http://www.boost-consulting.com -.. _`Open Systems Lab`: http://www.osl.iu.edu -.. _`Institute for Transport Railway Operation and Construction`: http://www.ive.uni-hannover.de - -:abstract: - -.. include:: iterator_adaptor_abstract.rst - -.. contents:: Table of Contents - -Introduction -============ - -.. include:: iterator_adaptor_body.rst - - -Reference -========= - -.. include:: iterator_adaptor_ref.rst diff --git a/doc/iterator_adaptor_abstract.rst b/doc/iterator_adaptor_abstract.rst deleted file mode 100644 index ee75455..0000000 --- a/doc/iterator_adaptor_abstract.rst +++ /dev/null @@ -1,10 +0,0 @@ -The ``iterator_adaptor`` is a base class template derived from an -instantiation of ``iterator_facade``. The core interface functions -expected by ``iterator_facade`` are implemented in terms of the -``iterator_adaptor``\ 's ``Base`` template parameter. A class derived -from ``iterator_adaptor`` typically redefines some of the core -interface functions to adapt the behavior of the ``Base`` type. -Whether the derived class models any of the standard iterator concepts -depends on the operations supported by the ``Base`` type and which -core interface functions of ``iterator_facade`` are redefined in the -``Derived`` class. diff --git a/doc/iterator_adaptor_body.rst b/doc/iterator_adaptor_body.rst deleted file mode 100644 index 0136ad1..0000000 --- a/doc/iterator_adaptor_body.rst +++ /dev/null @@ -1,32 +0,0 @@ -The ``iterator_adaptor`` class template adapts some ``Base`` [#base]_ -type to create a new iterator. Instantiations of ``iterator_adaptor`` -are derived from a corresponding instantiation of ``iterator_facade`` -and implement the core behaviors in terms of the ``Base`` type. In -essence, ``iterator_adaptor`` merely forwards all operations to an -instance of the ``Base`` type, which it stores as a member. - -.. [#base] The term "Base" here does not refer to a base class and is - not meant to imply the use of derivation. We have followed the lead - of the standard library, which provides a base() function to access - the underlying iterator object of a ``reverse_iterator`` adaptor. - -The user of ``iterator_adaptor`` creates a class derived from an -instantiation of ``iterator_adaptor`` and then selectively -redefines some of the core member functions described in the table -above. The ``Base`` type need not meet the full requirements for an -iterator. It need only support the operations used by the core -interface functions of ``iterator_adaptor`` that have not been -redefined in the user's derived class. - -Several of the template parameters of ``iterator_adaptor`` default to -``use_default``. This allows the user to make use of a default -parameter even when the user wants to specify a parameter later in the -parameter list. Also, the defaults for the corresponding associated -types are fairly complicated, so metaprogramming is required to -compute them, and ``use_default`` can help to simplify the -implementation. Finally, ``use_default`` is not left unspecified -because specification helps to highlight that the ``Reference`` -template parameter may not always be identical to the iterator's -``reference`` type, and will keep users making mistakes based on that -assumption. - diff --git a/doc/iterator_adaptor_ref.rst b/doc/iterator_adaptor_ref.rst deleted file mode 100644 index 69c6aa7..0000000 --- a/doc/iterator_adaptor_ref.rst +++ /dev/null @@ -1,178 +0,0 @@ -.. parsed-literal:: - - template < - class Derived - , class Base - , class Value = use_default - , class Category = use_default - , class Reference = use_default - , class Difference = use_default - > - class iterator_adaptor - : public iterator_facade - { - friend class iterator_core_access; - public: - iterator_adaptor(); - explicit iterator_adaptor(Base iter); - Base base() const; - protected: - Base const& base_reference() const; - Base& base_reference(); - private: // Core iterator interface for iterator_facade. - typename iterator_adaptor::reference dereference() const; - - template < - class OtherDerived, class OtherIterator, class V, class C, class R, class D - > - bool equal(iterator_adaptor const& x) const; - - void advance(typename iterator_adaptor::difference_type n); - void increment(); - void decrement(); - - template < - class OtherDerived, class OtherIterator, class V, class C, class R, class D - > - typename iterator_adaptor::difference_type distance_to( - iterator_adaptor const& y) const; - - private: - Base m_iterator; - }; - -__ : - -``iterator_adaptor`` requirements ---------------------------------- - -The ``Derived`` template parameter must be a derived class of -``iterator_adaptor``. The ``Base`` type must implement the -expressions involving ``m_iterator`` in the specifications of those -private member functions of ``iterator_adaptor`` that are not -redefined by the ``Derived`` class and that are needed to model the -concept corresponding to the ``iterator_adaptor``\ 's ``category`` -typedef according to the requirements of ``iterator_facade``. The -rest of the template parameters specify the types for the member -typedefs in ``iterator_facade``. The following pseudo-code -specifies the traits types for ``iterator_adaptor``. - -:: - - if (Value == use_default) - value_type = iterator_traits::value_type; - else - value_type = remove_cv::type; - - if (Reference == use_default) { - if (Value == use_default) - reference = iterator_traits::reference; - else - reference = Value&; - } else - reference = Reference; - - if (Distance == use_default) - difference_type = iterator_traits::difference_type; - else - difference_type = Distance; - - if (Category == use_default) - iterator_category = iterator_tag< - access_category< Base >, - traversal_category< Base > - > - else if (Category is an access tag) - iterator_category = iterator_tag< - Category - ... - - else if (Category is a traversal tag) - ... - else - iterator_category = Category; - // Actually the above is wrong. See the use of - // access_category_tag and - // new_category_to_access/iter_category_to_access. - - -.. Replaced with new semantics --thw - if (Category == use_default) - iterator_category = iterator_traits::iterator_category; - else - iterator_category = Category; - - Fix this up!! - - -``iterator_adaptor`` public operations --------------------------------------- - -``iterator_adaptor();`` - -:Requires: The ``Base`` type must be Default Constructible. -:Returns: An instance of ``iterator_adaptor`` with - ``m_iterator`` default constructed. - - -``explicit iterator_adaptor(Base iter);`` - -:Returns: An instance of ``iterator_adaptor`` with - ``m_iterator`` copy constructed from ``iter``. - -``Base base() const;`` - -:Returns: ``m_iterator`` - - -``iterator_adaptor`` protected member functions ------------------------------------------------ - -``Base const& base_reference() const;`` - -:Returns: A const reference to ``m_iterator``. - - -``Base& base_reference();`` - -:Returns: A non-const reference to ``m_iterator``. - - -``iterator_adaptor`` private member functions ---------------------------------------------- - -``typename iterator_adaptor::reference dereference() const;`` - -:Returns: ``*m_iterator`` - -:: - - template < - class OtherDerived, class OtherIterator, class V, class C, class R, class D - > - bool equal(iterator_adaptor const& x) const; - -:Returns: ``m_iterator == x.base()`` - - -``void advance(typename iterator_adaptor::difference_type n);`` - -:Effects: ``m_iterator += n;`` - -``void increment();`` - -:Effects: ``++m_iterator;`` - -``void decrement();`` - -:Effects: ``--m_iterator;`` - -:: - - template < - class OtherDerived, class OtherIterator, class V, class C, class R, class D - > - typename iterator_adaptor::difference_type distance_to( - iterator_adaptor const& y) const; - -:Returns: ``y.base() - m_iterator`` diff --git a/doc/iterator_facade.html b/doc/iterator_facade.html deleted file mode 100644 index 84f7e25..0000000 --- a/doc/iterator_facade.html +++ /dev/null @@ -1,580 +0,0 @@ - - - - - - -Iterator Facade - - - - - - - -
-

Iterator Facade

- --- - - - - - - - - - - - -
Author:David Abrahams, Jeremy Siek, Thomas Witt
Contact:dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de
Organization:Boost Consulting, Indiana University Open Systems -Lab, University of Hanover Institute for Transport -Railway Operation and Construction
Date:2003-08-05
Copyright:Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved
- --- - - - -
abstract:
-

iterator_facade is a base class template that implements the -interface of standard iterators in terms of a few core functions -and associated types, to be supplied by a derived iterator class.

- -
-

Motivation

-

While the iterator interface is rich, there is a core subset of the -interface that is necessary for all the functionality. We have -identified the following core behaviors for iterators:

-
    -
  • dereferencing
    • -
  • incrementing
    • -
  • decrementing
    • -
  • equality comparison
    • -
  • random-access motion
    • -
  • distance measurement
    • -
-

In addition to the behaviors listed above, the core interface elements -include the associated types exposed through iterator traits: -value_type, reference, difference_type, and -iterator_category.

-

Iterator facade uses the Curiously Recurring Template Pattern (CRTP) -[Cop95] so that the user can specify the behavior of -iterator_facade in a derived class. Former designs used policy -objects to specify the behavior. iterator_facade does not use policy -objects for several reasons:

-
-
    -
  1. the creation and eventual copying of the policy object may create -overhead that can be avoided with the current approach.
    2. -
  2. The policy object approach does not allow for custom constructors -on the created iterator types, an essential feature if -iterator_facade should be used in other library -implementations.
    3. -
  3. Without the use of CRTP, the standard requirement that an -iterator's operator++ returns the iterator type itself means -that all iterators generated by iterator_facade would be -instantiations of iterator_facade. Cumbersome type generator -metafunctions would be needed to build new parameterized -iterators, and a separate iterator_adaptor layer would be -impossible.
    4. -
-
-
-
-

Usage

-

The user of iterator_facade derives his iterator class from an -instantiation of iterator_facade which takes the derived iterator -class as the first template parameter. The order of the other -template parameters to iterator_facade have been carefully chosen -to take advantage of useful defaults. For example, when defining a -constant lvalue iterator, the user can pass a const-qualified version -of the iterator's value_type as iterator_facade's Value -parameter and omit the Reference parameter which follows.

-

The derived iterator class must define member functions implementing -the iterator's core behaviors. The following table describes -expressions which are required to be valid depending on the category -of the derived iterator type. These member functions are described -briefly below and in more detail in the iterator facade -requirements.

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - -
ExpressionEffects
i.dereference()Access the value referred to
i.equal(j)Compare for equality with j
i.increment()Advance by one position
i.decrement()Retreat by one position
i.advance(n)Advance by n positions
i.distance_to(j)Measure the distance to j
-
- -

In addition to implementing the core interface functions, an iterator -derived from iterator_facade typically defines several -constructors. To model any of the standard iterator concepts, the -iterator must at least have a copy constructor. Also, if the iterator -type X is meant to be automatically interoperate with another -iterator type Y (as with constant and mutable iterators) then -there must be an implicit conversion from X to Y or from Y -to X (but not both), typically implemented as a conversion -constructor. Finally, if the iterator is to model Forward Traversal -Iterator or a more-refined iterator concept, a default constructor is -required.

-
-
-

Iterator Core Access

-

iterator_facade and the operator implementations need to be able -to access the core member functions in the derived class. Making the -core member functions public would expose an implementation detail to -the user. The design used here ensures that implementation details do -not appear in the public interface of the derived iterator type.

-

Preventing direct access to the core member functions has two -advantages. First, there is no possibility for the user to accidently -use a member function of the iterator when a member of the value_type -was intended. This has been an issue with smart pointer -implementations in the past. The second and main advantage is that -library implementers can freely exchange a hand-rolled iterator -implementation for one based on iterator_facade without fear of -breaking code that was accessing the public core member functions -directly.

-

In a naive implementation, keeping the derived class' core member -functions private would require it to grant friendship to -iterator_facade and each of the seven operators. In order to -reduce the burden of limiting access, iterator_core_access is -provided, a class that acts as a gateway to the core member functions -in the derived iterator class. The author of the derived class only -needs to grant friendship to iterator_core_access to make his core -member functions available to the library.

- - -

iterator_core_access will be typically implemented as an empty -class containing only private static member functions which invoke the -iterator core member functions. There is, however, no need to -standardize the gateway protocol. Note that even if -iterator_core_access used public member functions it would not -open a safety loophole, as every core member function preserves the -invariants of the iterator.

-
-
-

operator[]

-

The indexing operator for a generalized iterator presents special -challenges. A random access iterator's operator[] is only -required to return something convertible to its value_type. -Requiring that it return an lvalue would rule out currently-legal -random-access iterators which hold the referenced value in a data -member (e.g. counting_iterator), because *(p+n) is a reference -into the temporary iterator p+n, which is destroyed when -operator[] returns.

-

Writable iterators built with iterator_facade implement the -semantics required by the preferred resolution to issue 299 and -adopted by proposal n1477: the result of p[n] is a proxy object -containing a copy of p+n, and p[n] = x is equivalent to *(p -+ n) = x. This approach will work properly for any random-access -iterator regardless of the other details of its implementation. A -user who knows more about the implementation of her iterator is free -to implement an operator[] which returns an lvalue in the derived -iterator class; it will hide the one supplied by iterator_facade -from clients of her iterator.

-
-
-

operator->

-

The reference type of a readable iterator (and today's input -iterator) need not in fact be a reference, so long as it is -convertible to the iterator's value_type. When the value_type -is a class, however, it must still be possible to access members -through operator->. Therefore, an iterator whose reference -type is not in fact a reference must return a proxy containing a copy -of the referenced value from its operator->.

-

The return type for operator-> and operator[] is not -explicitly specified. Instead it requires each iterator_facade -instantiation to meet the requirements of its iterator_category.

- - -- - - -
[Cop95][Coplien, 1995] Coplien, J., Curiously Recurring Template -Patterns, C++ Report, February 1995, pp. 24-27.
-
-
-

Reference

-
-template <
-    class Derived
-  , class Value
-  , class AccessCategory
-  , class TraversalCategory
-  , class Reference  = /* see below */
-  , class Difference = ptrdiff_t
->
-class iterator_facade {
-public:
-    typedef remove_cv<Value>::type value_type;
-    typedef Reference reference;
-    typedef /* see description of operator-> */ pointer;
-    typedef Difference difference_type;
-    typedef iterator_tag<AccessCategory, TraversalCategory> iterator_category;
-
-    reference operator*() const;
-    /* see below */ operator->() const;
-    /* see below */ operator[](difference_type n) const;
-    Derived& operator++();
-    Derived operator++(int);
-    Derived& operator--();
-    Derived operator--(int);
-    Derived& operator+=(difference_type n);
-    Derived& operator-=(difference_type n);
-    Derived operator-(difference_type n) const;
-};
-
-// Comparison operators
-template <class Dr1, class V1, class AC1, class TC1, class R1, class D1,
-          class Dr2, class V2, class AC2, class TC2, class R2, class D2>
-typename enable_if_interoperable<Dr1, Dr2, bool>::type // exposition
-operator ==(iterator_facade<Dr1, V1, AC1, TC1, R1, D1> const& lhs,
-            iterator_facade<Dr2, V2, AC2, TC2, R2, D2> const& rhs);
-
-template <class Dr1, class V1, class AC1, class TC1, class R1, class D1,
-          class Dr2, class V2, class AC2, class TC2, class R2, class D2>
-typename enable_if_interoperable<Dr1, Dr2, bool>::type
-operator !=(iterator_facade<Dr1, V1, AC1, TC1, R1, D1> const& lhs,
-            iterator_facade<Dr2, V2, AC2, TC2, R2, D2> const& rhs);
-
-template <class Dr1, class V1, class AC1, class TC1, class R1, class D1,
-          class Dr2, class V2, class AC2, class TC2, class R2, class D2>
-typename enable_if_interoperable<Dr1, Dr2, bool>::type
-operator <(iterator_facade<Dr1, V1, AC1, TC1, R1, D1> const& lhs,
-           iterator_facade<Dr2, V2, AC2, TC2, R2, D2> const& rhs);
-
-template <class Dr1, class V1, class AC1, class TC1, class R1, class D1,
-          class Dr2, class V2, class AC2, class TC2, class R2, class D2>
-typename enable_if_interoperable<Dr1, Dr2, bool>::type
-operator <=(iterator_facade<Dr1, V1, AC1, TC1, R1, D1> const& lhs,
-            iterator_facade<Dr2, V2, AC2, TC2, R2, D2> const& rhs);
-
-template <class Dr1, class V1, class AC1, class TC1, class R1, class D1,
-          class Dr2, class V2, class AC2, class TC2, class R2, class D2>
-typename enable_if_interoperable<Dr1, Dr2, bool>::type
-operator >(iterator_facade<Dr1, V1, AC1, TC1, R1, D1> const& lhs,
-           iterator_facade<Dr2, V2, AC2, TC2, R2, D2> const& rhs);
-
-template <class Dr1, class V1, class AC1, class TC1, class R1, class D1,
-          class Dr2, class V2, class AC2, class TC2, class R2, class D2>
-typename enable_if_interoperable<Dr1, Dr2, bool>::type
-operator >=(iterator_facade<Dr1, V1, AC1, TC1, R1, D1> const& lhs,
-            iterator_facade<Dr2, V2, AC2, TC2, R2, D2> const& rhs);
-
-template <class Dr1, class V1, class AC1, class TC1, class R1, class D1,
-          class Dr2, class V2, class AC2, class TC2, class R2, class D2>
-typename enable_if_interoperable<Dr1, Dr2, bool>::type
-operator >=(iterator_facade<Dr1, V1, AC1, TC1, R1, D1> const& lhs,
-            iterator_facade<Dr2, V2, AC2, TC2, R2, D2> const& rhs);
-
-// Iterator difference
-template <class Dr1, class V1, class AC1, class TC1, class R1, class D1,
-          class Dr2, class V2, class AC2, class TC2, class R2, class D2>
-typename enable_if_interoperable<Dr1, Dr2, bool>::type
-operator -(iterator_facade<Dr1, V1, AC1, TC1, R1, D1> const& lhs,
-           iterator_facade<Dr2, V2, AC2, TC2, R2, D2> const& rhs);
-
-// Iterator addition
-template <class Derived, class V, class AC, class TC, class R, class D>
-Derived operator+ (iterator_facade<Derived, V, AC, TC, R, D> const&,
-                   typename Derived::difference_type n)
-
-

[Note: The enable_if_interoperable template used above is for exposition -purposes. The member operators should be only be in an overload set -provided the derived types Dr1 and Dr2 are interoperable, by -which we mean they are convertible to each other. The -enable_if_interoperable approach uses SFINAE to take the operators -out of the overload set when the types are not interoperable.]

- -
-

iterator_facade requirements

-

The Derived template parameter must be a class derived from -iterator_facade.

-

The default for the Reference parameter is Value& if the -access category for iterator_facade is implicitly convertible to -writable_iterator_tag, and const Value& otherwise.

-

The following table describes the other requirements on the -Derived parameter. Depending on the resulting iterator's -iterator_category, a subset of the expressions listed in the table -are required to be valid. The operations in the first column must be -accessible to member functions of class iterator_core_access.

-

In the table below, X is the derived iterator type, a is an -object of type X, b and c are objects of type const X, -n is an object of X::difference_type, y is a constant -object of a single pass iterator type interoperable with X, and z -is a constant object of a random access traversal iterator type -interoperable with X.

- ------ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ExpressionReturn TypeAssertion/NoteRequired to implement -Iterator Concept(s)
c.dereference()X::reference Readable Iterator, Writable -Iterator
c.equal(b)convertible to booltrue iff b and c are -equivalent.Single Pass Iterator
c.equal(y)convertible to booltrue iff c and y refer to the -same position. Implements c == y -and c != y.Single Pass Iterator
a.advance(n)unused Random Access Traversal -Iterator
a.increment()unused Incrementable Iterator
a.decrement()unused Bidirectional Traversal -Iterator
c.distance_to(b)convertible to -X::difference_typeequivalent to distance(c, b)Random Access Traversal -Iterator
c.distance_to(z)convertible to -X::difference_typeequivalent to distance(c, z). -Implements c - z, c < z, c -<= z, c > z, and c >= c.Random Access Traversal -Iterator
- -
-
-

iterator_facade operations

-

The operations in this section are described in terms of operations on -the core interface of Derived which may be inaccessible -(i.e. private). The implementation should access these operations -through member functions of class iterator_core_access.

-

reference operator*() const;

- --- - - - -
Returns:static_cast<Derived const*>(this)->dereference()
-

operator->() const; (see below)

- --- - - - -
Returns:

If X::reference is a reference type, returns an object -of type X::pointer equal to:

-
-&static_cast<Derived const*>(this)->dereference()
-
-

Otherwise returns an object of unspecified type such that, given an -object a of type X, a->m is equivalent to (w = *a, -w.m) for some temporary object w of type X::value_type.

-

The type X::pointer is Value* if the access category for -X is implicitly convertible to writable_iterator_tag, and -Value const* otherwise.

-
-

unspecified operator[](difference_type n) const;

- --- - - - -
Returns:an object convertible to X::reference and holding a copy -p of a+n such that, for a constant object v of type -X::value_type, X::reference(a[n] = v) is equivalent -to p = v.
-

Derived& operator++();

- --- - - - -
Effects:
-static_cast<Derived*>(this)->increment();
-return *this;
-
-
- -

Derived operator++(int);

- --- - - - -
Effects:
-Derived tmp(static_cast<Derived const*>(this));
-++*this;
-return tmp;
-
-
-

Derived& operator--();

- --- - - - -
Effects:
-static_cast<Derived*>(this)->decrement();
-return *this;
-
-
-

Derived operator--(int);

- --- - - - -
Effects:
-Derived tmp(static_cast<Derived const*>(this));
---*this;
-return tmp;
-
-
-

Derived& operator+=(difference_type n);

- --- - - - -
Effects:
-static_cast<Derived*>(this)->advance(n);
-return *this;
-
-
-

Derived& operator-=(difference_type n);

- --- - - - -
Effects:
-static_cast<Derived*>(this)->advance(-n);
-return *this;
-
-
-

Derived operator-(difference_type n) const;

- --- - - - - - -
Effects:Derived tmp(static_cast<Derived const*>(this)); -return tmp -= n;
Returns:static_cast<Derived const*>(this)->advance(-n);
-
-
-
-
-
-View document source. -Generated on: 2003-09-14 02:16 UTC. -Generated by Docutils from reStructuredText source. -
- - diff --git a/doc/iterator_facade.rst b/doc/iterator_facade.rst deleted file mode 100644 index 473d095..0000000 --- a/doc/iterator_facade.rst +++ /dev/null @@ -1,33 +0,0 @@ -++++++++++++++++ - Iterator Facade -++++++++++++++++ - -:Author: David Abrahams, Jeremy Siek, Thomas Witt -:Contact: dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de -:organization: `Boost Consulting`_, Indiana University `Open Systems - Lab`_, University of Hanover `Institute for Transport - Railway Operation and Construction`_ -:date: $Date$ -:copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved - -.. _`Boost Consulting`: http://www.boost-consulting.com -.. _`Open Systems Lab`: http://www.osl.iu.edu -.. _`Institute for Transport Railway Operation and Construction`: http://www.ive.uni-hannover.de - -:abstract: - -.. include:: iterator_facade_abstract.rst - -.. contents:: Table of Contents - - -Motivation ----------- - -.. include:: iterator_facade_body.rst - - -Reference ---------- - -.. include:: iterator_facade_ref.rst diff --git a/doc/iterator_facade_abstract.rst b/doc/iterator_facade_abstract.rst deleted file mode 100644 index f024b9b..0000000 --- a/doc/iterator_facade_abstract.rst +++ /dev/null @@ -1,4 +0,0 @@ -``iterator_facade`` is a base class template that implements the -interface of standard iterators in terms of a few core functions -and associated types, to be supplied by a derived iterator class. - diff --git a/doc/iterator_facade_body.rst b/doc/iterator_facade_body.rst deleted file mode 100644 index ee6fb9c..0000000 --- a/doc/iterator_facade_body.rst +++ /dev/null @@ -1,180 +0,0 @@ -While the iterator interface is rich, there is a core subset of the -interface that is necessary for all the functionality. We have -identified the following core behaviors for iterators: - -* dereferencing -* incrementing -* decrementing -* equality comparison -* random-access motion -* distance measurement - -In addition to the behaviors listed above, the core interface elements -include the associated types exposed through iterator traits: -``value_type``, ``reference``, ``difference_type``, and -``iterator_category``. - -Iterator facade uses the Curiously Recurring Template Pattern (CRTP) -[Cop95]_ so that the user can specify the behavior of -``iterator_facade`` in a derived class. Former designs used policy -objects to specify the behavior. ``iterator_facade`` does not use policy -objects for several reasons: - - 1. the creation and eventual copying of the policy object may create - overhead that can be avoided with the current approach. - - 2. The policy object approach does not allow for custom constructors - on the created iterator types, an essential feature if - ``iterator_facade`` should be used in other library - implementations. - - 3. Without the use of CRTP, the standard requirement that an - iterator's ``operator++`` returns the iterator type itself means - that all iterators generated by ``iterator_facade`` would be - instantiations of ``iterator_facade``. Cumbersome type generator - metafunctions would be needed to build new parameterized - iterators, and a separate ``iterator_adaptor`` layer would be - impossible. - -Usage ------ - -The user of ``iterator_facade`` derives his iterator class from an -instantiation of ``iterator_facade`` which takes the derived iterator -class as the first template parameter. The order of the other -template parameters to ``iterator_facade`` have been carefully chosen -to take advantage of useful defaults. For example, when defining a -constant lvalue iterator, the user can pass a const-qualified version -of the iterator's ``value_type`` as ``iterator_facade``\ 's ``Value`` -parameter and omit the ``Reference`` parameter which follows. - -The derived iterator class must define member functions implementing -the iterator's core behaviors. The following table describes -expressions which are required to be valid depending on the category -of the derived iterator type. These member functions are described -briefly below and in more detail in the iterator facade -requirements. - - +------------------------+-------------------------------+ - |Expression |Effects | - +========================+===============================+ - |``i.dereference()`` |Access the value referred to | - +------------------------+-------------------------------+ - |``i.equal(j)`` |Compare for equality with ``j``| - +------------------------+-------------------------------+ - |``i.increment()`` |Advance by one position | - +------------------------+-------------------------------+ - |``i.decrement()`` |Retreat by one position | - +------------------------+-------------------------------+ - |``i.advance(n)`` |Advance by ``n`` positions | - +------------------------+-------------------------------+ - |``i.distance_to(j)`` |Measure the distance to ``j`` | - +------------------------+-------------------------------+ - -.. Should we add a comment that a zero overhead implementation of iterator_facade - is possible with proper inlining? - -In addition to implementing the core interface functions, an iterator -derived from ``iterator_facade`` typically defines several -constructors. To model any of the standard iterator concepts, the -iterator must at least have a copy constructor. Also, if the iterator -type ``X`` is meant to be automatically interoperate with another -iterator type ``Y`` (as with constant and mutable iterators) then -there must be an implicit conversion from ``X`` to ``Y`` or from ``Y`` -to ``X`` (but not both), typically implemented as a conversion -constructor. Finally, if the iterator is to model Forward Traversal -Iterator or a more-refined iterator concept, a default constructor is -required. - - - -Iterator Core Access --------------------- - -``iterator_facade`` and the operator implementations need to be able -to access the core member functions in the derived class. Making the -core member functions public would expose an implementation detail to -the user. The design used here ensures that implementation details do -not appear in the public interface of the derived iterator type. - -Preventing direct access to the core member functions has two -advantages. First, there is no possibility for the user to accidently -use a member function of the iterator when a member of the value_type -was intended. This has been an issue with smart pointer -implementations in the past. The second and main advantage is that -library implementers can freely exchange a hand-rolled iterator -implementation for one based on ``iterator_facade`` without fear of -breaking code that was accessing the public core member functions -directly. - -In a naive implementation, keeping the derived class' core member -functions private would require it to grant friendship to -``iterator_facade`` and each of the seven operators. In order to -reduce the burden of limiting access, ``iterator_core_access`` is -provided, a class that acts as a gateway to the core member functions -in the derived iterator class. The author of the derived class only -needs to grant friendship to ``iterator_core_access`` to make his core -member functions available to the library. - -.. This is no long uptodate -thw -.. Yes it is; I made sure of it! -DWA - -``iterator_core_access`` will be typically implemented as an empty -class containing only private static member functions which invoke the -iterator core member functions. There is, however, no need to -standardize the gateway protocol. Note that even if -``iterator_core_access`` used public member functions it would not -open a safety loophole, as every core member function preserves the -invariants of the iterator. - -``operator[]`` --------------- - -The indexing operator for a generalized iterator presents special -challenges. A random access iterator's ``operator[]`` is only -required to return something convertible to its ``value_type``. -Requiring that it return an lvalue would rule out currently-legal -random-access iterators which hold the referenced value in a data -member (e.g. `counting_iterator`__), because ``*(p+n)`` is a reference -into the temporary iterator ``p+n``, which is destroyed when -``operator[]`` returns. - -__ counting_iterator.html - -Writable iterators built with ``iterator_facade`` implement the -semantics required by the preferred resolution to `issue 299`_ and -adopted by proposal `n1477`_: the result of ``p[n]`` is a proxy object -containing a copy of ``p+n``, and ``p[n] = x`` is equivalent to ``*(p -+ n) = x``. This approach will work properly for any random-access -iterator regardless of the other details of its implementation. A -user who knows more about the implementation of her iterator is free -to implement an ``operator[]`` which returns an lvalue in the derived -iterator class; it will hide the one supplied by ``iterator_facade`` -from clients of her iterator. - -.. _`n1477`: http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/papers/2003/n1477.html - -.. _issue 299: http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/lwg-active.html#299 - -.. _`operator arrow`: - - -``operator->`` --------------- - -The ``reference`` type of a readable iterator (and today's input -iterator) need not in fact be a reference, so long as it is -convertible to the iterator's ``value_type``. When the ``value_type`` -is a class, however, it must still be possible to access members -through ``operator->``. Therefore, an iterator whose ``reference`` -type is not in fact a reference must return a proxy containing a copy -of the referenced value from its ``operator->``. - -The return type for ``operator->`` and ``operator[]`` is not -explicitly specified. Instead it requires each ``iterator_facade`` -instantiation to meet the requirements of its ``iterator_category``. - - -.. [Cop95] [Coplien, 1995] Coplien, J., Curiously Recurring Template - Patterns, C++ Report, February 1995, pp. 24-27. - diff --git a/doc/iterator_facade_ref.rst b/doc/iterator_facade_ref.rst deleted file mode 100644 index 04d5150..0000000 --- a/doc/iterator_facade_ref.rst +++ /dev/null @@ -1,284 +0,0 @@ -.. parsed-literal:: - - template < - class Derived - , class Value - , class AccessCategory - , class TraversalCategory - , class Reference = /* see below__ \*/ - , class Difference = ptrdiff_t - > - class iterator_facade { - public: - typedef remove_cv::type value_type; - typedef Reference reference; - typedef /* see `description of operator->`__ \*/ pointer; - typedef Difference difference_type; - typedef iterator_tag iterator_category; - - reference operator\*() const; - /* see below__ \*/ operator->() const; - /* see below__ \*/ operator[](difference_type n) const; - Derived& operator++(); - Derived operator++(int); - Derived& operator--(); - Derived operator--(int); - Derived& operator+=(difference_type n); - Derived& operator-=(difference_type n); - Derived operator-(difference_type n) const; - }; - - // Comparison operators - template - typename enable_if_interoperable::type // exposition - operator ==(iterator_facade const& lhs, - iterator_facade const& rhs); - - template - typename enable_if_interoperable::type - operator !=(iterator_facade const& lhs, - iterator_facade const& rhs); - - template - typename enable_if_interoperable::type - operator <(iterator_facade const& lhs, - iterator_facade const& rhs); - - template - typename enable_if_interoperable::type - operator <=(iterator_facade const& lhs, - iterator_facade const& rhs); - - template - typename enable_if_interoperable::type - operator >(iterator_facade const& lhs, - iterator_facade const& rhs); - - template - typename enable_if_interoperable::type - operator >=(iterator_facade const& lhs, - iterator_facade const& rhs); - - template - typename enable_if_interoperable::type - operator >=(iterator_facade const& lhs, - iterator_facade const& rhs); - - // Iterator difference - template - typename enable_if_interoperable::type - operator -(iterator_facade const& lhs, - iterator_facade const& rhs); - - // Iterator addition - template - Derived operator+ (iterator_facade const&, - typename Derived::difference_type n) - - -__ `iterator facade requirements`_ - -__ `operator arrow`_ - -__ `operator arrow`_ - -__ brackets_ - -[*Note:* The ``enable_if_interoperable`` template used above is for exposition -purposes. The member operators should be only be in an overload set -provided the derived types ``Dr1`` and ``Dr2`` are interoperable, by -which we mean they are convertible to each other. The -``enable_if_interoperable`` approach uses SFINAE to take the operators -out of the overload set when the types are not interoperable.] - - -.. we need a new label here because the presence of markup in the - title prevents an automatic link from being generated - -.. _iterator facade requirements: - -``iterator_facade`` requirements -................................ - -The ``Derived`` template parameter must be a class derived from -``iterator_facade``. - -The default for the ``Reference`` parameter is ``Value&`` if the -access category for ``iterator_facade`` is implicitly convertible to -``writable_iterator_tag``, and ``const Value&`` otherwise. - -The following table describes the other requirements on the -``Derived`` parameter. Depending on the resulting iterator's -``iterator_category``, a subset of the expressions listed in the table -are required to be valid. The operations in the first column must be -accessible to member functions of class ``iterator_core_access``. - -In the table below, ``X`` is the derived iterator type, ``a`` is an -object of type ``X``, ``b`` and ``c`` are objects of type ``const X``, -``n`` is an object of ``X::difference_type``, ``y`` is a constant -object of a single pass iterator type interoperable with X, and ``z`` -is a constant object of a random access traversal iterator type -interoperable with ``X``. - -+--------------------+-------------------+-------------------------------------+---------------------------+ -|Expression |Return Type |Assertion/Note |Required to implement | -| | | |Iterator Concept(s) | -+====================+===================+=====================================+===========================+ -|``c.dereference()`` |``X::reference`` | |Readable Iterator, Writable| -| | | |Iterator | -+--------------------+-------------------+-------------------------------------+---------------------------+ -|``c.equal(b)`` |convertible to bool|true iff ``b`` and ``c`` are |Single Pass Iterator | -| | |equivalent. | | -+--------------------+-------------------+-------------------------------------+---------------------------+ -|``c.equal(y)`` |convertible to bool|true iff ``c`` and ``y`` refer to the|Single Pass Iterator | -| | |same position. Implements ``c == y``| | -| | |and ``c != y``. | | -+--------------------+-------------------+-------------------------------------+---------------------------+ -|``a.advance(n)`` |unused | |Random Access Traversal | -| | | |Iterator | -+--------------------+-------------------+-------------------------------------+---------------------------+ -|``a.increment()`` |unused | |Incrementable Iterator | -+--------------------+-------------------+-------------------------------------+---------------------------+ -|``a.decrement()`` |unused | |Bidirectional Traversal | -| | | |Iterator | -+--------------------+-------------------+-------------------------------------+---------------------------+ -|``c.distance_to(b)``|convertible to |equivalent to ``distance(c, b)`` |Random Access Traversal | -| |X::difference_type | |Iterator | -+--------------------+-------------------+-------------------------------------+---------------------------+ -|``c.distance_to(z)``|convertible to |equivalent to ``distance(c, z)``. |Random Access Traversal | -| |X::difference_type |Implements ``c - z``, ``c < z``, ``c |Iterator | -| | |<= z``, ``c > z``, and ``c >= c``. | | -+--------------------+-------------------+-------------------------------------+---------------------------+ - -.. We should explain more about how the - functions in the interface of iterator_facade - are there conditionally. -JGS - - -``iterator_facade`` operations -.............................. - -The operations in this section are described in terms of operations on -the core interface of ``Derived`` which may be inaccessible -(i.e. private). The implementation should access these operations -through member functions of class ``iterator_core_access``. - -``reference operator*() const;`` - -:Returns: ``static_cast(this)->dereference()`` - -``operator->() const;`` (see below__) - -__ `operator arrow`_ - -:Returns: If ``X::reference`` is a reference type, returns an object - of type ``X::pointer`` equal to:: - - &static_cast(this)->dereference() - - Otherwise returns an object of unspecified type such that, given an - object ``a`` of type ``X``, ``a->m`` is equivalent to ``(w = *a, - w.m)`` for some temporary object ``w`` of type ``X::value_type``. - - The type ``X::pointer`` is ``Value*`` if the access category for - ``X`` is implicitly convertible to ``writable_iterator_tag``, and - ``Value const*`` otherwise. - - -.. _brackets: - -*unspecified* ``operator[](difference_type n) const;`` - -:Returns: an object convertible to ``X::reference`` and holding a copy - *p* of ``a+n`` such that, for a constant object ``v`` of type - ``X::value_type``, ``X::reference(a[n] = v)`` is equivalent - to ``p = v``. - - - -``Derived& operator++();`` - -:Effects: - - :: - - static_cast(this)->increment(); - return *this; - -.. I realize that the committee is moving away from specifying things - like this in terms of code, but I worried about the imprecision of - saying that a core interface function is invoked without describing - the downcast. An alternative to what I did would be to mention it - above where we talk about accessibility. - - -``Derived operator++(int);`` - -:Effects: - - :: - - Derived tmp(static_cast(this)); - ++*this; - return tmp; - - -``Derived& operator--();`` - -:Effects: - - :: - - static_cast(this)->decrement(); - return *this; - - -``Derived operator--(int);`` - -:Effects: - - :: - - Derived tmp(static_cast(this)); - --*this; - return tmp; - - -``Derived& operator+=(difference_type n);`` - -:Effects: - - :: - - static_cast(this)->advance(n); - return *this; - - -``Derived& operator-=(difference_type n);`` - -:Effects: - - :: - - static_cast(this)->advance(-n); - return *this; - - -``Derived operator-(difference_type n) const;`` - -:Effects: - - Derived tmp(static_cast(this)); - return tmp -= n; - -:Returns: ``static_cast(this)->advance(-n);`` - - diff --git a/doc/new-iter-concepts.html b/doc/new-iter-concepts.html deleted file mode 100755 index 8202cf7..0000000 --- a/doc/new-iter-concepts.html +++ /dev/null @@ -1,952 +0,0 @@ - - - - - - -New Iterator Concepts - - - - - - - -
-

New Iterator Concepts

- --- - - - - - - - - - - - - - -
Author:David Abrahams, Jeremy Siek, Thomas Witt
Contact:dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de
Organization:Boost Consulting, Indiana University Open Systems Lab, University of Hanover Institute for Transport Railway Operation and Construction
Date:2003-08-14
Number:This document is a revised version of the official N1477=03-0060
Copyright:Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved
- --- - - - -
Abstract:We propose a new system of iterator concepts that treat -access and positioning independently. This allows the -concepts to more closely match the requirements -of algorithms and provides better categorizations -of iterators that are used in practice. This proposal -is a revision of paper n1297.
- -
-

Motivation

-

The standard iterator categories and requirements are flawed because -they use a single hierarchy of concepts to address two orthogonal -issues: iterator traversal and value access. As a result, many -algorithms with requirements expressed in terms of the iterator -categories are too strict. Also, many real-world iterators can not be -accurately categorized. A proxy-based iterator with random-access -traversal, for example, may only legally have a category of "input -iterator", so generic algorithms are unable to take advantage of its -random-access capabilities. The current iterator concept hierarchy is -geared towards iterator traversal (hence the category names), while -requirements that address value access sneak in at various places. The -following table gives a summary of the current value access -requirements in the iterator categories.

- ---- - - - - - - - - - - - - - - -
Output Iterator*i = a
Input Iterator*i is convertible to T
Forward Iterator*i is T& (or const T& once issue 200 -is resolved)
Random Access Iteratori[n] is convertible to T (also i[n] = t -is required for mutable iterators once issue 299 -is resolved)
-

Because iterator traversal and value access are mixed together in a -single hierarchy, many useful iterators can not be appropriately -categorized. For example, vector<bool>::iterator is almost a -random access iterator, but the return type is not bool& (see -issue 96 and Herb Sutter's paper J16/99-0008 = WG21 -N1185). Therefore, the iterators of vector<bool> only meet the -requirements of input iterator and output iterator. This is so -nonintuitive that at least one implementation erroneously assigns -random_access_iterator_tag as its iterator_category.

-

Another difficult-to-categorize iterator is the transform iterator, an -adaptor which applies a unary function object to the dereferenced -value of the some underlying iterator (see transform_iterator). -For unary functions such as times, the return type of -operator* clearly needs to be the result_type of the function -object, which is typically not a reference. Because random access -iterators are required to return lvalues from operator*, if you -wrap int* with a transform iterator, you do not get a random -access iterator as might be expected, but an input iterator.

-

A third example is found in the vertex and edge iterators of the -Boost Graph Library. These iterators return vertex and edge -descriptors, which are lightweight handles created on-the-fly. They -must be returned by-value. As a result, their current standard -iterator category is input_iterator_tag, which means that, -strictly speaking, you could not use these iterators with algorithms -like min_element(). As a temporary solution, the concept -Multi-Pass Input Iterator was introduced to describe the vertex and -edge descriptors, but as the design notes for the concept suggest, a -better solution is needed.

-

In short, there are many useful iterators that do not fit into the -current standard iterator categories. As a result, the following bad -things happen:

-
    -
  • Iterators are often mis-categorized.
    • -
  • Algorithm requirements are more strict than necessary, because they -cannot separate the need for random access or bidirectional -traversal from the need for a true reference return type.
    • -
-
-
-

Impact on the Standard

-

The new iterator concepts are backward-compatible with the old -iterator requirements, and old iterators are forward-compatible with -the new iterator concepts. That is to say, iterators that satisfy the -old requirements also satisfy appropriate concepts in the new system, -and iterators modeling the new concepts will automatically satisfy the -appropriate old requirements.

- - -

The algorithms in the standard library benefit from the new iterator -concepts because the new concepts provide a more accurate way to -express their type requirements. The result is algorithms that are -usable in more situations and have fewer type requirements. The -following lists the proposed changes to the type requirements of -algorithms.

-

Forward Iterator -> Forward Traversal Iterator and Readable Iterator

-
-find_end, adjacent_find, search, search_n, rotate_copy, lower_bound, upper_bound, equal_range, binary_search, min_element, max_element
-

Forward Iterator (1) -> Single Pass Iterator and Readable Iterator -Forward Iterator (2) -> Forward Traversal Iterator and Readable Iterator

-
-find_first_of
-

Forward Iterator -> Readable Iterator and Writable Iterator

-
-iter_swap
-

Forward Iterator -> Single Pass Iterator and Writable Iterator

-
-fill, generate
-

Forward Iterator -> Forward Traversal Iterator and Swappable Iterator

-
-rotate
-

Forward Iterator (1) -> Swappable Iterator and Single Pass Iterator -Forward Iterator (2) -> Swappable Iterator and Incrementable Iterator

-
-swap_ranges
-
-
Forward Iterator -> Forward Traversal Iterator and Readable Iterator and Writable Iterator
-
remove, remove_if, unique
-
-

Forward Iterator -> Single Pass Iterator and Readable Iterator and Writable Iterator

-
-replace, replace_if
-
-
Bidirectional Iterator -> Bidirectional Traversal Iterator and Swappable Iterator
-
reverse
-
Bidirectional Iterator -> Bidirectional Traversal Iterator and Readable and Swappable Iterator
-
partition
-
-

Bidirectional Iterator (1) -> Bidirectional Traversal Iterator and Readable Iterator, -Bidirectional Iterator (2) -> Bidirectional Traversal Iterator and Writable Iterator

-
-copy_backwards
-
-
Bidirectional Iterator -> Bidirectional Traversal Iterator and Swappable Iterator and Readable Iterator
-
next_permutation, prev_permutation
-
Bidirectional Iterator -> Bidirectional Traversal Iterator and Readable Iterator and Writable Iterator
-
stable_partition, inplace_merge
-
Bidirectional Iterator -> Bidirectional Traversal Iterator and Readable Iterator
-
reverse_copy
-
Random Access Iterator -> Random Access Traversal Iterator and Readable and Swappable Iterator
-
random_shuffle, sort, stable_sort, partial_sort, nth_element, push_heap, pop_heap -make_heap, sort_heap
-
Input Iterator (2) -> Incrementable Iterator and Readable Iterator
-
equal
-
Input Iterator (2) -> Incrementable Iterator and Readable Iterator
-
transform
-
-
-
-

Design

-

The iterator requirements are be separated into two hierarchies. One -set of concepts handles the syntax and semantics of value access:

-
    -
  • Readable Iterator
    • -
  • Writable Iterator
    • -
  • Swappable Iterator
    • -
  • Readable Lvalue Iterator
    • -
  • Writable Lvalue Iterator
    • -
-

The refinement relationships among these iterator concepts are given -in the following diagram.

-

access.png

-

The access concepts describe requirements related to operator* and -operator->, including the value_type, reference, and -pointer associated types.

-

The other set of concepts handles traversal:

-
    -
  • Incrementable Iterator
    • -
  • Single Pass Iterator
    • -
  • Forward Traversal Iterator
    • -
  • Bidirectional Traversal Iterator
    • -
  • Random Access Traversal Iterator
    • -
-

The refinement relationships for the traversal concepts are in the -following diagram.

-

traversal.png

-

In addition to the iterator movement operators, such as -operator++, the traversal concepts also include requirements on -position comparison such as operator== and operator<. The -reason for the fine grain slicing of the concepts into the -Incrementable and Single Pass is to provide concepts that are exact -matches with the original input and output iterator requirements.

-

The relationship between the new iterator concepts and the old are -given in the following diagram.

-

oldeqnew.png

-

Like the old iterator requirements, we provide tags for purposes of -dispatching. There are two hierarchies of tags, one for the access -concepts and one for the traversal concepts. We provide an access -mechanism for mapping iterator types to these new tags. Our design -reuses iterator_traits<Iter>::iterator_category as the access -mechanism. To enable this, a pair of access and traversal tags are -combined into a single type using the following iterator_tag class.

-
-template <class AccessTag, class TraversalTag>
-struct iterator_tag : /* appropriate old category or categories */
-{
-  typedef AccessTag access;
-  typedef TraversalTag traversal;
-};
-
-

The iterator_tag class template is derived from the appropriate -iterator tag or tags from the old requirements based on the new-style -tags passed as template parameters. The algorithm for determining the -old tag or tags from the new tags picks the least-refined old concepts -that include all of the requirements of the access and traversal -concepts (that is, the closest fit), if any such category exists. For -example, a the category tag for a Readable Single Pass Iterator will -always be derived from input_iterator_tag, while the category tag -for a Single Pass Iterator that is both Readable and Writable will be -derived from both input_iterator_tag and output_iterator_tag.

-

We also provide two helper classes that make it convenient to obtain -the access and traversal tags of an iterator. These helper classes -work both for iterators whose iterator_category is -iterator_tag and also for iterators using the original iterator -categories.

-
-template <class Iterator> struct access_category { typedef ... type; };
-template <class Iterator> struct traversal_category { typedef ... type; };
-
-

The most difficult design decision concerned the operator[]. The -direct approach for specifying operator[] would have a return type -of reference; the same as operator*. However, going in this -direction would mean that an iterator satisfying the old Random Access -Iterator requirements would not necessarily be a model of Readable or -Writable Lvalue Iterator. Instead we have chosen a design that -matches the preferred resolution of issue 299: operator[] is -only required to return something convertible to the value_type -(for a Readable Iterator), and is required to support assignment -i[n] = t (for a Writable Iterator).

-
-
-

Proposed Text

-
-

Addition to [lib.iterator.requirements]

-
-

Iterator Value Access Concepts [lib.iterator.value.access]

-

In the tables below, X is an iterator type, a is a constant -object of type X, T is -std::iterator_traits<X>::value_type, and v is a constant -object of type T.

-
-

Readable Iterators [lib.readable.iterators]

-

A class or built-in type X models the Readable Iterator concept -for the value type T if the following expressions are valid and -respect the stated semantics. U is the type of any specified -member of type T.

-
- ----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Readable Iterator Requirements (in addition to CopyConstructible)
ExpressionReturn TypeAssertion/Note/Precondition/Postcondition
iterator_traits<X>::value_typeTAny non-reference, non-cv-qualified type
iterator_traits<X>::referenceConvertible to -iterator_traits<X>::value_type 
access_category<X>::typeConvertible to -readable_iterator_tag 
*aiterator_traits<X>::referencepre: a is dereferenceable. If a == -b then *a is equivalent to *b
a->mU&pre: (*a).m is well-defined. -Equivalent to (*a).m
-
-
-
-

Writable Iterators [lib.writable.iterators]

-

A class or built-in type X models the Writable Iterator concept -if the following expressions are valid and respect the stated -semantics. In addition, a model of Writable Iterator must include -in its documentation the set of value types that it allows for -output.

-
- ----- - - - - - - - - - - - - - - - - - - -
Writable Iterator Requirements (in addition to CopyConstructible)
ExpressionReturn TypePrecondition
access_category<X>::typeConvertible to -writable_iterator_tag 
*a = o pre: The type of o -is in the set of -value types of X
-
-
-
-

Swappable Iterators [lib.swappable.iterators]

-

A class or built-in type X models the Swappable Iterator concept -if the following expressions are valid and respect the stated -semantics.

-
- ----- - - - - - - - - - - - - - - -
Swappable Iterator Requirements (in addition to CopyConstructible)
ExpressionReturn TypePostcondition
iter_swap(a, b)voidpost: the pointed to values are exchanged
-
-
-
[Note: An iterator that is a model of the Readable and Writable Iterator concepts
-
is also a model of Swappable Iterator. --end note]
-
-
-
-

Readable Lvalue Iterators [lib.readable.lvalue.iterators]

-

The Readable Lvalue Iterator concept adds the requirement that the -reference type be a reference to the value type of the iterator.

-
- ----- - - - - - - - - - - - - - - - - - - -
Readable Lvalue Iterator Requirements (in addition to Readable Iterator)
ExpressionReturn TypeAssertion
iterator_traits<X>::referenceT&T is cv -iterator_traits<X>::value_type -where cv is an optional -cv-qualification
access_category<X>::typeConvertible to -readable_lvalue_iterator_tag 
-
-
-
-

Writable Lvalue Iterators [lib.writable.lvalue.iterators]

-

The Writable Lvalue Iterator concept adds the requirement that the -reference type be a non-const reference to the value type of the -iterator.

-
- ---- - - - - - - - - - - - - - - - -
Writable Lvalue Iterator Requirements (in addition to Readable Lvalue Iterator)
ExpressionReturn Type
iterator_traits<X>::referenceiterator_traits<X>::value_type&
access_category<X>::typeConvertible to writable_lvalue_iterator_tag
-
-
-
-
-

Iterator Traversal Concepts [lib.iterator.traversal]

-

In the tables below, X is an iterator type, a and b are -constant objects of type X, r and s are mutable objects of -type X, T is std::iterator_traits<X>::value_type, and -v is a constant object of type T.

-
-

Incrementable Iterators [lib.incrementable.iterators]

-

A class or built-in type X models the Incrementable Iterator -concept if the following expressions are valid and respect the stated -semantics.

-
- ----- - - - - - - - - - - - - - - - - - - - - - - -
Incrementable Iterator Requirements (in addition to Assignable, Copy Constructible)
ExpressionReturn TypeAssertion/Semantics
++rX&&r == &++r
r++X{ X tmp = r; ++r; return tmp; }
traversal_category<X>::typeConvertible to incrementable_iterator_tag 
-
-
-
-

Single Pass Iterators [lib.single.pass.iterators]

-

A class or built-in type X models the Single Pass Iterator -concept if the following expressions are valid and respect the stated -semantics.

-
- ----- - - - - - - - - - - - - - - - - - - - - - - - - - - -
Single Pass Iterator Requirements (in addition to Incrementable Iterator and Equality Comparable)
ExpressionReturn TypeAssertion/Semantics/Pre-/Post-condition
++rX&pre: r is dereferenceable; post: -r is dereferenceable or r is -past-the-end
a == bconvertible to bool== is an equivalence relation over -its domain
a != bconvertible to bool!(a == b)
traversal_category<X>::typeConvertible to -single_pass_iterator_tag 
-
-
-
-

Forward Traversal Iterators [lib.forward.traversal.iterators]

-

A class or built-in type X models the Forward Traversal Iterator -concept if the following expressions are valid and respect the stated -semantics.

-
- ----- - - - - - - - - - - - - - - - - - - - - - - - - - - -
Forward Traversal Iterator Requirements (in addition to Single Pass Iterator)
ExpressionReturn TypeAssertion/Note
X u;X&note: u may have a -singular value.
++rX&r == s and r is -dereferenceable implies -++r == ++s.
iterator_traits<X>::difference_typeA signed integral type representing -the distance between iterators 
traversal_category<X>::typeConvertible to -forward_traversal_iterator_tag 
-
-
-
-

Bidirectional Traversal Iterators [lib.bidirectional.traversal.iterators]

-

A class or built-in type X models the Bidirectional Traversal -Iterator concept if the following expressions are valid and respect -the stated semantics.

-
- ----- - - - - - - - - - - - - - - - - - - - - - - -
Bidirectional Traversal Iterator Requirements (in addition to Forward Traversal Iterator)
ExpressionReturn TypeAssertion/Semantics/Pre-/Post-condition
--rX&pre: there exists s such that r -== ++s. post: s is -dereferenceable. --(++r) == r. ---r == --s implies r == s. &r -== &--r.
r--convertible to const X&{ X tmp = r; --r; return tmp; }
traversal_category<X>::typeConvertible to -bidirectional_traversal_iterator_tag 
-
-
-
-

Random Access Traversal Iterators [lib.random.access.traversal.iterators]

-

A class or built-in type X models the Random Access Traversal -Iterator concept if the following expressions are valid and respect -the stated semantics. In the table below, Distance is -iterator_traits<X>::difference_type and n represents a -constant object of type Distance.

-
- ------ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Random Access Traversal Iterator Requirements (in addition to Bidirectional Traversal Iterator)
ExpressionReturn TypeOperational SemanticsAssertion/Precondition
r += nX&
-{
-  Distance m = n;
-  if (m >= 0)
-    while (m--)
-      ++r;
-  else
-    while (m++)
-      --r;
-  return r;
-}
-
-		 
a + n, n + aX{ X tmp = a; return -tmp += n; } 
r -= nX&return r += -n 
a - nX{ X tmp = a; return -tmp -= n; } 
b - aDistancea < b ? -distance(a,b) : --distance(b,a)pre: there exists a value -n of Distance such -that a + n == b. b == -a + (b - a).
a[n]convertible to T*(a + n)pre: a is a readable -iterator
a[n] = vconvertible to T*(a + n) = vpre: a is a writable -iterator
a < bconvertible to boolb - a > 0< is a total ordering -relation
a > bconvertible to boolb < a> is a total ordering -relation
a >= bconvertible to bool!(a < b) 
a <= bconvertible to bool!(a > b) 
traversal_category<X>::typeConvertible to -random_access_traversal_iterator_tag  
-
-
-
-
-
-

Addition to [lib.iterator.synopsis]

-
-// lib.iterator.traits, traits and tags
-template <class Iterator> struct access_category;
-template <class Iterator> struct traversal_category;
-
-template <class AccessTag, class TraversalTag>
-struct iterator_tag : /* appropriate old category or categories */ {
-  typedef AccessTag access;
-  typedef TraversalTag traversal;
-};
-
-struct readable_iterator_tag { };
-struct writable_iterator_tag { };
-struct swappable_iterator_tag { };
-struct readable_writable_iterator_tag
-  : virtual readable_iterator_tag
-  , virtual writable_iterator_tag
-  , virtual swappable_iterator_tag { };
-struct readable_lvalue_iterator_tag { };
-struct writable_lvalue_iterator_tag
-  : virtual public readable_writable_iterator_tag
-  , virtual public readable_lvalue_iterator_tag { };
-
-struct incrementable_iterator_tag { };
-struct single_pass_iterator_tag : incrementable_iterator_tag { };
-struct forward_traversal_tag : single_pass_iterator_tag { };
-struct bidirectional_traversal_tag : forward_traversal_tag { };
-struct random_access_traversal_tag : bidirectional_traversal_tag { };
-
-struct null_category_tag { };
-struct input_output_iterator_tag : input_iterator_tag, output_iterator_tag {};
-
-
-
-

Addition to [lib.iterator.traits]

-

The iterator_tag class template is an iterator category tag that -encodes the access and traversal tags in addition to being compatible -with the original iterator tags. The iterator_tag class inherits -from one of the original iterator tags according to the following -pseudo-code.

-
-inherit-category(access-tag, traversal-tag) =
-     if (access-tag is convertible to readable_lvalue_iterator_tag) {
-         if (traversal-tag is convertible to random_access_traversal_tag)
-             return random_access_iterator_tag;
-         else if (traversal-tag is convertible to bidirectional_traversal_tag)
-             return bidirectional_iterator_tag;
-         else if (traversal-tag is convertible to forward_traversal_tag)
-             return forward_iterator_tag;
-         else if (traversal-tag is convertible to single_pass_traversal_tag)
-             if (access-tag is convertible to writable_iterator_tag)
-                 return input_output_iterator_tag;
-             else
-                 return input_iterator_tag;
-         else if (access-tag is convertible to writable_iterator_tag)
-             return output_iterator_tag;
-         else
-             return null_category_tag;
-     } else if (access-tag is convertible to readable_writable_iterator_tag
-                and traversal-tag is convertible to single_pass_iterator_tag)
-         return input_output_iterator_tag;
-     else if (access-tag is convertible to readable_iterator_tag
-              and traversal-tag is convertible to single_pass_iterator_tag)
-         return input_iterator_tag;
-     else if (access-tag is convertible to writable_iterator_tag
-              and traversal-tag is convertible to incrementable_iterator_tag)
-         return output_iterator_tag;
-     else
-         return null_category_tag;
-
-

The access_category and traversal_category class templates are -traits classes. For iterators whose -iterator_traits<Iter>::iterator_category type is iterator_tag, -the access_category and traversal_category traits access the -access and traversal member types within iterator_tag. -For iterators whose iterator_traits<Iter>::iterator_category type -is not iterator_tag and instead is a tag convertible to one of the -original tags, the appropriate traversal and access tags is deduced. -The following pseudo-code describes the algorithm.

-
-access-category(Iterator) =
-    cat = iterator_traits<Iterator>::iterator_category;
-    if (cat == iterator_tag<Access,Traversal>)
-        return Access;
-    else if (cat is convertible to forward_iterator_tag) {
-        if (iterator_traits<Iterator>::reference is a const reference)
-            return readable_lvalue_iterator_tag;
-        else
-            return writable_lvalue_iterator_tag;
-    } else if (cat is convertible to input_iterator_tag)
-        return readable_iterator_tag;
-    else if (cat is convertible to output_iterator_tag)
-        return writable_iterator_tag;
-    else
-        return null_category_tag;
-
-traversal-category(Iterator) =
-    cat = iterator_traits<Iterator>::iterator_category;
-    if (cat == iterator_tag<Access,Traversal>)
-        return Traversal;
-    else if (cat is convertible to random_access_iterator_tag)
-        return random_access_traversal_tag;
-    else if (cat is convertible to bidirectional_iterator_tag)
-        return bidirectional_traversal_tag;
-    else if (cat is convertible to forward_iterator_tag)
-        return forward_traversal_tag;
-    else if (cat is convertible to input_iterator_tag)
-        return single_pass_iterator_tag;
-    else if (cat is convertible to output_iterator_tag)
-        return incrementable_iterator_tag;
-    else
-        return null_category_tag;
-
-

The following specializations provide the access and traversal -category tags for pointer types.

-
-template <typename T>
-struct access_category<const T*>
-{
-  typedef readable_lvalue_iterator_tag type;
-};
-template <typename T>
-struct access_category<T*>
-{
-  typedef writable_lvalue_iterator_tag type;
-};
-
-template <typename T>
-struct traversal_category<T*>
-{
-  typedef random_access_traversal_tag type;
-};
-
- -
-
-
-
-
-View document source. -Generated on: 2003-09-14 02:16 UTC. -Generated by Docutils from reStructuredText source. -
- - diff --git a/doc/new-iter-concepts.rst b/doc/new-iter-concepts.rst deleted file mode 100644 index a636584..0000000 --- a/doc/new-iter-concepts.rst +++ /dev/null @@ -1,760 +0,0 @@ -++++++++++++++++++++++ - New Iterator Concepts -++++++++++++++++++++++ - -:Author: David Abrahams, Jeremy Siek, Thomas Witt -:Contact: dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de -:organization: `Boost Consulting`_, Indiana University `Open Systems Lab`_, University of Hanover `Institute for Transport Railway Operation and Construction`_ -:date: $Date$ -:Number: **This document is a revised version of the official** N1477=03-0060 -:copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved - -.. _`Boost Consulting`: http://www.boost-consulting.com -.. _`Open Systems Lab`: http://www.osl.iu.edu -.. _`Institute for Transport Railway Operation and Construction`: http://www.ive.uni-hannover.de - -:Abstract: We propose a new system of iterator concepts that treat - access and positioning independently. This allows the - concepts to more closely match the requirements - of algorithms and provides better categorizations - of iterators that are used in practice. This proposal - is a revision of paper n1297_. - -.. contents:: Table of Contents - -.. _n1297: http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2001/n1297.html - -============ - Motivation -============ - -The standard iterator categories and requirements are flawed because -they use a single hierarchy of concepts to address two orthogonal -issues: *iterator traversal* and *value access*. As a result, many -algorithms with requirements expressed in terms of the iterator -categories are too strict. Also, many real-world iterators can not be -accurately categorized. A proxy-based iterator with random-access -traversal, for example, may only legally have a category of "input -iterator", so generic algorithms are unable to take advantage of its -random-access capabilities. The current iterator concept hierarchy is -geared towards iterator traversal (hence the category names), while -requirements that address value access sneak in at various places. The -following table gives a summary of the current value access -requirements in the iterator categories. - -+------------------------+-----------------------------------------------------+ -|Output Iterator |``*i = a`` | -+------------------------+-----------------------------------------------------+ -|Input Iterator |``*i`` is convertible to ``T`` | -+------------------------+-----------------------------------------------------+ -|Forward Iterator |``*i`` is ``T&`` (or ``const T&`` once `issue 200`_ | -| |is resolved) | -+------------------------+-----------------------------------------------------+ -|Random Access Iterator |``i[n]`` is convertible to ``T`` (also ``i[n] = t`` | -| |is required for mutable iterators once `issue 299`_ | -| |is resolved) | -+------------------------+-----------------------------------------------------+ - -.. _issue 200: http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/lwg-active.html#200 -.. _issue 299: http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/lwg-active.html#299 - - -Because iterator traversal and value access are mixed together in a -single hierarchy, many useful iterators can not be appropriately -categorized. For example, ``vector::iterator`` is almost a -random access iterator, but the return type is not ``bool&`` (see -`issue 96`_ and Herb Sutter's paper J16/99-0008 = WG21 -N1185). Therefore, the iterators of ``vector`` only meet the -requirements of input iterator and output iterator. This is so -nonintuitive that at least one implementation erroneously assigns -``random_access_iterator_tag`` as its ``iterator_category``. - -.. _issue 96: http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/lwg-active.html#96 - -Another difficult-to-categorize iterator is the transform iterator, an -adaptor which applies a unary function object to the dereferenced -value of the some underlying iterator (see `transform_iterator`_). -For unary functions such as ``times``, the return type of -``operator*`` clearly needs to be the ``result_type`` of the function -object, which is typically not a reference. Because random access -iterators are required to return lvalues from ``operator*``, if you -wrap ``int*`` with a transform iterator, you do not get a random -access iterator as might be expected, but an input iterator. - -.. _`transform_iterator`: http://www.boost.org/libs/utility/transform_iterator.htm - -A third example is found in the vertex and edge iterators of the -`Boost Graph Library`_. These iterators return vertex and edge -descriptors, which are lightweight handles created on-the-fly. They -must be returned by-value. As a result, their current standard -iterator category is ``input_iterator_tag``, which means that, -strictly speaking, you could not use these iterators with algorithms -like ``min_element()``. As a temporary solution, the concept -`Multi-Pass Input Iterator`_ was introduced to describe the vertex and -edge descriptors, but as the design notes for the concept suggest, a -better solution is needed. - -.. _Boost Graph Library: http://www.boost.org/libs/graph/doc/table_of_contents.html -.. _Multi-Pass Input Iterator: http://www.boost.org/libs/utility/MultiPassInputIterator.html - -In short, there are many useful iterators that do not fit into the -current standard iterator categories. As a result, the following bad -things happen: - -- Iterators are often mis-categorized. - -- Algorithm requirements are more strict than necessary, because they - cannot separate the need for random access or bidirectional - traversal from the need for a true reference return type. - - -======================== - Impact on the Standard -======================== - -The new iterator concepts are backward-compatible with the old -iterator requirements, and old iterators are forward-compatible with -the new iterator concepts. That is to say, iterators that satisfy the -old requirements also satisfy appropriate concepts in the new system, -and iterators modeling the new concepts will automatically satisfy the -appropriate old requirements. - -.. I think we need to say something about the resolution to allow - convertibility to any of the old-style tags as a TR issue (hope it - made it). -DWA - -.. Hmm, not sure I understand. Are you talking about whether a - standards conforming input iterator is allowed to have - a tag that is not input_iterator_tag but that - is convertible to input_iterator_tag? -JGS - -The algorithms in the standard library benefit from the new iterator -concepts because the new concepts provide a more accurate way to -express their type requirements. The result is algorithms that are -usable in more situations and have fewer type requirements. The -following lists the proposed changes to the type requirements of -algorithms. - -Forward Iterator -> Forward Traversal Iterator and Readable Iterator - - ``find_end, adjacent_find, search, search_n, rotate_copy, lower_bound, upper_bound, equal_range, binary_search, min_element, max_element`` - -Forward Iterator (1) -> Single Pass Iterator and Readable Iterator -Forward Iterator (2) -> Forward Traversal Iterator and Readable Iterator - - ``find_first_of`` - -Forward Iterator -> Readable Iterator and Writable Iterator - - ``iter_swap`` - -Forward Iterator -> Single Pass Iterator and Writable Iterator - - ``fill, generate`` - -Forward Iterator -> Forward Traversal Iterator and Swappable Iterator - - ``rotate`` - -Forward Iterator (1) -> Swappable Iterator and Single Pass Iterator -Forward Iterator (2) -> Swappable Iterator and Incrementable Iterator - - ``swap_ranges`` - -Forward Iterator -> Forward Traversal Iterator and Readable Iterator and Writable Iterator - ``remove, remove_if, unique`` - -Forward Iterator -> Single Pass Iterator and Readable Iterator and Writable Iterator - - ``replace, replace_if`` - -Bidirectional Iterator -> Bidirectional Traversal Iterator and Swappable Iterator - ``reverse`` - -Bidirectional Iterator -> Bidirectional Traversal Iterator and Readable and Swappable Iterator - ``partition`` - -Bidirectional Iterator (1) -> Bidirectional Traversal Iterator and Readable Iterator, -Bidirectional Iterator (2) -> Bidirectional Traversal Iterator and Writable Iterator - - ``copy_backwards`` - -Bidirectional Iterator -> Bidirectional Traversal Iterator and Swappable Iterator and Readable Iterator - ``next_permutation, prev_permutation`` - -Bidirectional Iterator -> Bidirectional Traversal Iterator and Readable Iterator and Writable Iterator - ``stable_partition, inplace_merge`` - -Bidirectional Iterator -> Bidirectional Traversal Iterator and Readable Iterator - ``reverse_copy`` - -Random Access Iterator -> Random Access Traversal Iterator and Readable and Swappable Iterator - ``random_shuffle, sort, stable_sort, partial_sort, nth_element, push_heap, pop_heap - make_heap, sort_heap`` - -Input Iterator (2) -> Incrementable Iterator and Readable Iterator - ``equal`` - -Input Iterator (2) -> Incrementable Iterator and Readable Iterator - ``transform`` - -======== - Design -======== - -The iterator requirements are be separated into two hierarchies. One -set of concepts handles the syntax and semantics of value access: - -- Readable Iterator -- Writable Iterator -- Swappable Iterator -- Readable Lvalue Iterator -- Writable Lvalue Iterator - -The refinement relationships among these iterator concepts are given -in the following diagram. - -.. image:: access.png - -The access concepts describe requirements related to ``operator*`` and -``operator->``, including the ``value_type``, ``reference``, and -``pointer`` associated types. - -The other set of concepts handles traversal: - -- Incrementable Iterator -- Single Pass Iterator -- Forward Traversal Iterator -- Bidirectional Traversal Iterator -- Random Access Traversal Iterator - -The refinement relationships for the traversal concepts are in the -following diagram. - -.. image:: traversal.png - -In addition to the iterator movement operators, such as -``operator++``, the traversal concepts also include requirements on -position comparison such as ``operator==`` and ``operator<``. The -reason for the fine grain slicing of the concepts into the -Incrementable and Single Pass is to provide concepts that are exact -matches with the original input and output iterator requirements. - -The relationship between the new iterator concepts and the old are -given in the following diagram. - -.. image:: oldeqnew.png - -Like the old iterator requirements, we provide tags for purposes of -dispatching. There are two hierarchies of tags, one for the access -concepts and one for the traversal concepts. We provide an access -mechanism for mapping iterator types to these new tags. Our design -reuses ``iterator_traits::iterator_category`` as the access -mechanism. To enable this, a pair of access and traversal tags are -combined into a single type using the following `iterator_tag` class. - -:: - - template - struct iterator_tag : /* appropriate old category or categories */ - { - typedef AccessTag access; - typedef TraversalTag traversal; - }; - -The ``iterator_tag`` class template is derived from the appropriate -iterator tag or tags from the old requirements based on the new-style -tags passed as template parameters. The algorithm for determining the -old tag or tags from the new tags picks the least-refined old concepts -that include all of the requirements of the access and traversal -concepts (that is, the closest fit), if any such category exists. For -example, a the category tag for a Readable Single Pass Iterator will -always be derived from ``input_iterator_tag``, while the category tag -for a Single Pass Iterator that is both Readable and Writable will be -derived from both ``input_iterator_tag`` and ``output_iterator_tag``. - -We also provide two helper classes that make it convenient to obtain -the access and traversal tags of an iterator. These helper classes -work both for iterators whose ``iterator_category`` is -``iterator_tag`` and also for iterators using the original iterator -categories. - -:: - - template struct access_category { typedef ... type; }; - template struct traversal_category { typedef ... type; }; - - -The most difficult design decision concerned the ``operator[]``. The -direct approach for specifying ``operator[]`` would have a return type -of ``reference``; the same as ``operator*``. However, going in this -direction would mean that an iterator satisfying the old Random Access -Iterator requirements would not necessarily be a model of Readable or -Writable Lvalue Iterator. Instead we have chosen a design that -matches the preferred resolution of `issue 299`_: ``operator[]`` is -only required to return something convertible to the ``value_type`` -(for a Readable Iterator), and is required to support assignment -``i[n] = t`` (for a Writable Iterator). - - -=============== - Proposed Text -=============== - -Addition to [lib.iterator.requirements] -======================================= - -Iterator Value Access Concepts [lib.iterator.value.access] -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -In the tables below, ``X`` is an iterator type, ``a`` is a constant -object of type ``X``, ``T`` is -``std::iterator_traits::value_type``, and ``v`` is a constant -object of type ``T``. - -.. _Readable Iterator: - -Readable Iterators [lib.readable.iterators] -------------------------------------------- - -A class or built-in type ``X`` models the *Readable Iterator* concept -for the value type ``T`` if the following expressions are valid and -respect the stated semantics. ``U`` is the type of any specified -member of type ``T``. - - +-------------------------------------------------------------------------------------------------------------------+ - |Readable Iterator Requirements (in addition to CopyConstructible) | - +--------------------------------------+----------------------------------+-----------------------------------------+ - |Expression |Return Type |Assertion/Note/Precondition/Postcondition| - +======================================+==================================+=========================================+ - |``iterator_traits::value_type`` |``T`` |Any non-reference, non-cv-qualified type | - +--------------------------------------+----------------------------------+-----------------------------------------+ - |``iterator_traits::reference`` |Convertible to | | - | |``iterator_traits::value_type``| | - +--------------------------------------+----------------------------------+-----------------------------------------+ - |``access_category::type`` |Convertible to | | - | |``readable_iterator_tag`` | | - +--------------------------------------+----------------------------------+-----------------------------------------+ - |``*a`` |``iterator_traits::reference`` |pre: ``a`` is dereferenceable. If ``a == | - | | |b`` then ``*a`` is equivalent to ``*b`` | - +--------------------------------------+----------------------------------+-----------------------------------------+ - |``a->m`` |``U&`` |pre: ``(*a).m`` is well-defined. | - | | |Equivalent to ``(*a).m`` | - +--------------------------------------+----------------------------------+-----------------------------------------+ - - -.. _Writable Iterator: - -Writable Iterators [lib.writable.iterators] -------------------------------------------- - -A class or built-in type ``X`` models the *Writable Iterator* concept -if the following expressions are valid and respect the stated -semantics. In addition, a model of *Writable Iterator* must include -in its documentation the *set of value types* that it allows for -output. - - +---------------------------------------------------------------------------------------------+ - |Writable Iterator Requirements (in addition to CopyConstructible) | - +--------------------------------------+-------------------------+----------------------------+ - |Expression |Return Type |Precondition | - +======================================+=========================+============================+ - |``access_category::type`` |Convertible to | | - | |``writable_iterator_tag``| | - +--------------------------------------+-------------------------+----------------------------+ - |``*a = o`` | | pre: The type of ``o`` | - | | | is in the set of | - | | | value types of ``X`` | - +--------------------------------------+-------------------------+----------------------------+ - - - -Swappable Iterators [lib.swappable.iterators] ---------------------------------------------- - -A class or built-in type ``X`` models the *Swappable Iterator* concept -if the following expressions are valid and respect the stated -semantics. - - +------------------------------------------------------------------------------------------------+ - |Swappable Iterator Requirements (in addition to CopyConstructible) | - +------------------------------------+-------------+---------------------------------------------+ - |Expression |Return Type |Postcondition | - +====================================+=============+=============================================+ - |``iter_swap(a, b)`` |``void`` |post: the pointed to values are exchanged | - +------------------------------------+-------------+---------------------------------------------+ - -[*Note:* An iterator that is a model of the *Readable* and *Writable Iterator* concepts - is also a model of *Swappable Iterator*. *--end note*] - - -Readable Lvalue Iterators [lib.readable.lvalue.iterators] ---------------------------------------------------------- - -The *Readable Lvalue Iterator* concept adds the requirement that the -``reference`` type be a reference to the value type of the iterator. - - +----------------------------------------------------------------------------------------------------------+ - |Readable Lvalue Iterator Requirements (in addition to Readable Iterator) | - +------------------------------------+---------------------------------+-----------------------------------+ - |Expression |Return Type |Assertion | - +====================================+=================================+===================================+ - |``iterator_traits::reference`` |``T&`` |``T`` is *cv* | - | | |``iterator_traits::value_type`` | - | | |where *cv* is an optional | - | | |cv-qualification | - +------------------------------------+---------------------------------+-----------------------------------+ - |``access_category::type`` |Convertible to | | - | |``readable_lvalue_iterator_tag`` | | - +------------------------------------+---------------------------------+-----------------------------------+ - - -Writable Lvalue Iterators [lib.writable.lvalue.iterators] ---------------------------------------------------------- - -The *Writable Lvalue Iterator* concept adds the requirement that the -``reference`` type be a non-const reference to the value type of the -iterator. - - - +--------------------------------------------------------------------------------------+ - | Writable Lvalue Iterator Requirements (in addition to Readable Lvalue Iterator) | - +--------------------------------------+-----------------------------------------------+ - | Expression | Return Type | - +======================================+===============================================+ - |``iterator_traits::reference`` |``iterator_traits::value_type&`` | - +--------------------------------------+-----------------------------------------------+ - |``access_category::type`` |Convertible to ``writable_lvalue_iterator_tag``| - | | | - +--------------------------------------+-----------------------------------------------+ - - -Iterator Traversal Concepts [lib.iterator.traversal] -++++++++++++++++++++++++++++++++++++++++++++++++++++ - -In the tables below, ``X`` is an iterator type, ``a`` and ``b`` are -constant objects of type ``X``, ``r`` and ``s`` are mutable objects of -type ``X``, ``T`` is ``std::iterator_traits::value_type``, and -``v`` is a constant object of type ``T``. - - -Incrementable Iterators [lib.incrementable.iterators] ------------------------------------------------------ - -A class or built-in type ``X`` models the *Incrementable Iterator* -concept if the following expressions are valid and respect the stated -semantics. - - - +-------------------------------------------------------------------------------------------------------------------------+ - |Incrementable Iterator Requirements (in addition to Assignable, Copy Constructible) | - +--------------------------------+---------------------------------------------+------------------------------------------+ - |Expression |Return Type |Assertion/Semantics | - +================================+=============================================+==========================================+ - |``++r`` |``X&`` |``&r == &++r`` | - +--------------------------------+---------------------------------------------+------------------------------------------+ - |``r++`` |``X`` |``{ X tmp = r; ++r; return tmp; }`` | - +--------------------------------+---------------------------------------------+------------------------------------------+ - |``traversal_category::type`` |Convertible to ``incrementable_iterator_tag``| | - +--------------------------------+---------------------------------------------+------------------------------------------+ - - -Single Pass Iterators [lib.single.pass.iterators] -------------------------------------------------- - -A class or built-in type ``X`` models the *Single Pass Iterator* -concept if the following expressions are valid and respect the stated -semantics. - - - +--------------------------------------------------------------------------------------------------------+ - |Single Pass Iterator Requirements (in addition to Incrementable Iterator and Equality Comparable) | - +----------------------------------+----------------------------+----------------------------------------+ - |Expression |Return Type |Assertion/Semantics/Pre-/Post-condition | - +==================================+============================+========================================+ - |``++r`` |``X&`` |pre: ``r`` is dereferenceable; post: | - | | |``r`` is dereferenceable or ``r`` is | - | | |past-the-end | - +----------------------------------+----------------------------+----------------------------------------+ - |``a == b`` |convertible to ``bool`` |``==`` is an equivalence relation over | - | | |its domain | - +----------------------------------+----------------------------+----------------------------------------+ - |``a != b`` |convertible to ``bool`` |``!(a == b)`` | - +----------------------------------+----------------------------+----------------------------------------+ - |``traversal_category::type`` |Convertible to | | - | |``single_pass_iterator_tag``| | - +----------------------------------+----------------------------+----------------------------------------+ - - -Forward Traversal Iterators [lib.forward.traversal.iterators] -------------------------------------------------------------- - -A class or built-in type ``X`` models the *Forward Traversal Iterator* -concept if the following expressions are valid and respect the stated -semantics. - - +------------------------------------------------------------------------------------------------------+ - |Forward Traversal Iterator Requirements (in addition to Single Pass Iterator) | - +---------------------------------------+-------------------------------------+------------------------+ - |Expression |Return Type |Assertion/Note | - +=======================================+=====================================+========================+ - |``X u;`` |``X&`` |``note: u may have a | - | | |singular value.`` | - +---------------------------------------+-------------------------------------+------------------------+ - |``++r`` |``X&`` |``r == s`` and ``r`` is | - | | |dereferenceable implies | - | | |``++r == ++s.`` | - +---------------------------------------+-------------------------------------+------------------------+ - |``iterator_traits::difference_type``|A signed integral type representing | | - | |the distance between iterators | | - +---------------------------------------+-------------------------------------+------------------------+ - |``traversal_category::type`` |Convertible to | | - | |``forward_traversal_iterator_tag`` | | - +---------------------------------------+-------------------------------------+------------------------+ - - -Bidirectional Traversal Iterators [lib.bidirectional.traversal.iterators] -------------------------------------------------------------------------- - -A class or built-in type ``X`` models the *Bidirectional Traversal -Iterator* concept if the following expressions are valid and respect -the stated semantics. - - +----------------------------------------------------------------------------------------------------------------+ - |Bidirectional Traversal Iterator Requirements (in addition to Forward Traversal Iterator) | - +-------------------------------+----------------------------------------+---------------------------------------+ - |Expression |Return Type |Assertion/Semantics/Pre-/Post-condition| - +===============================+========================================+=======================================+ - |``--r`` |``X&`` |pre: there exists ``s`` such that ``r | - | | |== ++s``. post: ``s`` is | - | | |dereferenceable. ``--(++r) == r``. | - | | |``--r == --s`` implies ``r == s``. ``&r| - | | |== &--r``. | - +-------------------------------+----------------------------------------+---------------------------------------+ - |``r--`` |convertible to ``const X&`` |``{ X tmp = r; --r; return tmp; }`` | - | | | | - | | | | - +-------------------------------+----------------------------------------+---------------------------------------+ - |``traversal_category::type``|Convertible to | | - | |``bidirectional_traversal_iterator_tag``| | - | | | | - +-------------------------------+----------------------------------------+---------------------------------------+ - - -Random Access Traversal Iterators [lib.random.access.traversal.iterators] -------------------------------------------------------------------------- - -A class or built-in type ``X`` models the *Random Access Traversal -Iterator* concept if the following expressions are valid and respect -the stated semantics. In the table below, ``Distance`` is -``iterator_traits::difference_type`` and ``n`` represents a -constant object of type ``Distance``. - - +------------------------------------------------------------------------------------------------------------------------------+ - |Random Access Traversal Iterator Requirements (in addition to Bidirectional Traversal Iterator) | - +--------------------------------+----------------------------------------+----------------------+-----------------------------+ - | Expression |Return Type | Operational Semantics| Assertion/Precondition | - +================================+========================================+======================+=============================+ - |``r += n`` |``X&`` |:: | | - | | | | | - | | | { | | - | | | Distance m = n; | | - | | | if (m >= 0) | | - | | | while (m--) | | - | | | ++r; | | - | | | else | | - | | | while (m++) | | - | | | --r; | | - | | | return r; | | - | | | } | | - +--------------------------------+----------------------------------------+----------------------+-----------------------------+ - | ``a + n``, ``n + a`` |``X`` |``{ X tmp = a; return | | - | | |tmp += n; }`` | | - +--------------------------------+----------------------------------------+----------------------+-----------------------------+ - |``r -= n`` |``X&`` |``return r += -n`` | | - +--------------------------------+----------------------------------------+----------------------+-----------------------------+ - |``a - n`` |``X`` |``{ X tmp = a; return | | - | | |tmp -= n; }`` | | - +--------------------------------+----------------------------------------+----------------------+-----------------------------+ - |``b - a`` |``Distance`` |``a < b ? |pre: there exists a value | - | | |distance(a,b) : |``n`` of ``Distance`` such | - | | |-distance(b,a)`` |that ``a + n == b``. ``b == | - | | | |a + (b - a)``. | - +--------------------------------+----------------------------------------+----------------------+-----------------------------+ - |``a[n]`` |convertible to T |``*(a + n)`` |pre: a is a `readable | - | | | |iterator`_ | - +--------------------------------+----------------------------------------+----------------------+-----------------------------+ - |``a[n] = v`` |convertible to T |``*(a + n) = v`` |pre: a is a `writable | - | | | |iterator`_ | - +--------------------------------+----------------------------------------+----------------------+-----------------------------+ - |``a < b`` |convertible to ``bool`` |``b - a > 0`` |``<`` is a total ordering | - | | | |relation | - +--------------------------------+----------------------------------------+----------------------+-----------------------------+ - |``a > b`` |convertible to ``bool`` |``b < a`` |``>`` is a total ordering | - | | | |relation | - +--------------------------------+----------------------------------------+----------------------+-----------------------------+ - |``a >= b`` |convertible to ``bool`` |``!(a < b)`` | | - +--------------------------------+----------------------------------------+----------------------+-----------------------------+ - |``a <= b`` |convertible to ``bool`` |``!(a > b)`` | | - +--------------------------------+----------------------------------------+----------------------+-----------------------------+ - |``traversal_category::type`` |Convertible to | | | - | |``random_access_traversal_iterator_tag``| | | - +--------------------------------+----------------------------------------+----------------------+-----------------------------+ - - - -Addition to [lib.iterator.synopsis] -=================================== - -:: - - // lib.iterator.traits, traits and tags - template struct access_category; - template struct traversal_category; - - template - struct iterator_tag : /* appropriate old category or categories */ { - typedef AccessTag access; - typedef TraversalTag traversal; - }; - - struct readable_iterator_tag { }; - struct writable_iterator_tag { }; - struct swappable_iterator_tag { }; - struct readable_writable_iterator_tag - : virtual readable_iterator_tag - , virtual writable_iterator_tag - , virtual swappable_iterator_tag { }; - struct readable_lvalue_iterator_tag { }; - struct writable_lvalue_iterator_tag - : virtual public readable_writable_iterator_tag - , virtual public readable_lvalue_iterator_tag { }; - - struct incrementable_iterator_tag { }; - struct single_pass_iterator_tag : incrementable_iterator_tag { }; - struct forward_traversal_tag : single_pass_iterator_tag { }; - struct bidirectional_traversal_tag : forward_traversal_tag { }; - struct random_access_traversal_tag : bidirectional_traversal_tag { }; - - struct null_category_tag { }; - struct input_output_iterator_tag : input_iterator_tag, output_iterator_tag {}; - -Addition to [lib.iterator.traits] -================================= - -The ``iterator_tag`` class template is an iterator category tag that -encodes the access and traversal tags in addition to being compatible -with the original iterator tags. The ``iterator_tag`` class inherits -from one of the original iterator tags according to the following -pseudo-code. - -:: - - inherit-category(access-tag, traversal-tag) = - if (access-tag is convertible to readable_lvalue_iterator_tag) { - if (traversal-tag is convertible to random_access_traversal_tag) - return random_access_iterator_tag; - else if (traversal-tag is convertible to bidirectional_traversal_tag) - return bidirectional_iterator_tag; - else if (traversal-tag is convertible to forward_traversal_tag) - return forward_iterator_tag; - else if (traversal-tag is convertible to single_pass_traversal_tag) - if (access-tag is convertible to writable_iterator_tag) - return input_output_iterator_tag; - else - return input_iterator_tag; - else if (access-tag is convertible to writable_iterator_tag) - return output_iterator_tag; - else - return null_category_tag; - } else if (access-tag is convertible to readable_writable_iterator_tag - and traversal-tag is convertible to single_pass_iterator_tag) - return input_output_iterator_tag; - else if (access-tag is convertible to readable_iterator_tag - and traversal-tag is convertible to single_pass_iterator_tag) - return input_iterator_tag; - else if (access-tag is convertible to writable_iterator_tag - and traversal-tag is convertible to incrementable_iterator_tag) - return output_iterator_tag; - else - return null_category_tag; - - -The ``access_category`` and ``traversal_category`` class templates are -traits classes. For iterators whose -``iterator_traits::iterator_category`` type is ``iterator_tag``, -the ``access_category`` and ``traversal_category`` traits access the -``access`` and ``traversal`` member types within ``iterator_tag``. -For iterators whose ``iterator_traits::iterator_category`` type -is not ``iterator_tag`` and instead is a tag convertible to one of the -original tags, the appropriate traversal and access tags is deduced. -The following pseudo-code describes the algorithm. - -:: - - access-category(Iterator) = - cat = iterator_traits::iterator_category; - if (cat == iterator_tag) - return Access; - else if (cat is convertible to forward_iterator_tag) { - if (iterator_traits::reference is a const reference) - return readable_lvalue_iterator_tag; - else - return writable_lvalue_iterator_tag; - } else if (cat is convertible to input_iterator_tag) - return readable_iterator_tag; - else if (cat is convertible to output_iterator_tag) - return writable_iterator_tag; - else - return null_category_tag; - - traversal-category(Iterator) = - cat = iterator_traits::iterator_category; - if (cat == iterator_tag) - return Traversal; - else if (cat is convertible to random_access_iterator_tag) - return random_access_traversal_tag; - else if (cat is convertible to bidirectional_iterator_tag) - return bidirectional_traversal_tag; - else if (cat is convertible to forward_iterator_tag) - return forward_traversal_tag; - else if (cat is convertible to input_iterator_tag) - return single_pass_iterator_tag; - else if (cat is convertible to output_iterator_tag) - return incrementable_iterator_tag; - else - return null_category_tag; - - -The following specializations provide the access and traversal -category tags for pointer types. - -:: - - template - struct access_category - { - typedef readable_lvalue_iterator_tag type; - }; - template - struct access_category - { - typedef writable_lvalue_iterator_tag type; - }; - - template - struct traversal_category - { - typedef random_access_traversal_tag type; - }; - - - -.. - LocalWords: Abrahams Siek Witt const bool Sutter's WG int UL LI href Lvalue - LocalWords: ReadableIterator WritableIterator SwappableIterator cv pre iter - LocalWords: ConstantLvalueIterator MutableLvalueIterator CopyConstructible TR - LocalWords: ForwardTraversalIterator BidirectionalTraversalIterator lvalue - LocalWords: RandomAccessTraversalIterator dereferenceable Incrementable tmp - LocalWords: incrementable xxx min prev inplace png oldeqnew AccessTag struct - LocalWords: TraversalTag typename lvalues DWA Hmm JGS diff --git a/doc/oldeqnew.png b/doc/oldeqnew.png deleted file mode 100644 index 30cd159..0000000 Binary files a/doc/oldeqnew.png and /dev/null differ diff --git a/doc/permutation_iterator.html b/doc/permutation_iterator.html deleted file mode 100644 index 4549786..0000000 --- a/doc/permutation_iterator.html +++ /dev/null @@ -1,128 +0,0 @@ - - - - - - -Permutation Iterator - - - - - - - -
-

Permutation Iterator

- --- - - - - - - - - - - - -
Author:Toon Knapen, David Abrahams, Roland Richter, Jeremy Siek
Contact:dave@boost-consulting.com, jsiek@osl.iu.edu
Organization:Boost Consulting, Indiana University Open Systems -Lab
Date:2003-08-05
Copyright:Copyright Toon Knapen, David Abrahams, Roland Richter, and Jeremy Siek 2003. All rights reserved
- --- - - - -
abstract:
-

The permutation iterator adaptor provides a permuted view of a given -range. That is, the view includes every element of the given range but -in a potentially different order.

- -
-

Introduction

-

The adaptor takes two arguments:

-
-
    -
  • an iterator to the range V on which the permutation -will be applied
    • -
  • the reindexing scheme that defines how the -elements of V will be permuted.
    • -
-
-

Note that the permutation iterator is not limited to strict -permutations of the given range V. The distance between begin and end -of the reindexing iterators is allowed to be smaller compared to the -size of the range V, in which case the permutation iterator only -provides a permutation of a subrange of V. The indexes neither need -to be unique. In this same context, it must be noted that the past the -end permutation iterator is completely defined by means of the -past-the-end iterator to the indices.

-
-
-

Reference

-
-template< class ElementIterator
-        , class IndexIterator
-        , class ValueT        = use_default
-        , class CategoryT     = use_default
-        , class ReferenceT    = use_default
-        , class DifferenceT   = use_default >
-class permutation_iterator
-  : public iterator_adaptor<...>
-{
-  typedef iterator_adaptor<...>
-  friend class iterator_core_access;
-public:
-  permutation_iterator();
-  explicit permutation_iterator(ElementIterator x, IndexIterator y);
-
-  template< class OEIter, class OIIter, class V, class C, class R, class D >
-  permutation_iterator(
-      permutation_iterator<OEIter, OIIter, V, C, R, D> const& r
-      , typename enable_if_convertible<OEIter, ElementIterator>::type* = 0
-      , typename enable_if_convertible<OIIter, IndexIterator>::type* = 0
-      );
-};
-
-
-

permutation_iterator requirements

-

ElementIterator must be a model of RandomAccessIterator. -IndexIterator must at least be a model ForwardIterator. The -value type of the IndexIterator must be convertible to the -difference type of ElementIterator.

-
-
-

permutation_iterator operations

-

The permutation iterator implements the member functions and operators -required for the Random Access Iterator concept. However, the -permutation iterator can only meet the complexity guarantees of the -same concept as the IndexIterator. Thus for instance, although the -permutation iterator provides operator+=(distance), this operation -will take linear time in case the IndexIterator is a model of -ForwardIterator instead of amortized constant time.

-
-
-
-
-
-View document source. -Generated on: 2003-09-14 02:16 UTC. -Generated by Docutils from reStructuredText source. -
- - diff --git a/doc/permutation_iterator.rst b/doc/permutation_iterator.rst deleted file mode 100644 index d506b78..0000000 --- a/doc/permutation_iterator.rst +++ /dev/null @@ -1,31 +0,0 @@ -++++++++++++++++++++++ - Permutation Iterator -++++++++++++++++++++++ - -:Author: Toon Knapen, David Abrahams, Roland Richter, Jeremy Siek -:Contact: dave@boost-consulting.com, jsiek@osl.iu.edu -:organization: `Boost Consulting`_, Indiana University `Open Systems - Lab`_ -:date: $Date$ -:copyright: Copyright Toon Knapen, David Abrahams, Roland Richter, and Jeremy Siek 2003. All rights reserved - -.. _`Boost Consulting`: http://www.boost-consulting.com -.. _`Open Systems Lab`: http://www.osl.iu.edu - -:abstract: - -.. include:: permutation_iterator_abstract.rst - -.. contents:: Table of Contents - - -Introduction -============ - -.. include:: permutation_iterator_body.rst - - -Reference -========= - -.. include:: permutation_iterator_ref.rst diff --git a/doc/permutation_iterator_abstract.rst b/doc/permutation_iterator_abstract.rst deleted file mode 100644 index 578b3ed..0000000 --- a/doc/permutation_iterator_abstract.rst +++ /dev/null @@ -1,4 +0,0 @@ -The permutation iterator adaptor provides a permuted view of a given -range. That is, the view includes every element of the given range but -in a potentially different order. - diff --git a/doc/permutation_iterator_body.rst b/doc/permutation_iterator_body.rst deleted file mode 100644 index 0f838e7..0000000 --- a/doc/permutation_iterator_body.rst +++ /dev/null @@ -1,15 +0,0 @@ -The adaptor takes two arguments: - - * an iterator to the range V on which the permutation - will be applied - * the reindexing scheme that defines how the - elements of V will be permuted. - -Note that the permutation iterator is not limited to strict -permutations of the given range V. The distance between begin and end -of the reindexing iterators is allowed to be smaller compared to the -size of the range V, in which case the permutation iterator only -provides a permutation of a subrange of V. The indexes neither need -to be unique. In this same context, it must be noted that the past the -end permutation iterator is completely defined by means of the -past-the-end iterator to the indices. diff --git a/doc/permutation_iterator_ref.rst b/doc/permutation_iterator_ref.rst deleted file mode 100644 index ef84045..0000000 --- a/doc/permutation_iterator_ref.rst +++ /dev/null @@ -1,54 +0,0 @@ -.. parsed-literal:: - - template< class ElementIterator - , class IndexIterator - , class ValueT = use_default - , class CategoryT = use_default - , class ReferenceT = use_default - , class DifferenceT = use_default > - class permutation_iterator - : public iterator_adaptor<...> - { - typedef iterator_adaptor<...> - friend class iterator_core_access; - public: - permutation_iterator(); - explicit permutation_iterator(ElementIterator x, IndexIterator y); - - template< class OEIter, class OIIter, class V, class C, class R, class D > - permutation_iterator( - permutation_iterator const& r - , typename enable_if_convertible::type* = 0 - , typename enable_if_convertible::type* = 0 - ); - }; - - - -``permutation_iterator`` requirements -------------------------------------- - -``ElementIterator`` must be a model of RandomAccessIterator__. -``IndexIterator`` must at least be a model ForwardIterator__. The -value type of the ``IndexIterator`` must be convertible to the -difference type of ``ElementIterator``. - -__ http://www.sgi.com/tech/stl/RandomAccessIterator.html - -__ http://www.sgi.com/tech/stl/ForwardIterator.html - - - - -``permutation_iterator`` operations ------------------------------------ - -The permutation iterator implements the member functions and operators -required for the `Random Access Iterator`__ concept. However, the -permutation iterator can only meet the complexity guarantees of the -same concept as the IndexIterator. Thus for instance, although the -permutation iterator provides ``operator+=(distance)``, this operation -will take linear time in case the IndexIterator is a model of -ForwardIterator instead of amortized constant time. - -__ http://www.sgi.com/tech/stl/RandomAccessIterator.html diff --git a/doc/reverse_iterator.html b/doc/reverse_iterator.html deleted file mode 100644 index 3aba842..0000000 --- a/doc/reverse_iterator.html +++ /dev/null @@ -1,143 +0,0 @@ - - - - - - -Reverse Iterator - - - - - - - -
-

Reverse Iterator

- --- - - - - - - - - - - - -
Author:David Abrahams, Jeremy Siek, Thomas Witt
Contact:dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de
Organization:Boost Consulting, Indiana University Open Systems -Lab, University of Hanover Institute for Transport -Railway Operation and Construction
Date:2003-08-05
Copyright:Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved
- --- - - - -
abstract:
- -

The reverse iterator adaptor flips the direction of a base iterator's -motion. Invoking operator++() moves the base iterator backward and -invoking operator--() moves the base iterator forward.

- -
-template <class Iterator>
-class reverse_iterator :
-  public iterator_adaptor< reverse_iterator<Iterator>, Iterator >
-{
-  friend class iterator_core_access;
-public:
-  reverse_iterator() {}
-  explicit reverse_iterator(Iterator x) ;
-
-  template<class OtherIterator>
-  reverse_iterator(
-      reverse_iterator<OtherIterator> const& r
-    , typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition
-  );
-
-private: // as-if specification
-  typename reverse_iterator::reference dereference() const { return *prior(this->base()); }
-
-  void increment() { --this->base_reference(); }
-  void decrement() { ++this->base_reference(); }
-
-  void advance(typename reverse_iterator::difference_type n)
-  {
-      this->base_reference() += -n;
-  }
-
-  template <class OtherIterator>
-  typename reverse_iterator::difference_type
-  distance_to(reverse_iterator<OtherIterator> const& y) const
-  {
-      return this->base_reference() - y.base();
-  }
-
-};
-
-
-

reverse_iterator requirements

-

The base Iterator must be a model of Bidirectional Traversal -Iterator. The resulting reverse_iterator will be a model of the -most refined standard traversal and access concepts that are modeled -by Iterator.

-

reverse_iterator();

- --- - - - - - -
Requires:Iterator must be Default Constructible.
Returns:An instance of reverse_iterator with a -default constructed base object.
-

explicit reverse_iterator(Iterator x);

- --- - - - -
Returns:An instance of reverse_iterator with a -base object copy constructed from x.
-
-template<class OtherIterator>
-reverse_iterator(
-    reverse_iterator<OtherIterator> const& r
-  , typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition
-);
-
- --- - - - - - -
Requires:OtherIterator is implicitly convertible to Iterator.
Returns:An instance of reverse_iterator that is a copy of r.
-
-
-
-
-View document source. -Generated on: 2003-09-14 02:16 UTC. -Generated by Docutils from reStructuredText source. -
- - diff --git a/doc/reverse_iterator.rst b/doc/reverse_iterator.rst deleted file mode 100644 index 5265076..0000000 --- a/doc/reverse_iterator.rst +++ /dev/null @@ -1,23 +0,0 @@ -++++++++++++++++++ - Reverse Iterator -++++++++++++++++++ - -:Author: David Abrahams, Jeremy Siek, Thomas Witt -:Contact: dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de -:organization: `Boost Consulting`_, Indiana University `Open Systems - Lab`_, University of Hanover `Institute for Transport - Railway Operation and Construction`_ -:date: $Date$ -:copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved - -.. _`Boost Consulting`: http://www.boost-consulting.com -.. _`Open Systems Lab`: http://www.osl.iu.edu -.. _`Institute for Transport Railway Operation and Construction`: http://www.ive.uni-hannover.de - -:abstract: - -.. include:: reverse_iterator_abstract.rst - -.. contents:: Table of Contents - -.. include:: reverse_iterator_ref.rst diff --git a/doc/reverse_iterator_abstract.rst b/doc/reverse_iterator_abstract.rst deleted file mode 100644 index 0574988..0000000 --- a/doc/reverse_iterator_abstract.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. I think we'd better strike the old reverse_iterator text from the standard, eh? - -The reverse iterator adaptor flips the direction of a base iterator's -motion. Invoking ``operator++()`` moves the base iterator backward and -invoking ``operator--()`` moves the base iterator forward. - diff --git a/doc/reverse_iterator_ref.rst b/doc/reverse_iterator_ref.rst deleted file mode 100644 index c0acc2b..0000000 --- a/doc/reverse_iterator_ref.rst +++ /dev/null @@ -1,69 +0,0 @@ -:: - - template - class reverse_iterator : - public iterator_adaptor< reverse_iterator, Iterator > - { - friend class iterator_core_access; - public: - reverse_iterator() {} - explicit reverse_iterator(Iterator x) ; - - template - reverse_iterator( - reverse_iterator const& r - , typename enable_if_convertible::type* = 0 // exposition - ); - - private: // as-if specification - typename reverse_iterator::reference dereference() const { return *prior(this->base()); } - - void increment() { --this->base_reference(); } - void decrement() { ++this->base_reference(); } - - void advance(typename reverse_iterator::difference_type n) - { - this->base_reference() += -n; - } - - template - typename reverse_iterator::difference_type - distance_to(reverse_iterator const& y) const - { - return this->base_reference() - y.base(); - } - - }; - - -``reverse_iterator`` requirements -................................. - -The base ``Iterator`` must be a model of Bidirectional Traversal -Iterator. The resulting ``reverse_iterator`` will be a model of the -most refined standard traversal and access concepts that are modeled -by ``Iterator``. - - -``reverse_iterator();`` - -:Requires: ``Iterator`` must be Default Constructible. -:Returns: An instance of ``reverse_iterator`` with a - default constructed base object. - -``explicit reverse_iterator(Iterator x);`` - -:Returns: An instance of ``reverse_iterator`` with a - base object copy constructed from ``x``. - - -:: - - template - reverse_iterator( - reverse_iterator const& r - , typename enable_if_convertible::type* = 0 // exposition - ); - -:Requires: ``OtherIterator`` is implicitly convertible to ``Iterator``. -:Returns: An instance of ``reverse_iterator`` that is a copy of ``r``. diff --git a/doc/transform_iterator.html b/doc/transform_iterator.html deleted file mode 100644 index 685d240..0000000 --- a/doc/transform_iterator.html +++ /dev/null @@ -1,169 +0,0 @@ - - - - - - -Transform Iterator - - - - - - - -
-

Transform Iterator

- --- - - - - - - - - - - - -
Author:David Abrahams, Jeremy Siek, Thomas Witt
Contact:dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de
Organization:Boost Consulting, Indiana University Open Systems -Lab, University of Hanover Institute for Transport -Railway Operation and Construction
Date:2003-08-05
Copyright:Copyright Dave Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved
- --- - - - -
abstract:
-

The transform iterator adapts an iterator by applying some function -object to the result of dereferencing the iterator. In other words, -the operator* of the transform iterator first dereferences the -base iterator, passes the result of this to the function object, and -then returns the result.

- -
-template <class AdaptableUnaryFunction,
-          class Iterator, 
-          class Reference = use_default, 
-          class Value = use_default>
-class transform_iterator
-  : public iterator_adaptor</* see discussion */>
-{
-  friend class iterator_core_access;
-public:
-  transform_iterator();
-  transform_iterator(Iterator const& x, AdaptableUnaryFunction f);
-
-  template<class OtherIterator, class R2, class V2>
-  transform_iterator(
-        transform_iterator<AdaptableUnaryFunction, OtherIterator, R2, V2> const& t
-      , typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition
-  );
-
-  AdaptableUnaryFunction functor() const;
-private:
-  typename transform_iterator::value_type dereference() const;
-  AdaptableUnaryFunction m_f;
-};
-
-
-

transform_iterator requirements

-

The type AdaptableUnaryFunction must be Assignable, Copy -Constructible, and the expression f(x) must be valid where f -is an object of type AdaptableUnaryFunction, x is an object of -type AdaptableUnaryFunction::argument_type, and where the type of -f(x) must be AdaptableUnaryFunction::result_type.

-

The type Iterator must at least model Readable Iterator. The -resulting transform_iterator models the most refined of the -following options that is also modeled by Iterator.

-
-
    -
  • Writable Lvalue Iterator if the result_type of the -AdaptableUnaryFunction is a non-const reference.
    • -
  • Readable Lvalue Iterator if the result_type is a const -reference.
    • -
  • Readable Iterator otherwise.
    • -
-
-

The transform_iterator models the most refined standard traversal -concept that is modeled by Iterator.

-

The value_type of transform_iterator is -remove_reference<result_type>::type. The reference type is -result_type.

-
-
-

transform_iterator public operations

-

transform_iterator();

- --- - - - -
Returns:An instance of transform_iterator with m_f -and m_iterator default constructed.
-

transform_iterator(Iterator const& x, AdaptableUnaryFunction f);

- --- - - - -
Returns:An instance of transform_iterator with m_f -initialized to f and m_iterator initialized to x.
-
-template<class OtherIterator, class R2, class V2>
-transform_iterator(
-      transform_iterator<AdaptableUnaryFunction, OtherIterator, R2, V2> const& t
-    , typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition
-);
-
- --- - - - - - -
Returns:An instance of transform_iterator that is a copy of t.
Requires:OtherIterator is implicitly convertible to Iterator.
-

AdaptableUnaryFunction functor() const;

- --- - - - -
Returns:m_f
-
-
-

transform_iterator private operations

-

typename transform_iterator::value_type dereference() const;

- --- - - - -
Returns:m_f(transform_iterator::dereference());
-
-
- - diff --git a/doc/transform_iterator.rst b/doc/transform_iterator.rst deleted file mode 100644 index 021532d..0000000 --- a/doc/transform_iterator.rst +++ /dev/null @@ -1,23 +0,0 @@ -++++++++++++++++++++ - Transform Iterator -++++++++++++++++++++ - -:Author: David Abrahams, Jeremy Siek, Thomas Witt -:Contact: dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de -:organization: `Boost Consulting`_, Indiana University `Open Systems - Lab`_, University of Hanover `Institute for Transport - Railway Operation and Construction`_ -:date: $Date$ -:copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved - -.. _`Boost Consulting`: http://www.boost-consulting.com -.. _`Open Systems Lab`: http://www.osl.iu.edu -.. _`Institute for Transport Railway Operation and Construction`: http://www.ive.uni-hannover.de - -:abstract: - -.. include:: transform_iterator_abstract.rst - -.. contents:: Table of Contents - -.. include:: transform_iterator_ref.rst diff --git a/doc/transform_iterator_abstract.rst b/doc/transform_iterator_abstract.rst deleted file mode 100644 index 6a7534e..0000000 --- a/doc/transform_iterator_abstract.rst +++ /dev/null @@ -1,5 +0,0 @@ -The transform iterator adapts an iterator by applying some function -object to the result of dereferencing the iterator. In other words, -the ``operator*`` of the transform iterator first dereferences the -base iterator, passes the result of this to the function object, and -then returns the result. diff --git a/doc/transform_iterator_ref.rst b/doc/transform_iterator_ref.rst deleted file mode 100644 index bb59c1e..0000000 --- a/doc/transform_iterator_ref.rst +++ /dev/null @@ -1,95 +0,0 @@ -:: - - template - class transform_iterator - : public iterator_adaptor - { - friend class iterator_core_access; - public: - transform_iterator(); - transform_iterator(Iterator const& x, AdaptableUnaryFunction f); - - template - transform_iterator( - transform_iterator const& t - , typename enable_if_convertible::type* = 0 // exposition - ); - - AdaptableUnaryFunction functor() const; - private: - typename transform_iterator::value_type dereference() const; - AdaptableUnaryFunction m_f; - }; - - -``transform_iterator`` requirements -................................... - -The type ``AdaptableUnaryFunction`` must be Assignable, Copy -Constructible, and the expression ``f(x)`` must be valid where ``f`` -is an object of type ``AdaptableUnaryFunction``, ``x`` is an object of -type ``AdaptableUnaryFunction::argument_type``, and where the type of -``f(x)`` must be ``AdaptableUnaryFunction::result_type``. - -The type ``Iterator`` must at least model Readable Iterator. The -resulting ``transform_iterator`` models the most refined of the -following options that is also modeled by ``Iterator``. - - * Writable Lvalue Iterator if the ``result_type`` of the - ``AdaptableUnaryFunction`` is a non-const reference. - - * Readable Lvalue Iterator if the ``result_type`` is a const - reference. - - * Readable Iterator otherwise. - - -The ``transform_iterator`` models the most refined standard traversal -concept that is modeled by ``Iterator``. - -The ``value_type`` of ``transform_iterator`` is -``remove_reference::type``. The ``reference`` type is -``result_type``. - - -``transform_iterator`` public operations -........................................ - - -``transform_iterator();`` - -:Returns: An instance of ``transform_iterator`` with ``m_f`` - and ``m_iterator`` default constructed. - - -``transform_iterator(Iterator const& x, AdaptableUnaryFunction f);`` - -:Returns: An instance of ``transform_iterator`` with ``m_f`` - initialized to ``f`` and ``m_iterator`` initialized to ``x``. - - -:: - - template - transform_iterator( - transform_iterator const& t - , typename enable_if_convertible::type* = 0 // exposition - ); - -:Returns: An instance of ``transform_iterator`` that is a copy of ``t``. -:Requires: ``OtherIterator`` is implicitly convertible to ``Iterator``. - -``AdaptableUnaryFunction functor() const;`` - -:Returns: ``m_f`` - -``transform_iterator`` private operations -......................................... - -``typename transform_iterator::value_type dereference() const;`` - -:Returns: ``m_f(transform_iterator::dereference());`` - diff --git a/doc/traversal.png b/doc/traversal.png deleted file mode 100644 index a9bbe98..0000000 Binary files a/doc/traversal.png and /dev/null differ diff --git a/example/Jamfile b/example/Jamfile deleted file mode 100644 index 921ff30..0000000 --- a/example/Jamfile +++ /dev/null @@ -1 +0,0 @@ -unit-test ia1 : reverse_iterator.cpp : ../../.. $(BOOST) ; \ No newline at end of file diff --git a/example/reverse_iterator.cpp b/example/reverse_iterator.cpp deleted file mode 100644 index ffe6e3d..0000000 --- a/example/reverse_iterator.cpp +++ /dev/null @@ -1,16 +0,0 @@ -#include -#include -#include -#include -#include - -int main() -{ - int x[] = { 1, 2, 3, 4 }; - boost::reverse_iterator - , std::ptrdiff_t> first(x + 4), last(x); - std::copy(first, last, std::ostream_iterator(std::cout, " ")); - std::cout << std::endl; - return 0; -} diff --git a/include/boost/function_output_iterator.hpp b/include/boost/function_output_iterator.hpp deleted file mode 100644 index 764c118..0000000 --- a/include/boost/function_output_iterator.hpp +++ /dev/null @@ -1,55 +0,0 @@ -// (C) Copyright Jeremy Siek 2001. Permission to copy, use, modify, -// sell and distribute this software is granted provided this -// copyright notice appears in all copies. This software is provided -// "as is" without express or implied warranty, and with no claim as -// to its suitability for any purpose. - -// Revision History: - -// 27 Feb 2001 Jeremy Siek -// Initial checkin. - -#ifndef BOOST_FUNCTION_OUTPUT_ITERATOR_HPP -#define BOOST_FUNCTION_OUTPUT_ITERATOR_HPP - -#include - -namespace boost { - - template - class function_output_iterator { - typedef function_output_iterator self; - public: - typedef std::output_iterator_tag iterator_category; - typedef void value_type; - typedef void difference_type; - typedef void pointer; - typedef void reference; - - explicit function_output_iterator(const UnaryFunction& f = UnaryFunction()) - : m_f(f) {} - - struct output_proxy { - output_proxy(UnaryFunction& f) : m_f(f) { } - template output_proxy& operator=(const T& value) { - m_f(value); - return *this; - } - UnaryFunction& m_f; - }; - output_proxy operator*() { return output_proxy(m_f); } - self& operator++() { return *this; } - self& operator++(int) { return *this; } - private: - UnaryFunction m_f; - }; - - template - inline function_output_iterator - make_function_output_iterator(const UnaryFunction& f = UnaryFunction()) { - return function_output_iterator(f); - } - -} // namespace boost - -#endif // BOOST_FUNCTION_OUTPUT_ITERATOR_HPP diff --git a/include/boost/half_open_range.hpp b/include/boost/half_open_range.hpp deleted file mode 100644 index c281846..0000000 --- a/include/boost/half_open_range.hpp +++ /dev/null @@ -1,426 +0,0 @@ -// (C) Copyright Jeremy Siek and David Abrahams 2000-2001. Permission to copy, -// use, modify, sell and distribute this software is granted provided this -// copyright notice appears in all copies. This software is provided "as is" -// without express or implied warranty, and with no claim as to its suitability -// for any purpose. -// -// Revision History: -// 11 Feb 2001 Use new iterator_adaptor interface, Fixes for Borland. -// (Dave Abrahams) -// 04 Feb 2001 Support for user-defined iterator categories (Dave Abrahams) -// 30 Jan 2001 Initial Checkin (Dave Abrahams) - -#ifndef BOOST_HALF_OPEN_RANGE_HPP_ -# define BOOST_HALF_OPEN_RANGE_HPP_ - -# include -# include -# include -# include -# include -# include -# include - -namespace boost { - -namespace detail { - - // Template class choose_finish -- allows us to maintain the invariant that - // start() <= finish() on half_open_range specializations that support random - // access. -#ifdef __MWERKS__ - template - const T& choose_finish(const T&, const T& finish, std::input_iterator_tag) - { - return finish; - } - - template - const T& choose_finish(const T&, const T& finish, std::output_iterator_tag) - { - return finish; - } - - template - const T& choose_finish(const T& start, const T& finish, std::random_access_iterator_tag) - { - return finish < start ? start : finish; - } -#else - template struct finish_chooser; - - template <> - struct finish_chooser - { - template - struct rebind - { - static T choose(const T&, const T& finish) - { return finish; } - }; - }; - - template <> - struct finish_chooser - { - template - struct rebind - { - static T choose(const T& start, const T& finish) - { return finish < start ? start : finish; } - }; - }; - - template - struct choose_finish - { - static const Incrementable choose(const Incrementable& start, const Incrementable& finish) - { - return finish_chooser<( - ::boost::is_convertible::value - )>::template rebind::choose(start, finish); - } - }; -#endif -} - -template -struct half_open_range -{ - typedef typename counting_iterator_generator::type iterator; - - private: // utility type definitions - // Using iter_t prevents compiler confusion with boost::iterator - typedef typename counting_iterator_generator::type iter_t; - - typedef std::less less_value; - typedef typename iter_t::iterator_category category; - typedef half_open_range self; - - public: - typedef iter_t const_iterator; - typedef typename iterator::value_type value_type; - typedef typename iterator::difference_type difference_type; - typedef typename iterator::reference reference; - typedef typename iterator::reference const_reference; - typedef typename iterator::pointer pointer; - typedef typename iterator::pointer const_pointer; - - // It would be nice to select an unsigned type, but this is appropriate - // since the library makes an attempt to select a difference_type which can - // hold the difference between any two iterators. - typedef typename iterator::difference_type size_type; - - half_open_range(Incrementable start, Incrementable finish) - : m_start(start), - m_finish( -#ifndef __MWERKS__ - detail::choose_finish::choose(start, finish) -#else - detail::choose_finish(start, finish, category()) -#endif - ) - {} - - // Implicit conversion from std::pair allows us - // to accept the results of std::equal_range(), for example. - half_open_range(const std::pair& x) - : m_start(x.first), - m_finish( -#ifndef __MWERKS__ - detail::choose_finish::choose(x.first, x.second) -#else - detail::choose_finish(x.first, x.second, category()) -#endif - ) - {} - - half_open_range& operator=(const self& x) - { - m_start = x.m_start; - m_finish = x.m_finish; - return *this; - } - - half_open_range& operator=(const std::pair& x) - { - m_start = x.first; - m_finish = -#ifndef __MWERKS__ - detail::choose_finish::choose(x.first, x.second); -#else - detail::choose_finish(x.first, x.second, category(); -#endif - } - - iterator begin() const { return iterator(m_start); } - iterator end() const { return iterator(m_finish); } - - Incrementable front() const { assert(!this->empty()); return m_start; } - Incrementable back() const { assert(!this->empty()); return boost::prior(m_finish); } - - Incrementable start() const { return m_start; } - Incrementable finish() const { return m_finish; } - - size_type size() const { return boost::detail::distance(begin(), end()); } - - bool empty() const - { - return m_finish == m_start; - } - - void swap(half_open_range& x) { - std::swap(m_start, x.m_start); - std::swap(m_finish, x.m_finish); - } - - public: // functions requiring random access elements - - // REQUIRES: x is reachable from this->front() - bool contains(const value_type& x) const - { - BOOST_STATIC_ASSERT((boost::is_same::value)); - return !less_value()(x, m_start) && less_value()(x, m_finish); - } - - bool contains(const half_open_range& x) const - { - BOOST_STATIC_ASSERT((boost::is_same::value)); - return x.empty() || !less_value()(x.m_start, m_start) && !less_value()(m_finish, x.m_finish); - } - - bool intersects(const half_open_range& x) const - { - BOOST_STATIC_ASSERT((boost::is_same::value)); - return less_value()( - less_value()(this->m_start, x.m_start) ? x.m_start : this->m_start, - less_value()(this->m_finish, x.m_finish) ? this->m_finish : x.m_finish); - } - - half_open_range& operator&=(const half_open_range& x) - { - BOOST_STATIC_ASSERT((boost::is_same::value)); - - if (less_value()(this->m_start, x.m_start)) - this->m_start = x.m_start; - - if (less_value()(x.m_finish, this->m_finish)) - this->m_finish = x.m_finish; - - if (less_value()(this->m_finish, this->m_start)) - this->m_start = this->m_finish; - - return *this; - } - - half_open_range& operator|=(const half_open_range& x) - { - BOOST_STATIC_ASSERT((boost::is_same::value)); - - if (!x.empty()) - { - if (this->empty()) - { - *this = x; - } - else - { - if (less_value()(x.m_start, this->m_start)) - this->m_start = x.m_start; - - if (less_value()(this->m_finish, x.m_finish)) - this->m_finish = x.m_finish; - } - } - return *this; - } - - // REQUIRES: x is reachable from this->front() - const_iterator find(const value_type& x) const - { - BOOST_STATIC_ASSERT((boost::is_same::value)); - - return const_iterator(this->contains(x) ? x : m_finish); - } - - // REQUIRES: index >= 0 && index < size() - value_type operator[](size_type index) const - { - assert(index >= 0 && index < size()); - return m_start + index; - } - - value_type at(size_type index) const - { - if (index < 0 || index >= size()) - throw std::out_of_range(std::string("half_open_range")); - return m_start + index; - } - - private: // data members - Incrementable m_start, m_finish; -}; - -template -half_open_range operator|( - half_open_range x, - const half_open_range& y) -{ - return x |= y; -} - -template -half_open_range operator&( - half_open_range x, - const half_open_range& y) -{ - return x &= y; -} - -template -inline bool operator==( - const half_open_range& x, - const half_open_range& y) -{ - const bool y_empty = y.empty(); - return x.empty() ? y_empty : !y_empty && x.start() == y.start() && x.finish() == y.finish(); -} - -template -inline bool operator!=( - const half_open_range& x, - const half_open_range& y) -{ - return !(x == y); -} - -template -inline half_open_range -make_half_open_range(Incrementable first, Incrementable last) -{ - return half_open_range(first, last); -} - -template -bool intersects( - const half_open_range& x, - const half_open_range& y) -{ - return x.intersects(y); -} - -template -bool contains( - const half_open_range& x, - const half_open_range& y) -{ - return x.contains(y); -} - -} // namespace boost - -#ifndef BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION - -namespace std { -template struct less > - : binary_function< - boost::half_open_range, - boost::half_open_range,bool> -{ - bool operator()( - const boost::half_open_range& x, - const boost::half_open_range& y) const - { - less cmp; - return !y.empty() && ( - cmp(x.start(), y.start()) - || !cmp(y.start(), x.start()) - && cmp(x.finish(), y.finish())); - } -}; - -template struct less_equal > - : binary_function< - boost::half_open_range, - boost::half_open_range,bool> -{ - bool operator()( - const boost::half_open_range& x, - const boost::half_open_range& y) const - { - typedef boost::half_open_range range; - less cmp; - return !cmp(y,x); - } -}; -template struct greater > - : binary_function< - boost::half_open_range, - boost::half_open_range,bool> -{ - bool operator()( - const boost::half_open_range& x, - const boost::half_open_range& y) const - { - typedef boost::half_open_range range; - less cmp; - return cmp(y,x); - } -}; - -template struct greater_equal > - : binary_function< - boost::half_open_range, - boost::half_open_range,bool> -{ - bool operator()( - const boost::half_open_range& x, - const boost::half_open_range& y) const - { - typedef boost::half_open_range range; - less cmp; - return !cmp(x,y); - } -}; -} // namespace std - -#else - -namespace boost { -// Can't partially specialize std::less et al, so we must provide the operators -template -bool operator<(const half_open_range& x, - const half_open_range& y) -{ - return !y.empty() && ( - x.empty() || std::less()(x.start(), y.start()) - || !std::less()(y.start(), x.start()) - && std::less()(x.finish(), y.finish())); -} - -template -bool operator>(const half_open_range& x, - const half_open_range& y) -{ - return y < x; -} - -template -bool operator<=(const half_open_range& x, - const half_open_range& y) -{ - return !(y < x); -} - -template -bool operator>=(const half_open_range& x, - const half_open_range& y) -{ - return !(x < y); -} -} // namespace boost - -#endif - - -#endif // BOOST_HALF_OPEN_RANGE_HPP_ diff --git a/include/boost/iterator.hpp b/include/boost/iterator.hpp deleted file mode 100644 index 8b82097..0000000 --- a/include/boost/iterator.hpp +++ /dev/null @@ -1,60 +0,0 @@ -// interator.hpp workarounds for non-conforming standard libraries ---------// - -// (C) Copyright Boost.org 2000. Permission to copy, use, modify, sell and -// distribute this software is granted provided this copyright notice appears -// in all copies. This software is provided "as is" without express or implied -// warranty, and with no claim as to its suitability for any purpose. - -// See http://www.boost.org/libs/utility for documentation. - -// Revision History -// 12 Jan 01 added for std::ptrdiff_t (Jens Maurer) -// 28 Jun 00 Workarounds to deal with known MSVC bugs (David Abrahams) -// 26 Jun 00 Initial version (Jeremy Siek) - -#ifndef BOOST_ITERATOR_HPP -#define BOOST_ITERATOR_HPP - -#include -#include // std::ptrdiff_t -#include - -namespace boost -{ -# if defined(BOOST_NO_STD_ITERATOR) && !defined(BOOST_MSVC_STD_ITERATOR) - template - struct iterator - { - typedef T value_type; - typedef Distance difference_type; - typedef Pointer pointer; - typedef Reference reference; - typedef Category iterator_category; - }; -# else - - // declare iterator_base in namespace detail to work around MSVC bugs which - // prevent derivation from an identically-named class in a different namespace. - namespace detail { - template -# if !defined(BOOST_MSVC_STD_ITERATOR) - struct iterator_base : std::iterator {}; -# else - struct iterator_base : std::iterator - { - typedef Reference reference; - typedef Pointer pointer; - typedef Distance difference_type; - }; -# endif - } - - template - struct iterator : detail::iterator_base {}; -# endif -} // namespace boost - -#endif // BOOST_ITERATOR_HPP diff --git a/include/boost/iterator_adaptors.hpp b/include/boost/iterator_adaptors.hpp deleted file mode 100644 index 6d876e7..0000000 --- a/include/boost/iterator_adaptors.hpp +++ /dev/null @@ -1,13 +0,0 @@ -// Permission to copy, use, modify, -// sell and distribute this software is granted provided this -// copyright notice appears in all copies. This software is provided -// "as is" without express or implied warranty, and with no claim as -// to its suitability for any purpose. - -#ifndef BOOST_ITERATOR_ADAPTOR_13062003HK_HPP -#define BOOST_ITERATOR_ADAPTOR_13062003HK_HPP - -#define BOOST_ITERATOR_ADAPTORS_VERSION 0x0200 -#include - -#endif // BOOST_ITERATOR_ADAPTOR_13062003HK_HPP diff --git a/include/boost/pending/detail/int_iterator.hpp b/include/boost/pending/detail/int_iterator.hpp deleted file mode 100644 index 2d96185..0000000 --- a/include/boost/pending/detail/int_iterator.hpp +++ /dev/null @@ -1,75 +0,0 @@ -// (C) Copyright Jeremy Siek 1999. Permission to copy, use, modify, -// sell and distribute this software is granted provided this -// copyright notice appears in all copies. This software is provided -// "as is" without express or implied warranty, and with no claim as -// to its suitability for any purpose. - -#ifndef BOOST_INT_ITERATOR_H -#define BOOST_INT_ITERATOR_H - -#include -#if !defined BOOST_MSVC -#include -#endif -#include -//using namespace std; - -#ifndef BOOST_NO_OPERATORS_IN_NAMESPACE -namespace boost { -#endif - -// this should use random_access_iterator_helper but I've had -// VC++ portablility problems with that. -JGS -template -class int_iterator -{ - typedef int_iterator self; -public: - typedef std::random_access_iterator_tag iterator_category; - typedef IntT value_type; - typedef IntT& reference; - typedef IntT* pointer; - typedef std::ptrdiff_t difference_type; - - inline int_iterator() : _i(0) { } - inline int_iterator(IntT i) : _i(i) { } - inline int_iterator(const self& x) : _i(x._i) { } - inline self& operator=(const self& x) { _i = x._i; return *this; } - inline IntT operator*() { return _i; } - inline IntT operator[](IntT n) { return _i + n; } - inline self& operator++() { ++_i; return *this; } - inline self operator++(int) { self t = *this; ++_i; return t; } - inline self& operator+=(IntT n) { _i += n; return *this; } - inline self operator+(IntT n) { self t = *this; t += n; return t; } - inline self& operator--() { --_i; return *this; } - inline self operator--(int) { self t = *this; --_i; return t; } - inline self& operator-=(IntT n) { _i -= n; return *this; } - inline IntT operator-(const self& x) const { return _i - x._i; } - inline bool operator==(const self& x) const { return _i == x._i; } - // vc++ had a problem finding != in random_access_iterator_helper - // need to look into this... for now implementing everything here -JGS - inline bool operator!=(const self& x) const { return _i != x._i; } - inline bool operator<(const self& x) const { return _i < x._i; } - inline bool operator<=(const self& x) const { return _i <= x._i; } - inline bool operator>(const self& x) const { return _i > x._i; } - inline bool operator>=(const self& x) const { return _i >= x._i; } -protected: - IntT _i; -}; - -template -inline int_iterator -operator+(IntT n, int_iterator t) { t += n; return t; } - -#ifndef BOOST_NO_OPERATORS_IN_NAMESPACE -} /* namespace boost */ -#endif - -#ifdef BOOST_NO_OPERATORS_IN_NAMESPACE -namespace boost { - using ::int_iterator; -} -#endif - - -#endif /* BOOST_INT_ITERATOR_H */ diff --git a/include/boost/pending/integer_range.hpp b/include/boost/pending/integer_range.hpp deleted file mode 100644 index 81ecf4d..0000000 --- a/include/boost/pending/integer_range.hpp +++ /dev/null @@ -1,59 +0,0 @@ -// (C) Copyright David Abrahams and Jeremy Siek 2000-2001. Permission to copy, -// use, modify, sell and distribute this software is granted provided this -// copyright notice appears in all copies. This software is provided "as is" -// without express or implied warranty, and with no claim as to its suitability -// for any purpose. -// -// Revision History: -// 04 Jan 2001 Factored counting_iterator stuff into -// boost/counting_iterator.hpp (David Abrahams) - -#ifndef BOOST_INTEGER_RANGE_HPP_ -#define BOOST_INTEGER_RANGE_HPP_ - -#include -#include - -namespace boost { - -//============================================================================= -// Counting Iterator and Integer Range Class - -template -struct integer_range { - typedef counting_iterator iterator; - - typedef iterator const_iterator; - typedef IntegerType value_type; - typedef std::ptrdiff_t difference_type; - typedef IntegerType reference; - typedef IntegerType const_reference; - typedef const IntegerType* pointer; - typedef const IntegerType* const_pointer; - typedef IntegerType size_type; - - integer_range(IntegerType start, IntegerType finish) - : m_start(start), m_finish(finish) { } - - iterator begin() const { return iterator(m_start); } - iterator end() const { return iterator(m_finish); } - size_type size() const { return m_finish - m_start; } - bool empty() const { return m_finish == m_start; } - void swap(integer_range& x) { - std::swap(m_start, x.m_start); - std::swap(m_finish, x.m_finish); - } -protected: - IntegerType m_start, m_finish; -}; - -template -inline integer_range -make_integer_range(IntegerType first, IntegerType last) -{ - return integer_range(first, last); -} - -} // namespace boost - -#endif // BOOST_INTEGER_RANGE_HPP_ diff --git a/include/boost/pending/iterator_adaptors.hpp b/include/boost/pending/iterator_adaptors.hpp deleted file mode 100644 index 4a3159b..0000000 --- a/include/boost/pending/iterator_adaptors.hpp +++ /dev/null @@ -1,7 +0,0 @@ -// Copyright David Abrahams 2003. Permission to copy, use, -// modify, sell and distribute this software is granted provided this -// copyright notice appears in all copies. This software is provided -// "as is" without express or implied warranty, and with no claim as -// to its suitability for any purpose. - -#include diff --git a/include/boost/pending/iterator_tests.hpp b/include/boost/pending/iterator_tests.hpp deleted file mode 100644 index 66e21aa..0000000 --- a/include/boost/pending/iterator_tests.hpp +++ /dev/null @@ -1,258 +0,0 @@ -// Copyright David Abrahams and Jeremy Siek 2003. Permission to copy, -// use, modify, sell and distribute this software is granted provided -// this copyright notice appears in all copies. This software is -// provided "as is" without express or implied warranty, and with no -// claim as to its suitability for any purpose. -#ifndef BOOST_ITERATOR_TESTS_HPP -# define BOOST_ITERATOR_TESTS_HPP - -// This is meant to be the beginnings of a comprehensive, generic -// test suite for STL concepts such as iterators and containers. -// -// Revision History: -// 28 Apr 2002 Fixed input iterator requirements. -// For a == b a++ == b++ is no longer required. -// See 24.1.1/3 for details. -// (Thomas Witt) -// 08 Feb 2001 Fixed bidirectional iterator test so that -// --i is no longer a precondition. -// (Jeremy Siek) -// 04 Feb 2001 Added lvalue test, corrected preconditions -// (David Abrahams) - -# include -# include -# include -# include -# include // for detail::dummy_constructor - -namespace boost { - - // use this for the value type -struct dummyT { - dummyT() { } - dummyT(detail::dummy_constructor) { } - dummyT(int x) : m_x(x) { } - int foo() const { return m_x; } - bool operator==(const dummyT& d) const { return m_x == d.m_x; } - int m_x; -}; - - -// Tests whether type Iterator satisfies the requirements for a -// TrivialIterator. -// Preconditions: i != j, *i == val -template -void trivial_iterator_test(const Iterator i, const Iterator j, T val) -{ - Iterator k; - assert(i == i); - assert(j == j); - assert(i != j); -#ifdef BOOST_NO_STD_ITERATOR_TRAITS - T v = *i; -#else - typename std::iterator_traits::value_type v = *i; -#endif - assert(v == val); -#if 0 - // hmm, this will give a warning for transform_iterator... perhaps - // this should be separated out into a stand-alone test since there - // are several situations where it can't be used, like for - // integer_range::iterator. - assert(v == i->foo()); -#endif - k = i; - assert(k == k); - assert(k == i); - assert(k != j); - assert(*k == val); -} - - -// Preconditions: i != j -template -void mutable_trivial_iterator_test(const Iterator i, const Iterator j, T val) -{ - *i = val; - trivial_iterator_test(i, j, val); -} - - -// Preconditions: *i == v1, *++i == v2 -template -void input_iterator_test(Iterator i, T v1, T v2) -{ - Iterator i1(i); - - assert(i == i1); - assert(!(i != i1)); - - // I can see no generic way to create an input iterator - // that is in the domain of== of i and != i. - // The following works for istream_iterator but is not - // guaranteed to work for arbitrary input iterators. - // - // Iterator i2; - // - // assert(i != i2); - // assert(!(i == i2)); - - assert(*i1 == v1); - assert(*i == v1); - - // we cannot test for equivalence of (void)++i & (void)i++ - // as i is only guaranteed to be single pass. - assert(*i++ == v1); - - i1 = i; - - assert(i == i1); - assert(!(i != i1)); - - assert(*i1 == v2); - assert(*i == v2); - - // i is dereferencable, so it must be incrementable. - ++i; - - // how to test for operator-> ? -} - -// how to test output iterator? - - -template struct lvalue_test -{ - template static void check(Iterator) - { -# ifndef BOOST_NO_STD_ITERATOR_TRAITS - typedef typename std::iterator_traits::reference reference; - typedef typename std::iterator_traits::value_type value_type; -# else - typedef typename Iterator::reference reference; - typedef typename Iterator::value_type value_type; -# endif - BOOST_STATIC_ASSERT(boost::is_reference::value); - BOOST_STATIC_ASSERT((boost::is_same::value - || boost::is_same::value - )); - } -}; - -# ifdef BOOST_NO_STD_ITERATOR_TRAITS -template <> struct lvalue_test { - template static void check(T) {} -}; -#endif - -template -void forward_iterator_test(Iterator i, T v1, T v2) -{ - input_iterator_test(i, v1, v2); - - Iterator i1 = i, i2 = i; - - assert(i == i1++); - assert(i != ++i2); - - trivial_iterator_test(i, i1, v1); - trivial_iterator_test(i, i2, v1); - - ++i; - assert(i == i1); - assert(i == i2); - ++i1; - ++i2; - - trivial_iterator_test(i, i1, v2); - trivial_iterator_test(i, i2, v2); - - // borland doesn't allow non-type template parameters -# if !defined(__BORLANDC__) || (__BORLANDC__ > 0x551) - lvalue_test<(boost::is_pointer::value)>::check(i); -#endif -} - -// Preconditions: *i == v1, *++i == v2 -template -void bidirectional_iterator_test(Iterator i, T v1, T v2) -{ - forward_iterator_test(i, v1, v2); - ++i; - - Iterator i1 = i, i2 = i; - - assert(i == i1--); - assert(i != --i2); - - trivial_iterator_test(i, i1, v2); - trivial_iterator_test(i, i2, v2); - - --i; - assert(i == i1); - assert(i == i2); - ++i1; - ++i2; - - trivial_iterator_test(i, i1, v1); - trivial_iterator_test(i, i2, v1); -} - -// mutable_bidirectional_iterator_test - -// Preconditions: [i,i+N) is a valid range -template -void random_access_iterator_test(Iterator i, int N, TrueVals vals) -{ - bidirectional_iterator_test(i, vals[0], vals[1]); - const Iterator j = i; - int c; - - for (c = 0; c < N-1; ++c) { - assert(i == j + c); - assert(*i == vals[c]); - assert(*i == j[c]); - assert(*i == *(j + c)); - assert(*i == *(c + j)); - ++i; - assert(i > j); - assert(i >= j); - assert(j <= i); - assert(j < i); - } - - Iterator k = j + N - 1; - for (c = 0; c < N-1; ++c) { - assert(i == k - c); - assert(*i == vals[N - 1 - c]); - assert(*i == j[N - 1 - c]); - Iterator q = k - c; - assert(*i == *q); - assert(i > j); - assert(i >= j); - assert(j <= i); - assert(j < i); - --i; - } -} - -// Precondition: i != j -template -void const_nonconst_iterator_test(Iterator i, ConstIterator j) -{ - assert(i != j); - assert(j != i); - - ConstIterator k(i); - assert(k == i); - assert(i == k); - - k = i; - assert(k == i); - assert(i == k); -} - -} // namespace boost - -#endif // BOOST_ITERATOR_TESTS_HPP diff --git a/include/boost/shared_container_iterator.hpp b/include/boost/shared_container_iterator.hpp deleted file mode 100644 index e21d8da..0000000 --- a/include/boost/shared_container_iterator.hpp +++ /dev/null @@ -1,62 +0,0 @@ -// (C) Copyright Ronald Garcia 2002. Permission to copy, use, modify, sell and -// distribute this software is granted provided this copyright notice appears -// in all copies. This software is provided "as is" without express or implied -// warranty, and with no claim as to its suitability for any purpose. - -// See http://www.boost.org/libs/utility/shared_container_iterator.html for documentation. - -#ifndef SHARED_CONTAINER_ITERATOR_RG08102002_HPP -#define SHARED_CONTAINER_ITERATOR_RG08102002_HPP - -#include "boost/iterator_adaptors.hpp" -#include "boost/shared_ptr.hpp" -#include - -namespace boost { - -template -class shared_container_iterator : public iterator_adaptor< - shared_container_iterator, - typename Container::iterator> { - - typedef iterator_adaptor< - shared_container_iterator, - typename Container::iterator> super_t; - - typedef typename Container::iterator iterator_t; - typedef boost::shared_ptr container_ref_t; - - container_ref_t container_ref; -public: - shared_container_iterator() { } - - shared_container_iterator(iterator_t const& x,container_ref_t const& c) : - super_t(x), container_ref(c) { } - - -}; - -template -shared_container_iterator -make_shared_container_iterator(typename Container::iterator iter, - boost::shared_ptr const& container) { - typedef shared_container_iterator iterator; - return iterator(iter,container); -} - - - -template -std::pair< - shared_container_iterator, - shared_container_iterator > -make_shared_container_range(boost::shared_ptr const& container) { - return - std::make_pair( - make_shared_container_iterator(container->begin(),container), - make_shared_container_iterator(container->end(),container)); -} - - -} // namespace boost -#endif // SHARED_CONTAINER_ITERATOR_RG08102002_HPP diff --git a/test/Jamfile b/test/Jamfile deleted file mode 100644 index a7bb4e3..0000000 --- a/test/Jamfile +++ /dev/null @@ -1,46 +0,0 @@ -# Copyright David Abrahams 2003. Permission to copy, use, -# modify, sell and distribute this software is granted provided this -# copyright notice appears in all copies. This software is provided -# "as is" without express or implied warranty, and with no claim as -# to its suitability for any purpose. - -subproject libs/iterator/test ; - -import testing ; - -test-suite iterator - : - # These first two tests will run last, and are expected to fail - # for many less-capable compilers. - - [ compile-fail interoperable_fail.cpp ] - # test uses expected success, so that we catch unrelated - # compilation problems. - [ run is_convertible_fail.cpp ] - - # These tests should work for just about everything. - [ run unit_tests.cpp ] - [ run concept_tests.cpp ] - [ run iterator_adaptor_cc.cpp ] - [ run iterator_adaptor_test.cpp ] - [ compile iterator_archetype_cc.cpp ] - [ run transform_iterator_test.cpp ] - [ run indirect_iterator_test.cpp ] - [ run filter_iterator_test.cpp ] - [ run reverse_iterator_test.cpp ] - [ run counting_iterator_test.cpp ] - [ run permutation_iterator_test.cpp : : : # on - ] - [ run zip_iterator_test.cpp ] - - [ run ../../utility/iterator_adaptor_examples.cpp ] - [ run ../../utility/counting_iterator_example.cpp ] - [ run ../../utility/filter_iterator_example.cpp ] - [ run ../../utility/fun_out_iter_example.cpp ] - [ run ../../utility/indirect_iterator_example.cpp ] - [ run ../../utility/projection_iterator_example.cpp ] - [ run ../../utility/reverse_iterator_example.cpp ] - [ run ../../utility/transform_iterator_example.cpp ] - [ run ../../utility/iterator_traits_test.cpp ] - -;