forked from boostorg/iterator
217 lines
6.3 KiB
Plaintext
217 lines
6.3 KiB
Plaintext
|
|
[section:transform Transform Iterator]
|
|
|
|
The transform iterator adapts an iterator by modifying the
|
|
`operator*` to apply a function object to the result of
|
|
dereferencing the iterator and returning the result.
|
|
|
|
|
|
[h2 Example]
|
|
|
|
|
|
This is a simple example of using the transform_iterators class to
|
|
generate iterators that multiply (or add to) the value returned by
|
|
dereferencing the iterator. It would be cooler to use lambda library
|
|
in this example.
|
|
|
|
int x[] = { 1, 2, 3, 4, 5, 6, 7, 8 };
|
|
const int N = sizeof(x)/sizeof(int);
|
|
|
|
typedef boost::binder1st< std::multiplies<int> > Function;
|
|
typedef boost::transform_iterator<Function, int*> doubling_iterator;
|
|
|
|
doubling_iterator i(x, boost::bind1st(std::multiplies<int>(), 2)),
|
|
i_end(x + N, 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;
|
|
|
|
std::cout << "adding 4 to each element in the array:" << std::endl;
|
|
std::copy(boost::make_transform_iterator(x, boost::bind1st(std::plus<int>(), 4)),
|
|
boost::make_transform_iterator(x + N, boost::bind1st(std::plus<int>(), 4)),
|
|
std::ostream_iterator<int>(std::cout, " "));
|
|
std::cout << std::endl;
|
|
|
|
|
|
The output is:
|
|
|
|
multiplying the array by 2:
|
|
2 4 6 8 10 12 14 16
|
|
adding 4 to each element in the array:
|
|
5 6 7 8 9 10 11 12
|
|
|
|
|
|
The source code for this example can be found
|
|
[@../example/transform_iterator_example.cpp here].
|
|
|
|
[h2 Reference]
|
|
|
|
|
|
[h3 Synopsis]
|
|
|
|
template <class UnaryFunction,
|
|
class Iterator,
|
|
class Reference = use_default,
|
|
class Value = use_default>
|
|
class transform_iterator
|
|
{
|
|
public:
|
|
typedef /* see below */ value_type;
|
|
typedef /* see below */ reference;
|
|
typedef /* see below */ pointer;
|
|
typedef iterator_traits<Iterator>::difference_type difference_type;
|
|
typedef /* see below */ iterator_category;
|
|
|
|
transform_iterator();
|
|
transform_iterator(Iterator const& x, UnaryFunction f);
|
|
|
|
template<class F2, class I2, class R2, class V2>
|
|
transform_iterator(
|
|
transform_iterator<F2, I2, R2, V2> const& t
|
|
, typename enable_if_convertible<I2, Iterator>::type* = 0 // exposition only
|
|
, typename enable_if_convertible<F2, UnaryFunction>::type* = 0 // exposition only
|
|
);
|
|
UnaryFunction functor() const;
|
|
Iterator const& base() const;
|
|
reference operator*() const;
|
|
transform_iterator& operator++();
|
|
transform_iterator& operator--();
|
|
private:
|
|
Iterator m_iterator; // exposition only
|
|
UnaryFunction m_f; // exposition only
|
|
};
|
|
|
|
|
|
If `Reference` is `use_default` then the `reference` member of
|
|
`transform_iterator` is[br]
|
|
`result_of<UnaryFunction(iterator_traits<Iterator>::reference)>::type`.
|
|
Otherwise, `reference` is `Reference`.
|
|
|
|
|
|
If `Value` is `use_default` then the `value_type` member is
|
|
`remove_cv<remove_reference<reference> >::type`. Otherwise,
|
|
`value_type` is `Value`.
|
|
|
|
|
|
If `Iterator` models Readable Lvalue Iterator and if `Iterator`
|
|
models Random Access Traversal Iterator, then `iterator_category` is
|
|
convertible to `random_access_iterator_tag`. Otherwise, if
|
|
`Iterator` models Bidirectional Traversal Iterator, then
|
|
`iterator_category` is convertible to
|
|
`bidirectional_iterator_tag`. Otherwise `iterator_category` is
|
|
convertible to `forward_iterator_tag`. If `Iterator` does not
|
|
model Readable Lvalue Iterator then `iterator_category` is
|
|
convertible to `input_iterator_tag`.
|
|
|
|
|
|
[h3 Requirements]
|
|
|
|
|
|
The type `UnaryFunction` must be Assignable, Copy Constructible, and
|
|
the expression `f(*i)` must be valid where `f` is an object of
|
|
type `UnaryFunction`, `i` is an object of type `Iterator`, and
|
|
where the type of `f(*i)` must be
|
|
`result_of<UnaryFunction(iterator_traits<Iterator>::reference)>::type`.
|
|
|
|
|
|
The argument `Iterator` shall model Readable Iterator.
|
|
|
|
|
|
[h3 Concepts]
|
|
|
|
|
|
The resulting `transform_iterator` models the most refined of the
|
|
following that is also modeled by `Iterator`.
|
|
|
|
|
|
* Writable Lvalue Iterator if `transform_iterator::reference` is a non-const reference.
|
|
|
|
* Readable Lvalue Iterator if `transform_iterator::reference` is a const reference.
|
|
|
|
* Readable Iterator otherwise.
|
|
|
|
|
|
The `transform_iterator` models the most refined standard traversal
|
|
concept that is modeled by the `Iterator` argument.
|
|
|
|
|
|
If `transform_iterator` is a model of Readable Lvalue Iterator then
|
|
it models the following original iterator concepts depending on what
|
|
the `Iterator` argument models.
|
|
|
|
|
|
[table Category
|
|
[[If `Iterator` models][then `transform_iterator` models]]
|
|
[[Single Pass Iterator][Input Iterator]]
|
|
[[Forward Traversal Iterator][Forward Iterator]]
|
|
[[Bidirectional Traversal Iterator][Bidirectional Iterator]]
|
|
[[Random Access Traversal Iterator][Random Access Iterator]]
|
|
]
|
|
|
|
If `transform_iterator` models Writable Lvalue Iterator then it is a
|
|
mutable iterator (as defined in the old iterator requirements).
|
|
|
|
|
|
`transform_iterator<F1, X, R1, V1>` is interoperable with
|
|
`transform_iterator<F2, Y, R2, V2>` if and only if `X` is
|
|
interoperable with `Y`.
|
|
|
|
[h3 Operations]
|
|
|
|
In addition to the operations required by the [link iterator.specialized.transform.concepts concepts] modeled by
|
|
`transform_iterator`, `transform_iterator` provides the following
|
|
operations:
|
|
|
|
transform_iterator();
|
|
|
|
[*Returns: ] An instance of `transform_iterator` with `m_f`
|
|
and `m_iterator` default constructed.
|
|
|
|
transform_iterator(Iterator const& x, UnaryFunction f);
|
|
|
|
[*Returns: ] An instance of `transform_iterator` with `m_f`
|
|
initialized to `f` and `m_iterator` initialized to `x`.
|
|
|
|
template<class F2, class I2, class R2, class V2>
|
|
transform_iterator(
|
|
transform_iterator<F2, I2, R2, V2> const& t
|
|
, typename enable_if_convertible<I2, Iterator>::type* = 0 // exposition only
|
|
, typename enable_if_convertible<F2, UnaryFunction>::type* = 0 // exposition only
|
|
);
|
|
|
|
[*Returns: ] An instance of `transform_iterator` with `m_f`
|
|
initialized to `t.functor()` and `m_iterator` initialized to
|
|
`t.base()`.[br]
|
|
[*Requires: ] `OtherIterator` is implicitly convertible to `Iterator`.
|
|
|
|
|
|
UnaryFunction functor() const;
|
|
|
|
[*Returns: ] `m_f`
|
|
|
|
|
|
Iterator const& base() const;
|
|
|
|
[*Returns: ] `m_iterator`
|
|
|
|
|
|
reference operator*() const;
|
|
|
|
[*Returns: ] `m_f(*m_iterator)`
|
|
|
|
|
|
transform_iterator& operator++();
|
|
|
|
[*Effects: ] `++m_iterator`[br]
|
|
[*Returns: ] `*this`
|
|
|
|
|
|
transform_iterator& operator--();
|
|
|
|
[*Effects: ] `--m_iterator`[br]
|
|
[*Returns: ] `*this`
|
|
|
|
[endsect]
|