From 7b472a05ee736bbf40bb31a85d34fc5148e0ac6b Mon Sep 17 00:00:00 2001 From: Dave Abrahams Date: Sun, 1 Feb 2004 04:30:15 +0000 Subject: [PATCH] Obsoleted old iterator adaptor docs [SVN r22101] --- counting_iterator.htm | 325 ----------- filter_iterator.htm | 273 ---------- function_output_iterator.htm | 169 ------ indirect_iterator.htm | 444 --------------- iterator_adaptors.htm | 1000 ---------------------------------- iterator_adaptors.pdf | Bin 84856 -> 0 bytes iterator_adaptors.ppt | Bin 103936 -> 0 bytes permutation_iterator.htm | 177 ------ projection_iterator.htm | 391 ------------- reverse_iterator.htm | 331 ----------- transform_iterator.htm | 223 -------- 11 files changed, 3333 deletions(-) delete mode 100644 counting_iterator.htm delete mode 100644 filter_iterator.htm delete mode 100644 function_output_iterator.htm delete mode 100644 indirect_iterator.htm delete mode 100644 iterator_adaptors.htm delete mode 100644 iterator_adaptors.pdf delete mode 100644 iterator_adaptors.ppt delete mode 100644 permutation_iterator.htm delete mode 100644 projection_iterator.htm delete mode 100644 reverse_iterator.htm delete mode 100644 transform_iterator.htm diff --git a/counting_iterator.htm b/counting_iterator.htm deleted file mode 100644 index 0f6cb64..0000000 --- a/counting_iterator.htm +++ /dev/null @@ -1,325 +0,0 @@ - - - - - - -Counting Iterator Adaptor Documentation - - - - -c++boost.gif (8819 bytes) - -

Counting Iterator Adaptor

- -Defined in header -boost/counting_iterator.hpp - -

-How would you fill up a vector with the numbers zero -through one hundred using std::copy()? The -only iterator operation missing from builtin integer types is an -operator*() that returns the current -value of the integer. The counting iterator adaptor adds this crucial piece of -functionality to whatever type it wraps. One can use the -counting iterator adaptor not only with integer types, but with any -type that is Incrementable (see type requirements below). The -following pseudo-code shows the general idea of how the -counting iterator is implemented. -

- -
-  // inside a hypothetical counting_iterator class...
-  typedef Incrementable value_type;
-  value_type counting_iterator::operator*() const {
-    return this->base; // no dereference!
-  }
-
- -All of the other operators of the counting iterator behave in the same -fashion as the Incrementable base type. - -

Synopsis

- -
-namespace boost {
-  template <class Incrementable>
-  struct counting_iterator_traits;
-
-  template <class Incrementable>
-  struct counting_iterator_generator;
-
-  template <class Incrementable>
-  typename counting_iterator_generator<Incrementable>::type
-  make_counting_iterator(Incrementable x);
-}
-
- -
- -

The Counting Iterator Type -Generator

- -The class template counting_iterator_generator<Incrementable> is a type generator for counting iterators. - -
-template <class Incrementable>
-class counting_iterator_generator
-{
-public:
-    typedef iterator_adaptor<...> type;
-};
-
- -

Example

- -In this example we use the counting iterator generator to create a -counting iterator, and count from zero to four. - -
-#include <boost/config.hpp>
-#include <iostream>
-#include <boost/counting_iterator.hpp>
-
-int main(int, char*[])
-{
-  // Example of using counting_iterator_generator
-  std::cout << "counting from 0 to 4:" << std::endl;
-  boost::counting_iterator_generator<int>::type first(0), last(4);
-  std::copy(first, last, std::ostream_iterator<int>(std::cout, " "));
-  std::cout << std::endl;
-
-  // to be continued...
-
-The output from this part is: -
-counting from 0 to 4:
-0 1 2 3 
-
- -

Template Parameters

- - - - - - - - - - - -
ParameterDescription
IncrementableThe type being wrapped by the adaptor.
- -

Model of

- -If the Incrementable type has all of the functionality of a -Random -Access Iterator except the operator*(), then the counting -iterator will be a model of Random -Access Iterator. If the Incrementable type has less -functionality, then the counting iterator will have correspondingly -less functionality. - -

Type Requirements

- -The Incrementable type must be Default -Constructible, Copy -Constructible, and Assignable. -Also, the Incrementable type must provide access to an -associated difference_type and iterator_category -through the counting_iterator_traits -class. - -

-Furthermore, if you wish to create a counting iterator that is a Forward -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 Iterator, then pre-decrement is also required: -
---i
-
-If you wish to create a counting iterator that is a Random -Access Iterator, then these additional expressions are also required: -
-counting_iterator_traits<Incrementable>::difference_type n;
-i += n
-n = i - j
-i < j
-
- - - -

Members

- -The counting iterator type implements the member functions and -operators required of the Random -Access Iterator concept. In addition it has the following -constructor: - -
-counting_iterator_generator::type(const Incrementable& i)
-
- -

-

-

- - -

The Counting Iterator Object Generator

- -
-template <class Incrementable>
-typename counting_iterator_generator<Incrementable>::type
-make_counting_iterator(Incrementable base);
-
- -An object -generator function that provides a convenient way to create counting -iterators.

- - - -

Example

- -In this example we count from negative five to positive five, this -time using the make_counting_iterator() function to save some -typing. - -
-  // continuing from previous example...
-
-  std::cout << "counting from -5 to 4:" << std::endl;
-  std::copy(boost::make_counting_iterator(-5),
-	    boost::make_counting_iterator(5),
-	    std::ostream_iterator<int>(std::cout, " "));
-  std::cout << std::endl;
-
-  // to be continued...
-
-The output from this part is: -
-counting from -5 to 4:
--5 -4 -3 -2 -1 0 1 2 3 4 
-
- -In the next example we create an array of numbers, and then create a -second array of pointers, where each pointer is the address of a -number in the first array. The counting iterator makes it easy to do -this since dereferencing a counting iterator that is wrapping an -iterator over the array of numbers just returns a pointer to the -current location in the array. We then use the indirect iterator adaptor to print -out the number in the array by accessing the numbers through the array -of pointers. - -
-  // continuing from previous example...
-
-  const int N = 7;
-  std::vector<int> numbers;
-  // Fill "numbers" array with [0,N)
-  std::copy(boost::make_counting_iterator(0), boost::make_counting_iterator(N),
-	    std::back_inserter(numbers));
-
-  std::vector<std::vector<int>::iterator> pointers;
-
-  // Use counting iterator to fill in the array of pointers.
-  std::copy(boost::make_counting_iterator(numbers.begin()),
-	    boost::make_counting_iterator(numbers.end()),
-	    std::back_inserter(pointers));
-
-  // Use indirect iterator to print out numbers by accessing
-  // them through the array of pointers.
-  std::cout << "indirectly printing out the numbers from 0 to " 
-	    << N << std::endl;
-  std::copy(boost::make_indirect_iterator(pointers.begin()),
-	    boost::make_indirect_iterator(pointers.end()),
-	    std::ostream_iterator<int>(std::cout, " "));
-  std::cout << std::endl;
-
-The output is: -
-indirectly printing out the numbers from 0 to 7
-0 1 2 3 4 5 6 
-
- -
- -

Counting Iterator Traits

- -The counting iterator adaptor needs to determine the appropriate -difference_type and iterator_category to use based on the -Incrementable type supplied by the user. The -counting_iterator_traits class provides these types. If the -Incrementable type is an integral type or an iterator, these types -will be correctly deduced by the counting_iterator_traits provided by -the library. Otherwise, the user must specialize -counting_iterator_traits for her type or add nested typedefs to -her type to fulfill the needs of - -std::iterator_traits. - -

The following pseudocode describes how the counting_iterator_traits are determined: - -

-template <class Incrementable>
-struct counting_iterator_traits
-{
-  if (numeric_limits<Incrementable>::is_specialized) {
-    if (!numeric_limits<Incrementable>::is_integer)
-       COMPILE_TIME_ERROR;
-
-    if (!numeric_limits<Incrementable>::is_bounded
-        && numeric_limits<Incrementable>::is_signed) {
-        typedef Incrementable difference_type;
-    }
-    else if (numeric_limits<Incrementable>::is_integral) {
-        typedef next-larger-signed-type-or-intmax_t difference_type;
-    }
-    typedef std::random_access_iterator_tag iterator_category;   
-  } else {
-    typedef std::iterator_traits<Incrementable>::difference_type difference_type;
-    typedef std::iterator_traits<Incrementable>::iterator_category iterator_category;
-  }
-};
-
- -

The italicized sections above are implementation details, but it is important -to know that the difference_type for integral types is selected so that -it can always represent the difference between two values if such a built-in -integer exists. On platforms with a working std::numeric_limits -implementation, the difference_type for any variable-length signed -integer type T is T itself. - -

-

Revised 19 Aug 2001

-

© Copyright Jeremy Siek 2000. Permission to copy, use, -modify, sell and distribute this document is granted provided this copyright -notice appears in all copies. This document is provided "as is" -without express or implied warranty, and with no claim as to its suitability for -any purpose.

- - - - - - - diff --git a/filter_iterator.htm b/filter_iterator.htm deleted file mode 100644 index 6c0c973..0000000 --- a/filter_iterator.htm +++ /dev/null @@ -1,273 +0,0 @@ - - - - - - -Filter Iterator Adaptor Documentation - - - - -c++boost.gif (8819 bytes) - -

Filter Iterator Adaptor

- -Defined in header -boost/iterator_adaptors.hpp - - -

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

Synopsis

- -
-namespace boost {
-  template <class Predicate, class BaseIterator, ...>
-  class filter_iterator_generator;
-
-  template <class Predicate, class BaseIterator>
-  typename filter_iterator_generator<Predicate, BaseIterator>::type
-  make_filter_iterator(BaseIterator first, BaseIterator last, const Predicate& p = Predicate());
-}
-
- -
- -

The Filter Iterator Type -Generator

- -The class filter_iterator_generator is a helper class whose -purpose is to construct a filter iterator type. The template -parameters for this class are the Predicate function object -type and the BaseIterator type that is being wrapped. In -most cases the associated types for the wrapped iterator can be -deduced from std::iterator_traits, but in some situations the -user may want to override these types, so there are also template -parameters for each of the iterator's associated types. - -
-template <class Predicate, class BaseIterator,
-          class Value, class Reference, class Pointer, class Category, class Distance>
-class filter_iterator_generator
-{
-public:
-  typedef iterator_adaptor<...> type; // the resulting filter iterator type 
-}
-
- - -

Example

- -The following example uses filter iterator to print out all the -positive integers in an array. - -
-struct is_positive_number {
-  bool operator()(int x) { return 0 < x; }
-};
-int main() {
-  int numbers[] = { 0, -1, 4, -3, 5, 8, -2 };
-  const int N = sizeof(numbers)/sizeof(int);
-
-  typedef boost::filter_iterator_generator<is_positive_number, int*, int>::type FilterIter;
-  is_positive_number predicate;
-  FilterIter::policies_type policies(predicate, numbers + N);
-  FilterIter filter_iter_first(numbers, policies);
-  FilterIter filter_iter_last(numbers + N, policies);
-
-  std::copy(filter_iter_first, filter_iter_last, std::ostream_iterator<int>(std::cout, " "));
-  std::cout << std::endl;
-  return 0;
-}
-
-The output is: -
-4 5 8
-
- - -

Template Parameters

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterDescription
PredicateThe function object that determines which elements are retained and which elements are skipped. -
BaseIteratorThe iterator type being wrapped. This type must at least be a model - of the InputIterator concept.
ValueThe value_type of the resulting iterator, -unless const. If const, a conforming compiler strips constness for the -value_type. Typically the default for this parameter is the -appropriate type[1].
Default: -std::iterator_traits<BaseIterator>::value_type
ReferenceThe reference type of the resulting iterator, and in -particular, the result type of operator*(). Typically the default for -this parameter is the appropriate type.
Default: If -Value is supplied, Value& is used. Otherwise -std::iterator_traits<BaseIterator>::reference is -used.
PointerThe pointer type of the resulting iterator, and in - particular, the result type of operator->(). - Typically the default for -this parameter is the appropriate type.
-Default: If Value was supplied, then Value*, -otherwise std::iterator_traits<BaseIterator>::pointer.
CategoryThe iterator_category type for the resulting iterator. -Typically the -default for this parameter is the appropriate type. If you override -this parameter, do not use bidirectional_iterator_tag -because filter iterators can not go in reverse.
-Default: std::iterator_traits<BaseIterator>::iterator_category
DistanceThe difference_type for the resulting iterator. Typically the default for -this parameter is the appropriate type.
-Default: std::iterator_traits<BaseIterator>::difference_type
- - -

Model of

- -The filter iterator adaptor (the type -filter_iterator_generator<...>::type) may be a model of InputIterator or ForwardIterator -depending on the adapted iterator type. - - -

Members

- -The filter iterator type implements all of the member functions and -operators required of the ForwardIterator -concept. In addition it has the following constructor: - -
filter_iterator_generator::type(const BaseIterator& it, const Policies& p = Policies())
- -

-The policies type has only one public function, which is its constructor: - -

filter_iterator_generator::policies_type(const Predicate& p, const BaseIterator& end)
- -

-

-

- -

The Make Filter Iterator Function

- -
-template <class Predicate, class BaseIterator>
-typename filter_generator<Predicate, BaseIterator>::type
-make_filter_iterator(BaseIterator first, BaseIterator last, const Predicate& p = Predicate())
-
- -This function provides a convenient way to create filter iterators. - -

Example

- -In this example we print out all numbers in the array that are -greater than negative two. - -
-int main()
-{
-  int numbers[] = { 0, -1, 4, -3, 5, 8, -2 };
-  const int N = sizeof(numbers)/sizeof(int);
-
-  std::copy(boost::make_filter_iterator(numbers, numbers + N, 
-					std::bind2nd(std::greater(), -2)),
-	    boost::make_filter_iterator(numbers + N, numbers + N, 
-					std::bind2nd(std::greater(), -2)),
-	    std::ostream_iterator(std::cout, " "));
-  std::cout << std::endl;
-
-}
-
-The output is: -
-0 -1 4 5 8 
-
- -

-In the next example we print the positive numbers using the -make_filter_iterator() function. - -

-struct is_positive_number {
-  bool operator()(int x) { return 0 < x; }
-};
-int main()
-{
-  int numbers[] = { 0, -1, 4, -3, 5, 8, -2 };
-  const int N = sizeof(numbers)/sizeof(int);
-
-  std::copy(boost::make_filter_iterator<is_positive_number>(numbers, numbers + N),
-	    boost::make_filter_iterator<is_positive_number>(numbers + N, numbers + N),
-	    std::ostream_iterator<int>(std::cout, " "));
-  std::cout << std::endl;
-  return 0;
-}
-
-The output is: -
-4 5 8
-
- - -

Notes

- -[1] If the compiler does not support partial -specialization and the wrapped iterator type is a builtin pointer then -the Value type must be explicitly specified (don't use the -default). - - -
-

Revised 09 Mar 2001

-

© Copyright Jeremy Siek 2000. Permission to copy, use, -modify, sell and distribute this document is granted provided this copyright -notice appears in all copies. This document is provided "as is" -without express or implied warranty, and with no claim as to its suitability for -any purpose.

- - - - diff --git a/function_output_iterator.htm b/function_output_iterator.htm deleted file mode 100644 index 6061a7b..0000000 --- a/function_output_iterator.htm +++ /dev/null @@ -1,169 +0,0 @@ - - - - - - - - - - Function Output Iterator Adaptor Documentation - - - - - c++boost.gif (8819 bytes) - -

Function Output Iterator Adaptor

- Defined in header boost/function_output_iterator.hpp - -

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 C++ Standard conforming output - iterator is non-trivial, particularly because the proper - implementation usually requires a proxy object. On the other hand, - creating a function (or function object) is much simpler. - -

Synopsis

- -
-
-namespace boost {
-  template <class UnaryFunction>
-  class function_output_iterator;
-
-  template <class UnaryFunction>
-  function_output_iterator<UnaryFunction>
-  make_function_output_iterator(const UnaryFunction& f = UnaryFunction())
-}
-
-
- -

Example

- - In this example we create an output iterator that appends - each item onto the end of a string, using the string_appender - function. - -
-
-#include <iostream>
-#include <string>
-#include <vector>
-
-#include <boost/function_output_iterator.hpp>
-
-struct string_appender {
-  string_appender(std::string& s) : m_str(s) { }
-  void operator()(const std::string& x) const {
-    m_str += x;
-  }
-  std::string& m_str;
-};
-
-int main(int, char*[])
-{
-  std::vector<std::string> x;
-  x.push_back("hello");
-  x.push_back(" ");
-  x.push_back("world");
-  x.push_back("!");
-
-  std::string s = "";
-  std::copy(x.begin(), x.end(), 
-            boost::make_function_output_iterator(string_appender(s)));
-  
-  std::cout << s << std::endl;
-
-  return 0;
-}
-
-
- -
- -

The Function Output Iterator Class

- -
-
-template <class UnaryFunction>
-class function_output_iterator;
-
-
- - The function_output_iterator class creates an Output - Iterator out of a - Unary - Function. Each item assigned to the output iterator is passed - as an argument to the unary function. - -

Template Parameters

- - - - - -
Parameter - - Description - -
UnaryFunction - - The function type being wrapped. The return type of the - function is not used, so it can be void. The - function must be a model of Unary - Function.
- -

Concept Model

- The function output iterator class is a model of Output - Iterator. - -

Members

- The function output iterator implements the member functions - and operators required of the Output - Iterator concept. In addition it has the following constructor: -
-explicit function_output_iterator(const UnaryFunction& f = UnaryFunction())
-
-
-
- -
-

The Function Output Iterator Object - Generator

- - The make_function_output_iterator() function provides a - more convenient way to create function output iterator objects. The - function saves the user the trouble of explicitly writing out the - iterator types. If the default argument is used, the function - type must be provided as an explicit template argument. - -
-
-template <class UnaryFunction>
-function_output_iterator<UnaryFunction>
-make_function_output_iterator(const UnaryFunction& f = UnaryFunction())
-
-
- -
- -

© Copyright Jeremy Siek 2001. Permission to copy, use, - modify, sell and distribute this document is granted provided this - copyright notice appears in all copies. This document is provided - "as is" without express or implied warranty, and with no claim as - to its suitability for any purpose. - - - diff --git a/indirect_iterator.htm b/indirect_iterator.htm deleted file mode 100644 index a318424..0000000 --- a/indirect_iterator.htm +++ /dev/null @@ -1,444 +0,0 @@ - - - - - - - - - - Indirect Iterator Adaptor Documentation - - - - - c++boost.gif (8819 bytes) - -

Indirect Iterator Adaptor

- Defined in header boost/iterator_adaptors.hpp - -

The indirect iterator adaptor augments an iterator by applying an - extra dereference inside of operator*(). For example, this - iterator makes it possible to view a container of pointers or - smart-pointers (e.g. std::list<boost::shared_ptr<foo> - >) as if it were a container of the pointed-to type. The following - pseudo-code shows the basic idea of the indirect iterator: - -

-
-// inside a hypothetical indirect_iterator class...
-typedef std::iterator_traits<BaseIterator>::value_type Pointer;
-typedef std::iterator_traits<Pointer>::reference reference;
-
-reference indirect_iterator::operator*() const {
-  return **this->base_iterator;
-}
-
-
- -

Synopsis

- -
-
-namespace boost {
-  template <class BaseIterator,
-            class Value, class Reference, class Category, class Pointer>
-  struct indirect_iterator_generator;
-  
-  template <class BaseIterator,
-            class Value, class Reference, class ConstReference, 
-            class Category, class Pointer, class ConstPointer>
-  struct indirect_iterator_pair_generator;
-
-  template <class BaseIterator>
-  typename indirect_iterator_generator<BaseIterator>::type
-  make_indirect_iterator(BaseIterator base)  
-}
-
-
-
- -

The Indirect Iterator Type - Generator

- The indirect_iterator_generator template is a generator of - indirect iterator types. The main template parameter for this class is the - BaseIterator type that is being wrapped. In most cases the type of - the elements being pointed to can be deduced using - std::iterator_traits, but in some situations the user may want to - override this type, so there are also template parameters that allow a user - to control the value_type, pointer, and - reference types of the resulting iterators. - -
-
-template <class BaseIterator,
-          class Value, class Reference, class Pointer>
-class indirect_iterator_generator
-{
-public:
-  typedef iterator_adaptor<...> type; // the resulting indirect iterator type 
-};
-
-
- -

Example

- This example uses the indirect_iterator_generator to create - indirect iterators which dereference the pointers stored in the - pointers_to_chars array to access the chars in the - characters array. - -
-
-#include <boost/config.hpp>
-#include <vector>
-#include <iostream>
-#include <iterator>
-#include <boost/iterator_adaptors.hpp>
-
-int main(int, char*[])
-{
-  char characters[] = "abcdefg";
-  const int N = sizeof(characters)/sizeof(char) - 1; // -1 since characters has a null char
-  char* pointers_to_chars[N];                        // at the end.
-  for (int i = 0; i < N; ++i)
-    pointers_to_chars[i] = &characters[i];
-  
-  boost::indirect_iterator_generator<char**, char>::type 
-    indirect_first(pointers_to_chars), indirect_last(pointers_to_chars + N);
-
-  std::copy(indirect_first, indirect_last, std::ostream_iterator<char>(std::cout, ","));
-  std::cout << std::endl;
-  
-  // to be continued...
-
-
- -

Template Parameters

- - - - - - - - -
Parameter - - Description - -
BaseIterator - - The iterator type being wrapped. The value_type - of the base iterator should itself be dereferenceable. - The return type of the operator* for the - value_type should match the Reference type. - -
Value - - The value_type of the resulting iterator, unless const. If - Value is const X, a conforming compiler makes the - value_type non-const X[1]. Note that 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. -
- Default: std::iterator_traits<
-   std::iterator_traits<BaseIterator>::value_type - >::value_type[2] - -
Reference - - The reference type of the resulting iterator, and in - particular, the result type of operator*().
- Default: Value& - -
Pointer - - The pointer type of the resulting iterator, and in - particular, the result type of operator->().
- Default: Value* - -
Category - The iterator_category type for the resulting iterator.
- Default: - std::iterator_traits<BaseIterator>::iterator_category - -
- -

Concept Model

- The indirect iterator will model whichever standard iterator - concept category is modeled by the base iterator. Thus, if the - base iterator is a model of Random - Access Iterator then so is the resulting indirect iterator. If - the base iterator models a more restrictive concept, the resulting - indirect iterator will model the same concept [3]. - -

Members

- The indirect iterator type implements the member functions and operators - required of the Random Access - Iterator concept. In addition it has the following constructor: -
-explicit indirect_iterator_generator::type(const BaseIterator& it)
-
-
-
- -
- -

- -

The Indirect Iterator Pair - Generator

- Sometimes a pair of const/non-const pair of iterators is - needed, such as when implementing a container. The - indirect_iterator_pair_generator class makes it more convenient to - create this pair of iterator types. - -
-
-  template <class BaseIterator,
-            class Value, class Reference, class ConstReference, 
-            class Category, class Pointer, class ConstPointer>
-  struct indirect_iterator_pair_generator;
-{
-public:
-  typedef iterator_adaptor<...> iterator;       // the mutable indirect iterator type 
-  typedef iterator_adaptor<...> const_iterator; // the immutable indirect iterator type 
-};
-
-
- -

Example

- -
-
-  // continuing from the last example...
-
-  typedef boost::indirect_iterator_pair_generator<char**,
-    char, char*, char&, const char*, const char&> PairGen;
-
-  char mutable_characters[N];
-  char* pointers_to_mutable_chars[N];
-  for (int i = 0; i < N; ++i)
-    pointers_to_mutable_chars[i] = &mutable_characters[i];
-
-  PairGen::iterator mutable_indirect_first(pointers_to_mutable_chars),
-    mutable_indirect_last(pointers_to_mutable_chars + N);
-  PairGen::const_iterator const_indirect_first(pointers_to_chars),
-    const_indirect_last(pointers_to_chars + N);
-
-  std::transform(const_indirect_first, const_indirect_last,
-     mutable_indirect_first, std::bind1st(std::plus<char>(), 1));
-
-  std::copy(mutable_indirect_first, mutable_indirect_last,
-      std::ostream_iterator<char>(std::cout, ","));
-  std::cout << std::endl;
-  // to be continued...
-
-
- -

The output is: - -

-
-b,c,d,e,f,g,h,
-
-
- -

Template Parameters

- - - - - - - - - - -
Parameter - - Description - -
BaseIterator - - The iterator type being wrapped. The value_type of the - base iterator should itself be dereferenceable. - The return type of the operator* for the - value_type should match the Reference type. - -
Value - - The value_type of the resulting iterators. - If Value is const X, a conforming compiler makes the - value_type non-const X[1]. Note that 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.
- - Default: std::iterator_traits<
-   std::iterator_traits<BaseIterator>::value_type - >::value_type[2] - -
Reference - - The reference type of the resulting iterator, and - in particular, the result type of its operator*().
- Default: Value& - -
ConstReference - - The reference type of the resulting - const_iterator, and in particular, the result type of its - operator*().
- Default: const Value& - -
Category - The iterator_category type for the resulting iterator.
- Default: - std::iterator_traits<BaseIterator>::iterator_category - -
Pointer - - The pointer type of the resulting iterator, and - in particular, the result type of its operator->().
- Default: Value* - -
ConstPointer - - The pointer type of the resulting const_iterator, - and in particular, the result type of its operator->().
- Default: const Value* - -
- -

Concept Model

- - The indirect iterators will model whichever standard iterator - concept category is modeled by the base iterator. Thus, if the - base iterator is a model of Random - Access Iterator then so are the resulting indirect - iterators. If the base iterator models a more restrictive concept, - the resulting indirect iterators will model the same concept [3]. - - -

Members

- The resulting iterator and const_iterator types implement - the member functions and operators required of the Random Access - Iterator concept. In addition they support the following constructors: - -
-
-explicit indirect_iterator_pair_generator::iterator(const BaseIterator& it)
-explicit indirect_iterator_pair_generator::const_iterator(const BaseIterator& it)
-
-
-
-
- -
- -

- -

The Indirect Iterator Object - Generator

- The make_indirect_iterator() function provides a more convenient - way to create indirect iterator objects. The function saves the user the - trouble of explicitly writing out the iterator types. - -
-
-template <class BaseIterator>
-typename indirect_iterator_generator<BaseIterator>::type
-make_indirect_iterator(BaseIterator base)  
-
-
- -

Example

- Here we again print the chars from the array characters - by accessing them through the array of pointers pointer_to_chars, - but this time we use the make_indirect_iterator() function which - saves us some typing. - -
-
-  // continuing from the last example...
-
-  std::copy(boost::make_indirect_iterator(pointers_to_chars), 
-      boost::make_indirect_iterator(pointers_to_chars + N),
-      std::ostream_iterator<char>(std::cout, ","));
-  std::cout << std::endl;
-
-  return 0;
-}
-
-
- The output is: - -
-
-a,b,c,d,e,f,g,
-
-
-
- -

Notes

- -

- -

[2] If your compiler does not support partial - specialization and the base iterator or its value_type is a - builtin pointer type, you will not be able to use the default for - Value and will need to specify this type explicitly. - -

[3]There is a caveat to which concept the - indirect iterator can model. If the return type of the - operator* for the base iterator's value type is not a - true reference, then strickly speaking, the indirect iterator can - not be a model of Forward - Iterator or any of the concepts that refine it. In this case - the Category for the indirect iterator should be - specified as std::input_iterator_tag. However, even in - this case, if the base iterator is a random access iterator, the - resulting indirect iterator will still satisfy most of the - requirements for Random - Access Iterator. - -

- -

Revised - 18 Sep 2001 - - -

© Copyright Jeremy Siek and David Abrahams 2001. Permission to - copy, use, modify, sell and distribute this document is granted provided - this copyright notice appears in all copies. This document is provided "as - is" without express or implied warranty, and with no claim as to its - suitability for any purpose. - - - - - - - - diff --git a/iterator_adaptors.htm b/iterator_adaptors.htm deleted file mode 100644 index c3d249e..0000000 --- a/iterator_adaptors.htm +++ /dev/null @@ -1,1000 +0,0 @@ - - - - - - - - - - Boost Iterator Adaptor Library - - - - - c++boost.gif (8819 bytes) - -

Boost Iterator Adaptor Library

- -

Introduction

- -

The Iterator Adaptor library allows you transform an arbitrary ``base'' - type into a standard-conforming iterator with the behaviors you choose. - Doing so is especially easy if the ``base'' type is itself an iterator. The - library also supplies several example adaptors which apply - specific useful behaviors to arbitrary base iterators. - -

Backward Compatibility Note

- -

The library's interface has changed since it was first released, breaking - backward compatibility: - -

    - -
  1. Policies classes now operate on instances of the - whole iterator_adaptor object, rather than just operating on the - Base object. This change not only gives the policies class access - to both members of a pair of interacting iterators, but also eliminates the - need for the ugly type<Reference> and - type<Difference> parameters to various policy functions. - -
  2. The Named Template Parameter - interface has been made simpler, easier to use, and compatible with more - compilers. - -
- -

Other Documentation

- -

``Policy Adaptors and the Boost Iterator - Adaptor Library'' is a technical paper describing this library and the - powerful design pattern on which it is based. It was presented at the C++ Template Workshop at OOPSLA - 2001; the slides from the talk are available here. Please note that while the slides - incorporate the minor interface changes described in the previous section, - the paper does not. - -

Table of Contents

- - - -

Dave - Abrahams started the library, applying policy class technique and - handling const/non-const iterator interactions. He also contributed the - indirect_ and reverse_ iterator generators, and expanded - counting_iterator_generator to - cover all incrementable types. He edited most of the documentation, - sometimes heavily.
- Jeremy - Siek contributed the transform - iterator adaptor, the integer-only version of counting_iterator_generator, - the function output iterator - adaptor, and most of the documentation.
- John - Potter contributed the projection_ and filter_ iterator generators and made some - simplifications to the main iterator_adaptor template.
- Jens Maurer - contributed the generator iterator - adaptor.
- Toon Knapen contributed the permutation - iterator adaptor.
- Ronald Garcia - contributed the shared container iterator - adaptor.
- -

Class template - iterator_adaptor

- Implementing standard conforming iterators is a non-trivial task. There are - some fine points such as the interactions between an iterator and its - corresponding const_iterator, and there are myriad operators that should be - implemented but are easily forgotten or mishandled, such as - operator->(). Using iterator_adaptor, you can easily - implement an iterator class, and even more easily extend and adapt existing iterator - types. Moreover, it is easy to make a pair of interoperable const - and non-const iterators. - -

iterator_adaptor is declared like this: -

-template <class Base, class Policies, 
-    class ValueOrNamedParam = typename std::iterator_traits<Base>::value_type,
-    class ReferenceOrNamedParam = ...(see below),
-    class PointerOrNamedParam = ...(see below),
-    class CategoryOrNamedParam = typename std::iterator_traits<Base>::iterator_category,
-    class DistanceOrNamedParam = typename std::iterator_traits<Base>::difference_type>
-struct iterator_adaptor;
-
- -

Template Parameters

- -

Although iterator_adaptor takes seven template parameters, - defaults have been carefully chosen to minimize the number of parameters - you must supply in most cases, especially if Base is an - iterator. - - - - - - - - - - - -
Parameter - - Description - - Requirements - -
Base - - The data type on which the resulting iterator is based. Do - not be misled by the name "Base": this is not a base - class. - - - Assignable, - Default Constructible - -
Policies - - A policy - class that supplies core functionality to the resulting iterator. - - See table below. - -
Value - - The value_type of the resulting iterator, unless const. If - Value is const X the - value_type will be (non-const) X[1]. If the value_type you wish to use is an abstract - base class see note [5].
- Default: - std::iterator_traits<Base>::value_type [2] - -
Reference - - The reference type of the resulting iterator, and in - particular, the result type of operator*().
- Default: If Value is supplied, Value& is - used. Otherwise - std::iterator_traits<Base>::reference is used. [7] - - 		ForwardIterators, - BidirectionalIterators, - and RandomAccessIterators - require that Reference is a true reference type (e.g. not a proxy). - -
Pointer - - The pointer type of the resulting iterator, and in - particular, the result type of operator->().
- Default: If Value was not supplied, std::iterator_traits<Base>::pointer. [7] Otherwise, if iterator_category is - input_iterator, then a class yielding - Value* when operator->() is applied. - Otherwise, Value*. - - 		value_type* or a - class which yields value_type* when - operator->() is applied. - -
Category - - The iterator_category type for the resulting iterator.
- Default: - std::iterator_traits<Base>::iterator_category - - 		One of - std::input_iterator_tag, - std::output_iterator_tag, - std::forward_iterator_tag, - std::bidirectional_iterator_tag, or - std::random_access_iterator_tag. - -
Distance - - The difference_type for the resulting iterator.
- Default: - std::iterator_traits<Base>::difference_type - 		A signed integral type - -
NamedParam - - A named template parameter (see below). -
- -

Named Template Parameters

- - With seven template parameters, providing arguments for - iterator_adaptor in the correct order can be challenging. - Also, often times one would like to specify the sixth or seventh - template parameter, but use the defaults for the third through - fifth. As a solution to these problems we provide a mechanism for - naming the last five template parameters, and providing them in - any order through a set of named template parameters. The following - classes are provided for specifying the parameters. Any of these - classes can be used for any of the last five template parameters - of iterator_adaptor. -
-
-template <class Value> struct value_type_is;
-template <class Reference> struct reference_is;
-template <class Pointer> struct pointer_is;
-template <class Distance> struct difference_type_is;
-template <class Category> struct iterator_category_is;
-
-
- - For example, the following adapts foo_iterator to create - an InputIterator - with reference type foo, and whose other traits - are determined according to the defaults described above. - -
-
-typedef iterator_adaptor<foo_iterator, foo_policies,
-  reference_is<foo>, iterator_category_is<std::input_iterator_tag>
-  > MyIterator;
-
-
- - -

The Policies Class

- -

The main task in using iterator_adaptor is creating an - appropriate Policies class. The Policies class will become - the functional heart of the resulting iterator, supplying the core - operations that determine its behavior. The iterator_adaptor - template defines all of the operators required of a Random Access - Iterator by dispatching to a Policies object. Your - Policies class must implement a subset of the core iterator - operations below corresponding to the iterator categories you want it to - support.
-
- - - - - - - - - - - - - -
- Policies Class Requirements
- T: adapted iterator type; x, y: objects of type - T; p: T::policies_type - d: - T::difference_type; i1, i2: - T::base_type -
Expression - - Effects - - Implements Operations - - Required for Iterator Categories - -
p.initialize(b) - - optionally modify base iterator during iterator construction - - constructors - - Input/ Output/ Forward/ Bidirectional/ - Random Access - - -
p.dereference(x) - - returns an element of the iterator's reference type - - *x, x[d] - - -
p.equal(x, y) - - tests the iterator for equality - - i1 == i2, i1 != i2 - -
p.increment(x) - - increments the iterator - - ++x, x++ - -
p.decrement(x) - - decrements the iterator - - --x, x-- - - Bidirectional/ - Random Access - -
p.distance(x, y) - - measures the distance between iterators - - y - x, x < y - - Random - Access - -
p.advance(x, n) - - adds an integer offset to iterators - - -x + d, -d + x, - -
-x += d, -x - d,
-x -= d - -
- -

The library also supplies a "trivial" policy class, - default_iterator_policies, which implements all seven of the core - operations in the usual way. If you wish to create an iterator adaptor that - only changes a few of the base type's behaviors, then you can derive your - new policy class from default_iterator_policies to avoid retyping - the usual behaviors. You should also look at - default_iterator_policies as the ``boilerplate'' for your own - policy classes, defining functions with the same interface. This is the - definition of default_iterator_policies:
-
- -

-
-struct default_iterator_policies
-{
-    // Some of these members were defined static, but Borland got confused
-    // and thought they were non-const. Also, Sun C++ does not like static
-    // function templates.
-
-    template <class Base>
-    void initialize(Base&)
-        { }
-
-    template <class IteratorAdaptor>
-    typename IteratorAdaptor::reference dereference(const IteratorAdaptor& x) const
-        { return *x.base(); }
-
-    template <class IteratorAdaptor>
-    void increment(IteratorAdaptor& x)
-        { ++x.base(); }
-
-    template <class IteratorAdaptor>
-    void decrement(IteratorAdaptor& x)
-        { --x.base(); }
-
-    template <class IteratorAdaptor, class DifferenceType>
-    void advance(IteratorAdaptor& x, DifferenceType n)
-        { x.base() += n; }
-
-    template <class IteratorAdaptor1, class IteratorAdaptor2>
-    typename IteratorAdaptor1::difference_type
-    distance(const IteratorAdaptor1& x, const IteratorAdaptor2& y) const
-        { return y.base() - x.base(); }
-
-    template <class IteratorAdaptor1, class IteratorAdaptor2>
-    bool equal(const IteratorAdaptor1& x, const IteratorAdaptor2& y) const
-        { return x.base() == y.base(); }
-};
-
- -

Template member functions are used throughout - default_iterator_policies so that it can be employed with a wide - range of iterators. If we had used concrete types above, we'd have tied the - usefulness of default_iterator_policies to a particular range of - adapted iterators. If you follow the same pattern with your - Policies classes, you can use them to generate more specialized - adaptors along the lines of those supplied by this library. - -

Additional Members

- In addition to all of the member functions required of a Random Access - Iterator, the iterator_adaptor class template defines the - following members.
-
- - - - - - - -
explicit iterator_adaptor(const Base&, const Policies& = - Policies()) -

- Construct an adapted iterator from a base object and a policies - object. As this constructor is explicit, it does not - provide for implicit conversions from the Base type to - the iterator adaptor. - -
template <class B, class V, class R, class P>
- iterator_adaptor(const - iterator_adaptor<B,Policies,V,R,P,Category,Distance>&) -

- This constructor allows for conversion from mutable to - constant adapted iterators. See below for more details.
- Requires: B is convertible to Base. - -
const base_type& base() const; -

- Return a const reference to the base object. - -
base_type& base(); -

- Return a reference to the base object. This is to give the policies object - access to the base object. See above for policies - iterator_adaptor interaction.[8] - -
const Policies& policies() const; -

- Return a const reference to the policies object. - -
Policies& policies(); -

- Return a reference to the policies object. -
- -

Example

- -

It is often useful to automatically apply some function to the value - returned by dereferencing an iterator. The transform iterator makes it easy to create - an iterator adaptor which does just that. Here we will show how easy it is - to implement the transform iterator using the iterator_adaptor - template. - -

We want to be able to adapt a range of iterators and functions, so the - policies class will have a template parameter for the function type and it - will have a data member of that type. We know that the function takes one - argument and that we'll need to be able to deduce the result_type - of the function so we can use it for the adapted iterator's - value_type. AdaptableUnaryFunction - is the Concept - that fulfills those requirements. - -

To implement a transform iterator we will only change one of the base - iterator's behaviors, so the transform_iterator_policies class can - inherit the rest from default_iterator_policies. We will define the - dereference() member function, which is used to implement - operator*() of the adapted iterator. The implementation will - dereference the base iterator and apply the function object. The complete - code for transform_iterator_policies is:
-
- -

-template <class AdaptableUnaryFunction>
-struct transform_iterator_policies : public default_iterator_policies
-{
-    transform_iterator_policies() { }
-
-    transform_iterator_policies(const AdaptableUnaryFunction& f)
-        : m_f(f) { }
-    
-    template <class IteratorAdaptor>
-    typename IteratorAdaptor::reference
-    dereference(const IteratorAdaptor& iter) const
-        { return m_f(*iter.base()); }
-
-    AdaptableUnaryFunction m_f;
-};
-
-
- -

The next step is to use the iterator_adaptor template to - construct the transform iterator type. The nicest way to package the - construction of the transform iterator is to create a type generator. - The first template parameter to the generator will be the type of the - function object and the second will be the base iterator type. We use - iterator_adaptor to define the transform iterator type as a nested - typedef inside the transform_iterator_generator class. - Because the function may return by-value, we must limit the - iterator_category to Input Iterator, and - the iterator's reference type cannot be a true reference (the - standard allows this for input iterators), so in this case we can use few - of iterator_adaptor's default template arguments.
-
- - -

-
-template <class AdaptableUnaryFunction, class Iterator>
-struct transform_iterator_generator
-{
-    typedef typename AdaptableUnaryFunction::result_type value_type;
-public:
-    typedef iterator_adaptor<Iterator, 
-        transform_iterator_policies<AdaptableUnaryFunction>,
-        value_type, value_type, value_type*, std::input_iterator_tag>
-      type;
-};
-
-
- -

As a finishing touch, we will create an object generator - for the transform iterator. Our object generator makes it more - convenient to create a transform iterator.
-
- - -

-
-template <class AdaptableUnaryFunction, class Iterator>
-typename transform_iterator_generator<AdaptableUnaryFunction,Iterator>::type
-make_transform_iterator(Iterator base,
-                        const AdaptableUnaryFunction& f = AdaptableUnaryFunction())
-{
-    typedef typename transform_iterator_generator<AdaptableUnaryFunction,
-      Iterator>::type result_t;
-    return result_t(base, f);
-}
-
-
- -

Here is an example that shows how to use a transform iterator to iterate - through a range of numbers, multiplying each of them by 2 and printing the - result to standard output.
-
- - -

-
-#include <functional>
-#include <algorithm>
-#include <iostream>
-#include <boost/iterator_adaptors.hpp>
-
-int main(int, char*[])
-{
-  int x[] = { 1, 2, 3, 4, 5, 6, 7, 8 };
-  const int N = sizeof(x)/sizeof(int);
-  std::cout << "multiplying the array by 2:" << std::endl;
-  std::copy(boost::make_transform_iterator(x, std::bind1st(std::multiplies<int>(), 2)),
-      boost::make_transform_iterator(x + N, std::bind1st(std::multiplies<int>(), 2)),
-      std::ostream_iterator<int>(std::cout, " "));
-  std::cout << std::endl;
-  return 0;
-}
-
- This output is: -
-2 4 6 8 10 12 14 16
-
-
- -

Iterator Interactions

- -

C++ allows const and non-const pointers to interact in - the following intuitive ways: - -

- - Getting user-defined iterators to work together that way is nontrivial (see - here for an example of where - the C++ standard got it wrong), but iterator_adaptor can make it - easy. The rules are as follows: - - - -

Example

- -

The Projection Iterator adaptor is similar to the transform iterator adaptor in that -its operator*() applies some function to the result of -dereferencing the base iterator and then returns the result. The -difference is that the function must return a reference to some -existing object (for example, a data member within the -value_type of the base iterator). - -

-The projection_iterator_pair_generator template - is a special two-type generator for mutable and constant versions of a - projection iterator. It is defined as follows: -

-
-template <class AdaptableUnaryFunction, class Iterator, class ConstIterator>
-struct projection_iterator_pair_generator {
-    typedef typename AdaptableUnaryFunction::result_type value_type;
-    typedef projection_iterator_policies<AdaptableUnaryFunction> policies;
-public:
-    typedef iterator_adaptor<Iterator,policies,value_type> iterator;
-    typedef iterator_adaptor<ConstIterator,policies,value_type,
-        const value_type&,const value_type*> const_iterator;
-};
-
-
- -

It is assumed that the Iterator and ConstIterator arguments are corresponding mutable -and constant iterators.

- -

Challenge

- -

There is an unlimited number of ways the iterator_adaptors - class can be used to create iterators. One interesting exercise would be to - re-implement the iterators of std::list and slist - using iterator_adaptors, where the adapted Iterator types - would be node pointers. - -

Concept Model

- Depending on the Base and Policies template parameters, - an iterator_adaptor can be a Input Iterator, Forward - Iterator, Bidirectional - Iterator, or Random Access - Iterator. - -

Declaration Synopsis

-
-template <class Base, class Policies, 
-    class Value = typename std::iterator_traits<Base>::value_type,
-    class Reference = ...(see below),
-    class Pointer = ...(see below),
-    class Category = typename std::iterator_traits<Base>::iterator_category,
-    class Distance = typename std::iterator_traits<Base>::difference_type
-         >
-struct iterator_adaptor
-{
-    typedef Distance difference_type;
-    typedef typename boost::remove_const<Value>::type value_type;
-    typedef Pointer pointer;
-    typedef Reference reference;
-    typedef Category iterator_category;
-    typedef Base base_type;
-    typedef Policies policies_type;
-
-    iterator_adaptor();
-    explicit iterator_adaptor(const Base&, const Policies& = Policies());
-
-    base_type&       base();
-    const base_type& base() const;
-
-    template <class B, class V, class R, class P>
-    iterator_adaptor(
-        const iterator_adaptor<B,Policies,V,R,P,Category,Distance>&);
-
-    reference operator*() const; [6]
-    operator_arrow_result_type operator->() const; [3]
-    value_type operator[](difference_type n) const; [4], [6]
-
-    iterator_adaptor& operator++();
-    iterator_adaptor& operator++(int);
-    iterator_adaptor& operator--();
-    iterator_adaptor& operator--(int);
-
-    iterator_adaptor& operator+=(difference_type n);
-    iterator_adaptor& operator-=(difference_type n);
-
-    iterator_adaptor& operator-(Distance x) const;
-};
-
-template <class B, class P, class V, class R, class Ptr, 
-    class C, class D1, class D2>
-iterator_adaptor<B,P,V,R,Ptr,C,D1>
-operator+(iterator_adaptor<B,P,V,R,Ptr,C,D1>, D2);
-
-template <class B, class P, class V, class R, class Ptr,
-    class C, class D1, class D2>
-iterator_adaptor<B,P,V,R,P,C,D1>
-operator+(D2, iterator_adaptor<B,P,V,R,Ptr,C,D1> p);
-
-template <class B1, class B2, class P, class V1, class V2,
-    class R1, class R2, class P1, class P2, class C, class D>
-Distance operator-(const iterator_adaptor<B1,P,V1,R1,P1,C,D>&, 
-                   const iterator_adaptor<B2,P,V2,R2,P2,C,D>&);
-
-template <class B1, class B2, class P, class V1, class V2,
-    class R1, class R2, class P1, class P2, class C, class D>
-bool operator==(const iterator_adaptor<B1,P,V1,R1,P1,C,D>&, 
-                const iterator_adaptor<B2,P,V2,R2,P2,C,D>&);
-
-// and similarly for operators !=, <, <=, >=, >
-
- -

Portability

- -

Generally, the iterator adaptors library can be compiled with all compilers - supporting iterator traits and type traits.

- -

Microsoft VC++ is not able to handle iterator adaptors based on a - vector::iterator without specifying all template paramters explicitly. - In case not all template parameters are specified explicitly, the iterator adaptors - library will deduce these types using iterator_traits. But since in VC++ a - vector::iterator is a T*, VC++ can't handle using - iterator_traits due to the lack of partial template specialization.

- - -

Notes

- -

[1] The standard specifies that the value_type - of const iterators to T (e.g. const T*) is - non-const T, while the pointer and - reference types for all Forward Iterators are - const T* and const T&, respectively. Stripping the - const-ness of Value allows you to easily make a constant - iterator by supplying a const type for Value, and allowing - the defaults for the Pointer and Reference parameters to - take effect. Although compilers that don't support partial specialization - won't strip const for you, having a const value_type is - often harmless in practice. - -

[2] If your compiler does not support partial - specialization and the base iterator is a builtin pointer type, you - will not be able to use the default for Value and will have to - specify this type explicitly. - -

[3] The result type for the operator->() - depends on the category and value type of the iterator and is somewhat - complicated to describe. But be assured, it works in a stardard conforming - fashion, providing access to members of the objects pointed to by the - iterator. - -

[4] The result type of operator[]() is - value_type instead of reference as might be expected. - There are two reasons for this choice. First, the C++ standard only - requires that the return type of an arbitrary Random Access - Iterator's operator[]be ``convertible to T'' (Table 76), so - when adapting an arbitrary base iterator we may not have a reference to - return. Second, and more importantly, for certain kinds of iterators, - returning a reference could cause serious memory problems due to the - reference being bound to a temporary object whose lifetime ends inside of - the operator[]. - -

[5] - The value_type of an iterator may not be - an abstract base class, however many common uses of iterators - never need the value_type, only the reference type. - If you wish to create such an iterator adaptor, use a dummy - type such as char for the Value parameter, - and use a reference to your abstract base class for - the Reference parameter. Note that such an iterator - does not fulfill the C++ standards requirements for a - - Forward Iterator, so you will need to use a less restrictive - iterator category such as std::input_iterator_tag. - -

[6] - There is a common misconception that an iterator should have two - versions of operator* and of operator[], one - version that is a const member function and one version - that is non-const. Perhaps the source of this - misconception is that containers typically have const and - non-const versions of many of their member functions. Iterators, - however, are different. A particular iterator type can be either - mutable or constant (but not both). One can assign - to and change the object pointed to by a mutable iterator whereas a - constant iterator returns constant objects when dereferenced. Whether - the iterator object itself is const has nothing to do with - whether the iterator is mutable or constant. This is analogous to - the way built-in pointer types behave. For example, one can - modify objects pointed to by a const pointer -

-    int* const x = new int;
-    int i = 3;
-    *x = i;
-
- but one cannot modify objects pointed to by a pointer - to const -
-    int const* x = new int;
-    int i = 3;
-    *x = i;
-
- -

[7] - If you are using a compiler that does not have a version of - std::iterator_traits that works for pointers (i.e., if your - compiler does not support partial specialization) then if the - Base type is a const pointer, then the correct defaults - for the reference and pointer types can not be - deduced. You must specify these types explicitly. -

[8] - Exposing the base object might be considered as being dangerous. - A possible fix would require compiler support for template friends. - As this is not widely available today, the base object remains exposed for now. - -

- -

Revised - 30 Nov 2001 - - -

© Copyright Dave Abrahams and Jeremy Siek 2001. Permission to copy, - use, modify, sell and distribute this document is granted provided this - copyright notice appears in all copies. This document is provided "as is" - without express or implied warranty, and with no claim as to its - suitability for any purpose. - - - - - - - - - - - - - - - diff --git a/iterator_adaptors.pdf b/iterator_adaptors.pdf deleted file mode 100644 index 6ae01b0aaf00b2db1ef3cda524c9b0c9c188eec0..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 84856 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�yd~$%wOh|N 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­Xn!{0{9yj!Y74K}kHt46`h&aJVotX4+&HjK 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 LgY1Q2QuPA>5%xMT diff --git a/permutation_iterator.htm b/permutation_iterator.htm deleted file mode 100644 index ea68387..0000000 --- a/permutation_iterator.htm +++ /dev/null @@ -1,177 +0,0 @@ - - - - -Permutation Iterator Adaptor Documentation - - - - -

Permutation Iterator Adaptor

-

Defined in header boost/permutation_iterator.hpp

-

The permutation iterator adaptor provides an iterator to a permutation of a given range. -(see definition of permutation). -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

- -

Synopsis

- -
-
-namespace boost {
-  template <class IndexIterator>
-  class permutation_iterator_policies;
-
-  template <class ElementIterator, class IndexIterator>
-  class permutation_iterator_generator;
-
-  template <class ElementIterator, class IndexIterator>
-  typename permutation_iterator_generator<ElementIterator, IndexIterator>::type
-  make_permutation_iterator(ElementIterator& base, IndexIterator& indexing);
-}
-
-
- - -

The Permutation Iterator Generator Class Template

- -

The permutation_iterator_generator is a helper class whose purpose -is to construct a permutation iterator type. This class has -two template arguments, the first being the iterator type over the range V, the -second being the type of the iterator over the indices. - -

-
-template <class ElementIterator, class IndexIterator>
-class permutation_iterator_generator
-{
-public:
-  typedef iterator_adaptor<...> type; // the resulting permutation iterator type 
-}
-
-
- - -

Template Parameters

- - - - - - - - - - - - - - - -
ParameterDescription
ElementIteratorThe iterator over the elements to be permuted. This type must be a model -of RandomAccessIterator
IndexIteratorThe iterator over the new indexing scheme. This type must at least be a model -of ForwardIterator. -The IndexIterator::value_type must be convertible to the -ElementIterator::difference_type.
- -

Concept Model

-The permutation iterator is always a model of the same concept as the IndexIterator. - -

Members

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

The Permutation Iterator Object Generator

- -The make_permutation_iterator() function provides a -convenient way to create permutation iterator objects. The function -saves the user the trouble of explicitly writing out the iterator -types. - -
-
-template <class ElementIterator, class IndexIterator >
-typename permutation_iterator_generator<ElementIterator, IndexIterator>::type
-make_permutation_iterator(ElementIterator& base, IndexIterator& indices);
-
-
- -

Example

-
-
-  using namespace boost;
-  int i = 0;
-
-  typedef std::vector< int > element_range_type;
-  typedef std::list< int > index_type;
-
-  static const int element_range_size = 10;
-  static const int index_size = 4;
-
-  element_range_type elements( element_range_size );
-  for(element_range_type::iterator el_it = elements.begin() ; el_it != elements.end() ; ++el_it) *el_it = std::distance(elements.begin(), el_it);
-
-  index_type indices( index_size );
-  for(index_type::iterator i_it = indices.begin() ; i_it != indices.end() ; ++i_it ) *i_it = element_range_size - index_size + std::distance(indices.begin(), i_it);
-  std::reverse( indices.begin(), indices.end() );
-
-  typedef permutation_iterator_generator< element_range_type::iterator, index_type::iterator >::type permutation_type;
-  permutation_type begin = make_permutation_iterator( elements.begin(), indices.begin() );
-  permutation_type it = begin;
-  permutation_type end = make_permutation_iterator( elements.begin(), indices.end() );
-
-  std::cout << "The original range is : ";
-  std::copy( elements.begin(), elements.end(), std::ostream_iterator< int >( std::cout, " " ) );
-  std::cout << "\n";
-
-  std::cout << "The reindexing scheme is : ";
-  std::copy( indices.begin(), indices.end(), std::ostream_iterator< int >( std::cout, " " ) );
-  std::cout << "\n";
-
-  std::cout << "The permutated range is : ";
-  std::copy( begin, end, std::ostream_iterator< int >( std::cout, " " ) );
-  std::cout << "\n";
-
-  std::cout << "Elements at even indices in the permutation : ";
-  it = begin;
-  for(i = 0; i < index_size / 2 ; ++i, it+=2 ) std::cout << *it << " ";
-  std::cout << "\n";
-
-  std::cout << "Permutation backwards : ";
-  it = begin + (index_size);
-  assert( it != begin );
-  for( ; it-- != begin ; ) std::cout << *it << " ";
-  std::cout << "\n";
-
-  std::cout << "Iterate backward with stride 2 : ";
-  it = begin + (index_size - 1);
-  for(i = 0 ; i < index_size / 2 ; ++i, it-=2 ) std::cout << *it << " ";
-  std::cout << "\n";
-
-
- -


-Thanks: The permutation iterator is only a small addition to the superb iterator adaptors -library of David Abrahams and Jeremy Siek. -

- -Copyright 2001 Toon Knapen. - - - diff --git a/projection_iterator.htm b/projection_iterator.htm deleted file mode 100644 index e6b0df3..0000000 --- a/projection_iterator.htm +++ /dev/null @@ -1,391 +0,0 @@ - - - - - - -Projection Iterator Adaptor Documentation - - - - -c++boost.gif (8819 bytes) - -

Projection Iterator Adaptor

- -Defined in header -boost/iterator_adaptors.hpp - -

-The projection iterator adaptor is similar to the transform iterator adaptor in that -its operator*() applies some function to the result of -dereferencing the base iterator and then returns the result. The -difference is that the function must return a reference to some -existing object (for example, a data member within the -value_type of the base iterator). The following -pseudo-code gives the basic idea. The data member p is -the function object. - -

-  reference projection_iterator::operator*() const {
-    return this->p(*this->base_iterator);
-  }
-
- -

Synopsis

- -
-namespace boost {
-  template <class AdaptableUnaryFunction, class BaseIterator>
-  struct projection_iterator_generator;
-  
-  template <class AdaptableUnaryFunction, 
-            class BaseIterator, class ConstBaseIterator>
-  struct projection_iterator_pair_generator;
-
-  template <class AdaptableUnaryFunction, class BaseIterator>
-  typename projection_iterator_generator<AdaptableUnaryFunction, BaseIterator>::type
-  make_projection_iterator(BaseIterator base,
-			   const AdaptableUnaryFunction& p = AdaptableUnaryFunction())
-
-  template <class AdaptableUnaryFunction, class ConstBaseIterator>
-  typename projection_iterator_generator<AdaptableUnaryFunction, ConstBaseIterator>::type
-  make_const_projection_iterator(ConstBaseIterator base,
-                                 const AdaptableUnaryFunction& p = AdaptableUnaryFunction())  
-}
-
- -
- -

The Projection Iterator Type -Generator

- -The class projection_iterator_generator is a helper class -whose purpose is to construct an projection iterator type. The main -template parameter for this class is the AdaptableUnaryFunction -function object type and the BaseIterator type that is being -wrapped. - -
-template <class AdaptableUnaryFunction, class BaseIterator>
-class projection_iterator_generator
-{
-public:
-  typedef iterator_adaptor<...> type; // the resulting projection iterator type 
-};
-
- -

Example

- -In the following example we have a list of personnel records. Each -record has an employee's name and ID number. We want to be able to -traverse through the list accessing either the name or the ID numbers -of the employees using the projection iterator so we create the -function object classes select_name and -select_ID. We then use the -projection_iterator_generator class to create a projection -iterator and use it to print out the names of the employees. - -
-#include <boost/config.hpp>
-#include <list>
-#include <iostream>
-#include <iterator>
-#include <algorithm>
-#include <string>
-#include <boost/iterator_adaptors.hpp>
-
-struct personnel_record {
-  personnel_record(std::string n, int id) : m_name(n), m_ID(id) { }
-  std::string m_name;
-  int m_ID;
-};
-
-struct select_name {
-  typedef personnel_record argument_type;
-  typedef std::string result_type;
-  const std::string& operator()(const personnel_record& r) const {
-    return r.m_name;
-  }
-  std::string& operator()(personnel_record& r) const {
-    return r.m_name;
-  }
-};
-
-struct select_ID {
-  typedef personnel_record argument_type;
-  typedef int result_type;
-  const int& operator()(const personnel_record& r) const {
-    return r.m_ID;
-  }
-  int& operator()(personnel_record& r) const {
-    return r.m_ID;
-  }
-};
-
-int main(int, char*[])
-{
-  std::list<personnel_record> personnel_list;
-
-  personnel_list.push_back(personnel_record("Barney", 13423));
-  personnel_list.push_back(personnel_record("Fred", 12343));
-  personnel_list.push_back(personnel_record("Wilma", 62454));
-  personnel_list.push_back(personnel_record("Betty", 20490));
-
-  // Example of using projection_iterator_generator
-  // to print out the names in the personnel list.
-
-  boost::projection_iterator_generator<select_name,
-    std::list<personnel_record>::iterator>::type
-    personnel_first(personnel_list.begin()),
-    personnel_last(personnel_list.end());
-
-  std::copy(personnel_first, personnel_last,
-            std::ostream_iterator<std::string>(std::cout, "\n"));
-  std::cout << std::endl;
-
-  // to be continued...
-
-The output for this part is: -
-Barney
-Fred
-Wilma
-Betty
-
- -

Template Parameters

- - - - - - - - - - - - - - - - - -
ParameterDescription
AdaptableUnaryFunctionThe type of the function object. The argument_type of the -function must match the value type of the base iterator. The function -should return a reference to the function's result_type. -The result_type will be the resulting iterator's value_type. -
BaseIteratorThe iterator type being wrapped.
- -

Model of

- -If the base iterator is a model of Random -Access Iterator then so is the resulting projection iterator. If -the base iterator supports less functionality than this the resulting -projection iterator will also support less functionality. - -

Members

- -The projection iterator type implements the member functions and -operators required of the Random -Access Iterator concept. -In addition it has the following constructor: - -
-projection_iterator_generator::type(const BaseIterator& it,
-                                    const AdaptableUnaryFunction& p = AdaptableUnaryFunction())
-
- -

-

-

- -

The Projection Iterator Pair -Generator

- -Sometimes a mutable/const pair of iterator types is needed, such as -when implementing a container type. The -projection_iterator_pair_generator class makes it more -convenient to create this pair of iterator types. - -
-template <class AdaptableUnaryFunction, class BaseIterator, class ConstBaseIterator>
-class projection_iterator_pair_generator
-{
-public:
-  typedef iterator_adaptor<...> iterator;       // the mutable projection iterator type 
-  typedef iterator_adaptor<...> const_iterator; // the immutable projection iterator type 
-};
-
- -

Example

- -In this part of the example we use the -projection_iterator_pair_generator to create a mutable/const -pair of projection iterators that access the ID numbers of the -personnel. We use the mutable iterator to re-index the ID numbers from -zero. We then use the constant iterator to print the ID numbers out. - -
-  // continuing from the last example...
-
-  typedef boost::projection_iterator_pair_generator<select_ID,
-    std::list<personnel_record>::iterator,
-    std::list<personnel_record>::const_iterator> PairGen;
-
-  PairGen::iterator ID_first(personnel_list.begin()),
-    ID_last(personnel_list.end());
-
-  int new_id = 0;
-  while (ID_first != ID_last) {
-    *ID_first = new_id++;
-    ++ID_first;
-  }
-
-  PairGen::const_iterator const_ID_first(personnel_list.begin()),
-    const_ID_last(personnel_list.end());
-
-  std::copy(const_ID_first, const_ID_last,
-            std::ostream_iterator<int>(std::cout, " "));
-  std::cout << std::endl;
-  std::cout << std::endl;
-  
-  // to be continued...
-
-0 1 2 3 
-
- -

Template Parameters

- - - - - - - - - - - - - - - - - - - - - - - -
ParameterDescription
AdaptableUnaryFunctionThe type of the function object. The argument_type of the -function must match the value type of the base iterator. The function -should return a true reference to the function's result_type. -The result_type will be the resulting iterator's value_type. -
BaseIteratorThe mutable iterator type being wrapped.
ConstBaseIteratorThe constant iterator type being wrapped.
- -

Model of

- -If the base iterator types model the Random -Access Iterator then so do the resulting projection iterator -types. If the base iterators support less functionality the -resulting projection iterator types will also support less -functionality. The resulting iterator type is mutable, and -the resulting const_iterator type is constant. - -

Members

- -The resulting iterator and const_iterator types -implements the member functions and operators required of the Random -Access Iterator concept. In addition they support the following -constructors: - -
-projection_iterator_pair_generator::iterator(const BaseIterator& it,
-                                             const AdaptableUnaryFunction& p = AdaptableUnaryFunction())
- -
-projection_iterator_pair_generator::const_iterator(const BaseIterator& it,
-                                                   const AdaptableUnaryFunction& p = AdaptableUnaryFunction())
-
- -

-

-

- -

The Projection Iterator Object Generators

- -The make_projection_iterator() and -make_const_projection_iterator() functions provide a more -convenient way to create projection iterator objects. The functions -save the user the trouble of explicitly writing out the iterator -types. - -
-template <class AdaptableUnaryFunction, class BaseIterator>
-typename projection_iterator_generator<AdaptableUnaryFunction, BaseIterator>::type
-make_projection_iterator(BaseIterator base,
-			 const AdaptableUnaryFunction& p = AdaptableUnaryFunction())  
-
-template <class AdaptableUnaryFunction, class ConstBaseIterator>
-typename projection_iterator_generator<AdaptableUnaryFunction, ConstBaseIterator>::type
-make_const_projection_iterator(ConstBaseIterator base,
-			       const AdaptableUnaryFunction& p = AdaptableUnaryFunction())  
-
- - -

Example

- -In this part of the example, we again print out the names of the -personnel, but this time we use the -make_const_projection_iterator() function to save some typing. - -
-  // continuing from the last example...
-
-  std::copy
-    (boost::make_const_projection_iterator<select_name>(personnel_list.begin()),
-     boost::make_const_projection_iterator<select_name>(personnel_list.end()),
-     std::ostream_iterator(std::cout, "\n"));
-
-  return 0;
-}
-
-The output is: -
-Barney
-Fred
-Wilma
-Betty
-
- -
-

Revised 19 Aug 2001

-

© Copyright Jeremy Siek 2000. Permission to copy, use, -modify, sell and distribute this document is granted provided this copyright -notice appears in all copies. This document is provided "as is" -without express or implied warranty, and with no claim as to its suitability for -any purpose.

- - - - - - - - diff --git a/reverse_iterator.htm b/reverse_iterator.htm deleted file mode 100644 index d20735f..0000000 --- a/reverse_iterator.htm +++ /dev/null @@ -1,331 +0,0 @@ - - - - - - - - - - Reverse Iterator Adaptor Documentation - - - - c++boost.gif (8819 bytes) - -

Reverse Iterator Adaptor

- Defined in header boost/iterator_adaptors.hpp - -

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. The Boost - reverse iterator adaptor is better to use than the - std::reverse_iterator class in situations where pairs of - mutable/constant iterators are needed (e.g., in containers) because - comparisons and conversions between the mutable and const versions are - implemented correctly. - -

Synopsis

-
-namespace boost {
-  template <class BidirectionalIterator,
-            class Value, class Reference, class Pointer, class Category, class Distance>
-  struct reverse_iterator_generator;
-  
-  template <class BidirectionalIterator>
-  typename reverse_iterator_generator<BidirectionalIterator>::type
-  make_reverse_iterator(BidirectionalIterator base)  
-}
-
-
- -

The Reverse Iterator Type - Generator

- The reverse_iterator_generator template is a generator of - reverse iterator types. The main template parameter for this class is the - base BidirectionalIterator type that is being adapted. In most - cases the associated types of the base iterator can be deduced using - std::iterator_traits, but in some situations the user may want to - override these types, so there are also template parameters for the base - iterator's associated types. - -
-
-template <class BidirectionalIterator,
-          class Value, class Reference, class Pointer, class Category, class Distance>
-class reverse_iterator_generator
-{
-public:
-  typedef iterator_adaptor<...> type; // the resulting reverse iterator type 
-};
-
-
- -

Example

- In this example we sort a sequence of letters and then output the sequence - in descending order using reverse iterators. - -
-
-#include <boost/config.hpp>
-#include <iostream>
-#include <algorithm>
-#include <boost/iterator_adaptors.hpp>
-
-int main(int, char*[])
-{
-  char letters[] = "hello world!";
-  const int N = sizeof(letters)/sizeof(char) - 1;
-  std::cout << "original sequence of letters:\t"
-      << letters << std::endl;
-
-  std::sort(letters, letters + N);
-
-  // Use reverse_iterator_generator to print a sequence
-  // of letters in reverse order.
-  
-  boost::reverse_iterator_generator<char*>::type
-    reverse_letters_first(letters + N),
-    reverse_letters_last(letters);
-
-  std::cout << "letters in descending order:\t";
-  std::copy(reverse_letters_first, reverse_letters_last,
-      std::ostream_iterator<char>(std::cout));
-  std::cout << std::endl;
-
-  // to be continued...
-
-
- The output is: - -
-
-original sequence of letters: hello world!
-letters in descending order:  wroolllhed! 
-
-
- -

Template Parameters

- - - - - - - - - -
Parameter - - Description - -
BidirectionalIterator - - - The iterator type being wrapped. - -
Value - - The value-type of the base iterator and the resulting reverse - iterator.
- Default:std::iterator_traits<BidirectionalIterator>::value_type - - -
Reference - - The reference type of the resulting iterator, and in - particular, the result type of operator*().
- Default: If Value is supplied, Value& is - used. Otherwise - std::iterator_traits<BidirectionalIterator>::reference - is used. - -
Pointer - - The pointer type of the resulting iterator, and in - particular, the result type of operator->().
- Default: If Value was supplied, then Value*, - otherwise - std::iterator_traits<BidirectionalIterator>::pointer. - -
Category - - The iterator_category type for the resulting iterator.
- Default: - std::iterator_traits<BidirectionalIterator>::iterator_category - - -
Distance - - The difference_type for the resulting iterator.
- Default: - std::iterator_traits<BidirectionalIterator&gt::difference_type - -
- -

Concept Model

- The indirect iterator will model whichever standard iterator concept - category is modeled by the base iterator. Thus, if the base iterator is - a model of Random Access - Iterator then so is the resulting indirect iterator. If the base - iterator models a more restrictive concept, the resulting indirect iterator - will model the same concept. The base iterator must be at least a Bidirectional - Iterator - -

Members

- The reverse iterator type implements the member functions and operators - required of the Random Access - Iterator concept. In addition it has the following constructor: - -
-
-reverse_iterator_generator::type(const BidirectionalIterator& it)
-
-
- - -
-
- -
- -

- -

The Reverse Iterator Object - Generator

- The make_reverse_iterator() function provides a more convenient - way to create reverse iterator objects. The function saves the user the - trouble of explicitly writing out the iterator types. - -
-
-template <class BidirectionalIterator>
-typename reverse_iterator_generator<BidirectionalIterator>::type
-make_reverse_iterator(BidirectionalIterator base);
-
-
- -

Example

- In this part of the example we use make_reverse_iterator() to - print the sequence of letters in reverse-reverse order, which is the - original order. - -
-
-  // continuing from the previous example...
-
-  std::cout << "letters in ascending order:\t";
-  std::copy(boost::make_reverse_iterator(reverse_letters_last),
-      boost::make_reverse_iterator(reverse_letters_first),
-      std::ostream_iterator<char>(std::cout));
-  std::cout << std::endl;
-
-  return 0;
-}
-
-
- The output is: - -
-
-letters in ascending order:  !dehllloorw
-
-
-
- -

Constant/Mutable Iterator Interactions

- -

One failing of the standard reverse_iterator - adaptor is that it doesn't properly support interactions between adapted - const and non-const iterators. For example: -

-
-#include <vector>
-
-template <class T> void convert(T x) {}
-
-// Test interactions of a matched pair of random access iterators
-template <class Iterator, class ConstIterator>
-void test_interactions(Iterator i, ConstIterator ci)
-{
-  bool eq = i == ci;               // comparisons
-  bool ne = i != ci;            
-  bool lt = i < ci;
-  bool le = i <= ci;
-  bool gt = i > ci;
-  bool ge = i >= ci;
-  std::size_t distance = i - ci;   // difference
-  ci = i;                          // assignment
-  ConstIterator ci2(i);            // construction
-  convert<ConstIterator>(i);       // implicit conversion
-}
-
-void f()
-{
-  typedef std::vector<int> vec;
-  vec v;
-  const vec& cv;
-
-  test_interactions(v.begin(), cv.begin());   // OK
-  test_interactions(v.rbegin(), cv.rbegin()); // ERRORS ON EVERY TEST!!
-
-
-Reverse iterators created with boost::reverse_iterator_generator don't have this problem, though: -
-
-  typedef boost::reverse_iterator_generator<vec::iterator>::type ri;
-  typedef boost::reverse_iterator_generator<vec::const_iterator>::type cri;
-  test_interactions(ri(v.begin()), cri(cv.begin()));   // OK!!
-
-
-Or, more simply, -
-
-  test_interactions(
-    boost::make_reverse_iterator(v.begin()), 
-    boost::make_reverse_iterator(cv.begin()));   // OK!!
-}
-
-
- -

If you are wondering why there is no -reverse_iterator_pair_generator in the manner of projection_iterator_pair_generator, -the answer is simple: we tried it, but found that in practice it took -more typing to use reverse_iterator_pair_generator than to -simply use reverse_iterator_generator twice!

- -

- - -

Revised - 19 Aug 2001 - - -

© Copyright Jeremy Siek 2000. Permission to copy, use, modify, sell - and distribute this document is granted provided this copyright notice - appears in all copies. This document is provided "as is" without express or - implied warranty, and with no claim as to its suitability for any purpose. - - - - - - - diff --git a/transform_iterator.htm b/transform_iterator.htm deleted file mode 100644 index 4b3dce3..0000000 --- a/transform_iterator.htm +++ /dev/null @@ -1,223 +0,0 @@ - - - - - - -Transform Iterator Adaptor Documentation - - - - -c++boost.gif (8819 bytes) - -

Transform Iterator Adaptor

- -Defined in header -boost/iterator_adaptors.hpp - -

-The transform iterator adaptor augments 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. The following -pseudo-code shows the basic idea: - -

-  value_type transform_iterator::operator*() const {
-    return this->f(*this->base_iterator);
-  }
-
- -All of the other operators of the transform iterator behave in the -same fashion as those of the base iterator. - - -

Synopsis

- -
-namespace boost {
-  template <class AdaptableUnaryFunction, class BaseIterator>
-  class transform_iterator_generator;
-
-  template <class AdaptableUnaryFunction, class BaseIterator>
-  typename transform_iterator_generator<AdaptableUnaryFunction,Iterator>::type
-  make_transform_iterator(BaseIterator base, const AdaptableUnaryFunction& f = AdaptableUnaryFunction());
-}
-
- -
- -

The Transform Iterator Type -Generator

- -The class transform_iterator_generator is a helper class whose -purpose is to construct a transform iterator type. The template -parameters for this class are the AdaptableUnaryFunction function object -type and the BaseIterator type that is being wrapped. - -
-template <class AdaptableUnaryFunction, class Iterator>
-class transform_iterator_generator
-{
-public:
-    typedef iterator_adaptor<...> type;
-};
-
- -

Example

- -

-The following is an example of how to use the -transform_iterator_generator class to iterate through a range -of numbers, multiplying each of them by 2 when they are dereferenced. -The boost::binder1st class is used instead of the standard -one because tranform iterator requires the function object to be -Default Constructible. - -

-

-#include <functional>
-#include <iostream>
-#include <boost/iterator_adaptors.hpp>
-
-// definition of class boost::binder1st and function boost::bind1st() ...
-
-int
-main(int, char*[])
-{
-  int x[] = { 1, 2, 3, 4, 5, 6, 7, 8 };
-
-  typedef boost::binder1st< std::multiplies<int> > Function;
-  typedef boost::transform_iterator_generator<Function, int*>::type doubling_iterator;
-
-  doubling_iterator i(x, boost::bind1st(std::multiplies<int>(), 2)),
-    i_end(x + sizeof(x)/sizeof(int), boost::bind1st(std::multiplies<int>(), 2));
-
-  std::cout << "multiplying the array by 2:" << std::endl;
-  while (i != i_end)
-    std::cout << *i++ << " ";
-  std::cout << std::endl;
-
-  // to be continued...
-
-The output from this part is: -
-2 4 6 8 10 12 14 16
-
- -

Template Parameters

- - - - - - - - - - - - - - - - -
ParameterDescription
AdaptableUnaryFunctionThe function object that transforms each element in the iterator -range. The argument_type of the function object must match -the value type of the base iterator. The result_type of the -function object will be the resulting iterator's -value_type. If you want the resulting iterator to behave as -an iterator, the result of the function should be solely a function of -its argument. Also, the function object must be Default -Constructible (which many of the standard function objects are not).
BaseIteratorThe iterator type being wrapped. This type must at least be a model - of the InputIterator concept.
- -

Model of

- -The transform iterator adaptor (the type -transform_iterator_generator<...>::type) is a model of Input Iterator[1]. - - -

Members

- -The transform iterator type implements the member functions and -operators required of the Random Access Iterator -concept, except that the reference type is the same as the value_type -so operator*() returns by-value. In addition it has the following constructor: - -
-transform_iterator_generator::type(const BaseIterator& it,
-                                   const AdaptableUnaryFunction& f = AdaptableUnaryFunction())
-
- -

-

-

- - -

The Transform Iterator Object Generator

- -
-template <class AdaptableUnaryFunction, class BaseIterator>
-typename transform_iterator_generator<AdaptableUnaryFunction,BaseIterator>::type
-make_transform_iterator(BaseIterator base,
-                        const AdaptableUnaryFunction& f = AdaptableUnaryFunction());
-
- -This function provides a convenient way to create transform iterators. - -

Example

- -Continuing from the previous example, we use the make_transform_iterator() -function to add four to each element of the array. - -
-  std::cout << "adding 4 to each element in the array:" << std::endl;
-
-  std::copy(boost::make_transform_iterator(x, boost::bind1st(std::plus(), 4)),
-	    boost::make_transform_iterator(x + N, boost::bind1st(std::plus(), 4)),
-	    std::ostream_iterator(std::cout, " "));
-  std::cout << std::endl;
-
-  return 0;
-}
-
-The output from this part is: -
-5 6 7 8 9 10 11 12
-
- -

Notes

- - -[1] If the base iterator is a model of Random Access Iterator -then the transform iterator will also suppport most of the -functionality required by the Random Access Iterator concept. However, a -transform iterator can never completely satisfy the requirements for -Forward Iterator -(or of any concepts that refine Forward Iterator, which includes -Random Access Iterator and Bidirectional Iterator) since the operator* of the transform -iterator always returns by-value. - - - -
-

Revised 19 Aug 2001

-

© Copyright Jeremy Siek 2000. Permission to copy, use, -modify, sell and distribute this document is granted provided this copyright -notice appears in all copies. This document is provided "as is" -without express or implied warranty, and with no claim as to its suitability for -any purpose.

- - - -