From 3d69cf95da510ca21ce794e98a59d459121ba7a8 Mon Sep 17 00:00:00 2001 From: Toon Knapen Date: Fri, 30 Nov 2001 10:40:03 +0000 Subject: [PATCH] added documentation for the permutation_iterator_adaptor and linked to it from the iterator_adaptors documentation. [SVN r11824] --- iterator_adaptors.htm | 4 + permutation_iterator.htm | 159 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 163 insertions(+) create mode 100644 permutation_iterator.htm diff --git a/iterator_adaptors.htm b/iterator_adaptors.htm index af3211b..7db55cc 100644 --- a/iterator_adaptors.htm +++ b/iterator_adaptors.htm @@ -124,6 +124,8 @@ Function Output Iterator Adaptor
  • Header boost/generator_iterator.hpp
    Generator Iterator Adaptor +
  • Header boost/permutation_iterator.hpp
    + Permutation Iterator Adaptor

    Dave @@ -150,6 +152,8 @@ Jens Maurer contributed the generator iterator adaptor.
    + Toon Knapen contributed the permutation + iterator adaptor.

    Class template iterator_adaptor

    diff --git a/permutation_iterator.htm b/permutation_iterator.htm new file mode 100644 index 0000000..fc19d23 --- /dev/null +++ b/permutation_iterator.htm @@ -0,0 +1,159 @@ + + + + +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 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

    + + + + + + + + + + + + + + +. +The IndexIterator::value_type must be convertible to the +ElementIterator::difference_type. +
    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
    + +

    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 OrderIterator. Thus for instance, although the permutation +iterator provides operator+=(distance), this operation will take linear time +in case the OrderIterator 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& order);
+
    +
    + +

    Example

    +
    +
    +  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 );
+  std::iota( elements.begin(), elements.end(), 0 );
+
+  index_type indices( index_size );
+  std::iota( indices.begin(), indices.end(), element_range_size - index_size );
+  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.setf( std::ios_base::left );
+  std::cout << std::setw( 50 ) << "The original range is : ";
+  std::copy( elements.begin(), elements.end(), std::ostream_iterator< int >( std::cout, " " ) );
+  std::cout << "\n";
+
+  std::cout << std::setw( 50 ) << "The reindexing scheme is : ";
+  std::copy( indices.begin(), indices.end(), std::ostream_iterator< int >( std::cout, " " ) );
+  std::cout << "\n";
+
+  std::cout << std::setw( 50 ) << "The permutated range is : ";
+  std::copy( begin, end, std::ostream_iterator< int >( std::cout, " " ) );
+  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. + + +