inplace_merge


Category: algorithms 
Component type: function 
Prototype
Inplace_merge is an overloaded name: there are actually two
inplace_merge functions.
template <class BidirectionalIterator>
inline void inplace_merge(BidirectionalIterator first,
BidirectionalIterator middle,
BidirectionalIterator last);
template <class BidirectionalIterator, class StrictWeakOrdering>
inline void inplace_merge(BidirectionalIterator first,
BidirectionalIterator middle,
BidirectionalIterator last, StrictWeakOrdering comp);
Description
Inplace_merge combines two consecutive sorted ranges [first, middle)
and [middle, last) into a single sorted range [first, last).
That is, it starts with a range [first, last) that consists of
two pieces each of which is in ascending order, and rearranges it
so that the entire range is in ascending order. Inplace_merge is
stable, meaning both that
the relative order of elements within each input range is preserved,
and that for equivalent [1] elements in both input ranges the element
from the first range precedes the element from the second.
The two versions of inplace_merge differ in how elements are compared.
The first version uses operator<. That is, the input ranges and
the output range satisfy the condition that for every pair of
iterators i and j such that i precedes j, *j < *i is false.
The second version uses the function object comp.
That is, the input ranges and the output range satisfy the condition
that for every pair of
iterators i and j such that i precedes j, comp(*j, *i) is false.
Definition
Defined in algo.h.
Requirements on types
For the first version:

BidirectionalIterator is a model of Bidirectional Iterator.

BidirectionalIterator is mutable.

BidirectionalIterator's value type is a model of LessThan Comparable.

The ordering on objects of BidirectionalIterator's value type is a
strict weak ordering, as defined in the LessThan Comparable
requirements.
For the second version:

BidirectionalIterator is a model of Bidirectional Iterator.

BidirectionalIterator is mutable.

StrictWeakOrdering is a model of Strict Weak Ordering.

BidirectionalIterator's value type is convertible to
StrictWeakOrdering's argument type.
Preconditions
For the first version:

[first, middle) is a valid range.

[middle, last) is a valid range.

[first, middle) is in ascending order. That is, for every pair
of iterators i and j in [first, middle) such that i precedes
j, *j < *i is false.

[middle, last) is in ascending order. That is, for every pair
of iterators i and j in [middle, last) such that i precedes
j, *j < *i is false.
For the second version:

[first, middle) is a valid range.

[middle, last) is a valid range.

[first, middle) is in ascending order. That is, for every pair
of iterators i and j in [first, middle) such that i precedes
j, comp(*j, *i) is false.

[middle, last) is in ascending order. That is, for every pair
of iterators i and j in [middle, last) such that i precedes
j, comp(*j, *i) is false.
Complexity
Inplace_merge
is an adaptive algorithm: it attempts to
allocate a temporary memory buffer, and its runtime complexity depends
on how much memory is available.
Inplace_merge performs no comparisons if
[first, last) is an empty range.
Otherwise, worstcase behavior (if no auxiliary memory is available) is
O(N log(N)), where N is last  first,
and best case (if a large enough auxiliary memory buffer is available) is
at most (last  first)  1 comparisons.
Example
int main()
{
int A[] = { 1, 3, 5, 7, 2, 4, 6, 8 };
inplace_merge(A, A + 4, A + 8);
copy(A, A + 8, ostream_iterator<int>(cout, " "));
// The output is "1 2 3 4 5 6 7 8".
}
Notes
[1]
Note that you may use an ordering that is a strict weak ordering
but not a total ordering; that is, there might be values x and y
such that x < y, x > y, and x == y are all false. (See the
LessThan Comparable requirements for a fuller discussion.)
Two elements x and y are equivalent if neither x < y nor
y < x. If you're using a total ordering, however (if you're
using strcmp, for example, or if you're using ordinary arithmetic
comparison on integers), then you can ignore this technical
distinction: for a total ordering, equality and equivalence are
the same.
See also
merge, set_union, sort