ceph/src/boost/libs/range/doc/reference/algorithm/transform.qbk

   1 [/
   2     Copyright 2010 Neil Groves
   3     Distributed under the Boost Software License, Version 1.0.
   4     (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   5 /]
   6 [section:transform transform]
   7
   8 [heading Prototype]
   9
  10 ``
  11 template<
  12     class SinglePassRange1,
  13     class OutputIterator,
  14     class UnaryOperation
  15 >
  16 OutputIterator transform(const SinglePassRange1& rng,
  17                          OutputIterator out,
  18                          UnaryOperation fun);
  19
  20 template<
  21     class SinglePassRange1,
  22     class SinglePassRange2,
  23     class OutputIterator,
  24     class BinaryOperation
  25 >
  26 OutputIterator transform(const SinglePassRange1& rng1,
  27                          const SinglePassRange2& rng2,
  28                          OutputIterator out,
  29                          BinaryOperation fun);
  30 ``
  31
  32 [heading Description]
  33
  34 [*UnaryOperation version:]
  35
  36 `transform` assigns the value `y` to each element `[out, out + distance(rng)), y = fun(x)` where `x` is the corresponding value to `y` in `rng1`. The return value is `out + distance(rng)`.
  37
  38 [*BinaryOperation version:]
  39
  40 `transform` assigns the value `z` to each element `[out, out + min(distance(rng1), distance(rng2))), z = fun(x,y)` where `x` is the corresponding value in `rng1` and `y` is the corresponding value in `rng2`. This version of `transform` stops upon reaching either the end of `rng1`, or the end of `rng2`. Hence there isn't a requirement for `distance(rng1) == distance(rng2)` since there is a safe guaranteed behaviour, unlike with the iterator counterpart in the standard library.
  41
  42 The return value is `out + min(distance(rng1), distance(rng2))`.
  43
  44 [heading Definition]
  45
  46 Defined in the header file `boost/range/algorithm/transform.hpp`
  47
  48 [heading Requirements]
  49
  50 [*For the unary versions of transform:]
  51
  52 * `SinglePassRange1` is a model of the __single_pass_range__ Concept.
  53 * `OutputIterator` is a model of the `OutputIteratorConcept`.
  54 * `UnaryOperation` is a model of the `UnaryFunctionConcept`.
  55 * `SinglePassRange1`'s value type must be convertible to `UnaryFunction`'s argument type.
  56 * `UnaryFunction`'s result type must be convertible to a type in `OutputIterator`'s set of value types.
  57
  58 [*For the binary versions of transform:]
  59
  60 * `SinglePassRange1` is a model of the __single_pass_range__ Concept.
  61 * `SinglePassRange2` is a model of the __single_pass_range__ Concept.
  62 * `OutputIterator` is a model of the `OutputIteratorConcept`.
  63 * `BinaryOperation` is a model of the `BinaryFunctionConcept`.
  64 * `SinglePassRange1`'s value type must be convertible to `BinaryFunction`'s first argument type.
  65 * `SinglePassRange2`'s value type must be convertible to `BinaryFunction`'s second argument type.
  66 * `BinaryOperation`'s result type must be convertible to a type in `OutputIterator`'s set of value types.
  67
  68 [heading Precondition:]
  69
  70 [*For the unary version of transform:]
  71
  72 * `out` is not an iterator within the range `[begin(rng1) + 1, end(rng1))`.
  73 * `[out, out + distance(rng1))` is a valid range.
  74
  75 [*For the binary version of transform:]
  76
  77 * `out` is not an iterator within the range `[begin(rng1) + 1, end(rng1))`.
  78 * `out` is not an iterator within the range `[begin(rng2) + 1, end(rng2))`.
  79 * `[out, out + min(distance(rng1), distance(rng2)))` is a valid range.
  80
  81
  82 [heading Complexity]
  83
  84 Linear. The operation is applied exactly `distance(rng1)` for the unary version and `min(distance(rng1), distance(rng2))` for the binary version.
  85
  86 [endsect]
  87
  88