Standard Template Library Programmer's Guide

[2] Note that this is not necessarily the information you are interested in! Usually, if you're testing whether an element is present in a range, you'd like to know where it is (if it's present), or where it should be inserted (if it's not present). The functions lower_bound , upper_bound , and equal_range provide this information.

[3] This difference between Random Access Iterators and Forward Iterators is simply because advance is constant time for Random Access Iterators and linear time for Forward Iterators.

lower_bound , upper_bound , equal_range

Category: algorithms

Component type: function

Merge is an overloaded name: there are actually two merge functions.

template

OutputIterator merge(InputIterator1 first1, InputIterator1 last1, InputIterator2 first2, InputIterator2 last2, OutputIterator result);

template

OutputIterator merge(InputIterator1 first1, InputIterator1 last1, InputIterator2 first2, InputIterator2 last2, OutputIterator result, StrictWeakOrdering comp);

Merge combines two sorted ranges [first1, last1) and [first2, last2) into a single sorted range. That is, it copies elements from [first1, last1) and [first2, last2) into [result, result + (last1 – first1) + (last2 – first2)) such that the resulting range is in ascending order. 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 return value is result + (last1 – first1) + (last2 – first2) .

The two versions of 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 .

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

For the first version:

• InputIterator1 is a model of Input Iterator.

• InputIterator2 is a model of Input Iterator.

• InputIterator1 's value type is the same type as InputIterator2 's value type.

• InputIterator1 's value type is a model of LessThan Comparable.

• The ordering on objects of InputIterator1 's value type is a strict weak ordering , as defined in the LessThan Comparable requirements.

• InputIterator1 's value type is convertible to a type in OutputIterator 's set of value types.

For the second version:

• InputIterator1 is a model of Input Iterator.

• InputIterator2 is a model of Input Iterator.

• InputIterator1 's value type is the same type as InputIterator2 's value type.

• StrictWeakOrdering is a model of Strict Weak Ordering.

• InputIterator1 's value type is convertible to StrictWeakOrdering 's argument type.

• InputIterator1 's value type is convertible to a type in OutputIterator 's set of value types.

For the first version:

• [first1, last1) is a valid range.

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

• [first2, last2) is a valid range.

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

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

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

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

For the second version:

• [first1, last1) is a valid range.

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

• [first2, last2) is a valid range.

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

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

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

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

Linear. No comparisons if both [first1, last1) and [first2, last2) are empty ranges, otherwise at most (last1 – first1) + (last2 – first2) – 1 comparisons.

int main() {

int A1[] = { 1, 3, 5, 7 };

int A2[] = { 2, 4, 6, 8 };

const int N1 = sizeof(A1) / sizeof(int);

const int N2 = sizeof(A2) / sizeof(int);

merge(A1, A1 + N1, A2, A2 + N2, ostream_iterator(cout, " "));

// The output is "1 2 3 4 5 6 7 8"

}

[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 more complete 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.