From a110b9fd277cdec7b9bbb020262072b65ea94077 Mon Sep 17 00:00:00 2001 From: Jeremy Siek Date: Sun, 18 Mar 2001 19:06:33 +0000 Subject: [PATCH] new files [SVN r9578] --- .../libs/iterator/iterator_concepts.gif | Bin 0 -> 2994 bytes .../libs/iterator/iterator_concepts.htm | 606 ++++++++++++++++++ 2 files changed, 606 insertions(+) create mode 100644 development/libs/iterator/iterator_concepts.gif create mode 100644 development/libs/iterator/iterator_concepts.htm diff --git a/development/libs/iterator/iterator_concepts.gif b/development/libs/iterator/iterator_concepts.gif new file mode 100644 index 0000000000000000000000000000000000000000..762c0553370a4314dcaeb85aa99811b438dc9d3d GIT binary patch literal 2994 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 + + + +Iterator Concepts + +C++ Boost + +
+ +

Iterator Concepts

+ +

The standard iterator concepts (the iterator requirements defined +in the C++ Standard) have a flaw. They glom together two separate +issues into a single set of concepts. The two issues are iterator +traversal and dereference return type semantics. These two issues are +inherently orthogonal and therefore ought to be represented by two +separate sets of concepts. The concepts described here do just +that.

+ +One set of concepts handles the return type semantics: + + +The other set of concepts handles iterator traversal: + + + +

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

+ +

Relationship with the standard iterator concepts

+ +

+std::Input Iterator refines boost::Single-Pass Iterator and +boost::ReadableIterator. + +

+std::Output Iterator refines boost::Single-Pass Iterator and +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.
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. For example, derefencing may return a temporary object and +therefore it would be a mistake to bind the result to a reference. +Also, an attempt to assign a value to the result will most likely +cause an error. + +
+  template <class Readable Iterator>
+  void foo(Readable Iterator x)
+  {
+    typedef std::iterator_traits<Readable Iterator>::value_type T;
+    T t = *x;  // Read a value. This is OK.
+    T& s = *x; // Bind to a reference. This is a bad idea.
+    *x = t;    // Try to assign. This is a really bad idea.
+  }
+
+ + +

Associated Types

+ + + + + + + + + + + + + + + +
Value typeboost::iterator_traits<X>::value_type + The type of the value obtained by dereferencing a LvalueIterator +
Return Categoryboost::iterator_traits<X>::return_category + A type convertible to boost::readable_iterator_tag +
+ +

Refinement of

+ +Assignable, +Equality Comparable, +Default Constructible + +

Valid expressions

+ + + + + + + + + + + + + + + +
NameExpressionType requirementsReturn type
Dereference*x Convertible to T.
Member accessx->mT is a type with a member named 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 Categoryboost::iterator_traits<X>::return_category + A type convertible to boost::writable_iterator_tag +
+ + + +

Refinement of

+ +Assignable, +Equality Comparable, +Default Constructible + +

Valid expressions

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

+ +

+ +

+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

+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
Value typeboost::iterator_traits<X>::value_type + The type of the value obtained by dereferencing a Constant Lvalue Iterator. +
Reference typeboost::iterator_traits<X>::reference + The return type of operator*(), which must be + const T&. +
POinter typeboost::iterator_traits<X>::pointer + The pointer to the value type, which must be const T*. +
Return Categoryboost::iterator_traits<X>::return_category + A type convertible to boost::constant_lvalue_iterator_tag +
+ + +

Valid expressions

+ + + + + + + + + + + + + + + +
NameExpressionType requirementsReturn type
Dereference*x const T&
Member accessx->mT is a type with a member named m. +   +
+ + +

+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 and +Writable Iterator. + + + +

Associated Types

+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
Value typeboost::iterator_traits<X>::value_type + The type of the value obtained by dereferencing a Mutable Lvalue Iterator. +
Reference typeboost::iterator_traits<X>::reference + The return type of operator*(), which is + T&. +
Pointer typeboost::iterator_traits<X>::pointer + The pointer to the value type, which is T*. +
Return Categoryboost::iterator_traits<X>::return_category + A type convertible to boost::mutable_lvalue_iterator_tag +
+ + +

Valid expressions

+ + + + + + + + + + + + + + + +
NameExpressionType requirementsReturn type
Dereference*x  T&
Member accessx->mT is a type with a member named m. +   +
+ +

+

+ +

+Single-Pass Iterator +

+ +A Single-Pass Iterator is an iterator that can be incremented to +traverse through a sequence of objects, but the sequence can only be +traversed a single time. + +

Associated types

+ + + + + + + + + + + + + + +
Difference typeboost::iterator_traits<X>::difference_type + A signed integral type used to represent the distance from one + iterator to another, or the number of elements in a range. +
Traversal Categoryboost::iterator_traits<X>::traversal_category + A type convertible to boost::single_pass_iterator_tag +
+ +

Valid expressions

+ + + + + + + + + + + + + + +
NameExpressionType requirementsReturn type
Preincrement++i X&
Postincrement(void)i++  
+ +

+

+ +

+Forward Iterator +

+ +The Forward Iterator is an iterator that can be incremented. Also, it +is permissible to make multiple passes through the sequence. + +

Refinement of

+ +Single-Pass Iterator + +

Associated types

+ + + + + + + +
Traversal Categoryboost::iterator_traits<X>::traversal_category + A type convertible to boost::forward_iterator_tag +
+ +

+

+ +

+Bidirectional Iterator +

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

Refinement of

+ +Forward Iterator + +

Associated types

+ + + + + + + +
Traversal Categoryboost::iterator_traits<X>::traversal_category + A type convertible to boost::bidirectional_iterator_tag +
+ +

Valid expressions

+ + + + + + + + + + + + +
NameExpressionType requirementsReturn type
Predecrement--i X&
Postdecrementi-- X
+ +

+

+ +

+Random Access Iterator +

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

Refinement of

+ +Bidirectional Iterator + +

Associated types

+ + + + + + + +
Traversal Categoryboost::iterator_traits<X>::traversal_category + A type convertible to boost::random_access_iterator_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 boost::iterator_traits<X>::difference_type
Element operatori[n]X must be a model of + Readable Iterator. The same return type as *i.
Element assignmenti[n] = tX must be a model of + Writable Iterator.unspecified
+ + +
+ +
+ + +
Copyright © 2000 +Jeremy Siek, Univ.of Notre Dame (jsiek@lsc.nd.edu) +
+ + +