A.2.4. Algorithms That Write Container Elements

Many algorithms write new values to the elements in the given sequence. These algorithms can be distinguished from one another both by the kinds of iterators they use to denote their input sequence and by whether they write elements in the input range or write to a given destination.

Algorithms That Write but Do Not Read Elements

These algorithms require an output iterator that denotes a destination. The _n versions take a second argument that specifies a count and write the given number of elements to the destination.

fill(beg, end, val)
fill_n(dest, cnt, val)
generate(beg, end, Gen)
generate_n(dest, cnt, Gen)

Assigns a new value to each element in the input sequence. fill assigns the value val; generate executes the generator object Gen(). A generator is a callable object (§ 10.3.2, p. 388) that is expected to produce a different return value each time it is called. fill and generate return void. The _n versions return an iterator that refers to the position immediately following the last element written to the output sequence.

Write Algorithms with Input Iterators

Each of these algorithms reads an input sequence and writes to an output sequence. They require dest to be an output iterator, and the iterators denoting the input range must be input iterators.

copy(beg, end, dest)
copy_if(beg, end, dest, unaryPred)
copy_n(beg, n, dest)

Copies from the input range to the sequence denoted by dest. copy copies all elements, copy_if copies those for which unaryPred succeeds, and copy_n copies the first n elements. The input sequence must have at least n elements.

move(beg, end, dest)

Calls std::move (§ 13.6.1, p. 533) on each element in the input sequence to move that element to the sequence beginning at iterator dest.

transform(beg, end, dest, unaryOp)
transform(beg, end, beg2, dest, binaryOp)

Calls the given operation and writes the result of that operation to dest. The first version applies a unary operation to each element in the input range. The second applies a binary operation to elements from the two input sequences.

replace_copy(beg, end, dest, old_val, new_val)
replace_copy_if(beg, end, dest, unaryPred, new_val)

Copies each element to dest, replacing the specified elements with new_val. The first version replaces those elements that are == old_val. The second version replaces those elements for which unaryPred succeeds.

merge(beg1, end1, beg2, end2, dest)
merge(beg1, end1, beg2, end2, dest, comp)

Both input sequences must be sorted. Writes a merged sequence to dest. The first version compares elements using the < operator; the second version uses the given comparison operation.

Write Algorithms with Forward Iterators

These algorithms require forward iterators because they write to elements in their input sequence. The iterators must give write access to the elements.

iter_swap(iter1, iter2)
swap_ranges(beg1, end1, beg2)

Swaps the element denoted by iter1 with the one denoted by iter2; or swaps all of the elements in the input range with those in the second sequence beginning at beg2. The ranges must not overlap. iter_swap returns void; swap_ranges returns beg2 incremented to denote the element just after the last one swapped.

replace(beg, end, old_val, new_val)
replace_if(beg, end, unaryPred, new_val)

Replaces each matching element with new_val. The first version uses == to compare elements with old_val; the second version replaces those elements for which unaryPred succeeds.

Write Algorithms with Bidirectional Iterators

These algorithms require the ability to go backward in the sequence, so they require bidirectional iterators.

copy_backward(beg, end, dest)
move_backward(beg, end, dest)

Copies or moves elements from the input range to the given destination. Unlike other algorithms, dest is the off-the-end iterator for the output sequence (i.e., the destination sequence will end immediately before dest). The last element in the input range is copied or moved to the last element in the destination, then the second-to-last element is copied/moved, and so on. Elements in the destination have the same order as those in the input range. If the range is empty, the return value is dest; otherwise, the return denotes the element that was copied or moved from *beg.

inplace_merge(beg, mid, end)
inplace_merge(beg, mid, end, comp)

Merges two sorted subsequences from the same sequence into a single, ordered sequence. The subsequences from beg to mid and from mid to end are merged and written back into the original sequence. The first version uses < to compare elements; the second version uses a given comparison operation. Returns void.