Standard Template Library Programmer's Guide

iter_swap , swap_ranges

Category: algorithms

Component type: function

template

inline void iter_swap(ForwardIterator1 a, ForwardIterator2 b);

Equivalent to swap(*a, *b) . [1]

Declared in algo.h. The implementation is in algobase.h.

• ForwardIterator1 and ForwardIterator2 are models of Forward Iterator.

• ForwardIterator1 and ForwardIterator2 are mutable.

• ForwardIterator1 and ForwardIterator2 have the same value type.

• ForwardIterator1 and ForwardIterator2 are dereferenceable.

See swap for a discussion.

int x = 1;

int y = 2;

assert(x == 1 && y == 2);

iter_swap(&x, &y);

assert(x == 2 && y == 1);

[1] Strictly speaking, iter_swap is redundant. It exists only for technical reasons: in some circumstances, some compilers have difficulty performing the type deduction required to interpret swap(*a, *b) .

swap , swap_ranges

Category: algorithms

Component type: function

template

ForwardIterator2 swap_ranges(ForwardIterator1 first1, ForwardIterator1 last1, ForwardIterator2 first2);

Swap_ranges swaps each of the elements in the range [first1, last1) with the corresponding element in the range [first2, first2 + (last1 – first1)) . That is, for each integer n such that 0 <= n < (last1 – first1) , it swaps *(first1 + n) and *(first2 + n) . The return value is first2 + (last1 – first1) .

Defined in the standard header algorithm, and in the nonstandard backward-compatibility header algo.h.

ForwardIterator1 and ForwardIterator2 must both be models of Forward Iterator. The value types of ForwardIterator1 and ForwardIterator2 must be convertible to each other.

• [first1, last1) is a valid range.

• [first2, first2 + (last1 – first1)) is a valid range.

• The two ranges [first1, last1) and [first2, first2 + (last1 – first1)) do not overlap.

Linear. Exactly last1 – first1 swaps are performed.

vector V1, V2;

V1.push_back(1);

V1.push_back(2);

V2.push_back(3);

V2.push_back(4);

assert(V1[0] == 1 && V1[1] == 2 && V2[0] == 3 && V2[1] == 4);

swap_ranges(V1.begin(), V1.end(), V2.begin());

assert(V1[0] == 3 && V1[1] == 4 && V2[0] == 1 && V2[1] == 2);

swap , iter_swap .

Category: algorithms

Component type: function

Transform is an overloaded name; there are actually two transform functions.

template

OutputIterator transform(InputIterator first, InputIterator last, OutputIterator result, UnaryFunction op);

template

OutputIterator transform(InputIterator1 first1, InputIterator1 last1, InputIterator2 first2, OutputIterator result, BinaryFunction binary_op);

Transform performs an operation on objects; there are two versions of transform , one of which uses a single range of Input Iterators and one of which uses two ranges of Input Iterators.

The first version of transform performs the operation op(*i) for each iterator i in the range [first, last) , and assigns the result of that operation to *o , where o is the corresponding output iterator. That is, for each n such that 0 <= n < last – first , it performs the assignment *(result + n) = op(*(first + n)) . The return value is result + (last – first) .

The second version of transform is very similar, except that it uses a Binary Function instead of a Unary Function: it performs the operation op(*i1, *i2) for each iterator i1 in the range [first1, last1) and assigns the result to *o , where i2 is the corresponding iterator in the second input range and where o is the corresponding output iterator. That is, for each n such that 0 <= n < last1 – first1 , it performs the assignment *(result + n) = op(*(first1 + n), *(first2 + n) . The return value is result + (last1 – first1) .

Note that transform may be used to modify a sequence "in place": it is permissible for the iterators first and result to be the same. [1]

Defined in the standard header algorithm, and in the nonstandard backward-compatibility header algo.h.

For the first (unary) version:

• InputIterator must be a model of Input Iterator.

• OutputIterator must be a model of Output Iterator.

• UnaryFunction must be a model of Unary Function.

• InputIterator 's value type must be convertible to UnaryFunction 's argument type.

• UnaryFunction 's result type must be convertible to a type in OutputIterator 's set of value types.

For the second (binary) version:

• InputIterator1 and InputIterator2 must be models of Input Iterator.

• OutputIterator must be a model of Output Iterator.

• BinaryFunction must be a model of Binary Function.

• InputIterator1 's and InputIterator2 's value types must be convertible, respectively, to BinaryFunction 's first and second argument types.

• UnaryFunction 's result type must be convertible to a type in OutputIterator 's set of value types.

For the first (unary) version:

• [first, last) is a valid range.

• result is not an iterator within the range [first+1, last) . [1]

• There is enough space to hold all of the elements being copied. More formally, the requirement is that [result, result + (last – first)) is a valid range.