# <algorithm> functions

## adjacent_find

Searches for two adjacent elements that are either equal or satisfy a specified condition.

```
template<class ForwardIterator>
ForwardIterator adjacent_find(
ForwardIterator first,
ForwardIterator last);
template<class ForwardIterator , class BinaryPredicate>
ForwardIterator adjacent_find(
ForwardIterator first,
ForwardIterator last,
BinaryPredicate pred);
template<class ExecutionPolicy, class ForwardIterator>
ForwardIterator adjacent_find(
ExecutionPolicy&& exec,
ForwardIterator first,
ForwardIterator last);
template<class ExecutionPolicy, class ForwardIterator, class BinaryPredicate>
ForwardIterator adjacent_find(
ExecutionPolicy&& exec,
ForwardIterator first,
ForwardIterator last,
BinaryPredicate pred);
```

### Parameters

*exec*

The execution policy to use.

*first*

A forward iterator addressing the position of the first element in the range to be searched.

*last*

A forward iterator addressing the position one past the final element in the range to be searched.

*pred*

The binary predicate giving the condition to be satisfied by the values of the adjacent elements in the range being searched.

### Return value

A forward iterator to the first of the adjacent elements that are either equal to each other (in the first version) or that satisfy the condition given by the binary predicate (in the second version), provided that such a pair of elements is found. Otherwise, an iterator pointing to *last* is returned.

### Remarks

The `adjacent_find`

algorithm is a nonmutating sequence algorithm. The range to be searched must be valid; all pointers must be dereferenceable and the last position is reachable from the first by incrementation. The time complexity of the algorithm is linear in the number of elements contained in the range.

The `operator==`

used to determine the match between elements must impose an equivalence relation between its operands.

### Example

```
// alg_adj_fnd.cpp
// compile with: /EHsc
#include <list>
#include <algorithm>
#include <iostream>
// Returns whether second element is twice the first
bool twice (int elem1, int elem2 )
{
return elem1 * 2 == elem2;
}
int main()
{
using namespace std;
list<int> L;
list<int>::iterator Iter;
list<int>::iterator result1, result2;
L.push_back( 50 );
L.push_back( 40 );
L.push_back( 10 );
L.push_back( 20 );
L.push_back( 20 );
cout << "L = ( " ;
for ( Iter = L.begin( ) ; Iter != L.end( ) ; Iter++ )
cout << *Iter << " ";
cout << ")" << endl;
result1 = adjacent_find( L.begin( ), L.end( ) );
if ( result1 == L.end( ) )
cout << "There are not two adjacent elements that are equal."
<< endl;
else
cout << "There are two adjacent elements that are equal.\n"
<< "They have a value of "
<< *( result1 ) << "." << endl;
result2 = adjacent_find( L.begin( ), L.end( ), twice );
if ( result2 == L.end( ) )
cout << "There are not two adjacent elements where the "
<< "second is twice the first." << endl;
else
{
cout << "There are two adjacent elements where "
<< "the second is twice the first.\n"
<< "They have values of " << *(result2++)
<< " & " << *result2 << "." << endl;
}
}
```

```
L = ( 50 40 10 20 20 )
There are two adjacent elements that are equal.
They have a value of 20.
There are two adjacent elements where the second is twice the first.
They have values of 10 & 20.
```

## all_of

Returns **true** when a condition is present at each element in the given range.

```
template<class InputIterator, class UnaryPredicate>
bool all_of(
InputIterator first,
InputIterator last,
UnaryPredicate pred);
template <class ExecutionPolicy, class ForwardIterator, class UnaryPredicate>
bool all_of(
ExecutionPolicy&& exec,
ForwardIterator first,
ForwardIterator last,
UnaryPredicate pred);
```

### Parameters

*exec*

The execution policy to use.

*first*

An input iterator that indicates where to start to check for a condition. The iterator marks where a range of elements starts.

*last*

An input iterator that indicates the end of the range of elements to check for a condition.

*pred*

A condition to test for. This is a user-defined predicate function object that defines the condition to be satisfied by an element being checked. A unary predicate takes a single argument and returns **true** or **false**.

### Return value

Returns **true** if the condition is detected at each element in the indicated range or if the range is empty, and **false** otherwise.

### Remarks

The template function returns **true** only if, for each `N`

in the range `[0, last - first)`

, the predicate `pred(*(first + N))`

is **true**.

### Example

```
// alg_all_of.cpp
// compile with: /EHsc
#include <list>
#include <algorithm>
#include <iostream>
int main()
{
using namespace std;
list<int> li { 50, 40, 10, 20, 20 };
list<int>::iterator iter;
cout << "li = ( ";
for (iter = li.begin(); iter != li.end(); iter++)
cout << *iter << " ";
cout << ")" << endl;
// Check if all elements in li are even.
auto is_even = [](int elem){ return !(elem % 2); };
if (all_of(li.begin(), li.end(), is_even))
cout << "All the elements are even numbers.\n";
else
cout << "Not all the elements are even numbers.\n";
}
```

```
li = ( 50 40 10 20 20 )
All the elements are even numbers.
```

## any_of

Returns **true** when a condition is present at least once in the specified range of elements.

```
template<class InputIterator, class UnaryPredicate>
bool any_of(
InputIterator first,
InputIterator last,
UnaryPredicate pred);
template <class ExecutionPolicy, class ForwardIterator, class UnaryPredicate>
bool any_of(
ExecutionPolicy&& exec,
ForwardIterator first,
ForwardIterator last,
UnaryPredicate pred);
```

### Parameters

*exec*

The execution policy to use.

*first*

An input iterator that indicates where to start checking a range of elements for a condition.

*last*

An input iterator that indicates the end of the range of elements to check for a condition.

*pred*

A condition to test for. This is provided by a user-defined predicate function object. The predicate defines the condition to be satisfied by the element being tested. A unary predicate takes a single argument and returns **true** or **false**.

### Return value

Returns **true** if the condition is detected at least once in the indicated range, **false** if the condition is never detected.

### Remarks

The template function returns **true** only if, for some `N`

in the range

`[0, last - first)`

, the predicate `pred(*(first + N))`

is true.

### Example

```
// alg_any_of.cpp
// compile with: /EHsc
#include <list>
#include <algorithm>
#include <iostream>
int main()
{
using namespace std;
list<int> li { 51, 41, 11, 21, 20 };
cout << "li = ( ";
for (auto const& el : li)
cout << el << " ";
cout << ")" << endl;
// Check if there is an even elememt in li.
auto is_even = [](int const elem){ return !(elem % 2); };
if (any_of(li.begin(), li.end(), is_even))
cout << "There's an even element in li.\n";
else
cout << "There are no even elements in li.\n";
}
```

```
li = ( 51 41 11 21 20 )
There's an even element in li.
```

## binary_search

Tests whether there is an element in a sorted range that is equal to a specified value or that is equivalent to it in a sense specified by a binary predicate.

```
template<class ForwardIterator, class Type>
bool binary_search(
ForwardIterator first,
ForwardIterator last,
const Type& value);
template<class ForwardIterator, class Type, class BinaryPredicate>
bool binary_search(
ForwardIterator first,
ForwardIterator last,
const Type& value,
BinaryPredicate pred);
```

### Parameters

*first*

A forward iterator addressing the position of the first element in the range to be searched.

*last*

A forward iterator addressing the position one past the final element in the range to be searched.

*value*

The value required to be matched by the value of the element or that must satisfy the condition with the element value specified by the binary predicate.

*pred*

User-defined predicate function object that defines sense in which one element is less than another. A binary predicate takes two arguments and returns **true** when satisfied and **false** when not satisfied.

### Return value

**true** if an element is found in the range that is equal or equivalent to the specified value; otherwise, **false**.

### Remarks

The sorted source range referenced must be valid; all pointers must be dereferenceable and, within the sequence, the last position must be reachable from the first by incrementation.

The sorted range must each be arranged as a precondition to the application of the `binary_search`

algorithm in accordance with the same ordering as is to be used by the algorithm to sort the combined ranges.

The source ranges are not modified by `binary_search`

.

The value types of the forward iterators need to be less-than comparable to be ordered, so that, given two elements, it may be determined either that they are equivalent (in the sense that neither is less than the other) or that one is less than the other. This results in an ordering between the nonequivalent elements

The complexity of the algorithm is logarithmic for random-access iterators and linear otherwise, with the number of steps proportional to (`last`

- `first`

).

### Example

```
// alg_bin_srch.cpp
// compile with: /EHsc
#include <list>
#include <vector>
#include <algorithm>
#include <functional> // greater<int>( )
#include <iostream>
// Return whether modulus of elem1 is less than modulus of elem2
bool mod_lesser( int elem1, int elem2 )
{
if (elem1 < 0)
elem1 = - elem1;
if (elem2 < 0)
elem2 = - elem2;
return elem1 < elem2;
}
int main()
{
using namespace std;
list<int> List1;
List1.push_back( 50 );
List1.push_back( 10 );
List1.push_back( 30 );
List1.push_back( 20 );
List1.push_back( 25 );
List1.push_back( 5 );
List1.sort();
cout << "List1 = ( " ;
for ( auto Iter : List1 )
cout << Iter << " ";
cout << ")" << endl;
// default binary search for 10
if ( binary_search(List1.begin(), List1.end(), 10) )
cout << "There is an element in list List1 with a value equal to 10."
<< endl;
else
cout << "There is no element in list List1 with a value equal to 10."
<< endl;
// a binary_search under the binary predicate greater
List1.sort(greater<int>());
if ( binary_search(List1.begin(), List1.end(), 10, greater<int>()) )
cout << "There is an element in list List1 with a value greater than 10 "
<< "under greater than." << endl;
else
cout << "No element in list List1 with a value greater than 10 "
<< "under greater than." << endl;
// a binary_search under the user-defined binary predicate mod_lesser
vector<int> v1;
for ( auto i = -2; i <= 4; ++i )
{
v1.push_back(i);
}
sort(v1.begin(), v1.end(), mod_lesser);
cout << "Ordered using mod_lesser, vector v1 = ( " ;
for ( auto Iter : v1 )
cout << Iter << " ";
cout << ")" << endl;
if ( binary_search(v1.begin(), v1.end(), -3, mod_lesser) )
cout << "There is an element with a value equivalent to -3 "
<< "under mod_lesser." << endl;
else
cout << "There is not an element with a value equivalent to -3 "
<< "under mod_lesser." << endl;
}
```

```
List1 = ( 5 10 20 25 30 50 )
There is an element in list List1 with a value equal to 10.
There is an element in list List1 with a value greater than 10 under greater than.
Ordered using mod_lesser, vector v1 = ( 0 -1 1 -2 2 3 4 )
There is an element with a value equivalent to -3 under mod_lesser.
```

## clamp

Compares a value to an upper and lower bound, and returns a reference to the value if it is between the bounds, or a reference to the upper or lower bound if the value is above or below them, respectively.

```
template<class Type>
constexpr const Type& clamp(
const Type& value,
const Type& lower,
const Type& upper);
template<class Type, class Compare>
constexpr const Type& clamp(
const Type& value,
const Type& lower,
const Type& upper,
Compare pred);
```

### Parameters

*value*

The value to compare to *upper* and *lower*.

*lower*

The lower bound of values to clamp *value* to.

*upper*

The upper bound of values to clamp *value* to.

*pred*

A predicate used to compare *value* to *lower* or *upper*. A comparison predicate takes two arguments and returns **true** if the first is in some sense less than the second, and otherwise, **false**.

### Return value

Returns a reference to *lower* if `value < lower`

, or a reference to *upper* if `upper < value`

. Otherwise, it returns a reference to *value*.

### Remarks

The behavior is undefined if *upper* is less than *lower*.

## copy

Assigns the values of elements from a source range to a destination range, iterating through the source sequence of elements and assigning them new positions in a forward direction.

```
template<class InputIterator, class OutputIterator>
OutputIterator copy(
InputIterator first,
InputIterator last,
OutputIterator destBeg);
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2>
ForwardIterator2 copy(
ExecutionPolicy&& exec,
ForwardIterator1 first,
ForwardIterator1 last,
ForwardIterator2 result);
```

### Parameters

*exec*

The execution policy to use.

*first*

An input iterator addressing the position of the first element in the source range.

*last*

An input iterator addressing the position that is one past the final element in the source range.

*destBeg*

An output iterator addressing the position of the first element in the destination range.

### Return value

An output iterator addressing the position that is one past the final element in the destination range, that is, the iterator addresses `result`

+ (*last* - *first*).

### Remarks

The source range must be valid and there must be sufficient space at the destination to hold all the elements being copied.

Because the algorithm copies the source elements in order beginning with the first element, the destination range can overlap with the source range provided the *last* position of the source range is not contained in the destination range. `copy`

can be used to shift elements to the left but not the right, unless there is no overlap between the source and destination ranges. To shift to the right any number of positions, use the copy_backward algorithm.

The `copy`

algorithm only modifies values pointed to by the iterators, assigning new values to elements in the destination range. It cannot be used to create new elements and cannot insert elements into an empty container directly.

### Example

```
// alg_copy.cpp
// compile with: /EHsc
#include <vector>
#include <algorithm>
#include <iostream>
int main() {
using namespace std;
vector<int> v1, v2;
vector<int>::iterator Iter1, Iter2;
int i;
for ( i = 0 ; i <= 5 ; i++ )
v1.push_back( 10 * i );
int ii;
for ( ii = 0 ; ii <= 10 ; ii++ )
v2.push_back( 3 * ii );
cout << "v1 = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")" << endl;
cout << "v2 = ( " ;
for ( Iter2 = v2.begin( ) ; Iter2 != v2.end( ) ; Iter2++ )
cout << *Iter2 << " ";
cout << ")" << endl;
// To copy the first 3 elements of v1 into the middle of v2
copy( v1.begin( ), v1.begin( ) + 3, v2.begin( ) + 4 );
cout << "v2 with v1 insert = ( " ;
for ( Iter2 = v2.begin( ) ; Iter2 != v2.end( ) ; Iter2++ )
cout << *Iter2 << " ";
cout << ")" << endl;
// To shift the elements inserted into v2 two positions
// to the left
copy( v2.begin( )+4, v2.begin( ) + 7, v2.begin( ) + 2 );
cout << "v2 with shifted insert = ( " ;
for ( Iter2 = v2.begin( ) ; Iter2 != v2.end( ) ; Iter2++ )
cout << *Iter2 << " ";
cout << ")" << endl;
}
```

```
v1 = ( 0 10 20 30 40 50 )
v2 = ( 0 3 6 9 12 15 18 21 24 27 30 )
v2 with v1 insert = ( 0 3 6 9 0 10 20 21 24 27 30 )
v2 with shifted insert = ( 0 3 0 10 20 10 20 21 24 27 30 )
```

## copy_backward

Assigns the values of elements from a source range to a destination range, iterating through the source sequence of elements and assigning them new positions in a backward direction.

```
template<class BidirectionalIterator1, class BidirectionalIterator2>
BidirectionalIterator2 copy_backward(
BidirectionalIterator1 first,
BidirectionalIterator1 last,
BidirectionalIterator2 destEnd);
```

### Parameters

*first*

A bidirectional iterator addressing the position of the first element in the source range.

*last*

A bidirectional iterator addressing the position that is one past the final element in the source range.

*destEnd*

A bidirectional iterator addressing the position of one past the final element in the destination range.

### Return value

An output iterator addressing the position that is one past the final element in the destination range, that is, the iterator addresses *destEnd* - (*last* - *first*).

### Remarks

The source range must be valid and there must be sufficient space at the destination to hold all the elements being copied.

The `copy_backward`

algorithm imposes more stringent requirements than that the `copy`

algorithm. Both its input and output iterators must be bidirectional.

The `copy_backward`

and move_backward algorithms are the only C++ Standard Library algorithms designating the output range with an iterator pointing to the end of the destination range.

Because the algorithm copies the source elements in order beginning with the last element, the destination range can overlap with the source range provided the *first* position of the source range is not contained in the destination range. `copy_backward`

can be used to shift elements to the right but not the left, unless there is no overlap between the source and destination ranges. To shift to the left any number of positions, use the copy algorithm.

The `copy_backward`

algorithm only modifies values pointed to by the iterators, assigning new values to elements in the destination range. It cannot be used to create new elements and cannot insert elements into an empty container directly.

### Example

```
// alg_copy_bkwd.cpp
// compile with: /EHsc
#include <vector>
#include <algorithm>
#include <iostream>
int main() {
using namespace std;
vector<int> v1, v2;
vector<int>::iterator Iter1, Iter2;
int i;
for ( i = 0 ; i <= 5 ; ++i )
v1.push_back( 10 * i );
int ii;
for ( ii = 0 ; ii <= 10 ; ++ii )
v2.push_back( 3 * ii );
cout << "v1 = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; ++Iter1 )
cout << *Iter1 << " ";
cout << ")" << endl;
cout << "v2 = ( " ;
for ( Iter2 = v2.begin( ) ; Iter2 != v2.end( ) ; ++Iter2 )
cout << *Iter2 << " ";
cout << ")" << endl;
// To copy_backward the first 3 elements of v1 into the middle of v2
copy_backward( v1.begin( ), v1.begin( ) + 3, v2.begin( ) + 7 );
cout << "v2 with v1 insert = ( " ;
for ( Iter2 = v2.begin( ) ; Iter2 != v2.end( ) ; ++Iter2 )
cout << *Iter2 << " ";
cout << ")" << endl;
// To shift the elements inserted into v2 two positions
// to the right
copy_backward( v2.begin( )+4, v2.begin( ) + 7, v2.begin( ) + 9 );
cout << "v2 with shifted insert = ( " ;
for ( Iter2 = v2.begin( ) ; Iter2 != v2.end( ) ; ++Iter2 )
cout << *Iter2 << " ";
cout << ")" << endl;
}
```

```
v1 = ( 0 10 20 30 40 50 )
v2 = ( 0 3 6 9 12 15 18 21 24 27 30 )
v2 with v1 insert = ( 0 3 6 9 0 10 20 21 24 27 30 )
v2 with shifted insert = ( 0 3 6 9 0 10 0 10 20 27 30 )
```

## copy_if

In a range of elements, copies the elements that are **true** for the specified condition.

```
template<class InputIterator, class OutputIterator, class UnaryPredicate>
OutputIterator copy_if(
InputIterator first,
InputIterator last,
OutputIterator dest,
UnaryPredicate pred);
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class UnaryPredicate>
ForwardIterator2 copy_if(
ExecutionPolicy&& exec,
ForwardIterator1 first,
ForwardIterator1 last,
ForwardIterator2 result,
UnaryPredicate pred);
```

### Parameters

*exec*

The execution policy to use.

*first*

An input iterator that indicates the start of a range to check for the condition.

*last*

An input iterator that indicates the end of the range.

*dest*

The output iterator that indicates the destination for the copied elements.

*pred*

The condition against which every element in the range is tested. This condition is provided by a user-defined predicate function object. A unary predicate takes one argument and returns **true** or **false**.

### Return value

An output iterator that equals *dest* incremented once for each element that fulfills the condition. In other words, the return value minus *dest* equals the number of copied elements.

### Remarks

The template function evaluates

`if (pred(*first + N)) * dest++ = *(first + N))`

once for each `N`

in the range `[0, last - first)`

, for strictly increasing values of `N`

starting with the lowest value. If *dest* and *first* designate regions of storage, *dest* must not be in the range `[ first, last )`

.

### Example

```
// alg_copy_if.cpp
// compile with: /EHsc
#include <list>
#include <algorithm>
#include <iostream>
void listlist(std::list<int> l)
{
std::cout << "( ";
for (auto const& el : l)
std::cout << el << " ";
std::cout << ")" << std::endl;
}
int main()
{
using namespace std;
list<int> li{ 46, 59, 88, 72, 79, 71, 60, 5, 40, 84 };
list<int> le(li.size()); // le = { 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 };
list<int> lo(li.size()); // lo = { 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 };
cout << "li = ";
listlist(li);
// is_even checks if the element is even.
auto is_even = [](int const elem) { return !(elem % 2); };
// use copy_if to select only even elements from li
// and copy them to le, starting from le's begin position
auto ec = copy_if(li.begin(),li.end(), le.begin(), is_even);
le.resize(std::distance(le.begin(), ec)); // shrink le to new size
cout << "Even numbers are le = ";
listlist(le);
// is_odd checks if the element is odd.
auto is_odd = [](int const elem) { return (elem % 2); };
// use copy_if to select only odd elements from li
// and copy them to lo, starting from lo's begin position
auto oc = copy_if(li.begin(), li.end(), lo.begin(), is_odd);
lo.resize(std::distance(lo.begin(), oc)); // shrink lo to new size
cout << "Odd numbers are lo = ";
listlist(lo);
}
```

```
li = ( 46 59 88 72 79 71 60 5 40 84 )
Even numbers are le = ( 46 88 72 60 40 84 )
Odd numbers are lo = ( 59 79 71 5 )
```

## copy_n

Copies a specified number of elements.

```
template<class InputIterator, class Size, class OutputIterator>
OutputIterator copy_n(
InputIterator first,
Size count,
OutputIterator dest);
template<class ExecutionPolicy, class ForwardIterator1, class Size, class ForwardIterator2>
ForwardIterator2 copy_n(
ExecutionPolicy&& exec,
ForwardIterator1 first,
Size count,
ForwardIterator2 dest);
```

### Parameters

*exec*

The execution policy to use.

*first*

An input iterator that indicates where to copy elements from.

*count*

A signed or unsigned integer type specifying the number of elements to copy.

*dest*

An output iterator that indicates where to copy elements to.

### Return value

Returns an output iterator where elements have been copied to. It is the same as the returned value of the *dest* parameter.

### Remarks

The template function evaluates `*(dest + N) = *(first + N))`

once for each `N`

in the range `[0, count)`

, for strictly increasing values of `N`

starting with the lowest value. It then returns `dest + N`

. If *dest* and *first* designate regions of storage, *dest* must not be in the range `[first, last)`

.

### Example

```
// alg_copy_n.cpp
// compile with: cl /EHsc /W4 alg_copy_n.cpp
#include <algorithm>
#include <iostream>
#include <string>
int main()
{
using namespace std;
string s1{"dandelion"};
string s2{"badger"};
cout << s1 << " + " << s2 << " = ";
// Copy the first 3 letters from s1
// to the first 3 positions in s2
copy_n(s1.begin(), 3, s2.begin());
cout << s2 << endl;
}
```

```
dandelion + badger = danger
```

## count

Returns the number of elements in a range whose values match a specified value.

```
template<class InputIterator, class Type>
typename iterator_traits<InputIterator>::difference_type count(
InputIterator first,
InputIterator last,
const Type& value);
template<class ExecutionPolicy, class ForwardIterator, class Type>
typename iterator_traits<ForwardIterator>::difference_type
count(
ExecutionPolicy&& exec,
ForwardIterator first,
ForwardIterator last,
const Type& value);
```

### Parameters

*exec*

The execution policy to use.

*first*

An input iterator addressing the position of the first element in the range to be traversed.

*last*

An input iterator addressing the position one past the final element in the range to be traversed.

*value*

The value of the elements to be counted.

### Return value

The difference type of the `InputIterator`

that counts the number of elements in the range [*first*, *last*) that have value *value*.

### Remarks

The `operator==`

used to determine the match between an element and the specified value must impose an equivalence relation between its operands.

This algorithm is generalized to count elements that satisfy any predicate with the template function count_if.

### Example

```
// alg_count.cpp
// compile with: /EHsc
#include <vector>
#include <algorithm>
#include <iostream>
int main()
{
using namespace std;
vector<int> v1;
vector<int>::iterator Iter;
v1.push_back(10);
v1.push_back(20);
v1.push_back(10);
v1.push_back(40);
v1.push_back(10);
cout << "v1 = ( " ;
for (Iter = v1.begin(); Iter != v1.end(); Iter++)
cout << *Iter << " ";
cout << ")" << endl;
vector<int>::iterator::difference_type result;
result = count(v1.begin(), v1.end(), 10);
cout << "The number of 10s in v2 is: " << result << "." << endl;
}
```

```
v1 = ( 10 20 10 40 10 )
The number of 10s in v2 is: 3.
```

## count_if

Returns the number of elements in a range whose values satisfy a specified condition.

```
template<class InputIterator, class UnaryPredicate>
typename iterator_traits<InputIterator>::difference_type count_if(
InputIterator first,
InputIterator last,
UnaryPredicate pred);
template<class ExecutionPolicy, class ForwardIterator, class UnaryPredicate>
typename iterator_traits<ForwardIterator>::difference_type
count_if(
ExecutionPolicy&& exec,
ForwardIterator first,
ForwardIterator last,
UnaryPredicate pred);
```

### Parameters

*exec*

The execution policy to use.

*first*

An input iterator addressing the position of the first element in the range to be searched.

*last*

An input iterator addressing the position one past the final element in the range to be searched.

*pred*

User-defined predicate function object that defines the condition to be satisfied if an element is to be counted. A unary predicate takes a single argument and returns **true** or **false**.

### Return value

The number of elements that satisfy the condition specified by the predicate.

### Remarks

This template function is a generalization of the algorithm count, replacing the predicate "equals a specific value" with any predicate.

### Example

```
// alg_count_if.cpp
// compile with: /EHsc
#include <vector>
#include <algorithm>
#include <iostream>
bool greater10(int value)
{
return value > 10;
}
int main()
{
using namespace std;
vector<int> v1;
vector<int>::iterator Iter;
v1.push_back(10);
v1.push_back(20);
v1.push_back(10);
v1.push_back(40);
v1.push_back(10);
cout << "v1 = ( ";
for (Iter = v1.begin(); Iter != v1.end(); Iter++)
cout << *Iter << " ";
cout << ")" << endl;
vector<int>::iterator::difference_type result1;
result1 = count_if(v1.begin(), v1.end(), greater10);
cout << "The number of elements in v1 greater than 10 is: "
<< result1 << "." << endl;
}
```

```
v1 = ( 10 20 10 40 10 )
The number of elements in v1 greater than 10 is: 2.
```

## equal

Compares two ranges element by element for equality or equivalence in a sense specified by a binary predicate.

Use `std::equal`

when comparing elements in different container types (for example `vector`

and `list`

) or when comparing different element types, or when you need to compare sub-ranges of containers. Otherwise, when comparing elements of the same type in the same container type, use the non-member `operator==`

that is provided for each container.

Use the dual-range overloads in C++14 code because the overloads that only take a single iterator for the second range will not detect differences if the second range is longer than the first range, and will result in undefined behavior if the second range is shorter than the first range.

```
template<class InputIterator1, class InputIterator2>
bool equal(
InputIterator1 first1,
InputIterator1 last1,
InputIterator2 first2);
template<class InputIterator1, class InputIterator2, class BinaryPredicate>
bool equal(
InputIterator1 first1,
InputIterator1 last1,
InputIterator2 first2,
BinaryPredicate pred); // C++14
template<class InputIterator1, class InputIterator2>
bool equal(
InputIterator1 first1,
InputIterator1 last1,
InputIterator2 first2,
InputIterator2 last2);
template<class InputIterator1, class InputIterator2, class BinaryPredicate>
bool equal(
InputIterator1 first1,
InputIterator1 last1,
InputIterator2 first2,
InputIterator2 last2,
BinaryPredicate pred);
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2>
bool equal(
ExecutionPolicy&& exec,
ForwardIterator1 first1,
ForwardIterator1 last1,
ForwardIterator2 first2);
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class BinaryPredicate>
bool equal(
ExecutionPolicy&& exec,
ForwardIterator1 first1,
ForwardIterator1 last1,
ForwardIterator2 first2,
BinaryPredicate pred);
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2>
bool equal(
ExecutionPolicy&& exec,
ForwardIterator1 first1,
ForwardIterator1 last1,
ForwardIterator2 first2,
ForwardIterator2 last2);
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class BinaryPredicate>
bool equal(
ExecutionPolicy&& exec,
ForwardIterator1 first1,
ForwardIterator1 last1,
ForwardIterator2 first2,
ForwardIterator2 last2,
BinaryPredicate pred);
```

### Parameters

*exec*

The execution policy to use.

*first1*

An input iterator addressing the position of the first element in the first range to be tested.

*last1*

An input iterator addressing the position one past the last element in the first range to be tested.

*first2*

An input iterator addressing the position of the first element in the second range to be tested.

*last2*

An input iterator addressing the position of one past the last element in the second range to be tested.

*pred*

User-defined predicate function object that defines the condition to be satisfied if two elements are to be taken as equivalent. A binary predicate takes two arguments and returns **true** when satisfied and **false** when not satisfied.

### Return value

**true** if and only if the ranges are identical or equivalent under the binary predicate when compared element by element; otherwise, **false**.

### Remarks

The range to be searched must be valid; all iterators must be dereferenceable and the last position is reachable from the first by incrementation.

If the two ranges are equal length, then the time complexity of the algorithm is linear in the number of elements contained in the range. Otherwise the function immediately returns **false**.

Neither the `operator==`

nor the user-defined predicate is required to impose an equivalence relation that symmetric, reflexive and transitive between its operands.

### Example

```
#include <iostream>
#include <vector>
#include <algorithm>
using namespace std;
int main()
{
vector<int> v1 { 0, 5, 10, 15, 20, 25 };
vector<int> v2 { 0, 5, 10, 15, 20, 25 };
vector<int> v3 { 0, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50 };
// Using range-and-a-half equal:
bool b = equal(v1.begin(), v1.end(), v2.begin());
cout << "v1 and v2 are equal: "
<< b << endl; // true, as expected
b = equal(v1.begin(), v1.end(), v3.begin());
cout << "v1 and v3 are equal: "
<< b << endl; // true, surprisingly
// Using dual-range equal:
b = equal(v1.begin(), v1.end(), v3.begin(), v3.end());
cout << "v1 and v3 are equal with dual-range overload: "
<< b << endl; // false
return 0;
}
```

## equal_range

Given an ordered range, finds the subrange in which all elements are equivalent to a given value.

```
template<class ForwardIterator, class Type>
pair<ForwardIterator, ForwardIterator> equal_range(
ForwardIterator first,
ForwardIterator last,
const Type& value);
template<class ForwardIterator, class Type, class Compare>
pair<ForwardIterator, ForwardIterator> equal_range(
ForwardIterator first,
ForwardIterator last,
const Type& value,
Compare pred);
```

### Parameters

*first*

A forward iterator addressing the position of the first element in the range to be searched.

*last*

A forward iterator addressing the position one past the final element in the range to be searched.

*value*

The value being searched for in the ordered range.

*pred*

User-defined predicate function object that defines the sense in which one element is less than another. A comparison predicate takes two arguments and returns **true** when satisfied and **false** when not satisfied.

### Return value

A pair of forward iterators that specify a subrange, contained within the range searched, in which all of the elements are equivalent to *value* in the sense defined by the binary predicate used (either *pred* or the default, less-than).

If no elements in the range are equivalent to *value*, the forward iterators in the returned pair are equal and specify the point where *value* could be inserted without disturbing the order of the range.

### Remarks

The first iterator of the pair returned by the algorithm is lower_bound, and the second iterator is upper_bound.

The range must be sorted according to the predicate provided to `equal_range`

. For example, if you are going to use the greater-than predicate, the range must be sorted in descending order.

Elements in the possibly empty subrange defined by the pair of iterators returned by `equal_range`

will be equivalent to *value* in the sense defined by the predicate used.

The complexity of the algorithm is logarithmic for random-access iterators and linear otherwise, with the number of steps proportional to (*last* - *first*).

### Example

```
// alg_equal_range.cpp
// compile with: /EHsc
#include <vector>
#include <algorithm>
#include <functional> // greater<int>()
#include <iostream>
#include <string>
using namespace std;
template<class T> void dump_vector( const vector<T>& v, pair<typename vector<T>::iterator, typename vector<T>::iterator> range )
{
// prints vector v with range delimited by [ and ]
for ( typename vector<T>::const_iterator i = v.begin(); i != v.end(); ++i )
{
if ( i == range.first )
{
cout << "[ ";
}
if ( i == range.second )
{
cout << "] ";
}
cout << *i << " ";
}
cout << endl;
}
template<class T> void equal_range_demo( const vector<T>& original_vector, T value )
{
vector<T> v(original_vector);
sort( v.begin(), v.end() );
cout << "Vector sorted by the default binary predicate <:" << endl << '\t';
for ( vector<T>::const_iterator i = v.begin(); i != v.end(); ++i )
{
cout << *i << " ";
}
cout << endl << endl;
pair<vector<T>::iterator, vector<T>::iterator> result
= equal_range( v.begin(), v.end(), value );
cout << "Result of equal_range with value = " << value << ":" << endl << '\t';
dump_vector( v, result );
cout << endl;
}
template<class T, class F> void equal_range_demo( const vector<T>& original_vector, T value, F pred, string predname )
{
vector<T> v(original_vector);
sort( v.begin(), v.end(), pred );
cout << "Vector sorted by the binary predicate " << predname << ":" << endl << '\t';
for ( typename vector<T>::const_iterator i = v.begin(); i != v.end(); ++i )
{
cout << *i << " ";
}
cout << endl << endl;
pair<typename vector<T>::iterator, typename vector<T>::iterator> result
= equal_range( v.begin(), v.end(), value, pred );
cout << "Result of equal_range with value = " << value << ":" << endl << '\t';
dump_vector( v, result );
cout << endl;
}
// Return whether absolute value of elem1 is less than absolute value of elem2
bool abs_lesser( int elem1, int elem2 )
{
return abs(elem1) < abs(elem2);
}
// Return whether string l is shorter than string r
bool shorter_than(const string& l, const string& r)
{
return l.size() < r.size();
}
int main()
{
vector<int> v1;
// Constructing vector v1 with default less than ordering
for ( int i = -1; i <= 4; ++i )
{
v1.push_back(i);
}
for ( int i =-3; i <= 0; ++i )
{
v1.push_back( i );
}
equal_range_demo( v1, 3 );
equal_range_demo( v1, 3, greater<int>(), "greater" );
equal_range_demo( v1, 3, abs_lesser, "abs_lesser" );
vector<string> v2;
v2.push_back("cute");
v2.push_back("fluffy");
v2.push_back("kittens");
v2.push_back("fun");
v2.push_back("meowmeowmeow");
v2.push_back("blah");
equal_range_demo<string>( v2, "fred" );
equal_range_demo<string>( v2, "fred", shorter_than, "shorter_than" );
}
```

## fill

Assigns the same new value to every element in a specified range.

```
template<class ForwardIterator, class Type>
void fill(
ForwardIterator first,
ForwardIterator last,
const Type& value);
template<class ExecutionPolicy, class ForwardIterator, class Type>
void fill(
ExecutionPolicy&& exec,
ForwardIterator first,
ForwardIterator last,
const Type& value);
```

### Parameters

*exec*

The execution policy to use.

*first*

A forward iterator addressing the position of the first element in the range to be traversed.

*last*

A forward iterator addressing the position one past the final element in the range to be traversed.

*value*

The value to be assigned to elements in the range [*first*, *last*).

### Remarks

The destination range must be valid; all pointers must be dereferenceable, and the last position is reachable from the first by incrementation. The complexity is linear with the size of the range.

### Example

```
// alg_fill.cpp
// compile with: /EHsc
#include <vector>
#include <algorithm>
#include <iostream>
int main()
{
using namespace std;
vector<int> v1;
vector<int>::iterator Iter1;
int i;
for ( i = 0 ; i <= 9 ; i++ )
{
v1.push_back( 5 * i );
}
cout << "Vector v1 = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")" << endl;
// Fill the last 5 positions with a value of 2
fill( v1.begin( ) + 5, v1.end( ), 2 );
cout << "Modified v1 = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")" << endl;
}
```

```
Vector v1 = ( 0 5 10 15 20 25 30 35 40 45 )
Modified v1 = ( 0 5 10 15 20 2 2 2 2 2 )
```

## fill_n

Assigns a new value to a specified number of elements in a range beginning with a particular element.

```
template<class OutputIterator, class Size, class Type>
OutputIterator fill_n(
OutputIterator first,
Size count,
const Type& value);
template<class ExecutionPolicy, class ForwardIterator, class Size, class Type>
ForwardIterator fill_n(
ExecutionPolicy&& exec,
ForwardIterator first,
Size count,
const Type& value);
```

### Parameters

*exec*

The execution policy to use.

*first*

An output iterator addressing the position of the first element in the range to be assigned the value *value*.

*count*

A signed or unsigned integer type specifying the number of elements to be assigned the value.

*value*

The value to be assigned to elements in the range [*first*, *first + count*).

### Return value

An iterator to the element that follows the last element filled if *count* > zero, otherwise the first element.

### Remarks

The destination range must be valid; all pointers must be dereferenceable, and the last position is reachable from the first by incrementation. The complexity is linear with the size of the range.

### Example

```
// alg_fill_n.cpp
// compile using /EHsc
#include <vector>
#include <algorithm>
#include <iostream>
int main()
{
using namespace std;
vector<int> v;
for ( auto i = 0 ; i < 9 ; ++i )
v.push_back( 0 );
cout << " vector v = ( " ;
for ( const auto &w : v )
cout << w << " ";
cout << ")" << endl;
// Fill the first 3 positions with a value of 1, saving position.
auto pos = fill_n( v.begin(), 3, 1 );
cout << "modified v = ( " ;
for ( const auto &w : v )
cout << w << " ";
cout << ")" << endl;
// Fill the next 3 positions with a value of 2, using last position.
fill_n( pos, 3, 2 );
cout << "modified v = ( " ;
for ( const auto &w : v )
cout << w << " ";
cout << ")" << endl;
// Fill the last 3 positions with a value of 3, using relative math.
fill_n( v.end()-3, 3, 3 );
cout << "modified v = ( " ;
for ( const auto &w : v )
cout << w << " ";
cout << ")" << endl;
}
```

## find

Locates the position of the first occurrence of an element in a range that has a specified value.

```
template<class InputIterator, class Type>
InputIterator find(
InputIterator first,
InputIterator last,
const Type& value);
template<class ExecutionPolicy, class ForwardIterator, class Type>
ForwardIterator find(
ExecutionPolicy&& exec,
ForwardIterator first,
ForwardIterator last,
const Type& value);
```

### Parameters

*exec*

The execution policy to use.

*first*

An input iterator addressing the position of the first element in the range to be searched for the specified value.

*last*

An input iterator addressing the position one past the final element in the range to be searched for the specified value.

*value*

The value to be searched for.

### Return value

An input iterator addressing the first occurrence of the specified value in the range being searched. If no element is found with an equivalent value, returns *last*.

### Remarks

The `operator==`

used to determine the match between an element and the specified value must impose an equivalence relation between its operands.

For a code example using `find()`

, see find_if.

## find_end

Looks in a range for the last subsequence that is identical to a specified sequence or that is equivalent in a sense specified by a binary predicate.

```
template<class ForwardIterator1, class ForwardIterator2>
ForwardIterator1 find_end(
ForwardIterator1 first1,
ForwardIterator1 last1,
ForwardIterator2 first2,
ForwardIterator2 last2);
template<class ForwardIterator1, class ForwardIterator2, class Pred>
ForwardIterator1 find_end(
ForwardIterator1 first1,
ForwardIterator1 last1,
ForwardIterator2 first2,
ForwardIterator2 last2,
Pred pred);
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2>
ForwardIterator1
find_end(
ExecutionPolicy&& exec,
ForwardIterator1 first1,
ForwardIterator1 last1,
ForwardIterator2 first2,
ForwardIterator2 last2);
template<class ExecutionPolicy, class ForwardIterator1,
class ForwardIterator2, class BinaryPredicate>
ForwardIterator1
find_end(
ExecutionPolicy&& exec,
ForwardIterator1 first1,
ForwardIterator1 last1,
ForwardIterator2 first2,
ForwardIterator2 last2,
BinaryPredicate pred);
```

### Parameters

*first1*

A forward iterator addressing the position of the first element in the range to be searched.

*last1*

A forward iterator addressing the position one past the last element in the range to be searched.

*first2*

A forward iterator addressing the position of the first element in the range to search for.

*last2*

A forward iterator addressing the position one past the last element in the range to search for.

*pred*

User-defined predicate function object that defines the condition to be satisfied if two elements are to be taken as equivalent. A binary predicate takes two arguments and returns **true** when satisfied and **false** when not satisfied.

### Return value

A forward iterator addressing the position of the first element of the last subsequence within [first1, last1) that matches the specified sequence [first2, last2).

### Remarks

The `operator==`

used to determine the match between an element and the specified value must impose an equivalence relation between its operands.

The ranges referenced must be valid; all pointers must be dereferenceable and, within each sequence, the last position is reachable from the first by incrementation.

### Example

```
// alg_find_end.cpp
// compile with: /EHsc
#include <vector>
#include <list>
#include <algorithm>
#include <iostream>
// Return whether second element is twice the first
bool twice ( int elem1, int elem2 )
{
return 2 * elem1 == elem2;
}
int main()
{
using namespace std;
vector<int> v1, v2;
list<int> L1;
vector<int>::iterator Iter1, Iter2;
list<int>::iterator L1_Iter, L1_inIter;
int i;
for ( i = 0 ; i <= 5 ; i++ )
{
v1.push_back( 5 * i );
}
for ( i = 0 ; i <= 5 ; i++ )
{
v1.push_back( 5 * i );
}
int ii;
for ( ii = 1 ; ii <= 4 ; ii++ )
{
L1.push_back( 5 * ii );
}
int iii;
for ( iii = 2 ; iii <= 4 ; iii++ )
{
v2.push_back( 10 * iii );
}
cout << "Vector v1 = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")" << endl;
cout << "List L1 = ( " ;
for ( L1_Iter = L1.begin( ) ; L1_Iter!= L1.end( ) ; L1_Iter++ )
cout << *L1_Iter << " ";
cout << ")" << endl;
cout << "Vector v2 = ( " ;
for ( Iter2 = v2.begin( ) ; Iter2 != v2.end( ) ; Iter2++ )
cout << *Iter2 << " ";
cout << ")" << endl;
// Searching v1 for a match to L1 under identity
vector<int>::iterator result1;
result1 = find_end ( v1.begin( ), v1.end( ), L1.begin( ), L1.end( ) );
if ( result1 == v1.end( ) )
cout << "There is no match of L1 in v1."
<< endl;
else
cout << "There is a match of L1 in v1 that begins at "
<< "position "<< result1 - v1.begin( ) << "." << endl;
// Searching v1 for a match to L1 under the binary predicate twice
vector<int>::iterator result2;
result2 = find_end ( v1.begin( ), v1.end( ), v2.begin( ), v2.end( ), twice );
if ( result2 == v1.end( ) )
cout << "There is no match of L1 in v1."
<< endl;
else
cout << "There is a sequence of elements in v1 that "
<< "are equivalent to those\n in v2 under the binary "
<< "predicate twice and that begins at position "
<< result2 - v1.begin( ) << "." << endl;
}
```

```
Vector v1 = ( 0 5 10 15 20 25 0 5 10 15 20 25 )
List L1 = ( 5 10 15 20 )
Vector v2 = ( 20 30 40 )
There is a match of L1 in v1 that begins at position 7.
There is a sequence of elements in v1 that are equivalent to those
in v2 under the binary predicate twice and that begins at position 8.
```

## find_first_of

Searches for the first occurrence of any of several values within a target range or for the first occurrence of any of several elements that are equivalent in a sense specified by a binary predicate to a specified set of the elements.

```
template<class ForwardIterator1, class ForwardIterator2>
ForwardIterator1 find_first_of(
ForwardIterator1 first1,
ForwardIterator1 last1,
ForwardIterator2 first2,
ForwardIterator2 last2);
template<class ForwardIterator1, class ForwardIterator2, class BinaryPredicate>
ForwardIterator1 find_first_of(
ForwardIterator1 first1,
ForwardIterator1 last1,
ForwardIterator2 first2,
ForwardIterator2 last2,
BinaryPredicate pred);
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2>
ForwardIterator1
find_first_of(
ExecutionPolicy&& exec,
ForwardIterator1 first1,
ForwardIterator1 last1,
ForwardIterator2 first2,
ForwardIterator2 last2);
template<class ExecutionPolicy, class ForwardIterator1,
class ForwardIterator2, class BinaryPredicate>
ForwardIterator1
find_first_of(
ExecutionPolicy&& exec,
ForwardIterator1 first1,
ForwardIterator1 last1,
ForwardIterator2 first2,
ForwardIterator2 last2,
BinaryPredicate pred);
```

### Parameters

*first1*

A forward iterator addressing the position of the first element in the range to be searched.

*last1*

A forward iterator addressing the position one past the final element in the range to be searched.

*first2*

A forward iterator addressing the position of the first element in the range to be matched.

*last2*

A forward iterator addressing the position one past the final element in the range to be matched.

*pred*

User-defined predicate function object that defines the condition to be satisfied if two elements are to be taken as equivalent. A binary predicate takes two arguments and returns **true** when satisfied and **false** when not satisfied.

### Return value

A forward iterator addressing the position of the first element of the first subsequence that matches the specified sequence or that is equivalent in a sense specified by a binary predicate.

### Remarks

`operator==`

used to determine the match between an element and the specified value must impose an equivalence relation between its operands.

The ranges referenced must be valid; all pointers must be dereferenceable and, within each sequence, the last position is reachable from the first by incrementation.

### Example

```
// alg_find_first_of.cpp
// compile with: /EHsc
#include <vector>
#include <list>
#include <algorithm>
#include <iostream>
// Return whether second element is twice the first
bool twice ( int elem1, int elem2 )
{
return 2 * elem1 == elem2;
}
int main()
{
using namespace std;
vector<int> v1, v2;
list<int> L1;
vector<int>::iterator Iter1, Iter2;
list<int>::iterator L1_Iter, L1_inIter;
int i;
for ( i = 0 ; i <= 5 ; i++ )
{
v1.push_back( 5 * i );
}
for ( i = 0 ; i <= 5 ; i++ )
{
v1.push_back( 5 * i );
}
int ii;
for ( ii = 3 ; ii <= 4 ; ii++ )
{
L1.push_back( 5 * ii );
}
int iii;
for ( iii = 2 ; iii <= 4 ; iii++ )
{
v2.push_back( 10 * iii );
}
cout << "Vector v1 = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")" << endl;
cout << "List L1 = ( " ;
for ( L1_Iter = L1.begin( ) ; L1_Iter!= L1.end( ) ; L1_Iter++ )
cout << *L1_Iter << " ";
cout << ")" << endl;
cout << "Vector v2 = ( " ;
for ( Iter2 = v2.begin( ) ; Iter2 != v2.end( ) ; Iter2++ )
cout << *Iter2 << " ";
cout << ")" << endl;
// Searching v1 for first match to L1 under identity
vector<int>::iterator result1;
result1 = find_first_of ( v1.begin( ), v1.end( ), L1.begin( ), L1.end( ) );
if ( result1 == v1.end( ) )
cout << "There is no match of L1 in v1."
<< endl;
else
cout << "There is at least one match of L1 in v1"
<< "\n and the first one begins at "
<< "position "<< result1 - v1.begin( ) << "." << endl;
// Searching v1 for a match to L1 under the binary predicate twice
vector<int>::iterator result2;
result2 = find_first_of ( v1.begin( ), v1.end( ), v2.begin( ), v2.end( ), twice );
if ( result2 == v1.end( ) )
cout << "There is no match of L1 in v1."
<< endl;
else
cout << "There is a sequence of elements in v1 that "
<< "are equivalent\n to those in v2 under the binary "
<< "predicate twice\n and the first one begins at position "
<< result2 - v1.begin( ) << "." << endl;
}
```

```
Vector v1 = ( 0 5 10 15 20 25 0 5 10 15 20 25 )
List L1 = ( 15 20 )
Vector v2 = ( 20 30 40 )
There is at least one match of L1 in v1
and the first one begins at position 3.
There is a sequence of elements in v1 that are equivalent
to those in v2 under the binary predicate twice
and the first one begins at position 2.
```

## find_if

Locates the position of the first occurrence of an element in a range that satisfies a specified condition.

```
template<class InputIterator, class UnaryPredicate>
InputIterator find_if(
InputIterator first,
InputIterator last,
UnaryPredicate pred);
template<class ExecutionPolicy, class ForwardIterator, class UnaryPredicate>
ForwardIterator find_if(
ExecutionPolicy&& exec,
ForwardIterator first, ForwardIterator last,
UnaryPredicate pred);
```

### Parameters

*first*

An input iterator addressing the position of the first element in the range to be searched.

*last*

An input iterator addressing the position one past the final element in the range to be searched.

*pred*

User-defined predicate function object or lambda expression that defines the condition to be satisfied by the element being searched for. A unary predicate takes a single argument and returns **true** if satisfied, or **false** if not satisfied. The signature of *pred* must effectively be `bool pred(const T& arg);`

, where `T`

is a type to which `InputIterator`

can be implicitly converted when dereferenced. The **const** keyword is shown only to illustrate that the function object or lambda should not modify the argument.

### Return value

An input iterator that refers to the first element in the range that satisfies the condition specified by the predicate (the predicate results in **true**). If no element is found to satisfy the predicate, returns *last*.

### Remarks

This template function is a generalization of the algorithm find, replacing the predicate "equals a specific value" with any predicate. For the logical opposite (find the first element that does not satisfy the predicate), see find_if_not.

### Example

```
// cl.exe /W4 /nologo /EHsc /MTd
#include <vector>
#include <algorithm>
#include <iostream>
#include <string>
using namespace std;
template <typename S> void print(const S& s) {
for (const auto& p : s) {
cout << "(" << p << ") ";
}
cout << endl;
}
// Test std::find()
template <class InputIterator, class T>
void find_print_result(InputIterator first, InputIterator last, const T& value) {
// call <algorithm> std::find()
auto p = find(first, last, value);
cout << "value " << value;
if (p == last) {
cout << " not found." << endl;
} else {
cout << " found." << endl;
}
}
// Test std::find_if()
template <class InputIterator, class Predicate>
void find_if_print_result(InputIterator first, InputIterator last,
Predicate Pred, const string& Str) {
// call <algorithm> std::find_if()
auto p = find_if(first, last, Pred);
if (p == last) {
cout << Str << " not found." << endl;
} else {
cout << "first " << Str << " found: " << *p << endl;
}
}
// Function to use as the UnaryPredicate argument to find_if() in this example
bool is_odd_int(int i) {
return ((i % 2) != 0);
}
int main()
{
// Test using a plain old array.
const int x[] = { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 };
cout << "array x[] contents: ";
print(x);
// Using non-member std::begin()/std::end() to get input iterators for the plain old array.
cout << "Test std::find() with array..." << endl;
find_print_result(begin(x), end(x), 10);
find_print_result(begin(x), end(x), 42);
cout << "Test std::find_if() with array..." << endl;
find_if_print_result(begin(x), end(x), is_odd_int, "odd integer"); // function name
find_if_print_result(begin(x), end(x), // lambda
[](int i){ return ((i % 2) == 0); }, "even integer");
// Test using a vector.
vector<int> v;
for (int i = 0; i < 10; ++i) {
v.push_back((i + 1) * 10);
}
cout << endl << "vector v contents: ";
print(v);
cout << "Test std::find() with vector..." << endl;
find_print_result(v.begin(), v.end(), 20);
find_print_result(v.begin(), v.end(), 12);
cout << "Test std::find_if() with vector..." << endl;
find_if_print_result(v.begin(), v.end(), is_odd_int, "odd integer");
find_if_print_result(v.begin(), v.end(), // lambda
[](int i){ return ((i % 2) == 0); }, "even integer");
}
```

## find_if_not

Returns the first element in the indicated range that does not satisfy a condition.

```
template<class InputIterator, class UnaryPredicate>
InputIterator find_if_not(
InputIterator first,
InputIterator last,
UnaryPredicate pred);
template<class ExecutionPolicy, class ForwardIterator, class UnaryPredicate>
ForwardIterator find_if_not(
ExecutionPolicy&& exec,
ForwardIterator first, ForwardIterator last,
UnaryPredicate pred);
```

### Parameters

*first*

An input iterator addressing the position of the first element in the range to be searched.

*last*

An input iterator addressing the position one past the final element in the range to be searched.

*pred*

User-defined predicate function object or lambda expression that defines the condition to be not satisfied by the element being searched for. A unary predicate takes a single argument and returns **true** if satisfied, or **false** if not satisfied. The signature of *pred* must effectively be `bool pred(const T& arg);`

, where `T`

is a type to which `InputIterator`

can be implicitly converted when dereferenced. The **const** keyword is shown only to illustrate that the function object or lambda should not modify the argument.

### Return value

An input iterator that refers to the first element in the range that does not satisfy the condition specified by the predicate (the predicate results in **false**). If all elements satisfy the predicate (the predicate results in **true** for every element), returns *last*.

### Remarks

This template function is a generalization of the algorithm find, replacing the predicate "equals a specific value" with any predicate. For the logical opposite (find the first element that does satisfy the predicate), see find_if.

For a code example readily adaptable to `find_if_not()`

, see find_if.

## for_each

Applies a specified function object to each element in a forward order within a range and returns the function object.

```
template<class InputIterator, class Function>
Function for_each(
InputIterator first,
InputIterator last,
Function func);
template<class ExecutionPolicy, class ForwardIterator, class Function>
void for_each(
ExecutionPolicy&& exec,
ForwardIterator first,
ForwardIterator last,
Function func);
```

### Parameters

*first*

An input iterator addressing the position of the first element in the range to be operated on.

*last*

An input iterator addressing the position one past the final element in the range operated on.

*func*

User-defined function object that is applied to each element in the range.

### Return value

A copy of the function object after it has been applied to all of the elements in the range.

### Remarks

The algorithm `for_each`

is very flexible, allowing the modification of each element within a range in different, user-specified ways. Templatized functions may be reused in a modified form by passing different parameters. User-defined functions may accumulate information within an internal state that the algorithm may return after processing all of the elements in the range.

The range referenced must be valid; all pointers must be dereferenceable and, within the sequence, the last position must be reachable from the first by incrementation.

The complexity is linear with at most (*last* - *first*) comparisons.

### Example

```
// alg_for_each.cpp
// compile with: /EHsc
#include <vector>
#include <algorithm>
#include <iostream>
// The function object multiplies an element by a Factor
template <class Type>
class MultValue
{
private:
Type Factor; // The value to multiply by
public:
// Constructor initializes the value to multiply by
MultValue ( const Type& value ) : Factor ( value ) {
}
// The function call for the element to be multiplied
void operator( ) ( Type& elem ) const
{
elem *= Factor;
}
};
// The function object to determine the average
class Average
{
private:
long num; // The number of elements
long sum; // The sum of the elements
public:
// Constructor initializes the value to multiply by
Average( ) : num ( 0 ) , sum ( 0 )
{
}
// The function call to process the next elment
void operator( ) ( int elem )
{
num++; // Increment the element count
sum += elem; // Add the value to the partial sum
}
// return Average
operator double( )
{
return static_cast<double> (sum) /
static_cast<double> (num);
}
};
int main()
{
using namespace std;
vector<int> v1;
vector<int>::iterator Iter1;
// Constructing vector v1
int i;
for ( i = -4 ; i <= 2 ; i++ )
{
v1.push_back( i );
}
cout << "Original vector v1 = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
// Using for_each to multiply each element by a Factor
for_each ( v1.begin( ), v1.end( ), MultValue<int> ( -2 ) );
cout << "Multiplying the elements of the vector v1\n "
<< "by the factor -2 gives:\n v1mod1 = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
// The function object is templatized and so can be
// used again on the elements with a different Factor
for_each (v1.begin( ), v1.end( ), MultValue<int> (5 ) );
cout << "Multiplying the elements of the vector v1mod\n "
<< "by the factor 5 gives:\n v1mod2 = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
// The local state of a function object can accumulate
// information about a sequence of actions that the
// return value can make available, here the Average
double avemod2 = for_each ( v1.begin( ), v1.end( ),
Average( ) );
cout << "The average of the elements of v1 is:\n Average ( v1mod2 ) = "
<< avemod2 << "." << endl;
}
```

```
Original vector v1 = ( -4 -3 -2 -1 0 1 2 ).
Multiplying the elements of the vector v1
by the factor -2 gives:
v1mod1 = ( 8 6 4 2 0 -2 -4 ).
Multiplying the elements of the vector v1mod
by the factor 5 gives:
v1mod2 = ( 40 30 20 10 0 -10 -20 ).
The average of the elements of v1 is:
Average ( v1mod2 ) = 10.
```

## for_each_n

```
template<class InputIterator, class Size, class Function>
InputIterator for_each_n(
InputIterator first,
Size n,
Function f);
template<class ExecutionPolicy, class ForwardIterator, class Size, class Function>
ForwardIterator for_each_n(
ExecutionPolicy&& exec,
ForwardIterator first,
Size n,
Function f);
```

## generate

Assigns the values generated by a function object to each element in a range.

```
template<class ForwardIterator, class Generator>
void generate(
ForwardIterator first,
ForwardIterator last,
Generator gen);
template<class ExecutionPolicy, class ForwardIterator, class Generator>
void generate(
ExecutionPolicy&& exec,
ForwardIterator first, ForwardIterator last,
Generator gen);
```

### Parameters

*first*

A forward iterator addressing the position of the first element in the range to which values are to be assigned.

*last*

A forward iterator addressing the position one past the final element in the range to which values are to be assigned.

*gen*

A function object that is called with no arguments that is used to generate the values to be assigned to each of the elements in the range.

### Remarks

The function object is invoked for each element in the range and does not need to return the same value each time it is called. It may, for example, read from a file or refer to and modify a local state. The generator's result type must be convertible to the value type of the forward iterators for the range.

The range referenced must be valid; all pointers must be dereferenceable and, within the sequence, the last position must be reachable from the first by incrementation.

The complexity is linear, with exactly ( `last`

- `first`

) calls to the generator being required.

### Example

```
// alg_generate.cpp
// compile with: /EHsc
#include <vector>
#include <deque>
#include <algorithm>
#include <iostream>
#include <ostream>
int main()
{
using namespace std;
// Assigning random values to vector integer elements
vector<int> v1 ( 5 );
vector<int>::iterator Iter1;
deque<int> deq1 ( 5 );
deque<int>::iterator d1_Iter;
generate ( v1.begin( ), v1.end( ), rand );
cout << "Vector v1 is ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
// Assigning random values to deque integer elements
generate ( deq1.begin( ), deq1.end( ), rand );
cout << "Deque deq1 is ( " ;
for ( d1_Iter = deq1.begin( ) ; d1_Iter != deq1.end( ) ; d1_Iter++ )
cout << *d1_Iter << " ";
cout << ")." << endl;
}
```

```
Vector v1 is ( 41 18467 6334 26500 19169 ).
Deque deq1 is ( 15724 11478 29358 26962 24464 ).
```

## generate_n

Assigns the values generated by a function object to a specified number of elements in a range and returns to the position one past the last assigned value.

```
template<class OutputIterator, class Diff, class Generator>
void generate_n(
OutputIterator first,
Diff count,
Generator gen);
template<class ExecutionPolicy, class ForwardIterator, class Size, class Generator>
ForwardIterator generate_n(
ExecutionPolicy&& exec,
ForwardIterator first,
Size count,
Generator gen);
```

### Parameters

*exec*

The execution policy to use.

*first*

An output iterator addressing the position of first element in the range to which values are to be assigned.

*count*

A signed or unsigned integer type specifying the number of elements to be assigned a value by the generator function.

*gen*

A function object that is called with no arguments that is used to generate the values to be assigned to each of the elements in the range.

### Remarks

The function object is invoked for each element in the range and does not need to return the same value each time it is called. It may, for example, read from a file or refer to and modify a local state. The generator's result type must be convertible to the value type of the forward iterators for the range.

The range referenced must be valid; all pointers must be dereferenceable and, within the sequence, the last position must be reachable from the first by incrementation.

The complexity is linear, with exactly `count`

calls to the generator being required.

### Example

```
// cl.exe /EHsc /nologo /W4 /MTd
#include <vector>
#include <deque>
#include <iostream>
#include <string>
#include <algorithm>
#include <random>
using namespace std;
template <typename C>
void print(const string& s, const C& c)
{
cout << s;
for (const auto& e : c) {
cout << e << " ";
}
cout << endl;
}
int main()
{
const int elemcount = 5;
vector<int> v(elemcount);
deque<int> dq(elemcount);
// Set up random number distribution
random_device rd;
mt19937 engine(rd());
uniform_int_distribution<int> dist(-9, 9);
// Call generate_n, using a lambda for the third parameter
generate_n(v.begin(), elemcount, [&](){ return dist(engine); });
print("vector v is: ", v);
generate_n(dq.begin(), elemcount, [&](){ return dist(engine); });
print("deque dq is: ", dq);
}
```

## includes

Tests whether one sorted range contains all the elements contained in a second sorted range, where the ordering or equivalence criterion between elements may be specified by a binary predicate.

```
template<class InputIterator1, class InputIterator2>
bool includes(
InputIterator1 first1,
InputIterator1 last1,
InputIterator2 first2,
InputIterator2 last2);
template<class InputIterator1, class InputIterator2, class Compare>
bool includes(
InputIterator1 first1,
InputIterator1 last1,
InputIterator2 first2,
InputIterator2 last2,
Compare pred );
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2>
bool includes(
ExecutionPolicy&& exec,
ForwardIterator1 first1,
ForwardIterator1 last1,
ForwardIterator2 first2,
ForwardIterator2 last2);
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class Compare>
bool includes(
ExecutionPolicy&& exec,
ForwardIterator1 first1,
ForwardIterator1 last1,
ForwardIterator2 first2,
ForwardIterator2 last2,
Compare pred);
```

### Parameters

*exec*

The execution policy to use.

*first1*

An input iterator addressing the position of the first element in the first of two sorted source ranges to be tested for whether all the elements of the second are contained in the first.

*last1*

An input iterator addressing the position one past the last element in the first of two sorted source ranges to be tested for whether all the elements of the second are contained in the first.

*first2*

An input iterator addressing the position of the first element in second of two consecutive sorted source ranges to be tested for whether all the elements of the second are contained in the first.

*last2*

An input iterator addressing the position one past the last element in second of two consecutive sorted source ranges to be tested for whether all the elements of the second are contained in the first.

*pred*

User-defined predicate function object that defines sense in which one element is less than another. A comparison predicate takes two arguments and returns **true** when satisfied and **false** when not satisfied.

### Return value

**true** if the first sorted range contains all the elements in the second sorted range; otherwise, **false**.

### Remarks

Another way to think of this test is that it determined whether the second source range is a subset of the first source range.

The sorted source ranges referenced must be valid; all pointers must be dereferenceable and, within each sequence, the last position must be reachable from the first by incrementation.

The sorted source ranges must each be arranged as a precondition to the application of the algorithm includes in accordance with the same ordering as is to be used by the algorithm to sort the combined ranges.

The source ranges are not modified by the algorithm `merge`

.

The value types of the input iterators need be less-than comparable to be ordered, so that, given two elements, it may be determined either that they are equivalent (in the sense that neither is less than the other) or that one is less than the other. This results in an ordering between the nonequivalent elements. More precisely, the algorithm tests whether all the elements in the first sorted range under a specified binary predicate have equivalent ordering to those in the second sorted range.

The complexity of the algorithm is linear with at most `2 * ((last1 - first1) - (last2 - first2)) - 1`

comparisons for nonempty source ranges.

### Example

```
// alg_includes.cpp
// compile with: /EHsc
#include <vector>
#include <algorithm>
#include <functional> // For greater<int>( )
#include <iostream>
// Return whether modulus of elem1 is less than modulus of elem2
bool mod_lesser (int elem1, int elem2 )
{
if ( elem1 < 0 )
elem1 = - elem1;
if ( elem2 < 0 )
elem2 = - elem2;
return elem1 < elem2;
}
int main()
{
using namespace std;
vector<int> v1a, v1b;
vector<int>::iterator Iter1a, Iter1b;
// Constructing vectors v1a & v1b with default less-than ordering
int i;
for ( i = -2 ; i <= 4 ; i++ )
{
v1a.push_back( i );
}
int ii;
for ( ii =-2 ; ii <= 3 ; ii++ )
{
v1b.push_back( ii );
}
cout << "Original vector v1a with range sorted by the\n "
<< "binary predicate less than is v1a = ( " ;
for ( Iter1a = v1a.begin( ) ; Iter1a != v1a.end( ) ; Iter1a++ )
cout << *Iter1a << " ";
cout << ")." << endl;
cout << "Original vector v1b with range sorted by the\n "
<< "binary predicate less than is v1b = ( " ;
for ( Iter1b = v1b.begin( ) ; Iter1b != v1b.end( ) ; Iter1b++ )
cout << *Iter1b << " ";
cout << ")." << endl;
// Constructing vectors v2a & v2b with ranges sorted by greater
vector<int> v2a ( v1a ) , v2b ( v1b );
vector<int>::iterator Iter2a, Iter2b;
sort ( v2a.begin( ), v2a.end( ), greater<int>( ) );
sort ( v2b.begin( ), v2b.end( ), greater<int>( ) );
v2a.pop_back( );
cout << "Original vector v2a with range sorted by the\n "
<< "binary predicate greater is v2a = ( " ;
for ( Iter2a = v2a.begin( ) ; Iter2a != v2a.end( ) ; Iter2a++ )
cout << *Iter2a << " ";
cout << ")." << endl;
cout << "Original vector v2b with range sorted by the\n "
<< "binary predicate greater is v2b = ( " ;
for ( Iter2b = v2b.begin( ) ; Iter2b != v2b.end( ) ; Iter2b++ )
cout << *Iter2b << " ";
cout << ")." << endl;
// Constructing vectors v3a & v3b with ranges sorted by mod_lesser
vector<int> v3a ( v1a ), v3b ( v1b ) ;
vector<int>::iterator Iter3a, Iter3b;
reverse (v3a.begin( ), v3a.end( ) );
v3a.pop_back( );
v3a.pop_back( );
sort ( v3a.begin( ), v3a.end( ), mod_lesser );
sort ( v3b.begin( ), v3b.end( ), mod_lesser );
cout << "Original vector v3a with range sorted by the\n "
<< "binary predicate mod_lesser is v3a = ( " ;
for ( Iter3a = v3a.begin( ) ; Iter3a != v3a.end( ) ; Iter3a++ )
cout << *Iter3a << " ";
cout << ")." << endl;
cout << "Original vector v3b with range sorted by the\n "
<< "binary predicate mod_lesser is v3b = ( " ;
for ( Iter3b = v3b.begin( ) ; Iter3b != v3b.end( ) ; Iter3b++ )
cout << *Iter3b << " ";
cout << ")." << endl;
// To test for inclusion under an asscending order
// with the default binary predicate less<int>( )
bool Result1;
Result1 = includes ( v1a.begin( ), v1a.end( ),
v1b.begin( ), v1b.end( ) );
if ( Result1 )
cout << "All the elements in vector v1b are "
<< "contained in vector v1a." << endl;
else
cout << "At least one of the elements in vector v1b "
<< "is not contained in vector v1a." << endl;
// To test for inclusion under descending
// order specify binary predicate greater<int>( )
bool Result2;
Result2 = includes ( v2a.begin( ), v2a.end( ),
v2b.begin( ), v2b.end( ), greater<int>( ) );
if ( Result2 )
cout << "All the elements in vector v2b are "
<< "contained in vector v2a." << endl;
else
cout << "At least one of the elements in vector v2b "
<< "is not contained in vector v2a." << endl;
// To test for inclusion under a user
// defined binary predicate mod_lesser
bool Result3;
Result3 = includes ( v3a.begin( ), v3a.end( ),
v3b.begin( ), v3b.end( ), mod_lesser );
if ( Result3 )
cout << "All the elements in vector v3b are "
<< "contained under mod_lesser in vector v3a."
<< endl;
else
cout << "At least one of the elements in vector v3b is "
<< " not contained under mod_lesser in vector v3a."
<< endl;
}
```

```
Original vector v1a with range sorted by the
binary predicate less than is v1a = ( -2 -1 0 1 2 3 4 ).
Original vector v1b with range sorted by the
binary predicate less than is v1b = ( -2 -1 0 1 2 3 ).
Original vector v2a with range sorted by the
binary predicate greater is v2a = ( 4 3 2 1 0 -1 ).
Original vector v2b with range sorted by the
binary predicate greater is v2b = ( 3 2 1 0 -1 -2 ).
Original vector v3a with range sorted by the
binary predicate mod_lesser is v3a = ( 0 1 2 3 4 ).
Original vector v3b with range sorted by the
binary predicate mod_lesser is v3b = ( 0 -1 1 -2 2 3 ).
All the elements in vector v1b are contained in vector v1a.
At least one of the elements in vector v2b is not contained in vector v2a.
At least one of the elements in vector v3b is not contained under mod_lesser in vector v3a.
```

## inplace_merge

Combines the elements from two consecutive sorted ranges into a single sorted range, where the ordering criterion may be specified by a binary predicate.

```
template<class BidirectionalIterator>
void inplace_merge(
BidirectionalIterator first,
BidirectionalIterator middle,
BidirectionalIterator last);
template<class BidirectionalIterator, class Compare>
void inplace_merge(
BidirectionalIterator first,
BidirectionalIterator middle,
BidirectionalIterator last,
Compare pred);
template<class ExecutionPolicy, class BidirectionalIterator>
void inplace_merge(
ExecutionPolicy&& exec,
BidirectionalIterator first,
BidirectionalIterator middle,
BidirectionalIterator last);
template<class ExecutionPolicy, class BidirectionalIterator, class Compare>
void inplace_merge(
ExecutionPolicy&& exec,
BidirectionalIterator first,
BidirectionalIterator middle,
BidirectionalIterator last,
Compare pred);
```

### Parameters

*exec*

The execution policy to use.

*first*

A bidirectional iterator addressing the position of the first element in the first of two consecutive sorted ranges to be combined and sorted into a single range.

*middle*

A bidirectional iterator addressing the position of the first element in the second of two consecutive sorted ranges to be combined and sorted into a single range.

*last*

A bidirectional iterator addressing the position one past the last element in the second of two consecutive sorted ranges to be combined and sorted into a single range.

*pred*

User-defined predicate function object that defines the sense in which one element is less than another. The comparison predicate takes two arguments and should return **true** when the first element is less than the second element and **false** otherwise.

### Remarks

The sorted consecutive ranges referenced must be valid; all pointers must be dereferenceable and, within each sequence, the last position must be reachable from the first by incrementation.

The sorted consecutive ranges must each be arranged as a precondition to the application of the `inplace_merge`

algorithm in accordance with the same ordering as is to be used by the algorithm to sort the combined ranges. The operation is stable as the relative order of elements within each range is preserved. When there are equivalent elements in both source ranges, the element is the first range precedes the element from the second in the combined range.

The complexity depends on the available memory as the algorithm allocates memory to a temporary buffer. If sufficient memory is available, the best case is linear with `(last - first) - 1`

comparisons; if no auxiliary memory is available, the worst case is `N log(N)`

, where *N* = *last* - *first*.

### Example

```
// alg_inplace_merge.cpp
// compile with: /EHsc
#include <vector>
#include <algorithm>
#include <functional> //For greater<int>( )
#include <iostream>
// Return whether modulus of elem1 is less than modulus of elem2
bool mod_lesser ( int elem1, int elem2 )
{
if ( elem1 < 0 )
elem1 = - elem1;
if ( elem2 < 0 )
elem2 = - elem2;
return elem1 < elem2;
}
int main()
{
using namespace std;
vector<int> v1;
vector<int>::iterator Iter1, Iter2, Iter3;
// Constructing vector v1 with default less-than ordering
int i;
for ( i = 0 ; i <= 5 ; i++ )
{
v1.push_back( i );
}
int ii;
for ( ii =-5 ; ii <= 0 ; ii++ )
{
v1.push_back( ii );
}
cout << "Original vector v1 with subranges sorted by the\n "
<< "binary predicate less than is v1 = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")" << endl;
// Constructing vector v2 with ranges sorted by greater
vector<int> v2 ( v1 );
vector<int>::iterator break2;
break2 = find ( v2.begin( ), v2.end( ), -5 );
sort ( v2.begin( ), break2 , greater<int>( ) );
sort ( break2 , v2.end( ), greater<int>( ) );
cout << "Original vector v2 with subranges sorted by the\n "
<< "binary predicate greater is v2 = ( " ;
for ( Iter2 = v2.begin( ) ; Iter2 != v2.end( ) ; Iter2++ )
cout << *Iter2 << " ";
cout << ")" << endl;
// Constructing vector v3 with ranges sorted by mod_lesser
vector<int> v3 ( v1 );
vector<int>::iterator break3;
break3 = find ( v3.begin( ), v3.end( ), -5 );
sort ( v3.begin( ), break3 , mod_lesser );
sort ( break3 , v3.end( ), mod_lesser );
cout << "Original vector v3 with subranges sorted by the\n "
<< "binary predicate mod_lesser is v3 = ( " ;
for ( Iter3 = v3.begin( ) ; Iter3 != v3.end( ) ; Iter3++ )
cout << *Iter3 << " ";
cout << ")" << endl;
vector<int>::iterator break1;
break1 = find (v1.begin( ), v1.end( ), -5 );
inplace_merge ( v1.begin( ), break1, v1.end( ) );
cout << "Merged inplace with default order,\n vector v1mod = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")" << endl;
// To merge inplace in descending order, specify binary
// predicate greater<int>( )
inplace_merge ( v2.begin( ), break2 , v2.end( ) , greater<int>( ) );
cout << "Merged inplace with binary predicate greater specified,\n "
<< "vector v2mod = ( " ;
for ( Iter2 = v2.begin( ) ; Iter2 != v2.end( ) ; Iter2++ )
cout << *Iter2 << " ";
cout << ")" << endl;
// Applying a user defined (UD) binary predicate mod_lesser
inplace_merge ( v3.begin( ), break3, v3.end( ), mod_lesser );
cout << "Merged inplace with binary predicate mod_lesser specified,\n "
<< "vector v3mod = ( " ; ;
for ( Iter3 = v3.begin( ) ; Iter3 != v3.end( ) ; Iter3++ )
cout << *Iter3 << " ";
cout << ")" << endl;
}
```

```
Original vector v1 with subranges sorted by the
binary predicate less than is v1 = ( 0 1 2 3 4 5 -5 -4 -3 -2 -1 0 )
Original vector v2 with subranges sorted by the
binary predicate greater is v2 = ( 5 4 3 2 1 0 0 -1 -2 -3 -4 -5 )
Original vector v3 with subranges sorted by the
binary predicate mod_lesser is v3 = ( 0 1 2 3 4 5 0 -1 -2 -3 -4 -5 )
Merged inplace with default order,
vector v1mod = ( -5 -4 -3 -2 -1 0 0 1 2 3 4 5 )
Merged inplace with binary predicate greater specified,
vector v2mod = ( 5 4 3 2 1 0 0 -1 -2 -3 -4 -5 )
Merged inplace with binary predicate mod_lesser specified,
vector v3mod = ( 0 0 1 -1 2 -2 3 -3 4 -4 5 -5 )
```

## is_heap

Returns **true** if the elements in the specified range form a heap.

```
template<class RandomAccessIterator>
bool is_heap(
RandomAccessIterator first,
RandomAccessIterator last);
template<class RandomAccessIterator, class Compare>
bool is_heap(
RandomAccessIterator first,
RandomAccessIterator last,
Compare pred);
template<class ExecutionPolicy, class RandomAccessIterator>
bool is_heap(
ExecutionPolicy&& exec,
RandomAccessIterator first,
RandomAccessIterator last);
template<class ExecutionPolicy, class RandomAccessIterator, class Compare>
bool is_heap(
ExecutionPolicy&& exec,
RandomAccessIterator first,
RandomAccessIterator last,
Compare pred);
```

### Parameters

*exec*

The execution policy to use.

*first*

A random access iterator that indicates the start of a range to check for a heap.

*last*

A random access iterator that indicates the end of a range.

*pred*

A condition to test to order elements. A comparison predicate takes two arguments and returns **true** or **false**.

### Return value

Returns **true** if the elements in the specified range form a heap, **false** if they do not.

### Remarks

The first template function returns is_heap_until`(first , last) == last`

.

The second template function returns

`is_heap_until(first, last, pred) == last`

.

## is_heap_until

Returns an iterator positioned at the first element in the range [ `first`

, `last`

) that does not satisfy the heap ordering condition, or *end* if the range forms a heap.

```
template<class RandomAccessIterator>
RandomAccessIterator is_heap_until(
RandomAccessIterator first,
RandomAccessIterator last);
template<class RandomAccessIterator, class Compare>
RandomAccessIterator is_heap_until(
RandomAccessIterator first,
RandomAccessIterator last,
Compare pred);
template<class ExecutionPolicy, class RandomAccessIterator>
RandomAccessIterator is_heap_until(
ExecutionPolicy&& exec,
RandomAccessIterator first,
RandomAccessIterator last);
template<class ExecutionPolicy, class RandomAccessIterator, class Compare>
RandomAccessIterator is_heap_until(
ExecutionPolicy&& exec,
RandomAccessIterator first,
RandomAccessIterator last,
Compare pred);
```

### Parameters

*exec*

The execution policy to use.

*first*

A random access iterator that specifies the first element of a range to check for a heap.

*last*

A random access iterator that specifies the end of the range to check for a heap.

*pred*

A binary predicate that specifies the strict weak ordering condition that defines a heap. The default predicate is `std::less<>`

when *pred* isn't specified.

### Return value

Returns *last* if the specified range forms a heap or contains one or fewer elements. Otherwise, returns an iterator for the first element found that does not satisfy the heap condition.

### Remarks

The first template function returns the last iterator `next`

in `[first, last)`

where `[first, next)`

is a heap ordered by the function object `std::less<>`

. If the distance `last - first`

is less than 2, the function returns *last*.

The second template function behaves the same as the first, except that it uses the predicate *pred* instead of `std::less<>`

as the heap ordering condition.

## is_partitioned

Returns **true** if all the elements in the given range that test **true** for a condition come before any elements that test **false**.

```
template<class InputIterator, class UnaryPredicate>
bool is_partitioned(
InputIterator first,
InputIterator last,
UnaryPredicate pred);
template <class ExecutionPolicy, class ForwardIterator, class UnaryPredicate>
bool is_partitioned(
ExecutionPolicy&& exec,
ForwardIterator first,
ForwardIterator last,
UnaryPredicate pred);
```

### Parameters

*exec*

The execution policy to use.

*first*

An input iterator that indicates where a range starts to check for a condition.

*last*

An input iterator that indicates the end of a range.

*pred*

The condition to test for. This is provided by a user-defined predicate function object that defines the condition to be satisfied by the element being searched for. A unary predicate takes a single argument and returns **true** or **false**.

### Return value

Returns **true** when all of the elements in the given range that test **true** for a condition come before any elements that test **false**, and otherwise, returns **false**.

### Remarks

The template function returns **true** only if all elements in `[first, last)`

are partitioned by *pred*; that is, all elements `X`

in `[first, last)`

for which `pred (X)`

is true occur before all elements `Y`

for which `pred (Y)`

is **false**.

## is_permutation

Returns true if both ranges contain the same elements, whether or not the elements are in the same order. Use the dual-range overloads in C++14 code because the overloads that only take a single iterator for the second range will not detect differences if the second range is longer than the first range, and will result in undefined behavior if the second range is shorter than the first range.

```
template<class ForwardIterator1, class ForwardIterator2>
bool is_permutation(
ForwardIterator1 first1,
ForwardIterator1 last1,
ForwardIterator2 first2);
template<class ForwardIterator1, class ForwardIterator2, class BinaryPredicate>
bool is_permutation(
ForwardIterator1 first1,
ForwardIterator1 last1,
ForwardIterator2 first2,
BinaryPredicate Pred);
// C++14
template<class ForwardIterator1, class ForwardIterator2>
bool is_permutation(
ForwardIterator1 first1,
ForwardIterator1 last1,
ForwardIterator2 first2,
ForwardIterator2 last2);
template<class ForwardIterator1, class ForwardIterator2, class BinaryPredicate>
bool is_permutation(
ForwardIterator1 first1,
ForwardIterator1 last1,
ForwardIterator2 first2,
ForwardIterator2 last2,
BinaryPredicate pred);
```

### Parameters

*first1*

A forward iterator that refers to the first element of the range.

*last1*

A forward iterator that refers one past the last element of the range.

*first2*

A forward iterator that refers to the first element of a second range, used for comparison.

*last2*

A forward iterator that refers to one past the last element of a second range, used for comparison.

*pred*

A predicate that tests for equivalence and returns a **bool**.

### Return value

**true** when the ranges can be rearranged so as to be identical according to the comparator predicate; otherwise, **false**.

### Remarks

`is_permutation`

has quadratic complexity in the worst case.

The first template function assumes that there are as many elements in the range beginning at *first2* as there are in the range designated by `[first1, last1)`

. If there are more elements in the second range, they are ignored; if there are less, undefined behavior will occur. The third template function (C++14 and later) does not make this assumption. Both return **true** only if, for each element X in the range designated by `[first1, last1)`

there are as many elements Y in the same range for which X == Y as there are in the range beginning at *first2* or `[first2, last2)`

. Here, `operator==`

must perform a pairwise comparison between its operands.

The second and fourth template functions behave the same, except that they replace `operator==(X, Y)`

with `Pred(X, Y)`

. To behave correctly, the predicate must be symmetric, reflexive and transitive.

### Example

The following example shows how to use `is_permutation`

:

```
#include <vector>
#include <iostream>
#include <algorithm>
#include <string>
using namespace std;
int main()
{
vector<int> vec_1{ 2, 3, 0, 1, 4, 5 };
vector<int> vec_2{ 5, 4, 0, 3, 1, 2 };
vector<int> vec_3{ 4, 9, 13, 3, 6, 5 };
vector<int> vec_4{ 7, 4, 11, 9, 2, 1 };
cout << "(1) Compare using built-in == operator: ";
cout << boolalpha << is_permutation(vec_1.begin(), vec_1.end(),
vec_2.begin(), vec_2.end()) << endl; // true
cout << "(2) Compare after modifying vec_2: ";
vec_2[0] = 6;
cout << is_permutation(vec_1.begin(), vec_1.end(),
vec_2.begin(), vec_2.end()) << endl; // false
// Define equivalence as "both are odd or both are even"
cout << "(3) vec_3 is a permutation of vec_4: ";
cout << is_permutation(vec_3.begin(), vec_3.end(),
vec_4.begin(), vec_4.end(),
[](int lhs, int rhs) { return lhs % 2 == rhs % 2; }) << endl; // true
// Initialize a vector using the 's' string literal to specify a std::string
vector<string> animals_1{ "dog"s, "cat"s, "bird"s, "monkey"s };
vector<string> animals_2{ "donkey"s, "bird"s, "meerkat"s, "cat"s };
// Define equivalence as "first letters are equal":
bool is_perm = is_permutation(animals_1.begin(), animals_1.end(), animals_2.begin(), animals_2.end(),
[](const string& lhs, const string& rhs)
{
return lhs[0] == rhs[0]; //std::string guaranteed to have at least a null terminator
});
cout << "animals_2 is a permutation of animals_1: " << is_perm << endl; // true
cout << "Press a letter" << endl;
char c;
cin >> c;
return 0;
}
```

## is_sorted

Returns **true** if the elements in the specified range are in sorted order.

```
template<class ForwardIterator>
bool is_sorted(
ForwardIterator first,
ForwardIterator last);
template<class ForwardIterator, class Compare>
bool is_sorted(
ForwardIterator first,
ForwardIterator last,
Compare pred);
template<class ExecutionPolicy, class ForwardIterator>
bool is_sorted(
ExecutionPolicy&& exec,
ForwardIterator first,
ForwardIterator last);
template<class ExecutionPolicy, class ForwardIterator, class Compare>
bool is_sorted(
ExecutionPolicy&& exec,
ForwardIterator first,
ForwardIterator last,
Compare pred);
```

### Parameters

*exec*

The execution policy to use.

*first*

A forward iterator that indicates where the range to check begins.

*last*

A forward iterator that indicates the end of a range.

*pred*

The condition to test to determine an order between two elements. A comparison predicate takes two arguments and returns **true** or **false**. This performs the same task as `operator<`

.

### Remarks

The first template function returns is_sorted_until`( first, last ) == last`

. The `operator<`

function performs the order comparison.

The second template function returns `is_sorted_until( first, last , pred ) == last`

. The *pred* predicate function performs the order comparison.

## is_sorted_until

Returns a `ForwardIterator`

that is set to the last element that is in sorted order from a specified range.

The second version lets you provide a comparison function object that returns **true** when two given elements are in sorted order, and **false** otherwise.

```
template<class ForwardIterator>
ForwardIterator is_sorted_until(
ForwardIterator first,
ForwardIterator last);
template<class ForwardIterator, class Compare>
ForwardIterator is_sorted_until(
ForwardIterator first,
ForwardIterator last,
Compare pred);
template<class ExecutionPolicy, class ForwardIterator>
ForwardIterator is_sorted_until(
ExecutionPolicy&& exec,
ForwardIterator first,
ForwardIterator last);
template<class ExecutionPolicy, class ForwardIterator, class Compare>
ForwardIterator is_sorted_until(
ExecutionPolicy&& exec,
ForwardIterator first,
ForwardIterator last,
Compare pred);
```

### Parameters

*exec*

The execution policy to use.

*first*

A forward iterator that indicates where the range to check starts.

*last*

A forward iterator that indicates the end of a range.

*pred*

The condition to test to determine an order between two elements. A comparison predicate takes two arguments and returns **true** or **false**.

### Return value

Returns a `ForwardIterator`

set to the last element in sorted order. The sorted sequence starts from *first*.

### Remarks

The first template function returns the last iterator `next`

in `[first, last]`

so that `[first, next)`

is a sorted sequence ordered by `operator<`

. If `distance()`

is less than 2, the function returns *last*.

The second template function behaves the same, except that it replaces `operator<(X, Y)`

with `pred(X, Y)`

.

## iter_swap

Exchanges two values referred to by a pair of specified iterators.

```
template<class ForwardIterator1, class ForwardIterator2>
void iter_swap( ForwardIterator1 left, ForwardIterator2 right );
```

### Parameters

*left*

One of the forward iterators whose value is to be exchanged.

*right*

The second of the forward iterators whose value is to be exchanged.

### Remarks

`swap`

should be used in preference to **iter_swap**, which was included in the C++ Standard for backward compatibility. If `Fit1`

and `Fit2`

are forward iterators, then `iter_swap( Fit1, Fit2 )`

, is equivalent to `swap( *Fit1, *Fit2 )`

.

The value types of the input forward iterators must have the same value.

### Example

```
// alg_iter_swap.cpp
// compile with: /EHsc
#include <vector>
#include <deque>
#include <algorithm>
#include <iostream>
#include <ostream>
using namespace std;
class CInt;
ostream& operator<<( ostream& osIn, const CInt& rhs );
class CInt
{
public:
CInt( int n = 0 ) : m_nVal( n ){}
CInt( const CInt& rhs ) : m_nVal( rhs.m_nVal ){}
CInt& operator=( const CInt& rhs ) { m_nVal =
rhs.m_nVal; return *this; }
bool operator<( const CInt& rhs ) const
{ return ( m_nVal < rhs.m_nVal );}
friend ostream& operator<<( ostream& osIn, const CInt& rhs );
private:
int m_nVal;
};
inline ostream& operator<<( ostream& osIn, const CInt& rhs )
{
osIn << "CInt(" << rhs.m_nVal << ")";
return osIn;
}
// Return whether modulus of elem1 is less than modulus of elem2
bool mod_lesser ( int elem1, int elem2 )
{
if ( elem1 < 0 )
elem1 = - elem1;
if ( elem2 < 0 )
elem2 = - elem2;
return elem1 < elem2;
};
int main()
{
CInt c1 = 5, c2 = 1, c3 = 10;
deque<CInt> deq1;
deque<CInt>::iterator d1_Iter;
deq1.push_back ( c1 );
deq1.push_back ( c2 );
deq1.push_back ( c3 );
cout << "The original deque of CInts is deq1 = (";
for ( d1_Iter = deq1.begin( ); d1_Iter != --deq1.end( ); d1_Iter++ )
cout << " " << *d1_Iter << ",";
d1_Iter = --deq1.end( );
cout << " " << *d1_Iter << " )." << endl;
// Exchanging first and last elements with iter_swap
iter_swap ( deq1.begin( ), --deq1.end( ) );
cout << "The deque of CInts with first & last elements swapped is:\n deq1 = (";
for ( d1_Iter = deq1.begin( ); d1_Iter != --deq1.end( ); d1_Iter++ )
cout << " " << *d1_Iter << ",";
d1_Iter = --deq1.end( );
cout << " " << *d1_Iter << " )." << endl;
// Swapping back first and last elements with swap
swap ( *deq1.begin( ), *(deq1.end( ) -1 ) );
cout << "The deque of CInts with first & last elements swapped back is:\n deq1 = (";
for ( d1_Iter = deq1.begin( ); d1_Iter != --deq1.end( ); d1_Iter++ )
cout << " " << *d1_Iter << ",";
d1_Iter = --deq1.end( );
cout << " " << *d1_Iter << " )." << endl;
// Swapping a vector element with a deque element
vector<int> v1;
vector<int>::iterator Iter1;
deque<int> deq2;
deque<int>::iterator d2_Iter;
int i;
for ( i = 0 ; i <= 3 ; i++ )
{
v1.push_back( i );
}
int ii;
for ( ii = 4 ; ii <= 5 ; ii++ )
{
deq2.push_back( ii );
}
cout << "Vector v1 is ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
cout << "Deque deq2 is ( " ;
for ( d2_Iter = deq2.begin( ) ; d2_Iter != deq2.end( ) ; d2_Iter++ )
cout << *d2_Iter << " ";
cout << ")." << endl;
iter_swap ( v1.begin( ), deq2.begin( ) );
cout << "After exchanging first elements,\n vector v1 is: v1 = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl << " & deque deq2 is: deq2 = ( ";
for ( d2_Iter = deq2.begin( ) ; d2_Iter != deq2.end( ) ; d2_Iter++ )
cout << *d2_Iter << " ";
cout << ")." << endl;
}
```

```
The original deque of CInts is deq1 = ( CInt(5), CInt(1), CInt(10) ).
The deque of CInts with first & last elements swapped is:
deq1 = ( CInt(10), CInt(1), CInt(5) ).
The deque of CInts with first & last elements swapped back is:
deq1 = ( CInt(5), CInt(1), CInt(10) ).
Vector v1 is ( 0 1 2 3 ).
Deque deq2 is ( 4 5 ).
After exchanging first elements,
vector v1 is: v1 = ( 4 1 2 3 ).
& deque deq2 is: deq2 = ( 0 5 ).
```

## lexicographical_compare

Compares element by element between two sequences to determine which is lesser of the two.

```
template<class InputIterator1, class InputIterator2>
bool lexicographical_compare(
InputIterator1 first1,
InputIterator1 last1,
InputIterator2 first2,
InputIterator2 last2 );
template<class InputIterator1, class InputIterator2, class Compare>
bool lexicographical_compare(
InputIterator1 first1,
InputIterator1 last1,
InputIterator2 first2,
InputIterator2 last2,
Compare pred );
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2>
bool lexicographical_compare(
ExecutionPolicy&& exec,
ForwardIterator1 first1,
ForwardIterator1 last1,
ForwardIterator2 first2,
ForwardIterator2 last2);
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class Compare>
bool lexicographical_compare(
ExecutionPolicy&& exec,
ForwardIterator1 first1,
ForwardIterator1 last1,
ForwardIterator2 first2,
ForwardIterator2 last2,
Compare pred);
```

### Parameters

*exec*

The execution policy to use.

*first1*

An input iterator addressing the position of the first element in the first range to be compared.

*last1*

An input iterator addressing the position one past the final element in the first range to be compared.

*first2*

An input iterator addressing the position of the first element in the second range to be compared.

*last2*

An input iterator addressing the position one past the final element in the second range to be compared.

*pred*

User-defined predicate function object that defines sense in which one element is less than another. A comparison predicate takes two arguments and returns **true** when satisfied and **false** when not satisfied.

### Return value

**true** if the first range is lexicographically less than the second range; otherwise **false**.

### Remarks

A lexicographical comparison between sequences compares them element by element until:

It finds two corresponding elements unequal, and the result of their comparison is taken as the result of the comparison between sequences.

No inequalities are found, but one sequence has more elements than the other, and the shorter sequence is considered less than the longer sequence.

No inequalities are found and the sequences have the same number of elements, and so the sequences are equal and the result of the comparison is

**false**.

### Example

```
// alg_lex_comp.cpp
// compile with: /EHsc
#include <vector>
#include <list>
#include <algorithm>
#include <iostream>
// Return whether second element is twice the first
bool twice ( int elem1, int elem2 )
{
return 2 * elem1 < elem2;
}
int main()
{
using namespace std;
vector<int> v1, v2;
list<int> L1;
vector<int>::iterator Iter1, Iter2;
list<int>::iterator L1_Iter, L1_inIter;
int i;
for ( i = 0 ; i <= 5 ; i++ )
{
v1.push_back( 5 * i );
}
int ii;
for ( ii = 0 ; ii <= 6 ; ii++ )
{
L1.push_back( 5 * ii );
}
int iii;
for ( iii = 0 ; iii <= 5 ; iii++ )
{
v2.push_back( 10 * iii );
}
cout << "Vector v1 = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")" << endl;
cout << "List L1 = ( " ;
for ( L1_Iter = L1.begin( ) ; L1_Iter!= L1.end( ) ; L1_Iter++ )
cout << *L1_Iter << " ";
cout << ")" << endl;
cout << "Vector v2 = ( " ;
for ( Iter2 = v2.begin( ) ; Iter2 != v2.end( ) ; Iter2++ )
cout << *Iter2 << " ";
cout << ")" << endl;
// Self lexicographical_comparison of v1 under identity
bool result1;
result1 = lexicographical_compare (v1.begin( ), v1.end( ),
v1.begin( ), v1.end( ) );
if ( result1 )
cout << "Vector v1 is lexicographically_less than v1." << endl;
else
cout << "Vector v1 is not lexicographically_less than v1." << endl;
// lexicographical_comparison of v1 and L2 under identity
bool result2;
result2 = lexicographical_compare (v1.begin( ), v1.end( ),
L1.begin( ), L1.end( ) );
if ( result2 )
cout << "Vector v1 is lexicographically_less than L1." << endl;
else
cout << "Vector v1 is lexicographically_less than L1." << endl;
bool result3;
result3 = lexicographical_compare (v1.begin( ), v1.end( ),
v2.begin( ), v2.end( ), twice );
if ( result3 )
cout << "Vector v1 is lexicographically_less than v2 "
<< "under twice." << endl;
else
cout << "Vector v1 is not lexicographically_less than v2 "
<< "under twice." << endl;
}
```

```
Vector v1 = ( 0 5 10 15 20 25 )
List L1 = ( 0 5 10 15 20 25 30 )
Vector v2 = ( 0 10 20 30 40 50 )
Vector v1 is not lexicographically_less than v1.
Vector v1 is lexicographically_less than L1.
Vector v1 is not lexicographically_less than v2 under twice.
```

## lower_bound

Finds the position of the first element in an ordered range that has a value greater than or equivalent to a specified value, where the ordering criterion may be specified by a binary predicate.

```
template<class ForwardIterator, class Type>
ForwardIterator lower_bound(
ForwardIterator first,
ForwardIterator last,
const Type& value );
template<class ForwardIterator, class Type, class BinaryPredicate>
ForwardIterator lower_bound(
ForwardIterator first,
ForwardIterator last,
const Type& value,
BinaryPredicate pred );
```

### Parameters

*first*

A forward iterator addressing the position of the first element in the range to be searched.

*last*

A forward iterator addressing the position one past the final element in the range to be searched.

*value*

The value whose first position or possible first position is being searched for in the ordered range.

*pred*

User-defined predicate function object that defines sense in which one element is less than another. A binary predicate takes two arguments and returns **true** when satisfied and **false** when not satisfied.

### Return value

A forward iterator at the position of the first element in an ordered range with a value that is greater than or equivalent to a specified value, where the equivalence is specified with a binary predicate.

### Remarks

The sorted source range referenced must be valid; all iterators must be dereferenceable and within the sequence the last position must be reachable from the first by incrementation.

A sorted range is a precondition of using `lower_bound`

and where the ordering is the same as specified by with binary predicate.

The range is not modified by the algorithm `lower_bound`

.

The value types of the forward iterators need be less-than comparable to be ordered, so that, given two elements, it may be determined either that they are equivalent (in the sense that neither is less than the other) or that one is less than the other. This results in an ordering between the nonequivalent elements

The complexity of the algorithm is logarithmic for random-access iterators and linear otherwise, with the number of steps proportional to (`last - first`

).

### Example

```
// alg_lower_bound.cpp
// compile with: /EHsc
#include <vector>
#include <algorithm>
#include <functional> // greater<int>( )
#include <iostream>
// Return whether modulus of elem1 is less than modulus of elem2
bool mod_lesser( int elem1, int elem2 )
{
if ( elem1 < 0 )
elem1 = - elem1;
if ( elem2 < 0 )
elem2 = - elem2;
return elem1 < elem2;
}
int main()
{
using namespace std;
vector<int> v1;
// Constructing vector v1 with default less-than ordering
for ( auto i = -1 ; i <= 4 ; ++i )
{
v1.push_back( i );
}
for ( auto ii =-3 ; ii <= 0 ; ++ii )
{
v1.push_back( ii );
}
cout << "Starting vector v1 = ( " ;
for (const auto &Iter : v1)
cout << Iter << " ";
cout << ")." << endl;
sort(v1.begin(), v1.end());
cout << "Original vector v1 with range sorted by the\n "
<< "binary predicate less than is v1 = ( " ;
for (const auto &Iter : v1)
cout << Iter << " ";
cout << ")." << endl;
// Constructing vector v2 with range sorted by greater
vector<int> v2(v1);
sort(v2.begin(), v2.end(), greater<int>());
cout << "Original vector v2 with range sorted by the\n "
<< "binary predicate greater is v2 = ( " ;
for (const auto &Iter : v2)
cout << Iter << " ";
cout << ")." << endl;
// Constructing vectors v3 with range sorted by mod_lesser
vector<int> v3(v1);
sort(v3.begin(), v3.end(), mod_lesser);
cout << "Original vector v3 with range sorted by the\n "
<< "binary predicate mod_lesser is v3 = ( " ;
for (const auto &Iter : v3)
cout << Iter << " ";
cout << ")." << endl;
// Demonstrate lower_bound
vector<int>::iterator Result;
// lower_bound of 3 in v1 with default binary predicate less<int>()
Result = lower_bound(v1.begin(), v1.end(), 3);
cout << "The lower_bound in v1 for the element with a value of 3 is: "
<< *Result << "." << endl;
// lower_bound of 3 in v2 with the binary predicate greater<int>( )
Result = lower_bound(v2.begin(), v2.end(), 3, greater<int>());
cout << "The lower_bound in v2 for the element with a value of 3 is: "
<< *Result << "." << endl;
// lower_bound of 3 in v3 with the binary predicate mod_lesser
Result = lower_bound(v3.begin(), v3.end(), 3, mod_lesser);
cout << "The lower_bound in v3 for the element with a value of 3 is: "
<< *Result << "." << endl;
}
```

## make_heap

Converts elements from a specified range into a heap in which the first element is the largest and for which a sorting criterion may be specified with a binary predicate.

```
template<class RandomAccessIterator>
void make_heap(
RandomAccessIterator first,
RandomAccessIterator last );
template<class RandomAccessIterator, class BinaryPredicate>
void make_heap(
RandomAccessIterator first,
RandomAccessIterator last,
BinaryPredicate pred );
```

### Parameters

*first*

A random-access iterator addressing the position of the first element in the range to be converted into a heap.

*last*

A random-access iterator addressing the position one past the final element in the range to be converted into a heap.

*pred*

User-defined predicate function object that defines sense in which one element is less than another. A binary predicate takes two arguments and returns **true** when satisfied and **false** when not satisfied.

### Remarks

Heaps have two properties:

The first element is always the largest.

Elements may be added or removed in logarithmic time.

Heaps are an ideal way to implement priority queues and they are used in the implementation of the C++ Standard Library container adaptor priority_queue Class.

The complexity is linear, requiring `3 * (last - first)`

comparisons.

### Example

```
// alg_make_heap.cpp
// compile with: /EHsc
#include <vector>
#include <algorithm>
#include <functional>
#include <iostream>
int main() {
using namespace std;
vector<int> v1, v2;
vector<int>::iterator Iter1, Iter2;
int i;
for ( i = 0 ; i <= 9 ; i++ )
v1.push_back( i );
random_shuffle( v1.begin( ), v1.end( ) );
cout << "Vector v1 is ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
// Make v1 a heap with default less than ordering
make_heap ( v1.begin( ), v1.end( ) );
cout << "The heaped version of vector v1 is ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
// Make v1 a heap with greater than ordering
make_heap ( v1.begin( ), v1.end( ), greater<int>( ) );
cout << "The greater-than heaped version of v1 is ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
}
```

## max

Compares two objects and returns the larger of the two, where the ordering criterion may be specified by a binary predicate.

```
template<class Type>
constexpr Type& max(
const Type& left,
const Type& right);
template<class Type, class Pr>
constexpr Type& max(
const Type& left,
const Type& right,
BinaryPredicate pred);
template<class Type>
constexpr Type& max (
initializer_list<Type> ilist);
template<class Type, class Pr>
constexpr Type& max(
initializer_list<Type> ilist,
BinaryPredicate pred);
```

### Parameters

*left*

The first of the two objects being compared.

*right*

The second of the two objects being compared.

*pred*

A binary predicate used to compare the two objects.

*inlist*

The initializer list that contains the objects to be compared.

### Return value

The greater of the two objects, unless neither is greater; in that case, it returns the first of the two objects. In the case of an initializer_list, it returns the greatest of the objects in the list.

### Remarks

The `max`

algorithm is unusual in having objects passed as parameters. Most C++ Standard Library algorithms operate on a range of elements whose position is specified by iterators passed as parameters. If you need a function that operates on a range of elements, use max_element instead. Visual Studio 2017 enables **constexpr** on the overloads that take an initializer_list.

### Example

```
// alg_max.cpp
// compile with: /EHsc
#include <vector>
#include <set>
#include <algorithm>
#include <iostream>
#include <ostream>
using namespace std;
class CInt;
ostream& operator<<( ostream& osIn, const CInt& rhs );
class CInt
{
public:
CInt( int n = 0 ) : m_nVal( n ){}
CInt( const CInt& rhs ) : m_nVal( rhs.m_nVal ){}
CInt& operator=( const CInt& rhs ) {m_nVal =
rhs.m_nVal; return *this;}
bool operator<( const CInt& rhs ) const
{return ( m_nVal < rhs.m_nVal );}
friend ostream& operator<<( ostream& osIn, const CInt& rhs );
private:
int m_nVal;
};
inline ostream& operator<<( ostream& osIn, const CInt& rhs )
{
osIn << "CInt( " << rhs.m_nVal << " )";
return osIn;
}
// Return whether absolute value of elem1 is greater than
// absolute value of elem2
bool abs_greater ( int elem1, int elem2 )
{
if ( elem1 < 0 )
elem1 = -elem1;
if ( elem2 < 0 )
elem2 = -elem2;
return elem1 < elem2;
};
int main()
{
int a = 6, b = -7;
// Return the integer with the larger absolute value
const int& result1 = max(a, b, abs_greater);
// Return the larger integer
const int& result2 = max(a, b);
cout << "Using integers 6 and -7..." << endl;
cout << "The integer with the greater absolute value is: "
<< result1 << "." << endl;
cout << "The integer with the greater value is: "
<< result2 << "." << endl;
cout << endl;
// Comparing the members of an initializer_list
const int& result3 = max({ a, b });
const int& result4 = max({ a, b }, abs_greater);
cout << "Comparing the members of an initializer_list..." << endl;
cout << "The member with the greater value is: " << result3 << endl;
cout << "The integer with the greater absolute value is: " << result4 << endl;
// Comparing set containers with elements of type CInt
// using the max algorithm
CInt c1 = 1, c2 = 2, c3 = 3;
set<CInt> s1, s2, s3;
set<CInt>::iterator s1_Iter, s2_Iter, s3_Iter;
s1.insert ( c1 );
s1.insert ( c2 );
s2.insert ( c2 );
s2.insert ( c3 );
cout << "s1 = (";
for ( s1_Iter = s1.begin( ); s1_Iter != --s1.end( ); s1_Iter++ )
cout << " " << *s1_Iter << ",";
s1_Iter = --s1.end( );
cout << " " << *s1_Iter << " )." << endl;
cout << "s2 = (";
for ( s2_Iter = s2.begin( ); s2_Iter != --s2.end( ); s2_Iter++ )
cout << " " << *s2_Iter << ",";
s2_Iter = --s2.end( );
cout << " " << *s2_Iter << " )." << endl;
s3 = max ( s1, s2 );
cout << "s3 = max ( s1, s2 ) = (";
for ( s3_Iter = s3.begin( ); s3_Iter != --s3.end( ); s3_Iter++ )
cout << " " << *s3_Iter << ",";
s3_Iter = --s3.end( );
cout << " " << *s3_Iter << " )." << endl << endl;
// Comparing vectors with integer elements using the max algorithm
vector<int> v1, v2, v3, v4, v5;
vector<int>::iterator Iter1, Iter2, Iter3, Iter4, Iter5;
int i;
for ( i = 0 ; i <= 2 ; i++ )
{
v1.push_back( i );
}
int ii;
for ( ii = 0 ; ii <= 2 ; ii++ )
{
v2.push_back( ii );
}
int iii;
for ( iii = 0 ; iii <= 2 ; iii++ )
{
v3.push_back( 2 * iii );
}
cout << "Vector v1 is ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
cout << "Vector v2 is ( " ;
for ( Iter2 = v2.begin( ) ; Iter2 != v2.end( ) ; Iter2++ )
cout << *Iter2 << " ";
cout << ")." << endl;
cout << "Vector v3 is ( " ;
for ( Iter3 = v3.begin( ) ; Iter3 != v3.end( ) ; Iter3++ )
cout << *Iter3 << " ";
cout << ")." << endl;
v4 = max ( v1, v2 );
v5 = max ( v1, v3 );
cout << "Vector v4 = max (v1,v2) is ( " ;
for ( Iter4 = v4.begin( ) ; Iter4 != v4.end( ) ; Iter4++ )
cout << *Iter4 << " ";
cout << ")." << endl;
cout << "Vector v5 = max (v1,v3) is ( " ;
for ( Iter5 = v5.begin( ) ; Iter5 != v5.end( ) ; Iter5++ )
cout << *Iter5 << " ";
cout << ")." << endl;
}
```

```
Using integers 6 and -7...
The integer with the greater absolute value is: -7
The integer with the greater value is: 6.
Comparing the members of an initializer_list...The member with the greater value is: 6The integer wiht the greater absolute value is: -7
s1 = ( CInt( 1 ), CInt( 2 ) ).
s2 = ( CInt( 2 ), CInt( 3 ) ).
s3 = max ( s1, s2 ) = ( CInt( 2 ), CInt( 3 ) ).
Vector v1 is ( 0 1 2 ).
Vector v2 is ( 0 1 2 ).
Vector v3 is ( 0 2 4 ).
Vector v4 = max (v1,v2) is ( 0 1 2 ).
Vector v5 = max (v1,v3) is ( 0 2 4 ).
```

## max_element

Finds the first occurrence of largest element in a specified range where the ordering criterion may be specified by a binary predicate.

```
template<class ForwardIterator>
constexpr ForwardIterator max_element(
ForwardIterator first,
ForwardIterator last );
template<class ForwardIterator, class Compare>
constexpr ForwardIterator max_element(
ForwardIterator first,
ForwardIterator last,
Compare pred );
template<class ExecutionPolicy, class ForwardIterator>
ForwardIterator max_element(
ExecutionPolicy&& exec,
ForwardIterator first,
ForwardIterator last);
template<class ExecutionPolicy, class ForwardIterator, class Compare>
ForwardIterator max_element(
ExecutionPolicy&& exec,
ForwardIterator first,
ForwardIterator last,
Compare pred);
```

### Parameters

*exec*

The execution policy to use.

*first*

A forward iterator addressing the position of the first element in the range to be searched for the largest element.

*last*

A forward iterator addressing the position one past the final element in the range to be searched for the largest element.

*pred*

User-defined predicate function object that defines the sense in which one element is less than another. The comparison predicate takes two arguments and should return **true** when the first element is less than the second element and **false** otherwise.

### Return value

A forward iterator addressing the position of the first occurrence of the largest element in the range searched.

### Remarks

The range referenced must be valid; all pointers must be dereferenceable and within each sequence the last position is reachable from the first by incrementation.

The complexity is linear: `(last - first) - 1`

comparisons are required for a nonempty range.

### Example

```
// alg_max_element.cpp
// compile with: /EHsc
#include <vector>
#include <set>
#include <algorithm>
#include <iostream>
#include <ostream>
using namespace std;
class CInt;
ostream& operator<<( ostream& osIn, const CInt& rhs );
class CInt
{
public:
CInt( int n = 0 ) : m_nVal( n ){}
CInt( const CInt& rhs ) : m_nVal( rhs.m_nVal ){}
CInt& operator=( const CInt& rhs ) {m_nVal =
rhs.m_nVal; return *this;}
bool operator<( const CInt& rhs ) const
{return ( m_nVal < rhs.m_nVal );}
friend ostream& operator<<( ostream& osIn, const CInt& rhs );
private:
int m_nVal;
};
inline ostream& operator<<(ostream& osIn, const CInt& rhs)
{
osIn << "CInt( " << rhs.m_nVal << " )";
return osIn;
}
// Return whether modulus of elem1 is greater than modulus of elem2
bool mod_lesser ( int elem1, int elem2 )
{
if ( elem1 < 0 )
elem1 = - elem1;
if ( elem2 < 0 )
elem2 = - elem2;
return elem1 < elem2;
};
int main()
{
// Searching a set container with elements of type CInt
// for the maximum element
CInt c1 = 1, c2 = 2, c3 = -3;
set<CInt> s1;
set<CInt>::iterator s1_Iter, s1_R1_Iter, s1_R2_Iter;
s1.insert ( c1 );
s1.insert ( c2 );
s1.insert ( c3 );
cout << "s1 = (";
for ( s1_Iter = s1.begin( ); s1_Iter != --s1.end( ); s1_Iter++ )
cout << " " << *s1_Iter << ",";
s1_Iter = --s1.end( );
cout << " " << *s1_Iter << " )." << endl;
s1_R1_Iter = max_element ( s1.begin( ), s1.end( ) );
cout << "The largest element in s1 is: " << *s1_R1_Iter << endl;
cout << endl;
// Searching a vector with elements of type int for the maximum
// element under default less than & mod_lesser binary predicates
vector<int> v1;
vector<int>::iterator v1_Iter, v1_R1_Iter, v1_R2_Iter;
int i;
for ( i = 0 ; i <= 3 ; i++ )
{
v1.push_back( i );
}
int ii;
for ( ii = 1 ; ii <= 4 ; ii++ )
{
v1.push_back( - 2 * ii );
}
cout << "Vector v1 is ( " ;
for ( v1_Iter = v1.begin( ) ; v1_Iter != v1.end( ) ; v1_Iter++ )
cout << *v1_Iter << " ";
cout << ")." << endl;
v1_R1_Iter = max_element ( v1.begin( ), v1.end( ) );
v1_R2_Iter = max_element ( v1.begin( ), v1.end( ), mod_lesser);
cout << "The largest element in v1 is: " << *v1_R1_Iter << endl;
cout << "The largest element in v1 under the mod_lesser"
<< "\n binary predicate is: " << *v1_R2_Iter << endl;
}
```

## merge

Combines all of the elements from two sorted source ranges into a single, sorted destination range, where the ordering criterion may be specified by a binary predicate.

```
template<class InputIterator1, class InputIterator2, class OutputIterator>
OutputIterator merge(
InputIterator1 first1,
InputIterator1 last1,
InputIterator2 first2,
InputIterator2 last2,
OutputIterator result );
template<class InputIterator1, class InputIterator2, class OutputIterator, class Compare>
OutputIterator merge(
InputIterator1 first1,
InputIterator1 last1,
InputIterator2 first2,
InputIterator2 last2,
OutputIterator result,
Compare pred );
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class ForwardIterator>
ForwardIterator merge(
ExecutionPolicy&& exec,
ForwardIterator1 first1,
ForwardIterator1 last1,
ForwardIterator2 first2,
ForwardIterator2 last2,
ForwardIterator result);
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class ForwardIterator, class Compare>
ForwardIterator merge(
ExecutionPolicy&& exec,
ForwardIterator1 first1,
ForwardIterator1 last1,
ForwardIterator2 first2,
ForwardIterator2 last2,
ForwardIterator result,
Compare pred);
```

### Parameters

*exec*

The execution policy to use.

*first1*

An input iterator addressing the position of the first element in the first of two sorted source ranges to be combined and sorted into a single range.

*last1*

An input iterator addressing the position one past the last element in the first of two sorted source ranges to be combined and sorted into a single range.

*first2*

An input iterator addressing the position of the first element in second of two consecutive sorted source ranges to be combined and sorted into a single range.

*last2*

An input iterator addressing the position one past the last element in second of two consecutive sorted source ranges to be combined and sorted into a single range.

*result*

An output iterator addressing the position of the first element in the destination range where the two source ranges are to be combined into a single sorted range.

*pred*

User-defined predicate function object that defines the sense in which one element is less than another. The comparison predicate takes two arguments and should return **true** when the first element is less than the second element, and **false** otherwise.

### Return value

An output iterator addressing the position one past the last element in the sorted destination range.

### Remarks

The sorted source ranges referenced must be valid; all pointers must be dereferenceable and within each sequence the last position must be reachable from the first by incrementation.

The destination range should not overlap either of the source ranges and should be large enough to contain the destination range.

The sorted source ranges must each be arranged as a precondition to the application of the `merge`

algorithm in accordance with the same ordering as is to be used by the algorithm to sort the combined ranges.

The operation is stable as the relative order of elements within each range is preserved in the destination range. The source ranges are not modified by the algorithm `merge`

.

The value types of the input iterators need be less-than comparable to be ordered, so that, given two elements, it may be determined either that they are equivalent (in the sense that neither is less than the other) or that one is less than the other. This results in an ordering between the nonequivalent elements. When there are equivalent elements in both source ranges, the elements in the first range precede the elements from the second source range in the destination range.

The complexity of the algorithm is linear with at most `(last1 - first1) - (last2 - first2) - 1`

comparisons.

The list class provides a member function "merge" to merge the elements of two lists.

### Example

```
// alg_merge.cpp
// compile with: /EHsc
#include <vector>
#include <algorithm>
#include <functional> // For greater<int>( )
#include <iostream>
// Return whether modulus of elem1 is less than modulus of elem2
bool mod_lesser ( int elem1, int elem2 ) {
if (elem1 < 0)
elem1 = - elem1;
if (elem2 < 0)
elem2 = - elem2;
return elem1 < elem2;
}
int main() {
using namespace std;
vector<int> v1a, v1b, v1 ( 12 );
vector<int>::iterator Iter1a, Iter1b, Iter1;
// Constructing vector v1a and v1b with default less than ordering
int i;
for ( i = 0 ; i <= 5 ; i++ )
v1a.push_back( i );
int ii;
for ( ii =-5 ; ii <= 0 ; ii++ )
v1b.push_back( ii );
cout << "Original vector v1a with range sorted by the\n "
<< "binary predicate less than is v1a = ( " ;
for ( Iter1a = v1a.begin( ) ; Iter1a != v1a.end( ) ; Iter1a++ )
cout << *Iter1a << " ";
cout << ")." << endl;
cout << "Original vector v1b with range sorted by the\n "
<< "binary predicate less than is v1b = ( " ;
for ( Iter1b = v1b.begin( ) ; Iter1b != v1b.end( ) ; Iter1b++ )
cout << *Iter1b << " ";
cout << ")." << endl;
// Constructing vector v2 with ranges sorted by greater
vector<int> v2a ( v1a ) , v2b ( v1b ) , v2 ( v1 );
vector<int>::iterator Iter2a, Iter2b, Iter2;
sort ( v2a.begin( ), v2a.end( ), greater<int>( ) );
sort ( v2b.begin( ), v2b.end( ), greater<int>( ) );
cout << "Original vector v2a with range sorted by the\n "
<< "binary predicate greater is v2a = ( " ;
for ( Iter2a = v2a.begin( ) ; Iter2a != v2a.end( ) ; Iter2a++ )
cout << *Iter2a << " ";
cout << ")." << endl;
cout << "Original vector v2b with range sorted by the\n "
<< "binary predicate greater is v2b = ( " ;
for ( Iter2b = v2b.begin( ) ; Iter2b != v2b.end( ) ; Iter2b++ )
cout << *Iter2b << " ";
cout << ")." << endl;
// Constructing vector v3 with ranges sorted by mod_lesser
vector<int> v3a( v1a ), v3b( v1b ) , v3( v1 );
vector<int>::iterator Iter3a, Iter3b, Iter3;
sort ( v3a.begin( ), v3a.end( ), mod_lesser );
sort ( v3b.begin( ), v3b.end( ), mod_lesser );
cout << "Original vector v3a with range sorted by the\n "
<< "binary predicate mod_lesser is v3a = ( " ;
for ( Iter3a = v3a.begin( ) ; Iter3a != v3a.end( ) ; Iter3a++ )
cout << *Iter3a << " ";
cout << ")." << endl;
cout << "Original vector v3b with range sorted by the\n "
<< "binary predicate mod_lesser is v3b = ( " ;
for ( Iter3b = v3b.begin( ) ; Iter3b != v3b.end( ) ; Iter3b++ )
cout << *Iter3b << " ";
cout << ")." << endl;
// To merge inplace in ascending order with default binary
// predicate less<int>( )
merge ( v1a.begin( ), v1a.end( ), v1b.begin( ), v1b.end( ), v1.begin( ) );
cout << "Merged inplace with default order,\n vector v1mod = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
// To merge inplace in descending order, specify binary
// predicate greater<int>( )
merge ( v2a.begin( ), v2a.end( ), v2b.begin( ), v2b.end( ),
v2.begin( ), greater<int>( ) );
cout << "Merged inplace with binary predicate greater specified,\n "
<< "vector v2mod = ( " ;
for ( Iter2 = v2.begin( ) ; Iter2 != v2.end( ) ; Iter2++ )
cout << *Iter2 << " ";
cout << ")." << endl;
// Applying A user-defined (UD) binary predicate mod_lesser
merge ( v3a.begin( ), v3a.end( ), v3b.begin( ), v3b.end( ),
v3.begin( ), mod_lesser );
cout << "Merged inplace with binary predicate mod_lesser specified,\n "
<< "vector v3mod = ( " ; ;
for ( Iter3 = v3.begin( ) ; Iter3 != v3.end( ) ; Iter3++ )
cout << *Iter3 << " ";
cout << ")." << endl;
}
```

## min

Compares two objects and returns the lesser of the two, where the ordering criterion may be specified by a binary predicate.

```
template<class Type>
constexpr const Type& min(
const Type& left,
const Type& right);
template<class Type, class Pr>
constexpr const Type& min(
const Type& left,
const Type& right,
BinaryPredicate pred);
template<class Type>
constexpr Type min(
initializer_list<Type> ilist);
template<class Type, class Pr>
constexpr Type min(
initializer_list<Type> ilist,
BinaryPredicate pred);
```

### Parameters

*left*

The first of the two objects being compared.

*right*

The second of the two objects being compared.

*pred*

A binary predicate used to compare the two objects.

*inlist*

The `initializer_list`

that contains the members to be compared.

### Return value

The lesser of the two objects, unless neither is lesser; in that case, it returns the first of the two objects. In the case of an `initializer_list`

, it returns the least of the objects in the list.

### Remarks

The `min`

algorithm is unusual in having objects passed as parameters. Most C++ Standard Library algorithms operate on a range of elements whose position is specified by iterators passed as parameters. If you need a function that uses a range of elements, use min_element. constexpr was enabled on the `initializer_list`

overloads in Visual Studio 2017.

### Example

```
// alg_min.cpp
// compile with: /EHsc
#include <vector>
#include <set>
#include <algorithm>
#include <iostream>
#include <ostream>
using namespace std;
class CInt;
ostream& operator<<( ostream& osIn, const CInt& rhs );
class CInt
{
public:
CInt( int n = 0 ) : m_nVal( n ){}
CInt( const CInt& rhs ) : m_nVal( rhs.m_nVal ){}
CInt& operator=( const CInt& rhs ) {m_nVal =
rhs.m_nVal; return *this;}
bool operator<( const CInt& rhs ) const
{return ( m_nVal < rhs.m_nVal );}
friend ostream& operator<<(ostream& osIn, const CInt& rhs);
private:
int m_nVal;
};
inline ostream& operator<<( ostream& osIn, const CInt& rhs )
{
osIn << "CInt( " << rhs.m_nVal << " )";
return osIn;
}
// Return whether modulus of elem1 is less than modulus of elem2
bool mod_lesser ( int elem1, int elem2 )
{
if ( elem1 < 0 )
elem1 = - elem1;
if ( elem2 < 0 )
elem2 = - elem2;
return elem1 < elem2;
};
int main()
{
// Comparing integers directly using the min algorithm with
// binary predicate mod_lesser & with default less than
int a = 6, b = -7, c = 7 ;
const int& result1 = min ( a, b, mod_lesser );
const int& result2 = min ( b, c );
cout << "The mod_lesser of the integers 6 & -7 is: "
<< result1 << "." << endl;
cout << "The lesser of the integers -7 & 7 is: "
<< result2 << "." << endl;
cout << endl;
// Comparing the members of an initializer_list
const int& result3 = min({ a, c });
const int& result4 = min({ a, b }, mod_lesser);
cout << "The lesser of the integers 6 & 7 is: "
<< result3 << "." << endl;
cout << "The mod_lesser of the integers 6 & -7 is: "
<< result4 << "." << endl;
cout << endl;
// Comparing set containers with elements of type CInt
// using the min algorithm
CInt c1 = 1, c2 = 2, c3 = 3;
set<CInt> s1, s2, s3;
set<CInt>::iterator s1_Iter, s2_Iter, s3_Iter;
s1.insert ( c1 );
s1.insert ( c2 );
s2.insert ( c2 );
s2.insert ( c3 );
cout << "s1 = (";
for ( s1_Iter = s1.begin( ); s1_Iter != --s1.end( ); s1_Iter++ )
cout << " " << *s1_Iter << ",";
s1_Iter = --s1.end( );
cout << " " << *s1_Iter << " )." << endl;
cout << "s2 = (";
for ( s2_Iter = s2.begin( ); s2_Iter != --s2.end( ); s2_Iter++ )
cout << " " << *s2_Iter << ",";
s2_Iter = --s2.end( );
cout << " " << *s2_Iter << " )." << endl;
s3 = min ( s1, s2 );
cout << "s3 = min ( s1, s2 ) = (";
for ( s3_Iter = s3.begin( ); s3_Iter != --s3.end( ); s3_Iter++ )
cout << " " << *s3_Iter << ",";
s3_Iter = --s3.end( );
cout << " " << *s3_Iter << " )." << endl << endl;
// Comparing vectors with integer elements using min algorithm
vector<int> v1, v2, v3, v4, v5;
vector<int>::iterator Iter1, Iter2, Iter3, Iter4, Iter5;
int i;
for ( i = 0 ; i <= 2 ; i++ )
{
v1.push_back( i );
}
int ii;
for ( ii = 0 ; ii <= 2 ; ii++ )
{
v2.push_back( ii );
}
int iii;
for ( iii = 0 ; iii <= 2 ; iii++ )
{
v3.push_back( 2 * iii );
}
cout << "Vector v1 is ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
cout << "Vector v2 is ( " ;
for ( Iter2 = v2.begin( ) ; Iter2 != v2.end( ) ; Iter2++ )
cout << *Iter2 << " ";
cout << ")." << endl;
cout << "Vector v3 is ( " ;
for ( Iter3 = v3.begin( ) ; Iter3 != v3.end( ) ; Iter3++ )
cout << *Iter3 << " ";
cout << ")." << endl;
v4 = min ( v1, v2 );
v5 = min ( v1, v3 );
cout << "Vector v4 = min ( v1,v2 ) is ( " ;
for ( Iter4 = v4.begin( ) ; Iter4 != v4.end( ) ; Iter4++ )
cout << *Iter4 << " ";
cout << ")." << endl;
cout << "Vector v5 = min ( v1,v3 ) is ( " ;
for ( Iter5 = v5.begin( ) ; Iter5 != v5.end( ) ; Iter5++ )
cout << *Iter5 << " ";
cout << ")." << endl;
}
```

```
The mod_lesser of the integers 6 & -7 is: 6.
The lesser of the integers -7 & 7 is: -7.
The lesser of the integers 6 & 7 is: 6.The mod_lesser of the integers 6 & -7 is: 6.
s1 = ( CInt( 1 ), CInt( 2 ) ).
s2 = ( CInt( 2 ), CInt( 3 ) ).
s3 = min ( s1, s2 ) = ( CInt( 1 ), CInt( 2 ) ).
Vector v1 is ( 0 1 2 ).
Vector v2 is ( 0 1 2 ).
Vector v3 is ( 0 2 4 ).
Vector v4 = min ( v1,v2 ) is ( 0 1 2 ).
Vector v5 = min ( v1,v3 ) is ( 0 1 2 ).
```

## min_element

Finds the first occurrence of smallest element in a specified range where the ordering criterion may be specified by a binary predicate.

```
template<class ForwardIterator>
constexpr ForwardIterator min_element(
ForwardIterator first,
ForwardIterator last );
template<class ForwardIterator, class Compare>
constexpr ForwardIterator min_element(
ForwardIterator first,
ForwardIterator last,
Compare pred);
template<class ExecutionPolicy, class ForwardIterator>
ForwardIterator min_element(
ExecutionPolicy&& exec,
ForwardIterator first,
ForwardIterator last);
template<class ExecutionPolicy, class ForwardIterator, class Compare>
ForwardIterator min_element(
ExecutionPolicy&& exec,
ForwardIterator first,
ForwardIterator last,
Compare pred);
```

### Parameters

*exec*

The execution policy to use.

*first*

A forward iterator addressing the position of the first element in the range to be searched for the smallest element.

*last*

A forward iterator addressing the position one past the final element in the range to be searched for the smallest element.

*pred*

User-defined predicate function object that defines the sense in which one element is less than another. The comparison predicate takes two arguments and should return **true** when the first element is less than the second element, and **false** otherwise.

### Return value

A forward iterator addressing the position of the first occurrence of the smallest element in the range searched.

### Remarks

The range referenced must be valid; all pointers must be dereferenceable and within each sequence the last position is reachable from the first by incrementation.

The complexity is linear: `(last - first) - 1`

comparisons are required for a nonempty range.

### Example

```
// alg_min_element.cpp
// compile with: /EHsc
#include <vector>
#include <set>
#include <algorithm>
#include <iostream>
#include <ostream>
using namespace std;
class CInt;
ostream& operator<<( ostream& osIn, const CInt& rhs );
class CInt
{
public:
CInt( int n = 0 ) : m_nVal( n ){}
CInt( const CInt& rhs ) : m_nVal( rhs.m_nVal ){}
CInt& operator=( const CInt& rhs ) {m_nVal =
rhs.m_nVal; return *this;}
bool operator<( const CInt& rhs ) const
{return ( m_nVal < rhs.m_nVal );}
friend ostream& operator<<( ostream& osIn, const CInt& rhs );
private:
int m_nVal;
};
inline ostream& operator<<( ostream& osIn, const CInt& rhs )
{
osIn << "CInt( " << rhs.m_nVal << " )";
return osIn;
}
// Return whether modulus of elem1 is less than modulus of elem2
bool mod_lesser ( int elem1, int elem2 )
{
if ( elem1 < 0 )
elem1 = - elem1;
if ( elem2 < 0 )
elem2 = - elem2;
return elem1 < elem2;
};
int main()
{
// Searching a set container with elements of type CInt
// for the minimum element
CInt c1 = 1, c2 = 2, c3 = -3;
set<CInt> s1;
set<CInt>::iterator s1_Iter, s1_R1_Iter, s1_R2_Iter;
s1.insert ( c1 );
s1.insert ( c2 );
s1.insert ( c3 );
cout << "s1 = (";
for ( s1_Iter = s1.begin( ); s1_Iter != --s1.end( ); s1_Iter++ )
cout << " " << *s1_Iter << ",";
s1_Iter = --s1.end( );
cout << " " << *s1_Iter << " )." << endl;
s1_R1_Iter = min_element ( s1.begin( ), s1.end( ) );
cout << "The smallest element in s1 is: " << *s1_R1_Iter << endl;
cout << endl;
// Searching a vector with elements of type int for the maximum
// element under default less than & mod_lesser binary predicates
vector<int> v1;
vector<int>::iterator v1_Iter, v1_R1_Iter, v1_R2_Iter;
int i;
for ( i = 0 ; i <= 3 ; i++ )
{
v1.push_back( i );
}
int ii;
for ( ii = 1 ; ii <= 4 ; ii++ )
{
v1.push_back( - 2 * ii );
}
cout << "Vector v1 is ( " ;
for ( v1_Iter = v1.begin( ) ; v1_Iter != v1.end( ) ; v1_Iter++ )
cout << *v1_Iter << " ";
cout << ")." << endl;
v1_R1_Iter = min_element ( v1.begin( ), v1.end( ) );
v1_R2_Iter = min_element ( v1.begin( ), v1.end( ), mod_lesser);
cout << "The smallest element in v1 is: " << *v1_R1_Iter << endl;
cout << "The smallest element in v1 under the mod_lesser"
<< "\n binary predicate is: " << *v1_R2_Iter << endl;
}
```

```
s1 = ( CInt( -3 ), CInt( 1 ), CInt( 2 ) ).
The smallest element in s1 is: CInt( -3 )
Vector v1 is ( 0 1 2 3 -2 -4 -6 -8 ).
The smallest element in v1 is: -8
The smallest element in v1 under the mod_lesser
binary predicate is: 0
```

## minmax_element

Performs the work performed by `min_element`

and `max_element`

in one call.

```
template<class ForwardIterator>
constexpr pair<ForwardIterator, ForwardIterator> minmax_element(
ForwardIterator first,
ForwardIterator last);
template<class ForwardIterator, class Compare>
constexpr pair<ForwardIterator, ForwardIterator> minmax_element(
ForwardIterator first,
ForwardIterator last,
Compare pred);
template<class ExecutionPolicy, class ForwardIterator>
pair<ForwardIterator, ForwardIterator> minmax_element(
ExecutionPolicy&& exec,
ForwardIterator first,
ForwardIterator last);
template<class ExecutionPolicy, class ForwardIterator, class Compare>
pair<ForwardIterator, ForwardIterator> minmax_element(
ExecutionPolicy&& exec,
ForwardIterator first,
ForwardIterator last,
Compare pred);
```

### Parameters

*exec*

The execution policy to use.

*first*

A forward iterator that indicates the beginning of a range.

*last*

A forward iterator that indicates the end of a range.

*pred*

A user-defined predicate function object that defines the sense in which one element is less than another. The comparison predicate takes two arguments and should return **true** when the first is less than the second, and **false** otherwise.

### Return value

Returns

`pair<ForwardIterator, ForwardIterator>( min_element(first, last), max_element(first, last))`

.

### Remarks

The first template function returns

`pair<ForwardIterator,ForwardIterator>(min_element(first,last), max_element(first,last))`

.

The second template function behaves the same, except that it replaces `operator<(X, Y)`

with `pred(X, Y)`

.

If the sequence is non-empty, the function performs at most `3 * (last - first - 1) / 2`

comparisons.

## minmax

Compares two input parameters and returns them as a pair, in order of lesser to greater.

```
template<class Type>
constexpr pair<const Type&, const Type&> minmax(
const Type& left,
const Type& right);
template<class Type, class BinaryPredicate>
constexpr pair<const Type&, const Type&> minmax(
const Type& left,
const Type& right,
BinaryPredicate pred);
template<class Type>
constexpr pair<Type&, Type&> minmax(
initializer_list<Type> ilist);
template<class Type, class BinaryPredicate>
constexpr pair<Type&, Type&> minmax(
initializer_list<Type> ilist,
BinaryPredicate pred);
```

### Parameters

*left*

The first of the two objects being compared.

*right*

The second of the two objects being compared.

*pred*

A binary predicate used to compare the two objects.

*inlist*

The `initializer_list`

that contains the members to be compared.

### Remarks

The first template function returns `pair<const Type&, const Type&>( right, left )`

if *right* is less than *left*. Otherwise, it returns `pair<const Type&, const Type&>( left, right )`

.

The second member function returns a pair where the first element is the lesser and the second is the greater when compared by the predicate *pred*.

The remaining template functions behave the same, except that they replace the *left* and *right* parameters with *inlist*.

The function performs exactly one comparison.

## mismatch

Compares two ranges element by element and locates the first position where a difference occurs.

Use the dual-range overloads in C++14 code because the overloads that only take a single iterator for the second range will not detect differences if the second range is longer than the first range, and will result in undefined behavior if the second range is shorter than the first range.

```
template<class InputIterator1, class InputIterator2>
pair<InputIterator1, InputIterator2>>
mismatch(
InputIterator1 first1,
InputIterator1 last1,
InputIterator2 first2 );
template<class InputIterator1, class InputIterator2, class BinaryPredicate> pair<InputIterator1, InputIterator2>>
mismatch(
InputIterator1 first1,
InputIterator1 last1,
InputIterator2 first2,
BinaryPredicate pred );
//C++14
template<class InputIterator1, class InputIterator2>
pair<InputIterator1, InputIterator2>>
mismatch(
InputIterator1 first1,
InputIterator1 last1,
InputIterator2 first2,
InputIterator2 last2 );
template<class InputIterator1, class InputIterator2, class BinaryPredicate> pair<InputIterator1, InputIterator2>>
mismatch(
InputIterator1 first1,
InputIterator1 last1,
InputIterator2 first2,
InputIterator2 last2,
BinaryPredicate pred);
//C++17
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2>
pair<ForwardIterator1, ForwardIterator2>
mismatch(
ExecutionPolicy&& exec,
ForwardIterator1 first1,
ForwardIterator1 last1,
ForwardIterator2 first2);
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class BinaryPredicate>
pair<ForwardIterator1, ForwardIterator2>
mismatch(
ExecutionPolicy&& exec,
ForwardIterator1 first1,
ForwardIterator1 last1,
ForwardIterator2 first2,
BinaryPredicate pred);
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2>
pair<ForwardIterator1, ForwardIterator2>
mismatch(
ExecutionPolicy&& exec,
ForwardIterator1 first1,
ForwardIterator1 last1,
ForwardIterator2 first2,
ForwardIterator2 last2);
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class BinaryPredicate>
pair<ForwardIterator1, ForwardIterator2>
mismatch(
ExecutionPolicy&& exec,
ForwardIterator1 first1,
ForwardIterator1 last1,
ForwardIterator2 first2,
ForwardIterator2 last2,
BinaryPredicate pred);
```

### Parameters

*exec*

The execution policy to use.

*first1*

An input iterator addressing the position of the first element in the first range to be tested.

*last1*

An input iterator addressing the position one past the last element in the first range to be tested.

*first2*

An input iterator addressing the position of the first element in the second range to be tested.

*last2*

An input iterator addressing the position of one past the last element in the second range to be tested.

*pred*

User-defined predicate function object that compares the current elements in each range and determines whether they are equivalent. It returns **true** when satisfied and **false** when not satisfied.

### Return value

A pair of iterators addressing the positions of the mismatch in the two ranges, the first component iterator to the position in the first range and the second component iterator to the position in the second range. If there is no difference between the elements in the ranges compared or if the binary predicate in the second version is satisfied by all element pairs from the two ranges, then the first component iterator points to the position one past the final element in the first range and the second component iterator to position one past the final element tested in the second range.

### Remarks

The first template function assumes that there are as many elements in the range beginning at first2 as there are in the range designated by [first1, last1). If there are more in the second range, they are ignored; if there are less, then undefined behavior will result.

The range to be searched must be valid; all iterators must be dereferenceable and the last position is reachable from the first by incrementation.

The time complexity of the algorithm is linear in the number of elements contained in the shorter range.

The user-defined predicate is not required to impose an equivalence relation that symmetric, reflexive and transitive between its operands.

### Example

The following example demonstrates how to use mismatch. The C++03 overload is shown only in order to demonstrate how it can produce an unexpected result.

```
#include <vector>
#include <list>
#include <algorithm>
#include <iostream>
#include <string>
#include <utility>
using namespace std;
// Return whether first element is twice the second
// Note that this is not a symmetric, reflexive and transitive equivalence.
// mismatch and equal accept such predicates, but is_permutation does not.
bool twice(int elem1, int elem2)
{
return elem1 == elem2 * 2;
}
void PrintResult(const string& msg, const pair<vector<int>::iterator, vector<int>::iterator>& result,
const vector<int>& left, const vector<int>& right)
{
// If either iterator stops before reaching the end of its container,
// it means a mismatch was detected.
if (result.first != left.end() || result.second != right.end())
{
string leftpos(result.first == left.end() ? "end" : to_string(*result.first));
string rightpos(result.second == right.end() ? "end" : to_string(*result.second));
cout << msg << "mismatch. Left iterator at " << leftpos
<< " right iterator at " << rightpos << endl;
}
else
{
cout << msg << " match." << endl;
}
}
int main()
{
vector<int> vec_1{ 0, 5, 10, 15, 20, 25 };
vector<int> vec_2{ 0, 5, 10, 15, 20, 25, 30 };
// Testing different length vectors for mismatch (C++03)
auto match_vecs = mismatch(vec_1.begin(), vec_1.end(), vec_2.begin());
bool is_mismatch = match_vecs.first != vec_1.end();
cout << "C++03: vec_1 and vec_2 are a mismatch: " << boolalpha << is_mismatch << endl;
// Using dual-range overloads:
// Testing different length vectors for mismatch (C++14)
match_vecs = mismatch(vec_1.begin(), vec_1.end(), vec_2.begin(), vec_2.end());
PrintResult("C++14: vec_1 and vec_2: ", match_vecs, vec_1, vec_2);
// Identify point of mismatch between vec_1 and modified vec_2.
vec_2[3] = 42;
match_vecs = mismatch(vec_1.begin(), vec_1.end(), vec_2.begin(), vec_2.end());
PrintResult("C++14 vec_1 v. vec_2 modified: ", match_vecs, vec_1, vec_2);
// Test vec_3 and vec_4 for mismatch under the binary predicate twice (C++14)
vector<int> vec_3{ 10, 20, 30, 40, 50, 60 };
vector<int> vec_4{ 5, 10, 15, 20, 25, 30 };
match_vecs = mismatch(vec_3.begin(), vec_3.end(), vec_4.begin(), vec_4.end(), twice);
PrintResult("vec_3 v. vec_4 with pred: ", match_vecs, vec_3, vec_4);
vec_4[5] = 31;
match_vecs = mismatch(vec_3.begin(), vec_3.end(), vec_4.begin(), vec_4.end(), twice);
PrintResult("vec_3 v. modified vec_4 with pred: ", match_vecs, vec_3, vec_4);
// Compare a vector<int> to a list<int>
list<int> list_1{ 0, 5, 10, 15, 20, 25 };
auto match_vec_list = mismatch(vec_1.begin(), vec_1.end(), list_1.begin(), list_1.end());
is_mismatch = match_vec_list.first != vec_1.end() || match_vec_list.second != list_1.end();
cout << "vec_1 and list_1 are a mismatch: " << boolalpha << is_mismatch << endl;
char c;
cout << "Press a key" << endl;
cin >> c;
}
```

```
C++03: vec_1 and vec_2 are a mismatch: false
C++14: vec_1 and vec_2: mismatch. Left iterator at end right iterator at 30
C++14 vec_1 v. vec_2 modified: mismatch. Left iterator at 15 right iterator at 42
C++14 vec_3 v. vec_4 with pred: match.
C++14 vec_3 v. modified vec_4 with pred: mismatch. Left iterator at 60 right iterator at 31
C++14: vec_1 and list_1 are a mismatch: false
Press a key
```

## <alg> move

Move elements associated with a specified range.

```
template<class InputIterator, class OutputIterator>
OutputIterator move(
InputIterator first,
InputIterator last,
OutputIterator dest);
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2>
ForwardIterator2 move(
ExecutionPolicy&& exec,
ForwardIterator1 first,
ForwardIterator1 last,
ForwardIterator2 result);
```

### Parameters

*exec*

The execution policy to use.

*first*

An input iterator that indicates where to start the range of elements to move.

*last*

An input iterator that indicates the end of a range of elements to move.

*dest*

The output iterator that is to contain the moved elements.

### Remarks

The template function evaluates `*(dest + N) = move(*(first + N))`

once for each `N`

in the range `[0, last - first)`

, for strictly increasing values of `N`

starting with the lowest value. It then returns `dest + N`

. If `dest`

and *first* designate regions of storage, *dest* must not be in the range `[first, last)`

.

## move_backward

Moves the elements of one iterator to another. The move starts with the last element in a specified range, and ends with the first element in that range.

```
template<class BidirectionalIterator1, class BidirectionalIterator2>
BidirectionalIterator2 move_backward(
BidirectionalIterator1 first,
BidirectionalIterator1 last,
BidirectionalIterator2 destEnd);
```

### Parameters

*first*

An iterator that indicates the start of a range to move elements from.

*last*

An iterator that indicates the end of a range to move elements from. This element is not moved.

*destEnd*

A bidirectional iterator addressing the position of one past the final element in the destination range.

### Remarks

The template function evaluates `*(destEnd - N - 1) = move(*(last - N - 1))`

once for each `N`

in the range `[0, last - first)`

, for strictly increasing values of `N`

starting with the lowest value. It then returns `destEnd - (last - first)`

. If *destEnd* and *first* designate regions of storage, *destEnd* must not be in the range `[first, last)`

.

`move`

and `move_backward`

are functionally equivalent to using `copy`

and `copy_backward`

with a move iterator.

## next_permutation

Reorders the elements in a range so that the original ordering is replaced by the lexicographically next greater permutation if it exists, where the sense of next may be specified with a binary predicate.

```
template<class BidirectionalIterator>
bool next_permutation(
BidirectionalIterator first,
BidirectionalIterator last);
template<class BidirectionalIterator, class BinaryPredicate>
bool next_permutation(
BidirectionalIterator first,
BidirectionalIterator last,
BinaryPredicate pred);
```

### Parameters

*first*

A bidirectional iterator pointing to the position of the first element in the range to be permuted.

*last*

A bidirectional iterator pointing to the position one past the final element in the range to be permuted.

*pred*

User-defined predicate function object that defines the comparison criterion to be satisfied by successive elements in the ordering. A binary predicate takes two arguments and returns **true** when satisfied and **false** when not satisfied.

### Return value

**true** if the lexicographically next permutation exists and has replaced the original ordering of the range; otherwise **false**, in which case the ordering is transformed into the lexicographically smallest permutation.

### Remarks

The range referenced must be valid; all pointers must be dereferenceable and within the sequence the last position is reachable from the first by incrementation.

The default binary predicate is less than and the elements in the range must be less than comparable to insure that the next permutation is well-defined.

The complexity is linear with at most `(last - first) / 2`

swaps.

### Example

```
// alg_next_perm.cpp
// compile with: /EHsc
#include <vector>
#include <deque>
#include <algorithm>
#include <iostream>
#include <ostream>
using namespace std;
class CInt;
ostream& operator<<( ostream& osIn, const CInt& rhs );
class CInt
{
public:
CInt( int n = 0 ) : m_nVal( n ) {}
CInt( const CInt& rhs ) : m_nVal( rhs.m_nVal ) {}
CInt& operator=( const CInt& rhs ) {m_nVal =
rhs.m_nVal; return *this;}
bool operator<( const CInt& rhs ) const
{ return ( m_nVal < rhs.m_nVal ); }
friend ostream& operator<<( ostream& osIn, const CInt& rhs );
private:
int m_nVal;
};
inline ostream& operator<<( ostream& osIn, const CInt& rhs )
{
osIn << "CInt( " << rhs.m_nVal << " )";
return osIn;
}
// Return whether modulus of elem1 is less than modulus of elem2
bool mod_lesser ( int elem1, int elem2 )
{
if ( elem1 < 0 )
elem1 = - elem1;
if ( elem2 < 0 )
elem2 = - elem2;
return elem1 < elem2;
};
int main()
{
// Reordering the elements of type CInt in a deque
// using the prev_permutation algorithm
CInt c1 = 5, c2 = 1, c3 = 10;
bool deq1Result;
deque<CInt> deq1, deq2, deq3;
deque<CInt>::iterator d1_Iter;
deq1.push_back ( c1 );
deq1.push_back ( c2 );
deq1.push_back ( c3 );
cout << "The original deque of CInts is deq1 = (";
for ( d1_Iter = deq1.begin( ); d1_Iter != --deq1.end( ); d1_Iter++ )
cout << " " << *d1_Iter << ",";
d1_Iter = --deq1.end( );
cout << " " << *d1_Iter << " )." << endl;
deq1Result = next_permutation ( deq1.begin( ), deq1.end( ) );
if ( deq1Result )
cout << "The lexicographically next permutation "
<< "exists and has\nreplaced the original "
<< "ordering of the sequence in deq1." << endl;
else
cout << "The lexicographically next permutation doesn't "
<< "exist\n and the lexicographically "
<< "smallest permutation\n has replaced the "
<< "original ordering of the sequence in deq1." << endl;
cout << "After one application of next_permutation,\n deq1 = (";
for ( d1_Iter = deq1.begin( ); d1_Iter != --deq1.end( ); d1_Iter++ )
cout << " " << *d1_Iter << ",";
d1_Iter = --deq1.end( );
cout << " " << *d1_Iter << " )." << endl << endl;
// Permuting vector elements with binary function mod_lesser
vector<int> v1;
vector<int>::iterator Iter1;
int i;
for ( i = -3 ; i <= 3 ; i++ )
{
v1.push_back( i );
}
cout << "Vector v1 is ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
next_permutation ( v1.begin( ), v1.end( ), mod_lesser );
cout << "After the first next_permutation, vector v1 is:\n v1 = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
int iii = 1;
while ( iii <= 5 ) {
next_permutation ( v1.begin( ), v1.end( ), mod_lesser );
cout << "After another next_permutation of vector v1,\n v1 = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ;Iter1 ++ )
cout << *Iter1 << " ";
cout << ")." << endl;
iii++;
}
}
```

```
The original deque of CInts is deq1 = ( CInt( 5 ), CInt( 1 ), CInt( 10 ) ).
The lexicographically next permutation exists and has
replaced the original ordering of the sequence in deq1.
After one application of next_permutation,
deq1 = ( CInt( 5 ), CInt( 10 ), CInt( 1 ) ).
Vector v1 is ( -3 -2 -1 0 1 2 3 ).
After the first next_permutation, vector v1 is:
v1 = ( -3 -2 -1 0 1 3 2 ).
After another next_permutation of vector v1,
v1 = ( -3 -2 -1 0 2 1 3 ).
After another next_permutation of vector v1,
v1 = ( -3 -2 -1 0 2 3 1 ).
After another next_permutation of vector v1,
v1 = ( -3 -2 -1 0 3 1 2 ).
After another next_permutation of vector v1,
v1 = ( -3 -2 -1 0 3 2 1 ).
After another next_permutation of vector v1,
v1 = ( -3 -2 -1 1 0 2 3 ).
```

## nth_element

Partitions a range of elements, correctly locating the *n*th element of the sequence in the range so that all the elements in front of it are less than or equal to it and all the elements that follow it in the sequence are greater than or equal to it.

```
template<class RandomAccessIterator>
void nth_element(
RandomAccessIterator first,
RandomAccessIterator nth,
RandomAccessIterator last);
template<class RandomAccessIterator, class Compare>
void nth_element(
RandomAccessIterator first,
RandomAccessIterator nth,
RandomAccessIterator last,
Compare pred);
template<class ExecutionPolicy, class RandomAccessIterator>
void nth_element(
ExecutionPolicy&& exec,
RandomAccessIterator first,
RandomAccessIterator nth,
RandomAccessIterator last);
template<class ExecutionPolicy, class RandomAccessIterator, class Compare>
void nth_element(
ExecutionPolicy&& exec,
RandomAccessIterator first,
RandomAccessIterator nth,
RandomAccessIterator last,
Compare pred);
```

### Parameters

*exec*

The execution policy to use.

*first*

A random-access iterator addressing the position of the first element in the range to be partitioned.

*nth*

A random-access iterator addressing the position of element to be correctly ordered on the boundary of the partition.

*last*

A random-access iterator addressing the position one past the final element in the range to be partitioned.

*pred*

User-defined predicate function object that defines the comparison criterion to be satisfied by successive elements in the ordering. A comparison predicate takes two arguments and returns **true** when satisfied and **false** when not satisfied.

### Remarks

The range referenced must be valid; all pointers must be dereferenceable and within the sequence the last position is reachable from the first by incrementation.

The `nth_element`

algorithm does not guarantee that elements in the sub-ranges either side of the *n*th element are sorted. It thus makes fewer guarantees than `partial_sort`

, which orders the elements in the range below some chosen element, and may be used as a faster alternative to `partial_sort`

when the ordering of the lower range is not required.

Elements are equivalent, but not necessarily equal, if neither is less than the other.

The average of a sort complexity is linear with respect to *last - first*.

### Example

```
// alg_nth_elem.cpp
// compile with: /EHsc
#include <vector>
#include <algorithm>
#include <functional> // For greater<int>( )
#include <iostream>
// Return whether first element is greater than the second
bool UDgreater ( int elem1, int elem2 ) {
return elem1 > elem2;
}
int main() {
using namespace std;
vector<int> v1;
vector<int>::iterator Iter1;
int i;
for ( i = 0 ; i <= 5 ; i++ )
v1.push_back( 3 * i );
int ii;
for ( ii = 0 ; ii <= 5 ; ii++ )
v1.push_back( 3 * ii + 1 );
int iii;
for ( iii = 0 ; iii <= 5 ; iii++ )
v1.push_back( 3 * iii +2 );
cout << "Original vector:\n v1 = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")" << endl;
nth_element(v1.begin( ), v1.begin( ) + 3, v1.end( ) );
cout << "Position 3 partitioned vector:\n v1 = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")" << endl;
// To sort in descending order, specify binary predicate
nth_element( v1.begin( ), v1.begin( ) + 4, v1.end( ),
greater<int>( ) );
cout << "Position 4 partitioned (greater) vector:\n v1 = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")" << endl;
random_shuffle( v1.begin( ), v1.end( ) );
cout << "Shuffled vector:\n v1 = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")" << endl;
// A user-defined (UD) binary predicate can also be used
nth_element( v1.begin( ), v1.begin( ) + 5, v1.end( ), UDgreater );
cout << "Position 5 partitioned (UDgreater) vector:\n v1 = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")" << endl;
}
```

## none_of

Returns **true** when a condition is never present among elements in the given range.

```
template<class InputIterator, class UnaryPredicate>
bool none_of(
InputIterator first,
InputIterator last,
UnaryPredicate pred);
template <class ExecutionPolicy, class ForwardIterator, class UnaryPredicate>
bool none_of(
ExecutionPolicy&& exec,
ForwardIterator first,
ForwardIterator last,
UnaryPredicate pred);
```

### Parameters

*exec*

The execution policy to use.

*first*

An input iterator that indicates where to start to check a range of elements for a condition.

*last*

An input iterator that indicates the end of a range of elements.

*pred*

The condition to test for. This is provided by a user-defined predicate function object that defines the condition. A unary predicate takes a single argument and returns **true** or **false**.

### Return value

Returns **true** if the condition is not detected at least once in the indicated range, and **false** if the condition is detected.

### Remarks

The template function returns **true** only if, for some `N`

in the range `[0, last - first)`

, the predicate `pred(*(first + N))`

is always **false**.

## partial_sort

Arranges a specified number of the smaller elements in a range into a nondescending order or according to an ordering criterion specified by a binary predicate.

```
template<class RandomAccessIterator>
void partial_sort(
RandomAccessIterator first,
RandomAccessIterator sortEnd,
RandomAccessIterator last);
template<class RandomAccessIterator, class Compare>
void partial_sort(
RandomAccessIterator first,
RandomAccessIterator sortEnd,
RandomAccessIterator last
Compare pred);
template<class ExecutionPolicy, class RandomAccessIterator>
void partial_sort(
ExecutionPolicy&& exec,
RandomAccessIterator first,
RandomAccessIterator middle,
RandomAccessIterator last);
template<class ExecutionPolicy, class RandomAccessIterator, class Compare>
void partial_sort(
ExecutionPolicy&& exec,
RandomAccessIterator first,
RandomAccessIterator middle,
RandomAccessIterator last,
Compare pred);
```

### Parameters

*exec*

The execution policy to use.

*first*

A random-access iterator addressing the position of the first element in the range to be sorted.

*sortEnd*

A random-access iterator addressing the position one past the final element in the subrange to be sorted.

*last*

A random-access iterator addressing the position one past the final element in the range to be partially sorted.

*pred*

User-defined predicate function object that defines the comparison criterion to be satisfied by successive elements in the ordering. A binary predicate takes two arguments and returns **true** when satisfied and **false** when not satisfied.

### Remarks

The range referenced must be valid; all pointers must be dereferenceable and within the sequence the last position is reachable from the first by incrementation.

Elements are equivalent, but not necessarily equal, if neither is less than the other. The `sort`

algorithm is not stable and does not guarantee that the relative ordering of equivalent elements will be preserved. The algorithm `stable_sort`

does preserve this original ordering.

The average partial sort complexity is *O*((`last`

- `first`

) log (`sortEnd`

- `first`

)).

### Example

```
// alg_partial_sort.cpp
// compile with: /EHsc
#include <vector>
#include <algorithm>
#include <functional> // For greater<int>( )
#include <iostream>
// Return whether first element is greater than the second
bool UDgreater ( int elem1, int elem2 )
{
return elem1 > elem2;
}
int main()
{
using namespace std;
vector<int> v1;
vector<int>::iterator Iter1;
int i;
for ( i = 0 ; i <= 5 ; i++ )
{
v1.push_back( 2 * i );
}
int ii;
for ( ii = 0 ; ii <= 5 ; ii++ )
{
v1.push_back( 2 * ii +1 );
}
cout << "Original vector:\n v1 = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")" << endl;
partial_sort(v1.begin( ), v1.begin( ) + 6, v1.end( ) );
cout << "Partially sorted vector:\n v1 = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")" << endl;
// To partially sort in descending order, specify binary predicate
partial_sort(v1.begin( ), v1.begin( ) + 4, v1.end( ), greater<int>( ) );
cout << "Partially resorted (greater) vector:\n v1 = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")" << endl;
// A user-defined (UD) binary predicate can also be used
partial_sort(v1.begin( ), v1.begin( ) + 8, v1.end( ), UDgreater );
cout << "Partially resorted (UDgreater) vector:\n v1 = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")" << endl;
}
```

```
Original vector:
v1 = ( 0 2 4 6 8 10 1 3 5 7 9 11 )
Partially sorted vector:
v1 = ( 0 1 2 3 4 5 10 8 6 7 9 11 )
Partially resorted (greater) vector:
v1 = ( 11 10 9 8 0 1 2 3 4 5 6 7 )
Partially resorted (UDgreater) vector:
v1 = ( 11 10 9 8 7 6 5 4 0 1 2 3 )
```

## partial_sort_copy

Copies elements from a source range into a destination range where the source elements are ordered by either less than or another specified binary predicate.

```
template<class InputIterator, class RandomAccessIterator>
RandomAccessIterator partial_sort_copy(
InputIterator first1,
InputIterator last1,
RandomAccessIterator first2,
RandomAccessIterator last2 );
template<class InputIterator, class RandomAccessIterator, class Compare>
RandomAccessIterator partial_sort_copy(
InputIterator first1,
InputIterator last1,
RandomAccessIterator first2,
RandomAccessIterator last2,
Compare pred);
template<class ExecutionPolicy, class ForwardIterator, class RandomAccessIterator>
RandomAccessIterator partial_sort_copy(
ExecutionPolicy&& exec,
ForwardIterator first,
ForwardIterator last,
RandomAccessIterator result_first,
RandomAccessIterator result_last);
template<class ExecutionPolicy, class ForwardIterator, class RandomAccessIterator, class Compare>
RandomAccessIterator partial_sort_copy(
ExecutionPolicy&& exec,
ForwardIterator first,
ForwardIterator last,
RandomAccessIterator result_first,
RandomAccessIterator result_last,
Compare pred);
```

### Parameters

*exec*

The execution policy to use.

*first1*

An input iterator addressing the position of the first element in the source range.

*last1*

An input iterator addressing the position one past the final element in the source range.

*first2*

A random-access iterator addressing the position of the first element in the sorted destination range.

*last2*

A random-access iterator addressing the position one past the final element in the sorted destination range.

*pred*

User-defined predicate function object that defines the comparison criterion to be satisfied by successive elements in the ordering. A binary predicate takes two arguments and returns **true** when satisfied and **false** when not satisfied.

### Return value

A random-access iterator addressing the element in the destination range one position beyond the last element inserted from the source range.

### Remarks

The source and destination ranges must not overlap and must be valid; all pointers must be dereferenceable and within each sequence the last position must be reachable from the first by incrementation.

The binary predicate must provide a strict weak ordering so that elements that are not equivalent are ordered, but elements that are equivalent are not. Two elements are equivalent under less than, but not necessarily equal, if neither is less than the other.

### Example

```
// alg_partial_sort_copy.cpp
// compile with: /EHsc
#include <vector>
#include <list>
#include <algorithm>
#include <functional>
#include <iostream>
int main() {
using namespace std;
vector<int> v1, v2;
list<int> list1;
vector<int>::iterator iter1, iter2;
list<int>::iterator list1_Iter, list1_inIter;
int i;
for (i = 0; i <= 9; i++)
v1.push_back(i);
random_shuffle(v1.begin(), v1.end());
list1.push_back(60);
list1.push_back(50);
list1.push_back(20);
list1.push_back(30);
list1.push_back(40);
list1.push_back(10);
cout << "Vector v1 = ( " ;
for (iter1 = v1.begin(); iter1 != v1.end(); iter1++)
cout << *iter1 << " ";
cout << ")" << endl;
cout << "List list1 = ( " ;
for (list1_Iter = list1.begin();
list1_Iter!= list1.end();
list1_Iter++)
cout << *list1_Iter << " ";
cout << ")" << endl;
// Copying a partially sorted copy of list1 into v1
vector<int>::iterator result1;
result1 = partial_sort_copy(list1.begin(), list1.end(),
v1.begin(), v1.begin() + 3);
cout << "List list1 Vector v1 = ( " ;
for (iter1 = v1.begin() ; iter1 != v1.end() ; iter1++)
cout << *iter1 << " ";
cout << ")" << endl;
cout << "The first v1 element one position beyond"
<< "\n the last L 1 element inserted was " << *result1
<< "." << endl;
// Copying a partially sorted copy of list1 into v2
int ii;
for (ii = 0; ii <= 9; ii++)
v2.push_back(ii);
random_shuffle(v2.begin(), v2.end());
vector<int>::iterator result2;
result2 = partial_sort_copy(list1.begin(), list1.end(),
v2.begin(), v2.begin() + 6);
cout << "List list1 into Vector v2 = ( " ;
for (iter2 = v2.begin() ; iter2 != v2.end(); iter2++)
cout << *iter2 << " ";
cout << ")" << endl;
cout << "The first v2 element one position beyond"
<< "\n the last L 1 element inserted was " << *result2
<< "." << endl;
}
```

## partition

Classifies elements in a range into two disjoint sets, with those elements satisfying a unary predicate preceding those that fail to satisfy it.

```
template<class BidirectionalIterator, class UnaryPredicate>
BidirectionalIterator partition(
BidirectionalIterator first,
BidirectionalIterator last,
UnaryPredicate pred);
template<class ExecutionPolicy, class ForwardIterator, class UnaryPredicate>
ForwardIterator partition(
ExecutionPolicy&& exec,
ForwardIterator first,
ForwardIterator last,
UnaryPredicate pred);
```

### Parameters

*exec*

The execution policy to use.

*first*

A bidirectional iterator addressing the position of the first element in the range to be partitioned.

*last*

A bidirectional iterator addressing the position one past the final element in the range to be partitioned.

*pred*

User-defined predicate function object that defines the condition to be satisfied if an element is to be classified. A unary predicate takes a single argument and returns **true** or **false**.

### Return value

A bidirectional iterator addressing the position of the first element in the range to not satisfy the predicate condition.

### Remarks

Elements *a* and *b* are equivalent, but not necessarily equal, if both `pred( a, b )`

is false and `pred( b, a )`

is false, where *pred* is the parameter-specified predicate. The `partition`

algorithm is not stable and does not guarantee that the relative ordering of equivalent elements will be preserved. The algorithm `stable_partition`

does preserve this original ordering.

The complexity is linear: there are `(last - first)`

applications of *pred* and at most `(last - first)/2`

swaps.

### Example

```
// alg_partition.cpp
// compile with: /EHsc
#include <vector>
#include <algorithm>
#include <iostream>
bool greater5 ( int value )
{
return value > 5;
}
int main()
{
using namespace std;
vector<int> v1, v2;
vector<int>::iterator Iter1, Iter2;
int i;
for ( i = 0 ; i <= 10 ; i++ )
{
v1.push_back( i );
}
random_shuffle( v1.begin( ), v1.end( ) );
cout << "Vector v1 is ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
// Partition the range with predicate greater10
partition ( v1.begin( ), v1.end( ), greater5 );
cout << "The partitioned set of elements in v1 is: ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
}
```

## partition_copy

Copies elements for which a condition is **true** to one destination, and for which the condition is **false** to another. The elements must come from a specified range.

```
template<class InputIterator, class OutputIterator1, class OutputIterator2, class UnaryPredicate>
pair<OutputIterator1, OutputIterator2> partition_copy(
InputIterator first,
InputIterator last,
OutputIterator1 dest1,
OutputIterator2 dest2,
UnaryPredicate pred);
template <class ExecutionPolicy, class ForwardIterator, class ForwardIterator1, class ForwardIterator2, class UnaryPredicate>
pair<ForwardIterator1, ForwardIterator2> partition_copy(
ExecutionPolicy&& exec,
ForwardIterator first,
ForwardIterator last,
ForwardIterator1 out_true,
ForwardIterator2 out_false,
UnaryPredicate pred);
```

### Parameters

*exec*

The execution policy to use.

*first*

An input iterator that indicates the beginning of a range to check for a condition.

*last*

An input iterator that indicates the end of a range.

*dest1*

An output iterator used to copy elements that return true for a condition tested by using *pred*.

*dest2*

An output iterator used to copy elements that return false for a condition tested by using *pred*.

*pred*

The condition to test for. This is provided by a user-defined predicate function object that defines the condition to be tested. A unary predicate takes a single argument and returns **true** or **false**.

### Remarks

The template function copies each element `X`

in `[first,last)`

to `*dest1++`

if `pred(X)`

is true, or to `*dest2++`

if not. It returns `pair<OutputIterator1, OutputIterator2>(dest1, dest2)`

.

## partition_point

Returns the first element in the given range that does not satisfy the condition. The elements are sorted so that those that satisfy the condition come before those that do not.

```
template<class ForwardIterator, class UnaryPredicate>
ForwardIterator partition_point(
ForwardIterator first,
ForwardIterator last,
UnaryPredicate pred);
```

### Parameters

*first*

A `ForwardIterator`

that indicates the start of a range to check for a condition.

*last*

A `ForwardIterator`

that indicates the end of a range.

*pred*

The condition to test for. This is provided by a user-defined predicate function object that defines the condition to be satisfied by the element being searched for. A unary predicate takes a single argument and returns **true** or **false**.

### Return value

Returns a `ForwardIterator`

that refers to the first element that does not fulfill the condition tested for by *pred*, or returns *last* if one is not found.

### Remarks

The template function finds the first iterator `it`

in `[first, last)`

for which `pred(*it)`

is **false**. The sequence must be ordered by *pred*.

## pop_heap

Removes the largest element from the front of a heap to the next-to-last position in the range and then forms a new heap from the remaining elements.

```
template<class RandomAccessIterator>
void pop_heap(
RandomAccessIterator first,
RandomAccessIterator last);
template<class RandomAccessIterator, class BinaryPredicate>
void pop_heap(
RandomAccessIterator first,
RandomAccessIterator last,
BinaryPredicate pred);
```

### Parameters

*first*

A random-access iterator addressing the position of the first element in the heap.

*last*

A random-access iterator addressing the position one past the final element in the heap.

*pred*

User-defined predicate function object that defines sense in which one element is less than another. A binary predicate takes two arguments and returns **true** when satisfied and **false** when not satisfied.

### Remarks

The `pop_heap`

algorithm is the inverse of the operation performed by the push_heap algorithm, in which an element at the next-to-last position of a range is added to a heap consisting of the prior elements in the range, in the case when the element being added to the heap is larger than any of the elements already in the heap.

Heaps have two properties:

The first element is always the largest.

Elements may be added or removed in logarithmic time.

Heaps are an ideal way to implement priority queues and they are used in the implementation of the C++ Standard Library container adaptor priority_queue Class.

The range excluding the newly added element at the end must be a heap.

The complexity is logarithmic, requiring at most `log (last - first)`

comparisons.

### Example

```
// alg_pop_heap.cpp
// compile with: /EHsc
#include <vector>
#include <algorithm>
#include <functional>
#include <iostream>
int main()
{
using namespace std;
vector<int> v1;
vector<int>::iterator Iter1, Iter2;
int i;
for ( i = 1 ; i <= 9 ; i++ )
v1.push_back( i );
// Make v1 a heap with default less than ordering
random_shuffle( v1.begin( ), v1.end( ) );
make_heap ( v1.begin( ), v1.end( ) );
cout << "The heaped version of vector v1 is ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
// Add an element to the back of the heap
v1.push_back( 10 );
push_heap( v1.begin( ), v1.end( ) );
cout << "The reheaped v1 with 10 added is ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
// Remove the largest element from the heap
pop_heap( v1.begin( ), v1.end( ) );
cout << "The heap v1 with 10 removed is ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl << endl;
// Make v1 a heap with greater-than ordering with a 0 element
make_heap ( v1.begin( ), v1.end( ), greater<int>( ) );
v1.push_back( 0 );
push_heap( v1.begin( ), v1.end( ), greater<int>( ) );
cout << "The 'greater than' reheaped v1 puts the smallest "
<< "element first:\n ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
// Application of pop_heap to remove the smallest element
pop_heap( v1.begin( ), v1.end( ), greater<int>( ) );
cout << "The 'greater than' heaped v1 with the smallest element\n "
<< "removed from the heap is: ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
}
```

## prev_permutation

Reorders the elements in a range so that the original ordering is replaced by the lexicographically previous greater permutation if it exists, where the sense of previous may be specified with a binary predicate.

```
template<class BidirectionalIterator>
bool prev_permutation(
BidirectionalIterator first,
BidirectionalIterator last);
template<class BidirectionalIterator, class BinaryPredicate>
bool prev_permutation(
BidirectionalIterator first,
BidirectionalIterator last,
BinaryPredicate pred);
```

### Parameters

*first*

A bidirectional iterator pointing to the position of the first element in the range to be permuted.

*last*

A bidirectional iterator pointing to the position one past the final element in the range to be permuted.

*pred*

User-defined predicate function object that defines the comparison criterion to be satisfied by successive elements in the ordering. A binary predicate takes two arguments and returns **true** when satisfied and **false** when not satisfied.

### Return value

**true** if the lexicographically previous permutation exists and has replaced the original ordering of the range; otherwise **false**, in which case the ordering is transformed into the lexicographically largest permutation.

### Remarks

The default binary predicate is less than and the elements in the range must be less-than comparable to ensure that the previous permutation is well-defined.

The complexity is linear, with at most (`last`

- `first`

)/2 swaps.

### Example

```
// alg_prev_perm.cpp
// compile with: /EHsc
#include <vector>
#include <deque>
#include <algorithm>
#include <iostream>
#include <ostream>
using namespace std;
class CInt;
ostream& operator<<( ostream& osIn, const CInt& rhs );
class CInt {
public:
CInt( int n = 0 ) : m_nVal( n ){}
CInt( const CInt& rhs ) : m_nVal( rhs.m_nVal ){}
CInt& operator=( const CInt& rhs ) {m_nVal =
rhs.m_nVal; return *this;}
bool operator<( const CInt& rhs ) const
{return ( m_nVal < rhs.m_nVal );}
friend ostream& operator<<( ostream& osIn, const CInt& rhs );
private:
int m_nVal;
};
inline ostream& operator<<( ostream& osIn, const CInt& rhs ) {
osIn << "CInt( " << rhs.m_nVal << " )";
return osIn;
}
// Return whether modulus of elem1 is less than modulus of elem2
bool mod_lesser (int elem1, int elem2 ) {
if ( elem1 < 0 )
elem1 = - elem1;
if ( elem2 < 0 )
elem2 = - elem2;
return elem1 < elem2;
};
int main()
{
// Reordering the elements of type CInt in a deque
// using the prev_permutation algorithm
CInt c1 = 1, c2 = 5, c3 = 10;
bool deq1Result;
deque<CInt> deq1, deq2, deq3;
deque<CInt>::iterator d1_Iter;
deq1.push_back ( c1 );
deq1.push_back ( c2 );
deq1.push_back ( c3 );
cout << "The original deque of CInts is deq1 = (";
for ( d1_Iter = deq1.begin( ); d1_Iter != --deq1.end( ); d1_Iter++ )
cout << " " << *d1_Iter << ",";
d1_Iter = --deq1.end( );
cout << " " << *d1_Iter << " )." << endl;
deq1Result = prev_permutation ( deq1.begin( ), deq1.end( ) );
if ( deq1Result )
cout << "The lexicographically previous permutation "
<< "exists and has \nreplaced the original "
<< "ordering of the sequence in deq1." << endl;
else
cout << "The lexicographically previous permutation doesn't "
<< "exist\n and the lexicographically "
<< "smallest permutation\n has replaced the "
<< "original ordering of the sequence in deq1." << endl;
cout << "After one application of prev_permutation,\n deq1 = (";
for ( d1_Iter = deq1.begin( ); d1_Iter != --deq1.end( ); d1_Iter++ )
cout << " " << *d1_Iter << ",";
d1_Iter = --deq1.end( );
cout << " " << *d1_Iter << " )." << endl << endl;
// Permutating vector elements with binary function mod_lesser
vector<int> v1;
vector<int>::iterator Iter1;
int i;
for ( i = -3 ; i <= 3 ; i++ )
v1.push_back( i );
cout << "Vector v1 is ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
prev_permutation ( v1.begin( ), v1.end( ), mod_lesser );
cout << "After the first prev_permutation, vector v1 is:\n v1 = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
int iii = 1;
while ( iii <= 5 ) {
prev_permutation ( v1.begin( ), v1.end( ), mod_lesser );
cout << "After another prev_permutation of vector v1,\n v1 = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ;Iter1 ++ )
cout << *Iter1 << " ";
cout << ")." << endl;
iii++;
}
}
```

```
The original deque of CInts is deq1 = ( CInt( 1 ), CInt( 5 ), CInt( 10 ) ).
The lexicographically previous permutation doesn't exist
and the lexicographically smallest permutation
has replaced the original ordering of the sequence in deq1.
After one application of prev_permutation,
deq1 = ( CInt( 10 ), CInt( 5 ), CInt( 1 ) ).
Vector v1 is ( -3 -2 -1 0 1 2 3 ).
After the first prev_permutation, vector v1 is:
v1 = ( -3 -2 0 3 2 1 -1 ).
After another prev_permutation of vector v1,
v1 = ( -3 -2 0 3 -1 2 1 ).
After another prev_permutation of vector v1,
v1 = ( -3 -2 0 3 -1 1 2 ).
After another prev_permutation of vector v1,
v1 = ( -3 -2 0 2 3 1 -1 ).
After another prev_permutation of vector v1,
v1 = ( -3 -2 0 2 -1 3 1 ).
After another prev_permutation of vector v1,
v1 = ( -3 -2 0 2 -1 1 3 ).
```

## push_heap

Adds an element that is at the end of a range to an existing heap consisting of the prior elements in the range.

```
template<class RandomAccessIterator>
void push_heap(
RandomAccessIterator first,
RandomAccessIterator last );
template<class RandomAccessIterator, class BinaryPredicate>
void push_heap(
RandomAccessIterator first,
RandomAccessIterator last,
BinaryPredicate pred);
```

### Parameters

*first*

A random-access iterator addressing the position of the first element in the heap.

*last*

A random-access iterator addressing the position one past the final element in the range to be converted into a heap.

*pred*

User-defined predicate function object that defines sense in which one element is less than another. A binary predicate takes two arguments and returns **true** when satisfied and **false** when not satisfied.

### Remarks

The element must first be pushed back to the end of an existing heap and then the algorithm is used to add this element to the existing heap.

Heaps have two properties:

The first element is always the largest.

Elements may be added or removed in logarithmic time.

Heaps are an ideal way to implement priority queues and they are used in the implementation of the C++ Standard Library container adaptor priority_queue Class.

The range excluding the newly added element at the end must be a heap.

The complexity is logarithmic, requiring at most `log(last - first)`

comparisons.

### Example

```
// alg_push_heap.cpp
// compile with: /EHsc
#include <vector>
#include <algorithm>
#include <functional>
#include <iostream>
int main() {
using namespace std;
vector<int> v1, v2;
vector<int>::iterator Iter1, Iter2;
int i;
for ( i = 1 ; i <= 9 ; i++ )
v1.push_back( i );
random_shuffle( v1.begin( ), v1.end( ) );
cout << "Vector v1 is ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
// Make v1 a heap with default less than ordering
make_heap ( v1.begin( ), v1.end( ) );
cout << "The heaped version of vector v1 is ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
// Add an element to the heap
v1.push_back( 10 );
cout << "The heap v1 with 10 pushed back is ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
push_heap( v1.begin( ), v1.end( ) );
cout << "The reheaped v1 with 10 added is ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl << endl;
// Make v1 a heap with greater than ordering
make_heap ( v1.begin( ), v1.end( ), greater<int>( ) );
cout << "The greater-than heaped version of v1 is\n ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
v1.push_back(0);
cout << "The greater-than heap v1 with 11 pushed back is\n ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
push_heap( v1.begin( ), v1.end( ), greater<int>( ) );
cout << "The greater than reheaped v1 with 11 added is\n ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
}
```

## random_shuffle

The std::random_shuffle() function is deprecated, replaced by std::shuffle. For a code example and more information, see <random> and the Stack Overflow post Why are std::random_shuffle methods being deprecated in C++14?.

## remove

Eliminates a specified value from a given range without disturbing the order of the remaining elements and returning the end of a new range free of the specified value.

```
template<class ForwardIterator, class Type>
ForwardIterator remove(
ForwardIterator first,
ForwardIterator last,
const Type& value);
template<class ExecutionPolicy, class ForwardIterator, class Type>
ForwardIterator remove(
ExecutionPolicy&& exec,
ForwardIterator first,
ForwardIterator last,
const Type& value);
```

### Parameters

*exec*

The execution policy to use.

*first*

A forward iterator addressing the position of the first element in the range from which elements are being removed.

*last*

A forward iterator addressing the position one past the final element in the range from which elements are being removed.

*value*

The value that is to be removed from the range.

### Return value

A forward iterator addressing the new end position of the modified range, one past the final element of the remnant sequence free of the specified value.

### Remarks

The order of the elements not removed remains stable.

The `operator==`

used to determine the equality between elements must impose an equivalence relation between its operands.

The complexity is linear; there are (`last`

- `first`

) comparisons for equality.

The list class has a more efficient member function version of `remove`

, which also relinks pointers.

### Example

```
// alg_remove.cpp
// compile with: /EHsc
#include <vector>
#include <algorithm>
#include <iostream>
int main()
{
using namespace std;
vector<int> v1;
vector<int>::iterator Iter1, Iter2, new_end;
int i;
for ( i = 0 ; i <= 9 ; i++ )
v1.push_back( i );
int ii;
for ( ii = 0 ; ii <= 3 ; ii++ )
v1.push_back( 7 );
random_shuffle ( v1.begin( ), v1.end( ) );
cout << "Vector v1 is ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
// Remove elements with a value of 7
new_end = remove ( v1.begin( ), v1.end( ), 7 );
cout << "Vector v1 with value 7 removed is ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
// To change the sequence size, use erase
v1.erase (new_end, v1.end( ) );
cout << "Vector v1 resized with value 7 removed is ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
}
```

## remove_copy

Copies elements from a source range to a destination range, except that elements of a specified value are not copied, without disturbing the order of the remaining elements and returning the end of a new destination range.

```
template<class InputIterator, class OutputIterator, class Type>
OutputIterator remove_copy(
InputIterator first,
InputIterator last,
OutputIterator result,
const Type& value);
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class Type>
ForwardIterator2 remove_copy(
ExecutionPolicy&& exec,
ForwardIterator1 first,
ForwardIterator1 last,
ForwardIterator2 result,
const Type& value);
```

### Parameters

*exec*

The execution policy to use.

*first*

An input iterator addressing the position of the first element in the range from which elements are being removed.

*last*

An input iterator addressing the position one past the final element in the range from which elements are being removed.

*result*

An output iterator addressing the position of the first element in the destination range to which elements are being removed.

*value*

The value that is to be removed from the range.

### Return value

A forward iterator addressing the new end position of the destination range, one past the final element of the copy of the remnant sequence free of the specified value.

### Remarks

The source and destination ranges referenced must be valid; all pointers must be dereferenceable and within the sequence the last position is reachable from the first by incrementation.

There must be enough space in the destination range to contain the remnant elements that will be copied after elements of the specified value are removed.

The order of the elements not removed remains stable.

The `operator==`

used to determine the equality between elements must impose an equivalence relation between its operands.

The complexity is linear; there are (`last`

- `first`

) comparisons for equality and at most (`last`

- `first`

) assignments.

### Example

```
// alg_remove_copy.cpp
// compile with: /EHsc
#include <vector>
#include <algorithm>
#include <iostream>
int main()
{
using namespace std;
vector<int> v1, v2(10);
vector<int>::iterator Iter1, Iter2, new_end;
int i;
for ( i = 0 ; i <= 9 ; i++ )
v1.push_back( i );
int ii;
for ( ii = 0 ; ii <= 3 ; ii++ )
v1.push_back( 7 );
random_shuffle (v1.begin( ), v1.end( ) );
cout << "The original vector v1 is: ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
// Remove elements with a value of 7
new_end = remove_copy ( v1.begin( ), v1.end( ), v2.begin( ), 7 );
cout << "Vector v1 is left unchanged as ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
cout << "Vector v2 is a copy of v1 with the value 7 removed:\n ( " ;
for ( Iter2 = v2.begin( ) ; Iter2 != v2.end( ) ; Iter2++ )
cout << *Iter2 << " ";
cout << ")." << endl;
}
```

## remove_copy_if

Copies elements from a source range to a destination range, except for elements that satisfy a predicate. Elements are copied without disturbing the order of the remaining elements. Returns the end of a new destination range.

```
template<class InputIterator, class OutputIterator, class UnaryPredicate>
OutputIterator remove_copy_if(
InputIterator first,
InputIterator last,
OutputIterator result,
UnaryPredicate pred);
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class UnaryPredicate>
ForwardIterator2 remove_copy_if(
ExecutionPolicy&& exec,
ForwardIterator1 first,
ForwardIterator1 last,
ForwardIterator2 result,
UnaryPredicate pred);
```

### Parameters

*exec*

The execution policy to use.

*first*

An input iterator addressing the position of the first element in the range from which elements are being removed.

*last*

An input iterator addressing the position one past the final element in the range from which elements are being removed.

*result*

An output iterator addressing the position of the first element in the destination range to which elements are being removed.

*pred*

The unary predicate that must be satisfied is the value of an element is to be replaced.

### Return value

A forward iterator addressing the new end position of the destination range, one past the final element of the remnant sequence free of the elements satisfying the predicate.

### Remarks

The source range referenced must be valid; all pointers must be dereferenceable and within the sequence the last position is reachable from the first by incrementation.

There must be enough space in the destination range to contain the remnant elements that will be copied after elements of the specified value are removed.

The order of the elements not removed remains stable.

The `operator==`

used to determine the equality between elements must impose an equivalence relation between its operands.

The complexity is linear: there are (`last`

- `first`

) comparisons for equality and at most (`last`

- `first`

) assignments.

For information on how these functions behave, see Checked Iterators.

### Example

```
// alg_remove_copy_if.cpp
// compile with: /EHsc
#include <vector>
#include <algorithm>
#include <iostream>
bool greater6 ( int value ) {
return value > 6;
}
int main()
{
using namespace std;
vector<int> v1, v2(10);
vector<int>::iterator Iter1, Iter2, new_end;
int i;
for ( i = 0 ; i <= 9 ; i++ )
v1.push_back( i );
int ii;
for ( ii = 0 ; ii <= 3 ; ii++ )
v1.push_back( 7 );
random_shuffle ( v1.begin( ), v1.end( ) );
cout << "The original vector v1 is: ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
// Remove elements with a value greater than 6
new_end = remove_copy_if ( v1.begin( ), v1.end( ),
v2.begin( ), greater6 );
cout << "After the appliation of remove_copy_if to v1,\n "
<< "vector v1 is left unchanged as ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
cout << "Vector v2 is a copy of v1 with values greater "
<< "than 6 removed:\n ( " ;
for ( Iter2 = v2.begin( ) ; Iter2 != new_end ; Iter2++ )
cout << *Iter2 << " ";
cout << ")." << endl;
}
```

## remove_if

Eliminates elements that satisfy a predicate from a given range without disturbing the order of the remaining elements and returning the end of a new range free of the specified value.

```
template<class ForwardIterator, class UnaryPredicate>
ForwardIterator remove_if(
ForwardIterator first,
ForwardIterator last,
UnaryPredicate pred);
template<class ExecutionPolicy, class ForwardIterator, class UnaryPredicate>
ForwardIterator remove_if(
ExecutionPolicy&& exec,
ForwardIterator first,
ForwardIterator last,
UnaryPredicate pred);
```

### Parameters

*exec*

The execution policy to use.

*first*

A forward iterator pointing to the position of the first element in the range from which elements are being removed.

*last*

A forward iterator pointing to the position one past the final element in the range from which elements are being removed.

*pred*

The unary predicate that must be satisfied is the value of an element is to be replaced.

### Return value

A forward iterator addressing the new end position of the modified range, one past the final element of the remnant sequence free of the specified value.

### Remarks

The order of the elements not removed remains stable.

`operator==`

used to determine the equality between elements must impose an equivalence relation between its operands.

The complexity is linear: there are (`last`

- `first`

) comparisons for equality.

List has a more efficient member function version of remove which relinks pointers.

### Example

```
// alg_remove_if.cpp
// compile with: /EHsc
#include <vector>
#include <algorithm>
#include <iostream>
bool greater6 ( int value )
{
return value > 6;
}
int main()
{
using namespace std;
vector<int> v1, v2;
vector<int>::iterator Iter1, Iter2, new_end;
int i;
for ( i = 0 ; i <= 9 ; i++ )
v1.push_back( i );
int ii;
for ( ii = 0 ; ii <= 3 ; ii++ )
v1.push_back( 7 );
random_shuffle ( v1.begin( ), v1.end( ) );
cout << "Vector v1 is ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
// Remove elements satisfying predicate greater6
new_end = remove_if (v1.begin( ), v1.end( ), greater6 );
cout << "Vector v1 with elements satisfying greater6 removed is\n ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
// To change the sequence size, use erase
v1.erase (new_end, v1.end( ) );
cout << "Vector v1 resized elements satisfying greater6 removed is\n ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
}
```

## replace

Examines each element in a range and replaces it if it matches a specified value.

```
template<class ForwardIterator, class Type>
void replace(
ForwardIterator first,
ForwardIterator last,
const Type& oldVal,
const Type& newVal);
template<class ExecutionPolicy, class ForwardIterator, class Type>
void replace(
ExecutionPolicy&& exec,
ForwardIterator first,
ForwardIterator last,
const Type& oldVal,
const Type& newVal);
```

### Parameters

*exec*

The execution policy to use.

*first*

A forward iterator pointing to the position of the first element in the range from which elements are being replaced.

*last*

A forward iterator pointing to the position one past the final element in the range from which elements are being replaced.

*oldVal*

The old value of the elements being replaced.

*newVal*

The new value being assigned to the elements with the old value.

### Remarks

The order of the elements not replaced remains stable.

`operator==`

used to determine the equality between elements must impose an equivalence relation between its operands.

The complexity is linear; there are (`last`

- `first`

) comparisons for equality and at most (`last`

- `first`

) assignments of new values.

### Example

```
// alg_replace.cpp
// compile with: /EHsc
#include <vector>
#include <algorithm>
#include <iostream>
int main()
{
using namespace std;
vector<int> v1;
vector<int>::iterator Iter1;
int i;
for ( i = 0 ; i <= 9 ; i++ )
v1.push_back( i );
int ii;
for ( ii = 0 ; ii <= 3 ; ii++ )
v1.push_back( 7 );
random_shuffle (v1.begin( ), v1.end( ) );
cout << "The original vector v1 is:\n ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
// Replace elements with a value of 7 with a value of 700
replace (v1.begin( ), v1.end( ), 7 , 700);
cout << "The vector v1 with a value 700 replacing that of 7 is:\n ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
}
```

## replace_copy

Examines each element in a source range and replaces it if it matches a specified value while copying the result into a new destination range.

```
template<class InputIterator, class OutputIterator, class Type>
OutputIterator replace_copy(
InputIterator first,
InputIterator last,
OutputIterator result,
const Type& oldVal,
const Type& newVal);
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class Type>
ForwardIterator2 replace_copy(
ExecutionPolicy&& exec,
ForwardIterator1 first,
ForwardIterator1 last,
ForwardIterator2 result,
const Type& oldVal,
const Type& newVal);
```

### Parameters

*exec*

The execution policy to use.

*first*

An input iterator pointing to the position of the first element in the range from which elements are being replaced.

*last*

An input iterator pointing to the position one past the final element in the range from which elements are being replaced.

*result*

An output iterator pointing to the first element in the destination range to where the altered sequence of elements is being copied.

*oldVal*

The old value of the elements being replaced.

*newVal*

The new value being assigned to the elements with the old value.

### Return value

An output iterator pointing to the position one past the final element in the destination range the altered sequence of elements is copied to.

### Remarks

The source and destination ranges referenced must not overlap and must both be valid: all pointers must be dereferenceable and within the sequences the last position is reachable from the first by incrementation.

The order of the elements not replaced remains stable.

`operator==`

used to determine the equality between elements must impose an equivalence relation between its operands.

The complexity is linear: there are (`last`

- `first`

) comparisons for equality and at most (`last`

- `first`

) assignments of new values.

### Example

```
// alg_replace_copy.cpp
// compile with: /EHsc
#include <vector>
#include <list>
#include <algorithm>
#include <iostream>
int main()
{
using namespace std;
vector<int> v1;
list<int> L1 (15);
vector<int>::iterator Iter1;
list<int>::iterator L_Iter1;
int i;
for ( i = 0 ; i <= 9 ; i++ )
v1.push_back( i );
int ii;
for ( ii = 0 ; ii <= 3 ; ii++ )
v1.push_back( 7 );
random_shuffle ( v1.begin( ), v1.end( ) );
int iii;
for ( iii = 0 ; iii <= 15 ; iii++ )
v1.push_back( 1 );
cout << "The original vector v1 is:\n ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
// Replace elements in one part of a vector with a value of 7
// with a value of 70 and copy into another part of the vector
replace_copy ( v1.begin( ), v1.begin( ) + 14,v1.end( ) -15, 7 , 70);
cout << "The vector v1 with a value 70 replacing that of 7 is:\n ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
// Replace elements in a vector with a value of 70
// with a value of 1 and copy into a list
replace_copy ( v1.begin( ), v1.begin( ) + 14,L1.begin( ), 7 , 1);
cout << "The list copy L1 of v1 with the value 0 replacing "
<< "that of 7 is:\n ( " ;
for ( L_Iter1 = L1.begin( ) ; L_Iter1 != L1.end( ) ; L_Iter1++ )
cout << *L_Iter1 << " ";
cout << ")." << endl;
}
```

## replace_copy_if

Examines each element in a source range and replaces it if it satisfies a specified predicate while copying the result into a new destination range.

```
template<class InputIterator, class OutputIterator, class UnaryPredicate, class Type>
OutputIterator replace_copy_if(
InputIterator first,
InputIterator last,
OutputIterator result,
UnaryPredicate pred,
const Type& value);
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class UnaryPredicate, class Type>
ForwardIterator2 replace_copy_if(
ExecutionPolicy&& exec,
ForwardIterator1 first,
ForwardIterator1 last,
ForwardIterator2 result,
UnaryPredicate pred,
const Type& value);
```

### Parameters

*exec*

The execution policy to use.

*first*

An input iterator pointing to the position of the first element in the range from which elements are being replaced.

*last*

An input iterator pointing to the position one past the final element in the range from which elements are being replaced.

*result*

An output iterator pointing to the position of the first element in the destination range to which elements are being copied.

*pred*

The unary predicate that must be satisfied is the value of an element is to be replaced.

*value*

The new value being assigned to the elements whose old value satisfies the predicate.

### Return value

An output iterator pointing to the position one past the final element in the destination range the altered sequence of elements is copied to.

### Remarks

The source and destination ranges referenced must not overlap and must both be valid: all pointers must be dereferenceable and within the sequences the last position is reachable from the first by incrementation.

The order of the elements not replaced remains stable.

`operator==`

used to determine the equality between elements must impose an equivalence relation between its operands.

The complexity is linear; there are (`last`

- `first`

) comparisons for equality and at most (`last`

- `first`

) assignments of new values.

### Example

```
// alg_replace_copy_if.cpp
// compile with: /EHsc
#include <vector>
#include <list>
#include <algorithm>
#include <iostream>
bool greater6 ( int value )
{
return value > 6;
}
int main()
{
using namespace std;
vector<int> v1;
list<int> L1 (13);
vector<int>::iterator Iter1;
list<int>::iterator L_Iter1;
int i;
for ( i = 0 ; i <= 9 ; i++ )
v1.push_back( i );
int ii;
for ( ii = 0 ; ii <= 3 ; ii++ )
v1.push_back( 7 );
random_shuffle ( v1.begin( ), v1.end( ) );
int iii;
for ( iii = 0 ; iii <= 13 ; iii++ )
v1.push_back( 1 );
cout << "The original vector v1 is:\n ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
// Replace elements with a value of 7 in the 1st half of a vector
// with a value of 70 and copy it into the 2nd half of the vector
replace_copy_if ( v1.begin( ), v1.begin( ) + 14,v1.end( ) -14,
greater6 , 70);
cout << "The vector v1 with values of 70 replacing those greater"
<< "\n than 6 in the 1st half & copied into the 2nd half is:\n ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
// Replace elements in a vector with a value of 70
// with a value of 1 and copy into a list
replace_copy_if ( v1.begin( ), v1.begin( ) + 13,L1.begin( ),
greater6 , -1 );
cout << "A list copy of vector v1 with the value -1\n replacing "
<< "those greater than 6 is:\n ( " ;
for ( L_Iter1 = L1.begin( ) ; L_Iter1 != L1.end( ) ; L_Iter1++ )
cout << *L_Iter1 << " ";
cout << ")." << endl;
}
```

## replace_if

Examines each element in a range and replaces it if it satisfies a specified predicate.

```
template<class ForwardIterator, class UnaryPredicate, class Type>
void replace_if(
ForwardIterator first,
ForwardIterator last,
UnaryPredicate pred,
const Type& value);
template<class ExecutionPolicy, class ForwardIterator, class UnaryPredicate, class Type>
void replace_if(
ExecutionPolicy&& exec,
ForwardIterator first,
ForwardIterator last,
UnaryPredicate pred,
const Type& value);
```

### Parameters

*exec*

The execution policy to use.

*first*

A forward iterator pointing to the position of the first element in the range from which elements are being replaced.

*last*

An iterator pointing to the position one past the final element in the range from which elements are being replaced.

*pred*

The unary predicate that must be satisfied is the value of an element is to be replaced.

*value*

The new value being assigned to the elements whose old value satisfies the predicate.

### Remarks

The order of the elements not replaced remains stable.

The algorithm `replace_if`

is a generalization of the algorithm `replace`

, allowing any predicate to be specified, rather than equality to a specified constant value.

`operator==`

used to determine the equality between elements must impose an equivalence relation between its operands.

The complexity is linear: there are (`last`

- `first`

) comparisons for equality and at most (`last`

- `first`

) assignments of new values.

### Example

```
// alg_replace_if.cpp
// compile with: /EHsc
#include <vector>
#include <algorithm>
#include <iostream>
bool greater6 ( int value )
{
return value > 6;
}
int main()
{
using namespace std;
vector<int> v1;
vector<int>::iterator Iter1;
int i;
for ( i = 0 ; i <= 9 ; i++ )
v1.push_back( i );
int ii;
for ( ii = 0 ; ii <= 3 ; ii++ )
v1.push_back( 7 );
random_shuffle ( v1.begin( ), v1.end( ) );
cout << "The original vector v1 is:\n ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
// Replace elements satisfying the predicate greater6
// with a value of 70
replace_if ( v1.begin( ), v1.end( ), greater6 , 70);
cout << "The vector v1 with a value 70 replacing those\n "
<< "elements satisfying the greater6 predicate is:\n ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
}
```

## reverse

Reverses the order of the elements within a range.

```
template<class BidirectionalIterator>
void reverse(
BidirectionalIterator first,
BidirectionalIterator last);
template<class ExecutionPolicy, class BidirectionalIterator>
void reverse(
ExecutionPolicy&& exec,
BidirectionalIterator first,
BidirectionalIterator last);
```

### Parameters

*exec*

The execution policy to use.

*first*

A bidirectional iterator pointing to the position of the first element in the range within which the elements are being permuted.

*last*

A bidirectional iterator pointing to the position one past the final element in the range within which the elements are being permuted.

### Remarks

The source range referenced must be valid; all pointers must be dereferenceable and within the sequence the last position is reachable from the first by incrementation.

### Example

```
// alg_reverse.cpp
// compile with: /EHsc
#include <vector>
#include <algorithm>
#include <iostream>
int main()
{
using namespace std;
vector<int> v1;
vector<int>::iterator Iter1;
int i;
for ( i = 0 ; i <= 9 ; i++ )
{
v1.push_back( i );
}
cout << "The original vector v1 is:\n ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
// Reverse the elements in the vector
reverse (v1.begin( ), v1.end( ) );
cout << "The modified vector v1 with values reversed is:\n ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
}
```

```
The original vector v1 is:
( 0 1 2 3 4 5 6 7 8 9 ).
The modified vector v1 with values reversed is:
( 9 8 7 6 5 4 3 2 1 0 ).
```

## reverse_copy

Reverses the order of the elements within a source range while copying them into a destination range

```
template<class BidirectionalIterator, class OutputIterator>
OutputIterator reverse_copy(
BidirectionalIterator first,
BidirectionalIterator last,
OutputIterator result);
template<class ExecutionPolicy, class BidirectionalIterator, class ForwardIterator>
ForwardIterator reverse_copy(
ExecutionPolicy&& exec,
BidirectionalIterator first,
BidirectionalIterator last,
ForwardIterator result);
```

### Parameters

*exec*

The execution policy to use.

*first*

A bidirectional iterator pointing to the position of the first element in the source range within which the elements are being permuted.

*last*

A bidirectional iterator pointing to the position one past the final element in the source range within which the elements are being permuted.

*result*

An output iterator pointing to the position of the first element in the destination range to which elements are being copied.

### Return value

An output iterator pointing to the position one past the final element in the destination range the altered sequence of elements is copied to.

### Remarks

The source and destination ranges referenced must be valid; all pointers must be dereferenceable and within the sequence the last position is reachable from the first by incrementation.

### Example

```
// alg_reverse_copy.cpp
// compile with: /EHsc
#include <vector>
#include <algorithm>
#include <iostream>
int main()
{
using namespace std;
vector<int> v1, v2( 10 );
vector<int>::iterator Iter1, Iter2;
int i;
for ( i = 0 ; i <= 9 ; i++ )
{
v1.push_back( i );
}
cout << "The original vector v1 is:\n ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
// Reverse the elements in the vector
reverse_copy (v1.begin( ), v1.end( ), v2.begin( ) );
cout << "The copy v2 of the reversed vector v1 is:\n ( " ;
for ( Iter2 = v2.begin( ) ; Iter2 != v2.end( ) ; Iter2++ )
cout << *Iter2 << " ";
cout << ")." << endl;
cout << "The original vector v1 remains unmodified as:\n ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
}
```

## rotate

Exchanges the elements in two adjacent ranges.

```
template<class ForwardIterator>
void rotate(
ForwardIterator first,
ForwardIterator middle,
ForwardIterator last);
template<class ExecutionPolicy, class ForwardIterator>
ForwardIterator rotate(
ExecutionPolicy&& exec,
ForwardIterator first,
ForwardIterator middle,
ForwardIterator last);
```

### Parameters

*exec*

The execution policy to use.

*first*

A forward iterator addressing the position of the first element in the range to be rotated.

*middle*

A forward iterator defining the boundary within the range that addresses the position of the first element in the second part of the range whose elements are to be exchanged with those in the first part of the range.

*last*

A forward iterator addressing the position one past the final element in the range to be rotated.

### Remarks

The ranges referenced must be valid; all pointers must be dereferenceable and within the sequence the last position is reachable from the first by incrementation.

The complexity is linear with at most (`last`

- `first`

) swaps.

### Example

```
// alg_rotate.cpp
// compile with: /EHsc
#include <vector>
#include <deque>
#include <algorithm>
#include <iostream>
int main() {
using namespace std;
vector<int> v1;
deque<int> d1;
vector<int>::iterator v1Iter1;
deque<int>::iterator d1Iter1;
int i;
for ( i = -3 ; i <= 5 ; i++ )
{
v1.push_back( i );
}
int ii;
for ( ii =0 ; ii <= 5 ; ii++ )
{
d1.push_back( ii );
}
cout << "Vector v1 is ( " ;
for ( v1Iter1 = v1.begin( ) ; v1Iter1 != v1.end( ) ;v1Iter1 ++ )
cout << *v1Iter1 << " ";
cout << ")." << endl;
rotate ( v1.begin( ), v1.begin( ) + 3 , v1.end( ) );
cout << "After rotating, vector v1 is ( " ;
for ( v1Iter1 = v1.begin( ) ; v1Iter1 != v1.end( ) ;v1Iter1 ++ )
cout << *v1Iter1 << " ";
cout << ")." << endl;
cout << "The original deque d1 is ( " ;
for ( d1Iter1 = d1.begin( ) ; d1Iter1 != d1.end( ) ;d1Iter1 ++ )
cout << *d1Iter1 << " ";
cout << ")." << endl;
int iii = 1;
while ( iii <= d1.end( ) - d1.begin( ) ) {
rotate ( d1.begin( ), d1.begin( ) + 1 , d1.end( ) );
cout << "After the rotation of a single deque element to the back,\n d1 is ( " ;
for ( d1Iter1 = d1.begin( ) ; d1Iter1 != d1.end( ) ;d1Iter1 ++ )
cout << *d1Iter1 << " ";
cout << ")." << endl;
iii++;
}
}
```

```
Vector v1 is ( -3 -2 -1 0 1 2 3 4 5 ).
After rotating, vector v1 is ( 0 1 2 3 4 5 -3 -2 -1 ).
The original deque d1 is ( 0 1 2 3 4 5 ).
After the rotation of a single deque element to the back,
d1 is ( 1 2 3 4 5 0 ).
After the rotation of a single deque element to the back,
d1 is ( 2 3 4 5 0 1 ).
After the rotation of a single deque element to the back,
d1 is ( 3 4 5 0 1 2 ).
After the rotation of a single deque element to the back,
d1 is ( 4 5 0 1 2 3 ).
After the rotation of a single deque element to the back,
d1 is ( 5 0 1 2 3 4 ).
After the rotation of a single deque element to the back,
d1 is ( 0 1 2 3 4 5 ).
```

## rotate_copy

Exchanges the elements in two adjacent ranges within a source range and copies the result to a destination range.

```
template<class ForwardIterator, class OutputIterator>
OutputIterator rotate_copy(
ForwardIterator first,
ForwardIterator middle,
ForwardIterator last,
OutputIterator result );
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2>
ForwardIterator2 rotate_copy(
ExecutionPolicy&& exec,
ForwardIterator1 first,
ForwardIterator1 middle,
ForwardIterator1 last,
ForwardIterator2 result);
```

### Parameters

*exec*

The execution policy to use.

*first*

A forward iterator addressing the position of the first element in the range to be rotated.

*middle*

A forward iterator defining the boundary within the range that addresses the position of the first element in the second part of the range whose elements are to be exchanged with those in the first part of the range.

*last*

A forward iterator addressing the position one past the final element in the range to be rotated.

*result*

An output iterator addressing the position of the first element in the destination range.

### Return value

An output iterator addressing the position one past the final element in the destination range.

### Remarks

The ranges referenced must be valid; all pointers must be dereferenceable and within the sequence the last position is reachable from the first by incrementation.

The complexity is linear with at most (`last`

- `first`

) swaps.

### Example

```
// alg_rotate_copy.cpp
// compile with: /EHsc
#include <vector>
#include <deque>
#include <algorithm>
#include <iostream>
int main()
{
using namespace std;
vector<int> v1 , v2 ( 9 );
deque<int> d1 , d2 ( 6 );
vector<int>::iterator v1Iter , v2Iter;
deque<int>::iterator d1Iter , d2Iter;
int i;
for ( i = -3 ; i <= 5 ; i++ )
v1.push_back( i );
int ii;
for ( ii =0 ; ii <= 5 ; ii++ )
d1.push_back( ii );
cout << "Vector v1 is ( " ;
for ( v1Iter = v1.begin( ) ; v1Iter != v1.end( ) ;v1Iter ++ )
cout << *v1Iter << " ";
cout << ")." << endl;
rotate_copy ( v1.begin( ), v1.begin( ) + 3 , v1.end( ), v2.begin( ) );
cout << "After rotating, the vector v1 remains unchanged as:\n v1 = ( " ;
for ( v1Iter = v1.begin( ) ; v1Iter != v1.end( ) ;v1Iter ++ )
cout << *v1Iter << " ";
cout << ")." << endl;
cout << "After rotating, the copy of vector v1 in v2 is:\n v2 = ( " ;
for ( v2Iter = v2.begin( ) ; v2Iter != v2.end( ) ;v2Iter ++ )
cout << *v2Iter << " ";
cout << ")." << endl;
cout << "The original deque d1 is ( " ;
for ( d1Iter = d1.begin( ) ; d1Iter != d1.end( ) ;d1Iter ++ )
cout << *d1Iter << " ";
cout << ")." << endl;
int iii = 1;
while ( iii <= d1.end( ) - d1.begin( ) )
{
rotate_copy ( d1.begin( ), d1.begin( ) + iii , d1.end( ), d2.begin( ) );
cout << "After the rotation of a single deque element to the back,\n d2 is ( " ;
for ( d2Iter = d2.begin( ) ; d2Iter != d2.end( ) ;d2Iter ++ )
cout << *d2Iter << " ";
cout << ")." << endl;
iii++;
}
}
```

## sample

```
template<class PopulationIterator, class SampleIterator, class Distance, class UniformRandomBitGenerator>
SampleIterator sample(
PopulationIterator first,
PopulationIterator last,
SampleIterator out,
Distance n,
UniformRandomBitGenerator&& g);
```

## search

Searches for the first occurrence of a sequence within a target range whose elements are equal to those in a given sequence of elements or whose elements are equivalent in a sense specified by a binary predicate to the elements in the given sequence.

```
template<class ForwardIterator1, class ForwardIterator2>
ForwardIterator1 search(
ForwardIterator1 first1,
ForwardIterator1 last1,
ForwardIterator2 first2,
ForwardIterator2 last2);
template<class ForwardIterator1, class ForwardIterator2, class BinaryPredicate>
ForwardIterator1 search(
ForwardIterator1 first1,
ForwardIterator1 last1,
ForwardIterator2 first2,
ForwardIterator2 last2
BinaryPredicate pred);
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2>
ForwardIterator1 search(
ExecutionPolicy&& exec,
ForwardIterator1 first1,
ForwardIterator1 last1,
ForwardIterator2 first2,
ForwardIterator2 last2);
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class BinaryPredicate>
ForwardIterator1 search(
ExecutionPolicy&& exec,
ForwardIterator1 first1,
ForwardIterator1 last1,
ForwardIterator2 first2,
ForwardIterator2 last2,
BinaryPredicate pred);
template <class ForwardIterator, class Searcher>
ForwardIterator search(
ForwardIterator first,
ForwardIterator last,
const Searcher& searcher);
```

### Parameters

*exec*

The execution policy to use.

*first1*

A forward iterator addressing the position of the first element in the range to be searched.

*last1*

A forward iterator addressing the position one past the final element in the range to be searched.

*first2*

A forward iterator addressing the position of the first element in the range to be matched.

*last2*

A forward iterator addressing the position one past the final element in the range to be matched.

*pred*

User-defined predicate function object that defines the condition to be satisfied if two elements are to be taken as equivalent. A binary predicate takes two arguments and returns **true** when satisfied and **false** when not satisfied.

*searcher*

The searcher that encapsulates the pattern to look for and the search algorithm to use. For more information on searchers, see default_searcher class, boyer_moore_horspool_searcher class, and boyer_moore_searcher class.

### Return value

A forward iterator addressing the position of the first element of the first subsequence that matches the specified sequence or that is equivalent in a sense specified by a binary predicate.

### Remarks

`operator==`

used to determine the match between an element and the specified value must impose an equivalence relation between its operands.

The ranges referenced must be valid; all pointers must be dereferenceable and within each sequence the last position is reachable from the first by incrementation.

Average complexity is linear with respect to the size of the searched range, and worst case complexity is also linear with respect to the size of the sequence being searched for.

### Example

```
// alg_search.cpp
// compile with: /EHsc
#include <vector>
#include <list>
#include <algorithm>
#include <iostream>
// Return whether second element is twice the first
bool twice (int elem1, int elem2 )
{
return 2 * elem1 == elem2;
}
int main()
{
using namespace std;
vector<int> v1, v2;
list<int> L1;
vector<int>::iterator Iter1, Iter2;
list<int>::iterator L1_Iter, L1_inIter;
int i;
for ( i = 0 ; i <= 5 ; i++ )
{
v1.push_back( 5 * i );
}
for ( i = 0 ; i <= 5 ; i++ )
{
v1.push_back( 5 * i );
}
int ii;
for ( ii = 4 ; ii <= 5 ; ii++ )
{
L1.push_back( 5 * ii );
}
int iii;
for ( iii = 2 ; iii <= 4 ; iii++ )
{
v2.push_back( 10 * iii );
}
cout << "Vector v1 = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")" << endl;
cout << "List L1 = ( " ;
for ( L1_Iter = L1.begin( ) ; L1_Iter!= L1.end( ) ; L1_Iter++ )
cout << *L1_Iter << " ";
cout << ")" << endl;
cout << "Vector v2 = ( " ;
for ( Iter2 = v2.begin( ) ; Iter2 != v2.end( ) ; Iter2++ )
cout << *Iter2 << " ";
cout << ")" << endl;
// Searching v1 for first match to L1 under identity
vector<int>::iterator result1;
result1 = search (v1.begin( ), v1.end( ), L1.begin( ), L1.end( ) );
if ( result1 == v1.end( ) )
cout << "There is no match of L1 in v1."
<< endl;
else
cout << "There is at least one match of L1 in v1"
<< "\n and the first one begins at "
<< "position "<< result1 - v1.begin( ) << "." << endl;
// Searching v1 for a match to L1 under the binary predicate twice
vector<int>::iterator result2;
result2 = search (v1.begin( ), v1.end( ), v2.begin( ), v2.end( ), twice );
if ( result2 == v1.end( ) )
cout << "There is no match of L1 in v1."
<< endl;
else
cout << "There is a sequence of elements in v1 that "
<< "are equivalent\n to those in v2 under the binary "
<< "predicate twice\n and the first one begins at position "
<< result2 - v1.begin( ) << "." << endl;
}
```

```
Vector v1 = ( 0 5 10 15 20 25 0 5 10 15 20 25 )
List L1 = ( 20 25 )
Vector v2 = ( 20 30 40 )
There is at least one match of L1 in v1
and the first one begins at position 4.
There is a sequence of elements in v1 that are equivalent
to those in v2 under the binary predicate twice
and the first one begins at position 2.
```

## search_n

Searches for the first subsequence in a range that of a specified number of elements having a particular value or a relation to that value as specified by a binary predicate.

```
template<class ForwardIterator1, class Diff2, class Type>
ForwardIterator1 search_n(
ForwardIterator1 first1,
ForwardIterator1 last1,
Diff2 count,
const Type& value);
template<class ForwardIterator1, class Diff2, class Type, class BinaryPredicate>
ForwardIterator1 search_n(
ForwardIterator1 first1,
ForwardIterator1 last1,
Diff2 count,
const Type& value,
BinaryPredicate pred);
template<class ExecutionPolicy, class ForwardIterator, class Size, class Type>
ForwardIterator search_n(
ExecutionPolicy&& exec,
ForwardIterator first,
ForwardIterator last,
Size count,
const Type& value);
template<class ExecutionPolicy, class ForwardIterator, class Size, class Type, class BinaryPredicate>
ForwardIterator search_n(
ExecutionPolicy&& exec,
ForwardIterator first,
ForwardIterator last,
Size count,
const Type& value,
BinaryPredicate pred);
```

### Parameters

*exec*

The execution policy to use.

*first1*

A forward iterator addressing the position of the first element in the range to be searched.

*last1*

A forward iterator addressing the position one past the final element in the range to be searched.

*count*

The size of the subsequence being searched for.

*value*

The value of the elements in the sequence being searched for.

*pred*

User-defined predicate function object that defines the condition to be satisfied if two elements are to be taken as equivalent. A binary predicate takes two arguments and returns **true** when satisfied and **false** when not satisfied.

### Return value

A forward iterator addressing the position of the first element of the first subsequence that matches the specified sequence or that is equivalent in a sense specified by a binary predicate.

### Remarks

`operator==`

used to determine the match between an element and the specified value must impose an equivalence relation between its operands.

Complexity is linear with respect to the size of the searched.

### Example

```
// alg_search_n.cpp
// compile with: /EHsc
#include <vector>
#include <list>
#include <algorithm>
#include <iostream>
// Return whether second element is 1/2 of the first
bool one_half ( int elem1, int elem2 )
{
return elem1 == 2 * elem2;
}
int main()
{
using namespace std;
vector<int> v1, v2;
vector<int>::iterator Iter1;
int i;
for ( i = 0 ; i <= 5 ; i++ )
{
v1.push_back( 5 * i );
}
for ( i = 0 ; i <= 2 ; i++ )
{
v1.push_back( 5 );
}
for ( i = 0 ; i <= 5 ; i++ )
{
v1.push_back( 5 * i );
}
for ( i = 0 ; i <= 2 ; i++ )
{
v1.push_back( 10 );
}
cout << "Vector v1 = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")" << endl;
// Searching v1 for first match to (5 5 5) under identity
vector<int>::iterator result1;
result1 = search_n ( v1.begin( ), v1.end( ), 3, 5 );
if ( result1 == v1.end( ) )
cout << "There is no match for a sequence ( 5 5 5 ) in v1."
<< endl;
else
cout << "There is at least one match of a sequence ( 5 5 5 )"
<< "\n in v1 and the first one begins at "
<< "position "<< result1 - v1.begin( ) << "." << endl;
// Searching v1 for first match to (5 5 5) under one_half
vector<int>::iterator result2;
result2 = search_n (v1.begin( ), v1.end( ), 3, 5, one_half );
if ( result2 == v1.end( ) )
cout << "There is no match for a sequence ( 5 5 5 ) in v1"
<< " under the equivalence predicate one_half." << endl;
else
cout << "There is a match of a sequence ( 5 5 5 ) "
<< "under the equivalence\n predicate one_half "
<< "in v1 and the first one begins at "
<< "position "<< result2 - v1.begin( ) << "." << endl;
}
```

```
Vector v1 = ( 0 5 10 15 20 25 5 5 5 0 5 10 15 20 25 10 10 10 )
There is at least one match of a sequence ( 5 5 5 )
in v1 and the first one begins at position 6.
There is a match of a sequence ( 5 5 5 ) under the equivalence
predicate one_half in v1 and the first one begins at position 15.
```

## set_difference

Unites all of the elements that belong to one sorted source range, but not to a second sorted source range, into a single, sorted destination range, where the ordering criterion may be specified by a binary predicate.

```
template<class InputIterator1, class InputIterator2, class OutputIterator>
OutputIterator set_difference(
InputIterator1 first1,
InputIterator1 last1,
InputIterator2 first2,
InputIterator2 last2,
OutputIterator result );
template<class InputIterator1, class InputIterator2, class OutputIterator, class Compare>
OutputIterator set_difference(
InputIterator1 first1,
InputIterator1 last1,
InputIterator2 first2,
InputIterator2 last2,
OutputIterator result,
Compare pred );
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class ForwardIterator>
ForwardIterator set_difference(
ExecutionPolicy&& exec,
ForwardIterator1 first1,
ForwardIterator1 last1,
ForwardIterator2 first2,
ForwardIterator2 last2,
ForwardIterator result);
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class ForwardIterator, class Compare>
ForwardIterator set_difference(
ExecutionPolicy&& exec,
ForwardIterator1 first1,
ForwardIterator1 last1,
ForwardIterator2 first2,
ForwardIterator2 last2,
ForwardIterator result,
Compare pred);
```

### Parameters

*exec*

The execution policy to use.

*first1*

An input iterator addressing the position of the first element in the first of two sorted source ranges to be united and sorted into a single range representing the difference of the two source ranges.

*last1*

An input iterator addressing the position one past the last element in the first of two sorted source ranges to be united and sorted into a single range representing the difference of the two source ranges.

*first2*

An input iterator addressing the position of the first element in second of two consecutive sorted source ranges to be united and sorted into a single range representing the difference of the two source ranges.

*last2*

An input iterator addressing the position one past the last element in second of two consecutive sorted source ranges to be united and sorted into a single range representing the difference of the two source ranges.

*result*

An output iterator addressing the position of the first element in the destination range where the two source ranges are to be united into a single sorted range representing the difference of the two source ranges.

*pred*

User-defined predicate function object that defines the sense in which one element is less than another. The binary predicate takes two arguments and should return **true** when the first element is less than the second element and **false** otherwise.

### Return value

An output iterator addressing the position one past the last element in the sorted destination range representing the difference of the two source ranges.

### Remarks

The sorted source ranges referenced must be valid; all pointers must be dereferenceable and within each sequence the last position must be reachable from the first by incrementation.

The destination range should not overlap either of the source ranges and should be large enough to contain the first source range.

The sorted source ranges must each be arranged as a precondition to the application of the `set_difference`

algorithm in accordance with the same ordering as is to be used by the algorithm to sort the combined ranges.

The operation is stable as the relative order of elements within each range is preserved in the destination range. The source ranges are not modified by the algorithm merge.

The value types of the input iterators need be less-than-comparable to be ordered, so that, given two elements, it may be determined either that they are equivalent (in the sense that neither is less than the other) or that one is less than the other. This results in an ordering between the nonequivalent elements. When there are equivalent elements in both source ranges, the elements in the first range precede the elements from the second source range in the destination range. If the source ranges contain duplicates of an element such that there are more in the first source range than in the second, then the destination range will contain the number by which the occurrences of those elements in the first source range exceed the occurrences of those elements in the second source range.

The complexity of the algorithm is linear with at most `2 * ((last1 - first1) - (last2 - first2)) - 1`

comparisons for nonempty source ranges.

### Example

```
// alg_set_diff.cpp
// compile with: /EHsc
#include <vector>
#include <algorithm>
#include <functional> // For greater<int>( )
#include <iostream>
// Return whether modulus of elem1 is less than modulus of elem2
bool mod_lesser (int elem1, int elem2 )
{
if (elem1 < 0)
elem1 = - elem1;
if (elem2 < 0)
elem2 = - elem2;
return elem1 < elem2;
}
int main()
{
using namespace std;
vector<int> v1a, v1b, v1 ( 12 );
vector<int>::iterator Iter1a, Iter1b, Iter1, Result1;
// Constructing vectors v1a & v1b with default less-than ordering
int i;
for ( i = -1 ; i <= 4 ; i++ )
{
v1a.push_back( i );
}
int ii;
for ( ii =-3 ; ii <= 0 ; ii++ )
{
v1b.push_back( ii );
}
cout << "Original vector v1a with range sorted by the\n "
<< "binary predicate less than is v1a = ( " ;
for ( Iter1a = v1a.begin( ) ; Iter1a != v1a.end( ) ; Iter1a++ )
cout << *Iter1a << " ";
cout << ")." << endl;
cout << "Original vector v1b with range sorted by the\n "
<< "binary predicate less than is v1b = ( " ;
for ( Iter1b = v1b.begin( ) ; Iter1b != v1b.end( ) ; Iter1b++ )
cout << *Iter1b << " ";
cout << ")." << endl;
// Constructing vectors v2a & v2b with ranges sorted by greater
vector<int> v2a ( v1a ) , v2b ( v1b ) , v2 ( v1 );
vector<int>::iterator Iter2a, Iter2b, Iter2, Result2;
sort ( v2a.begin( ), v2a.end( ), greater<int>( ) );
sort ( v2b.begin( ), v2b.end( ), greater<int>( ) );
cout << "Original vector v2a with range sorted by the\n "
<< "binary predicate greater is v2a = ( " ;
for ( Iter2a = v2a.begin( ) ; Iter2a != v2a.end( ) ; Iter2a++ )
cout << *Iter2a << " ";
cout << ")." << endl;
cout << "Original vector v2b with range sorted by the\n "
<< "binary predicate greater is v2b = ( " ;
for ( Iter2b = v2b.begin( ) ; Iter2b != v2b.end( ) ; Iter2b++ )
cout << *Iter2b << " ";
cout << ")." << endl;
// Constructing vectors v3a & v3b with ranges sorted by mod_lesser
vector<int> v3a ( v1a ), v3b ( v1b ) , v3 ( v1 );
vector<int>::iterator Iter3a, Iter3b, Iter3, Result3;
sort ( v3a.begin( ), v3a.end( ), mod_lesser );
sort ( v3b.begin( ), v3b.end( ), mod_lesser );
cout << "Original vector v3a with range sorted by the\n "
<< "binary predicate mod_lesser is v3a = ( " ;
for ( Iter3a = v3a.begin( ) ; Iter3a != v3a.end( ) ; Iter3a++ )
cout << *Iter3a << " ";
cout << ")." << endl;
cout << "Original vector v3b with range sorted by the\n "
<< "binary predicate mod_lesser is v3b = ( " ;
for ( Iter3b = v3b.begin( ) ; Iter3b != v3b.end( ) ; Iter3b++ )
cout << *Iter3b << " ";
cout << ")." << endl;
// To combine into a difference in asscending
// order with the default binary predicate less<int>( )
Result1 = set_difference ( v1a.begin( ), v1a.end( ),
v1b.begin( ), v1b.end( ), v1.begin( ) );
cout << "Set_difference of source ranges with default order,"
<< "\n vector v1mod = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != Result1 ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
// To combine into a difference in descending
// order specify binary predicate greater<int>( )
Result2 = set_difference ( v2a.begin( ), v2a.end( ),
v2b.begin( ), v2b.end( ),v2.begin( ), greater<int>( ) );
cout << "Set_difference of source ranges with binary"
<< "predicate greater specified,\n vector v2mod = ( " ;
for ( Iter2 = v2.begin( ) ; Iter2 != Result2 ; Iter2++ )
cout << *Iter2 << " ";
cout << ")." << endl;
// To combine into a difference applying a user
// defined binary predicate mod_lesser
Result3 = set_difference ( v3a.begin( ), v3a.end( ),
v3b.begin( ), v3b.end( ), v3.begin( ), mod_lesser );
cout << "Set_difference of source ranges with binary "
<< "predicate mod_lesser specified,\n vector v3mod = ( " ; ;
for ( Iter3 = v3.begin( ) ; Iter3 != Result3 ; Iter3++ )
cout << *Iter3 << " ";
cout << ")." << endl;
}
```

## set_intersection

Unites all of the elements that belong to both sorted source ranges into a single, sorted destination range, where the ordering criterion may be specified by a binary predicate.

```
template<class InputIterator1, class InputIterator2, class OutputIterator>
OutputIterator set_intersection(
InputIterator1 first1,
InputIterator1 last1,
InputIterator2 first2,
InputIterator2 last2,
OutputIterator result);
template<class InputIterator1, class InputIterator2, class OutputIterator, class Compare>
OutputIterator set_intersection(
InputIterator1 first1,
InputIterator1 last1,
InputIterator2 first2,
InputIterator2 last2,
OutputIterator result,
Compare pred);
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class ForwardIterator>
ForwardIterator set_intersection(
ExecutionPolicy&& exec,
ForwardIterator1 first1,
ForwardIterator1 last1,
ForwardIterator2 first2,
ForwardIterator2 last2,
ForwardIterator result);
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class ForwardIterator, class Compare>
ForwardIterator set_intersection(
ExecutionPolicy&& exec,
ForwardIterator1 first1,
ForwardIterator1 last1,
ForwardIterator2 first2,
ForwardIterator2 last2,
ForwardIterator result,
Compare pred);
```

### Parameters

*exec*

The execution policy to use.

*first1*

An input iterator addressing the position of the first element in the first of two sorted source ranges to be united and sorted into a single range representing the intersection of the two source ranges.

*last1*

An input iterator addressing the position one past the last element in the first of two sorted source ranges to be united and sorted into a single range representing the intersection of the two source ranges.

*first2*

An input iterator addressing the position of the first element in second of two consecutive sorted source ranges to be united and sorted into a single range representing the intersection of the two source ranges.

*last2*

An input iterator addressing the position one past the last element in second of two consecutive sorted source ranges to be united and sorted into a single range representing the intersection of the two source ranges.

*result*

An output iterator addressing the position of the first element in the destination range where the two source ranges are to be united into a single sorted range representing the intersection of the two source ranges.

*pred*

User-defined predicate function object that defines the sense in which one element is less than another. The binary predicate takes two arguments and should return **true** when the first element is less than the second element and **false** otherwise.

### Return value

An output iterator addressing the position one past the last element in the sorted destination range representing the intersection of the two source ranges.

### Remarks

The sorted source ranges referenced must be valid; all pointers must be dereferenceable and within each sequence the last position must be reachable from the first by incrementation.

The destination range should not overlap either of the source ranges and should be large enough to contain the destination range.

The sorted source ranges must each be arranged as a precondition to the application of the merge algorithm in accordance with the same ordering as is to be used by the algorithm to sort the combined ranges.

The operation is stable as the relative order of elements within each range is preserved in the destination range. The source ranges are not modified by the algorithm.

The value types of the input iterators need be less-than comparable to be ordered, so that, given two elements, it may be determined either that they are equivalent (in the sense that neither is less than the other) or that one is less than the other. This results in an ordering between the nonequivalent elements. When there are equivalent elements in both source ranges, the elements in the first range precede the elements from the second source range in the destination range. If the source ranges contain duplicates of an element, then the destination range will contain the maximum number of those elements that occur in both source ranges.

The complexity of the algorithm is linear with at most `2 * ((last1 - first1) + (last2 - first2)) - 1`

comparisons for nonempty source ranges.

### Example

```
// alg_set_intersection.cpp
// compile with: /EHsc
#include <vector>
#include <algorithm>
#include <functional> // For greater<int>( )
#include <iostream>
// Return whether modulus of elem1 is less than modulus of elem2
bool mod_lesser (int elem1, int elem2 )
{
if ( elem1 < 0 )
elem1 = - elem1;
if ( elem2 < 0 )
elem2 = - elem2;
return elem1 < elem2;
}
int main()
{
using namespace std;
vector<int> v1a, v1b, v1 ( 12 );
vector<int>::iterator Iter1a, Iter1b, Iter1, Result1;
// Constructing vectors v1a & v1b with default less than ordering
int i;
for ( i = -1 ; i <= 3 ; i++ )
v1a.push_back( i );
int ii;
for ( ii =-3 ; ii <= 1 ; ii++ )
v1b.push_back( ii );
cout << "Original vector v1a with range sorted by the\n "
<< "binary predicate less than is v1a = ( " ;
for ( Iter1a = v1a.begin( ) ; Iter1a != v1a.end( ) ; Iter1a++ )
cout << *Iter1a << " ";
cout << ")." << endl;
cout << "Original vector v1b with range sorted by the\n "
<< "binary predicate less than is v1b = ( " ;
for ( Iter1b = v1b.begin( ) ; Iter1b != v1b.end( ) ; Iter1b++ )
cout << *Iter1b << " ";
cout << ")." << endl;
// Constructing vectors v2a & v2b with ranges sorted by greater
vector<int> v2a ( v1a ) , v2b ( v1b ) , v2 ( v1 );
vector<int>::iterator Iter2a, Iter2b, Iter2, Result2;
sort ( v2a.begin( ), v2a.end( ), greater<int>( ) );
sort ( v2b.begin( ), v2b.end( ), greater<int>( ) );
cout << "Original vector v2a with range sorted by the\n "
<< "binary predicate greater is v2a = ( " ;
for ( Iter2a = v2a.begin( ) ; Iter2a != v2a.end( ) ; Iter2a++ )
cout << *Iter2a << " ";
cout << ")." << endl;
cout << "Original vector v2b with range sorted by the\n "
<< "binary predicate greater is v2b = ( " ;
for ( Iter2b = v2b.begin( ) ; Iter2b != v2b.end( ) ; Iter2b++ )
cout << *Iter2b << " ";
cout << ")." << endl;
// Constructing vectors v3a & v3b with ranges sorted by mod_lesser
vector<int> v3a ( v1a ), v3b ( v1b ) , v3 ( v1 );
vector<int>::iterator Iter3a, Iter3b, Iter3, Result3;
sort ( v3a.begin( ), v3a.end( ), mod_lesser );
sort ( v3b.begin( ), v3b.end( ), mod_lesser );
cout << "Original vector v3a with range sorted by the\n "
<< "binary predicate mod_lesser is v3a = ( " ;
for ( Iter3a = v3a.begin( ) ; Iter3a != v3a.end( ) ; Iter3a++ )
cout << *Iter3a << " ";
cout << ")." << endl;
cout << "Original vector v3b with range sorted by the\n "
<< "binary predicate mod_lesser is v3b = ( " ;
for ( Iter3b = v3b.begin( ) ; Iter3b != v3b.end( ) ; Iter3b++ )
cout << *Iter3b << " ";
cout << ")." << endl;
// To combine into an intersection in asscending order with the
// default binary predicate less<int>( )
Result1 = set_intersection ( v1a.begin( ), v1a.end( ),
v1b.begin( ), v1b.end( ), v1.begin( ) );
cout << "Intersection of source ranges with default order,"
<< "\n vector v1mod = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != Result1 ; ++Iter1 )
cout << *Iter1 << " ";
cout << ")." << endl;
// To combine into an intersection in descending order, specify
// binary predicate greater<int>( )
Result2 = set_intersection ( v2a.begin( ), v2a.end( ),
v2b.begin( ), v2b.end( ),v2.begin( ), greater<int>( ) );
cout << "Intersection of source ranges with binary predicate"
<< " greater specified,\n vector v2mod = ( " ;
for ( Iter2 = v2.begin( ) ; Iter2 != Result2 ; ++Iter2 )
cout << *Iter2 << " ";
cout << ")." << endl;
// To combine into an intersection applying a user-defined
// binary predicate mod_lesser
Result3 = set_intersection ( v3a.begin( ), v3a.end( ),
v3b.begin( ), v3b.end( ), v3.begin( ), mod_lesser );
cout << "Intersection of source ranges with binary predicate "
<< "mod_lesser specified,\n vector v3mod = ( " ; ;
for ( Iter3 = v3.begin( ) ; Iter3 != Result3 ; ++Iter3 )
cout << *Iter3 << " ";
cout << ")." << endl;
}
```

## set_symmetric_difference

Unites all of the elements that belong to one, but not both, of the sorted source ranges into a single, sorted destination range, where the ordering criterion may be specified by a binary predicate.

```
template<class InputIterator1, class InputIterator2, class OutputIterator>
OutputIterator set_symmetric_difference(
InputIterator1 first1,
InputIterator1 last1,
InputIterator2 first2,
InputIterator2 last2,
OutputIterator result );
template<class InputIterator1, class InputIterator2, class OutputIterator, class Compare>
OutputIterator set_symmetric_difference(
InputIterator1 first1,
InputIterator1 last1,
InputIterator2 first2,
InputIterator2 last2,
OutputIterator result,
Compare pred );
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class ForwardIterator>
ForwardIterator set_symmetric_difference(
ExecutionPolicy&& exec,
ForwardIterator1 first1,
ForwardIterator1 last1,
ForwardIterator2 first2,
ForwardIterator2 last2,
ForwardIterator result);
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class ForwardIterator, class Compare>
ForwardIterator set_symmetric_difference(
ExecutionPolicy&& exec,
ForwardIterator1 first1,
ForwardIterator1 last1,
ForwardIterator2 first2,
ForwardIterator2 last2,
ForwardIterator result,
Compare pred);
```

### Parameters

*exec*

The execution policy to use.

*first1*

An input iterator addressing the position of the first element in the first of two sorted source ranges to be united and sorted into a single range representing the symmetric difference of the two source ranges.

*last1*

An input iterator addressing the position one past the last element in the first of two sorted source ranges to be united and sorted into a single range representing the symmetric difference of the two source ranges.

*first2*

An input iterator addressing the position of the first element in second of two consecutive sorted source ranges to be united and sorted into a single range representing the symmetric difference of the two source ranges.

*last2*

An input iterator addressing the position one past the last element in second of two consecutive sorted source ranges to be united and sorted into a single range representing the symmetric difference of the two source ranges.

*result*

An output iterator addressing the position of the first element in the destination range where the two source ranges are to be united into a single sorted range representing the symmetric difference of the two source ranges.

*pred*

User-defined predicate function object that defines the sense in which one element is less than another. The binary predicate takes two arguments and should return **true** when the first element is less than the second element and **false** otherwise.

### Return value

An output iterator addressing the position one past the last element in the sorted destination range representing the symmetric difference of the two source ranges.

### Remarks

The destination range should not overlap either of the source ranges and should be large enough to contain the destination range.

The sorted source ranges must each be arranged as a precondition to the application of the `merge*`

algorithm in accordance with the same ordering as is to be used by the algorithm to sort the combined ranges.

The operation is stable as the relative order of elements within each range is preserved in the destination range. The source ranges are not modified by the algorithm merge.

The value types of the input iterators need be less-than comparable to be ordered, so that, given two elements, it may be determined either that they are equivalent (in the sense that neither is less than the other) or that one is less than the other. This results in an ordering between the nonequivalent elements. When there are equivalent elements in both source ranges, the elements in the first range precede the elements from the second source range in the destination range. If the source ranges contain duplicates of an element, then the destination range will contain the absolute value of the number by which the occurrences of those elements in the one of the source ranges exceeds the occurrences of those elements in the second source range.

The complexity of the algorithm is linear with at most `2 * ((last1 - first1) - (last2 - first2)) - 1`

comparisons for nonempty source ranges.

### Example

```
// alg_set_sym_diff.cpp
// compile with: /EHsc
#include <vector>
#include <algorithm>
#include <functional> // For greater<int>( )
#include <iostream>
// Return whether modulus of elem1 is less than modulus of elem2
bool mod_lesser (int elem1, int elem2 )
{
if ( elem1 < 0 )
elem1 = - elem1;
if ( elem2 < 0 )
elem2 = - elem2;
return elem1 < elem2;
}
int main()
{
using namespace std;
vector<int> v1a, v1b, v1 ( 12 );
vector<int>::iterator Iter1a, Iter1b, Iter1, Result1;
// Constructing vectors v1a & v1b with default less-than ordering
int i;
for ( i = -1 ; i <= 4 ; i++ )
{
v1a.push_back( i );
}
int ii;
for ( ii =-3 ; ii <= 0 ; ii++ )
{
v1b.push_back( ii );
}
cout << "Original vector v1a with range sorted by the\n "
<< "binary predicate less than is v1a = ( " ;
for ( Iter1a = v1a.begin( ) ; Iter1a != v1a.end( ) ; Iter1a++ )
cout << *Iter1a << " ";
cout << ")." << endl;
cout << "Original vector v1b with range sorted by the\n "
<< "binary predicate less than is v1b = ( " ;
for ( Iter1b = v1b.begin( ) ; Iter1b != v1b.end( ) ; Iter1b++ )
cout << *Iter1b << " ";
cout << ")." << endl;
// Constructing vectors v2a & v2b with ranges sorted by greater
vector<int> v2a ( v1a ) , v2b ( v1b ) , v2 ( v1 );
vector<int>::iterator Iter2a, Iter2b, Iter2, Result2;
sort ( v2a.begin( ), v2a.end( ), greater<int>( ) );
sort ( v2b.begin( ), v2b.end( ), greater<int>( ) );
cout << "Original vector v2a with range sorted by the\n "
<< "binary predicate greater is v2a = ( " ;
for ( Iter2a = v2a.begin( ) ; Iter2a != v2a.end( ) ; Iter2a++ )
cout << *Iter2a << " ";
cout << ")." << endl;
cout << "Original vector v2b with range sorted by the\n "
<< "binary predicate greater is v2b = ( " ;
for ( Iter2b = v2b.begin( ) ; Iter2b != v2b.end( ) ; Iter2b++ )
cout << *Iter2b << " ";
cout << ")." << endl;
// Constructing vectors v3a & v3b with ranges sorted by mod_lesser
vector<int> v3a ( v1a ), v3b ( v1b ) , v3 ( v1 );
vector<int>::iterator Iter3a, Iter3b, Iter3, Result3;
sort ( v3a.begin( ), v3a.end( ), mod_lesser );
sort ( v3b.begin( ), v3b.end( ), mod_lesser );
cout << "Original vector v3a with range sorted by the\n "
<< "binary predicate mod_lesser is v3a = ( " ;
for ( Iter3a = v3a.begin( ) ; Iter3a != v3a.end( ) ; Iter3a++ )
cout << *Iter3a << " ";
cout << ")." << endl;
cout << "Original vector v3b with range sorted by the\n "
<< "binary predicate mod_lesser is v3b = ( " ;
for ( Iter3b = v3b.begin( ) ; Iter3b != v3b.end( ) ; Iter3b++ )
cout << *Iter3b << " ";
cout << ")." << endl;
// To combine into a symmetric difference in ascending
// order with the default binary predicate less<int>( )
Result1 = set_symmetric_difference ( v1a.begin( ), v1a.end( ),
v1b.begin( ), v1b.end( ), v1.begin( ) );
cout << "Set_symmetric_difference of source ranges with default order,"
<< "\n vector v1mod = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != Result1 ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
// To combine into a symmetric difference in descending
// order, specify binary predicate greater<int>( )
Result2 = set_symmetric_difference ( v2a.begin( ), v2a.end( ),
v2b.begin( ), v2b.end( ),v2.begin( ), greater<int>( ) );
cout << "Set_symmetric_difference of source ranges with binary"
<< "predicate greater specified,\n vector v2mod = ( " ;
for ( Iter2 = v2.begin( ) ; Iter2 != Result2 ; Iter2++ )
cout << *Iter2 << " ";
cout << ")." << endl;
// To combine into a symmetric difference applying a user
// defined binary predicate mod_lesser
Result3 = set_symmetric_difference ( v3a.begin( ), v3a.end( ),
v3b.begin( ), v3b.end( ), v3.begin( ), mod_lesser );
cout << "Set_symmetric_difference of source ranges with binary "
<< "predicate mod_lesser specified,\n vector v3mod = ( " ; ;
for ( Iter3 = v3.begin( ) ; Iter3 != Result3 ; Iter3++ )
cout << *Iter3 << " ";
cout << ")." << endl;
}
```

## set_union

Unites all of the elements that belong to at least one of two sorted source ranges into a single, sorted destination range, where the ordering criterion may be specified by a binary predicate.

```
template<class InputIterator1, class InputIterator2, class OutputIterator>
OutputIterator set_union(
InputIterator1 first1,
InputIterator1 last1,
InputIterator2 first2,
InputIterator2 last2,
OutputIterator result );
template<class InputIterator1, class InputIterator2, class OutputIterator, class Compare>
OutputIterator set_union(
InputIterator1 first1,
InputIterator1 last1,
InputIterator2 first2,
InputIterator2 last2,
OutputIterator result,
Compare pred );
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class ForwardIterator>
ForwardIterator set_union(
ExecutionPolicy&& exec,
ForwardIterator1 first1,
ForwardIterator1 last1,
ForwardIterator2 first2,
ForwardIterator2 last2,
ForwardIterator result);
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class ForwardIterator, class Compare>
ForwardIterator set_union(
ExecutionPolicy&& exec,
ForwardIterator1 first1,
ForwardIterator1 last1,
ForwardIterator2 first2,
ForwardIterator2 last2,
ForwardIterator result,
Compare pred);
```

### Parameters

*exec*

The execution policy to use.

*first1*

An input iterator addressing the position of the first element in the first of two sorted source ranges to be united and sorted into a single range representing the union of the two source ranges.

*last1*

An input iterator addressing the position one past the last element in the first of two sorted source ranges to be united and sorted into a single range representing the union of the two source ranges.

*first2*

An input iterator addressing the position of the first element in second of two consecutive sorted source ranges to be united and sorted into a single range representing the union of the two source ranges.

*last2*

An input iterator addressing the position one past the last element in second of two consecutive sorted source ranges to be united and sorted into a single range representing the union of the two source ranges.

*result*

An output iterator addressing the position of the first element in the destination range where the two source ranges are to be united into a single sorted range representing the union of the two source ranges.

*pred*

User-defined predicate function object that defines the sense in which one element is less than another. The binary predicate takes two arguments and should return **true** when the first element is less than the second element and **false** otherwise.

### Return value

An output iterator addressing the position one past the last element in the sorted destination range representing the union of the two source ranges.

### Remarks

The sorted source ranges must each be arranged as a precondition to the application of the `merge`

algorithm in accordance with the same ordering as is to be used by the algorithm to sort the combined ranges.

The operation is stable as the relative order of elements within each range is preserved in the destination range. The source ranges are not modified by the algorithm `merge`

.

The value types of the input iterators need be less-than comparable to be ordered, so that, given two elements, it may be determined either that they are equivalent (in the sense that neither is less than the other) or that one is less than the other. This results in an ordering between the nonequivalent elements. When there are equivalent elements in both source ranges, the elements in the first range precede the elements from the second source range in the destination range. If the source ranges contain duplicates of an element, then the destination range will contain the maximum number of those elements that occur in both source ranges.

The complexity of the algorithm is linear with at most `2 * ((last1 - first1) - (last2 - first2)) - 1`

comparisons.

### Example

```
// alg_set_union.cpp
// compile with: /EHsc
#include <vector>
#include <algorithm>
#include <functional> // For greater<int>( )
#include <iostream>
// Return whether modulus of elem1 is less than modulus of elem2
bool mod_lesser ( int elem1, int elem2 )
{
if ( elem1 < 0 )
elem1 = - elem1;
if ( elem2 < 0 )
elem2 = - elem2;
return elem1 < elem2;
}
int main()
{
using namespace std;
vector<int> v1a, v1b, v1 ( 12 );
vector<int>::iterator Iter1a, Iter1b, Iter1, Result1;
// Constructing vectors v1a & v1b with default less than ordering
int i;
for ( i = -1 ; i <= 3 ; i++ )
{
v1a.push_back( i );
}
int ii;
for ( ii =-3 ; ii <= 1 ; ii++ )
{
v1b.push_back( ii );
}
cout << "Original vector v1a with range sorted by the\n "
<< "binary predicate less than is v1a = ( " ;
for ( Iter1a = v1a.begin( ) ; Iter1a != v1a.end( ) ; Iter1a++ )
cout << *Iter1a << " ";
cout << ")." << endl;
cout << "Original vector v1b with range sorted by the\n "
<< "binary predicate less than is v1b = ( " ;
for ( Iter1b = v1b.begin( ) ; Iter1b != v1b.end( ) ; Iter1b++ )
cout << *Iter1b << " ";
cout << ")." << endl;
// Constructing vectors v2a & v2b with ranges sorted by greater
vector<int> v2a ( v1a ) , v2b ( v1b ) , v2 ( v1 );
vector<int>::iterator Iter2a, Iter2b, Iter2, Result2;
sort ( v2a.begin( ), v2a.end( ), greater<int>( ) );
sort ( v2b.begin( ), v2b.end( ), greater<int>( ) );
cout << "Original vector v2a with range sorted by the\n "
<< "binary predicate greater is v2a = ( " ;
for ( Iter2a = v2a.begin( ) ; Iter2a != v2a.end( ) ; Iter2a++ )
cout << *Iter2a << " ";
cout << ")." << endl;
cout << "Original vector v2b with range sorted by the\n "
<< "binary predicate greater is v2b = ( " ;
for ( Iter2b = v2b.begin( ) ; Iter2b != v2b.end( ) ; Iter2b++ )
cout << *Iter2b << " ";
cout << ")." << endl;
// Constructing vectors v3a & v3b with ranges sorted by mod_lesser
vector<int> v3a ( v1a ), v3b ( v1b ) , v3 ( v1 );
vector<int>::iterator Iter3a, Iter3b, Iter3, Result3;
sort ( v3a.begin( ), v3a.end( ), mod_lesser );
sort ( v3b.begin( ), v3b.end( ), mod_lesser );
cout << "Original vector v3a with range sorted by the\n "
<< "binary predicate mod_lesser is v3a = ( " ;
for ( Iter3a = v3a.begin( ) ; Iter3a != v3a.end( ) ; Iter3a++ )
cout << *Iter3a << " ";
cout << ")." << endl;
cout << "Original vector v3b with range sorted by the\n "
<< "binary predicate mod_lesser is v3b = ( " ;
for ( Iter3b = v3b.begin( ) ; Iter3b != v3b.end( ) ; Iter3b++ )
cout << *Iter3b << " ";
cout << ")." << endl;
// To combine into a union in ascending order with the default
// binary predicate less<int>( )
Result1 = set_union ( v1a.begin( ), v1a.end( ),
v1b.begin( ), v1b.end( ), v1.begin( ) );
cout << "Union of source ranges with default order,"
<< "\n vector v1mod = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != Result1 ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
// To combine into a union in descending order, specify binary
// predicate greater<int>( )
Result2 = set_union ( v2a.begin( ), v2a.end( ),
v2b.begin( ), v2b.end( ),v2.begin( ), greater<int>( ) );
cout << "Union of source ranges with binary predicate greater "
<< "specified,\n vector v2mod = ( " ;
for ( Iter2 = v2.begin( ) ; Iter2 != Result2 ; Iter2++ )
cout << *Iter2 << " ";
cout << ")." << endl;
// To combine into a union applying a user-defined
// binary predicate mod_lesser
Result3 = set_union ( v3a.begin( ), v3a.end( ),
v3b.begin( ), v3b.end( ), v3.begin( ), mod_lesser );
cout << "Union of source ranges with binary predicate "
<< "mod_lesser specified,\n vector v3mod = ( " ; ;
for ( Iter3 = v3.begin( ) ; Iter3 != Result3 ; Iter3++ )
cout << *Iter3 << " ";
cout << ")." << endl;
}
```

## shuffle

Shuffles (rearranges) elements for a given range by using a random number generator.

```
template<class RandomAccessIterator, class UniformRandomNumberGenerator>
void shuffle(
RandomAccessIterator first,
RandomAccessIterator last,
UniformRandomNumberGenerator&& gen);
```

### Parameters

*first*

An iterator to the first element in the range to be shuffled, inclusive. Must meet the requirements of `RandomAccessIterator`

and `ValueSwappable`

.

*last*

An iterator to the last element in the range to be shuffled, exclusive. Must meet the requirements of `RandomAccessIterator`

and `ValueSwappable`

.

*gen*

The random number generator that the `shuffle()`

function will use for the operation. Must meet the requirements of a `UniformRandomNumberGenerator`

.

### Remarks

For more information, and a code sample that uses `shuffle()`

, see <random>.

## sort

Arranges the elements in a specified range into a nondescending order or according to an ordering criterion specified by a binary predicate.

```
template<class RandomAccessIterator>
void sort(
RandomAccessIterator first,
RandomAccessIterator last);
template<class RandomAccessIterator, class Compare>
void sort(
RandomAccessIterator first,
RandomAccessIterator last,
Compare pred);
template<class ExecutionPolicy, class RandomAccessIterator>
void sort(
ExecutionPolicy&& exec,
RandomAccessIterator first,
RandomAccessIterator last);
template<class ExecutionPolicy, class RandomAccessIterator, class Compare>
void sort(
ExecutionPolicy&& exec,
RandomAccessIterator first,
RandomAccessIterator last,
Compare pred);
```

### Parameters

*exec*

The execution policy to use.

*first*

A random-access iterator addressing the position of the first element in the range to be sorted.

*last*

A random-access iterator addressing the position one past the final element in the range to be sorted.

*pred*

User-defined predicate function object that defines the comparison criterion to be satisfied by successive elements in the ordering. This binary predicate takes two arguments and returns **true** if the two arguments are in order and **false** otherwise. This comparator function must impose a strict weak ordering on pairs of elements from the sequence. For more information, see Algorithms.

### Remarks

Elements are equivalent, but not necessarily equal, if neither is less than the other. The `sort`

algorithm is not stable and so does not guarantee that the relative ordering of equivalent elements will be preserved. The algorithm `stable_sort`

does preserve this original ordering.

The average of a sort complexity is `O( N log N )`

, where *N* = *last* - *first*.

### Example

```
// alg_sort.cpp
// compile with: /EHsc
#include <vector>
#include <algorithm>
#include <functional> // For greater<int>( )
#include <iostream>
// Return whether first element is greater than the second
bool UDgreater ( int elem1, int elem2 )
{
return elem1 > elem2;
}
int main()
{
using namespace std;
vector<int> v1;
vector<int>::iterator Iter1;
int i;
for ( i = 0 ; i <= 5 ; i++ )
{
v1.push_back( 2 * i );
}
int ii;
for ( ii = 0 ; ii <= 5 ; ii++ )
{
v1.push_back( 2 * ii + 1 );
}
cout << "Original vector v1 = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")" << endl;
sort( v1.begin( ), v1.end( ) );
cout << "Sorted vector v1 = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")" << endl;
// To sort in descending order. specify binary predicate
sort( v1.begin( ), v1.end( ), greater<int>( ) );
cout << "Resorted (greater) vector v1 = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")" << endl;
// A user-defined (UD) binary predicate can also be used
sort( v1.begin( ), v1.end( ), UDgreater );
cout << "Resorted (UDgreater) vector v1 = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")" << endl;
}
```

```
Original vector v1 = ( 0 2 4 6 8 10 1 3 5 7 9 11 )
Sorted vector v1 = ( 0 1 2 3 4 5 6 7 8 9 10 11 )
Resorted (greater) vector v1 = ( 11 10 9 8 7 6 5 4 3 2 1 0 )
Resorted (UDgreater) vector v1 = ( 11 10 9 8 7 6 5 4 3 2 1 0 )
```

## sort_heap

Converts a heap into a sorted range.

```
template<class RandomAccessIterator>
void sort_heap(
RandomAccessIterator first,
RandomAccessIterator last);
template<class RandomAccessIterator, class Compare>
void sort_heap(
RandomAccessIterator first,
RandomAccessIterator last,
Compare pred);
```

### Parameters

*first*

A random-access iterator addressing the position of the first element in the target heap.

*last*

A random-access iterator addressing the position one past the final element in the target heap.

*pred*

User-defined predicate function object that defines the sense in which one element is less than another. A comparison predicate takes two arguments and returns **true** when satisfied and **false** when not satisfied.

### Remarks

Heaps have two properties:

The first element is always the largest.

Elements may be added or removed in logarithmic time.

After the application if this algorithm, the range it was applied to is no longer a heap.

This is not a stable sort because the relative order of equivalent elements is not necessarily preserved.

The complexity is at most `N log N`

, where *N* = *last* - *first*.

### Example

```
// alg_sort_heap.cpp
// compile with: /EHsc
#include <algorithm>
#include <functional>
#include <iostream>
#include <ostream>
#include <string>
#include <vector>
using namespace std;
void print(const string& s, const vector<int>& v)
{
cout << s << ": ( ";
for (auto i = v.begin(); i != v.end(); ++i)
{
cout << *i << " ";
}
cout << ")" << endl;
}
int main()
{
vector<int> v;
for (int i = 1; i <= 9; ++i)
{
v.push_back(i);
}
print("Initially", v);
random_shuffle(v.begin(), v.end());
print("After random_shuffle", v);
make_heap(v.begin(), v.end());
print(" After make_heap", v);
sort_heap(v.begin(), v.end());
print(" After sort_heap", v);
random_shuffle(v.begin(), v.end());
print(" After random_shuffle", v);
make_heap(v.begin(), v.end(), greater<int>());
print("After make_heap with greater<int>", v);
sort_heap(v.begin(), v.end(), greater<int>());
print("After sort_heap with greater<int>", v);
}
```

## stable_partition

Classifies elements in a range into two disjoint sets, with those elements satisfying a unary predicate preceding those that fail to satisfy it, preserving the relative order of equivalent elements.

```
template<class BidirectionalIterator, class UnaryPredicate>
BidirectionalIterator stable_partition(
BidirectionalIterator first,
BidirectionalIterator last,
UnaryPredicate pred );
template<class ExecutionPolicy, class BidirectionalIterator, class UnaryPredicate>
BidirectionalIterator stable_partition(
ExecutionPolicy&& exec,
BidirectionalIterator first,
BidirectionalIterator last,
UnaryPredicate pred);
```

### Parameters

*exec*

The execution policy to use.

*first*

A bidirectional iterator addressing the position of the first element in the range to be partitioned.

*last*

A bidirectional iterator addressing the position one past the final element in the range to be partitioned.

*pred*

User-defined predicate function object that defines the condition to be satisfied if an element is to be classified. A unary predicate takes a single argument and returns **true** if satisfied, or **false** if not satisfied.

### Return value

A bidirectional iterator addressing the position of the first element in the range to not satisfy the predicate condition.

### Remarks

Elements *a* and *b* are equivalent, but not necessarily equal, if both `pred( a, b )`

is false and `pred( b, a )`

is false, where *pred* is the parameter-specified predicate. The `stable_partition`

algorithm is stable and guarantees that the relative ordering of equivalent elements will be preserved. The algorithm `partition`

does not necessarily preserve this original ordering.

### Example

```
// alg_stable_partition.cpp
// compile with: /EHsc
#include <vector>
#include <algorithm>
#include <iostream>
bool greater5 ( int value )
{
return value > 5;
}
int main()
{
using namespace std;
vector<int> v1, v2;
vector<int>::iterator Iter1, Iter2, result;
int i;
for ( i = 0 ; i <= 10 ; i++ )
v1.push_back( i );
int ii;
for ( ii = 0 ; ii <= 4 ; ii++ )
v1.push_back( 5 );
random_shuffle(v1.begin( ), v1.end( ) );
cout << "Vector v1 is ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
// Partition the range with predicate greater10
result = stable_partition (v1.begin( ), v1.end( ), greater5 );
cout << "The partitioned set of elements in v1 is:\n ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
cout << "The first element in v1 to fail to satisfy the"
<< "\n predicate greater5 is: " << *result << "." << endl;
}
```

## stable_sort

Arranges the elements in a specified range into a nondescending order or according to an ordering criterion specified by a binary predicate and preserves the relative ordering of equivalent elements.

```
template<class BidirectionalIterator>
void stable_sort(
BidirectionalIterator first,
BidirectionalIterator last );
template<class BidirectionalIterator, class Compare>
void stable_sort(
BidirectionalIterator first,
BidirectionalIterator last,
Compare pred );
template<class ExecutionPolicy, class RandomAccessIterator>
void stable_sort(
ExecutionPolicy&& exec,
RandomAccessIterator first,
RandomAccessIterator last);
template<class ExecutionPolicy, class RandomAccessIterator, class Compare>
void stable_sort(
ExecutionPolicy&& exec,
RandomAccessIterator first,
RandomAccessIterator last,
Compare pred);
```

### Parameters

*exec*

The execution policy to use.

*first*

A bidirectional iterator addressing the position of the first element in the range to be sorted.

*last*

A bidirectional iterator addressing the position one past the final element in the range to be sorted.

*pred*

User-defined predicate function object that defines the comparison criterion to be satisfied by successive elements in the ordering. A binary predicate takes two arguments and returns **true** when satisfied and **false** when not satisfied.

### Remarks

Elements are equivalent, but not necessarily equal, if neither is less than the other. The `sort`

algorithm is stable and guarantees that the relative ordering of equivalent elements will be preserved.

The run-time complexity of `stable_sort`

depends on the amount of memory available, but the best case (given sufficient memory) is `O(N log N)`

and the worst case is `O(N (log N)^2)`

, where *N* = *last* - *first*. Usually, the `sort`

algorithm is significantly faster than `stable_sort`

.

### Example

```
// alg_stable_sort.cpp
// compile with: /EHsc
#include <vector>
#include <algorithm>
#include <functional> // For greater<int>( )
#include <iostream>
// Return whether first element is greater than the second
bool UDgreater (int elem1, int elem2 )
{
return elem1 > elem2;
}
int main()
{
using namespace std;
vector<int> v1;
vector<int>::iterator Iter1;
int i;
for ( i = 0 ; i <= 5 ; i++ )
{
v1.push_back( 2 * i );
}
for ( i = 0 ; i <= 5 ; i++ )
{
v1.push_back( 2 * i );
}
cout << "Original vector v1 = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")" << endl;
stable_sort(v1.begin( ), v1.end( ) );
cout << "Sorted vector v1 = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")" << endl;
// To sort in descending order, specify binary predicate
stable_sort(v1.begin( ), v1.end( ), greater<int>( ) );
cout << "Resorted (greater) vector v1 = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")" << endl;
// A user-defined (UD) binary predicate can also be used
stable_sort(v1.begin( ), v1.end( ), UDgreater );
cout << "Resorted (UDgreater) vector v1 = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")" << endl;
}
```

```
Original vector v1 = ( 0 2 4 6 8 10 0 2 4 6 8 10 )
Sorted vector v1 = ( 0 0 2 2 4 4 6 6 8 8 10 10 )
Resorted (greater) vector v1 = ( 10 10 8 8 6 6 4 4 2 2 0 0 )
Resorted (UDgreater) vector v1 = ( 10 10 8 8 6 6 4 4 2 2 0 0 )
```

## swap

The first override exchanges the values of two objects. The second override exchanges the values between two arrays of objects.

```
template<class Type>
void swap(
Type& left,
Type& right);
template<class Type, size_t N>
void swap(
Type (& left)[N],
Type (& right)[N]);
```

### Parameters

*left*

For the first override, the first object to have its contents exchanged. For the second override, the first array of objects to have its contents exchanged.

*right*

For the first override, the second object to have its contents exchanged. For the second override, the second array of objects to have its contents exchanged.

### Remarks

The first overload is designed to operate on individual objects. The second overload swaps the contents of objects between two arrays.

### Example

```
// alg_swap.cpp
// compile with: /EHsc
#include <vector>
#include <algorithm>
#include <iostream>
int main()
{
using namespace std;
vector<int> v1, v2;
vector<int>::iterator Iter1, Iter2, result;
for ( int i = 0 ; i <= 10 ; i++ )
{
v1.push_back( i );
}
for ( int ii = 0 ; ii <= 4 ; ii++ )
{
v2.push_back( 5 );
}
cout << "Vector v1 is ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
cout << "Vector v2 is ( " ;
for ( Iter2 = v2.begin( ) ; Iter2 != v2.end( ) ; Iter2++ )
cout << *Iter2 << " ";
cout << ")." << endl;
swap( v1, v2 );
cout << "Vector v1 is ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
cout << "Vector v2 is ( " ;
for ( Iter2 = v2.begin( ) ; Iter2 != v2.end( ) ; Iter2++ )
cout << *Iter2 << " ";
cout << ")." << endl;
}
```

```
Vector v1 is ( 0 1 2 3 4 5 6 7 8 9 10 ).
Vector v2 is ( 5 5 5 5 5 ).
Vector v1 is ( 5 5 5 5 5 ).
Vector v2 is ( 0 1 2 3 4 5 6 7 8 9 10 ).
```

## swap_ranges

Exchanges the elements of one range with the elements of another, equal sized range.

```
template<class ForwardIterator1, class ForwardIterator2>
ForwardIterator2 swap_ranges(
ForwardIterator1 first1,
ForwardIterator1 last1,
ForwardIterator2 first2 );
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2>
ForwardIterator2 swap_ranges(
ExecutionPolicy&& exec,
ForwardIterator1 first1,
ForwardIterator1 last1,
ForwardIterator2 first2);
```

### Parameters

*exec*

The execution policy to use.

*first1*

A forward iterator pointing to the first position of the first range whose elements are to be exchanged.

*last1*

A forward iterator pointing to one past the final position of the first range whose elements are to be exchanged.

*first2*

A forward iterator pointing to the first position of the second range whose elements are to be exchanged.

### Return value

A forward iterator pointing to one past the final position of the second range whose elements are to be exchanged.

### Remarks

The ranges referenced must be valid; all pointers must be dereferenceable and within each sequence the last position is reachable from the first by incrementation. The second range has to be as large as the first range.

The complexity is linear with *last1* - *first1* swaps performed. If elements from containers of the same type are being swapped, them the `swap`

member function from that container should be used, because the member function typically has constant complexity.

### Example

```
// alg_swap_ranges.cpp
// compile with: /EHsc
#include <vector>
#include <deque>
#include <algorithm>
#include <iostream>
int main()
{
using namespace std;
vector<int> v1;
deque<int> d1;
vector<int>::iterator v1Iter1;
deque<int>::iterator d1Iter1;
int i;
for ( i = 0 ; i <= 5 ; i++ )
{
v1.push_back( i );
}
int ii;
for ( ii =4 ; ii <= 9 ; ii++ )
{
d1.push_back( 6 );
}
cout << "Vector v1 is ( " ;
for ( v1Iter1 = v1.begin( ) ; v1Iter1 != v1.end( ) ;v1Iter1 ++ )
cout << *v1Iter1 << " ";
cout << ")." << endl;
cout << "Deque d1 is ( " ;
for ( d1Iter1 = d1.begin( ) ; d1Iter1 != d1.end( ) ;d1Iter1 ++ )
cout << *d1Iter1 << " ";
cout << ")." << endl;
swap_ranges ( v1.begin( ), v1.end( ), d1.begin( ) );
cout << "After the swap_range, vector v1 is ( " ;
for ( v1Iter1 = v1.begin( ) ; v1Iter1 != v1.end( ) ;v1Iter1 ++ )
cout << *v1Iter1 << " ";
cout << ")." << endl;
cout << "After the swap_range deque d1 is ( " ;
for ( d1Iter1 = d1.begin( ) ; d1Iter1 != d1.end( ) ;d1Iter1 ++ )
cout << *d1Iter1 << " ";
cout << ")." << endl;
}
```

```
Vector v1 is ( 0 1 2 3 4 5 ).
Deque d1 is ( 6 6 6 6 6 6 ).
After the swap_range, vector v1 is ( 6 6 6 6 6 6 ).
After the swap_range deque d1 is ( 0 1 2 3 4 5 ).
```

## transform

Applies a specified function object to each element in a source range or to a pair of elements from two source ranges and copies the return values of the function object into a destination range.

```
template<class InputIterator, class OutputIterator, class UnaryFunction>
OutputIterator transform(
InputIterator first1,
InputIterator last1,
OutputIterator result,
UnaryFunction func );
template<class InputIterator1, class InputIterator2, class OutputIterator, class BinaryFunction>
OutputIterator transform(
InputIterator1 first1,
InputIterator1 last1,
InputIterator2 first2,
OutputIterator result,
BinaryFunction func );
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class UnaryOperation>
ForwardIterator2 transform(
ExecutionPolicy&& exec,
ForwardIterator1 first,
ForwardIterator1 last,
ForwardIterator2 result,
UnaryOperation op);
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class ForwardIterator, class BinaryOperation>
ForwardIterator transform(
ExecutionPolicy&& exec,
ForwardIterator1 first1,
ForwardIterator1 last1,
ForwardIterator2 first2,
ForwardIterator result,
BinaryOperation binary_op);
```

### Parameters

*exec*

The execution policy to use.

*first1*

An input iterator addressing the position of the first element in the first source range to be operated on.

*last1*

An input iterator addressing the position one past the final element in the first source range operated on.

*first2*

An input iterator addressing the position of the first element in the second source range to be operated on.

*result*

An output iterator addressing the position of the first element in the destination range.

*func*

User-defined unary function object used in the first version of the algorithm that is applied to each element in the first source range or A user-defined (UD) binary function object used in the second version of the algorithm that is applied pairwise, in a forward order, to the two source ranges.

### Return value

An output iterator addressing the position one past the final element in the destination range that is receiving the output elements transformed by the function object.

### Remarks

The ranges referenced must be valid; all pointers must be dereferenceable and within each sequence the last position must be reachable from the first by incrementation. The destination range must be large enough to contain the transformed source range.

If *result* is set equal to *first1* in the first version of the algorithm, then the source and destination ranges will be the same and the sequence will be modified in place. But the *result* may not address a position within the range [`first1`

+ 1, `last1`

).

The complexity is linear with at most (`last1`

- `first1`

) comparisons.

### Example

```
// alg_transform.cpp
// compile with: /EHsc
#include <vector>
#include <algorithm>
#include <functional>
#include <iostream>
// The function object multiplies an element by a Factor
template <class Type>
class MultValue
{
private:
Type Factor; // The value to multiply by
public:
// Constructor initializes the value to multiply by
MultValue ( const Type& value ) : Factor ( value ) { }
// The function call for the element to be multiplied
Type operator( ) ( Type& elem ) const
{
return elem * Factor;
}
};
int main()
{
using namespace std;
vector<int> v1, v2 ( 7 ), v3 ( 7 );
vector<int>::iterator Iter1, Iter2 , Iter3;
// Constructing vector v1
int i;
for ( i = -4 ; i <= 2 ; i++ )
{
v1.push_back( i );
}
cout << "Original vector v1 = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
// Modifying the vector v1 in place
transform (v1.begin( ), v1.end( ), v1.begin( ), MultValue<int> ( 2 ) );
cout << "The elements of the vector v1 multiplied by 2 in place gives:"
<< "\n v1mod = ( " ;
for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
cout << *Iter1 << " ";
cout << ")." << endl;
// Using transform to multiply each element by a factor of 5
transform ( v1.begin( ), v1.end( ), v2.begin( ), MultValue<int> ( 5 ) );
cout << "Multiplying the elements of the vector v1mod\n "
<< "by the factor 5 & copying to v2 gives:\n v2 = ( " ;
for ( Iter2 = v2.begin( ) ; Iter2 != v2.end( ) ; Iter2++ )
cout << *Iter2 << " ";
cout << ")." << endl;
// The second version of transform used to multiply the
// elements of the vectors v1mod & v2 pairwise
transform ( v1.begin( ), v1.end( ), v2.begin( ), v3.begin( ),
multiplies<int>( ) );
cout << "Multiplying elements of the vectors v1mod and v2 pairwise "
<< "gives:\n v3 = ( " ;
for ( Iter3 = v3.begin( ) ; Iter3 != v3.end( ) ; Iter3++ )
cout << *Iter3 << " ";
cout << ")." << endl;
}
```

```
Original vector v1 = ( -4 -3 -2 -1 0 1 2 ).
The elements of the vector v1 multiplied by 2 in place gives:
v1mod = ( -8 -6 -4 -2 0 2 4 ).
Multiplying the elements of the vector v1mod
by the factor 5 & copying to v2 gives:
v2 = ( -40 -30 -20 -10 0 10 20 ).
Multiplying elements of the vectors v1mod and v2 pairwise gives:
v3 = ( 320 180 80 20 0 20 80 ).
```

## unique

Removes duplicate elements that are adjacent to each other in a specified range.

```
template<class ForwardIterator>
ForwardIterator unique(
ForwardIterator first,
ForwardIterator last);
template<class ForwardIterator, class BinaryPredicate>
ForwardIterator unique(
ForwardIterator first,
ForwardIterator last,
BinaryPredicate pred);
template<class ExecutionPolicy, class ForwardIterator>
ForwardIterator unique(
ExecutionPolicy&& exec,
ForwardIterator first,
ForwardIterator last);
template<class ExecutionPolicy, class ForwardIterator, class BinaryPredicate>
ForwardIterator unique(
ExecutionPolicy&& exec,
ForwardIterator first,
ForwardIterator last,
BinaryPredicate pred);
```

### Parameters

*exec*

The execution policy to use.

*first*

A forward iterator addressing the position of the first element in the range to be scanned for duplicate removal.

*last*

A forward iterator addressing the position one past the final element in the range to be scanned for duplicate removal.

*pred*

User-defined predicate function object that defines the condition to be satisfied if two elements are to be taken as equivalent. A binary predicate takes two arguments and returns **true** when satisfied and **false** when not satisfied.

### Return value

A forward iterator to the new end of the modified sequence that contains no consecutive duplicates, addressing the position one past the last element not removed.

### Remarks

Both forms of the algorithm remove the second duplicate of a consecutive pair of equal elements.

The operation of the algorithm is stable so that the relative order of the undeleted elements is not changed.

The range referenced must be valid; all pointers must be dereferenceable and within the sequence the last position is reachable from the first by incrementation. he number of elements in the sequence is not changed by the algorithm `unique`

and the elements beyond the end of the modified sequence are dereferenceable but not specified.

The complexity is linear, requiring `(last - first) - 1`

comparisons.

List provides a more efficient member function "unique", which may perform better.

These algorithms cannot be used on an associative container.

### Example

```
// alg_unique.cpp
// compile with: /EHsc
#include <vector>
#include <algorithm>
#include <functional>
#include <iostream>
#include <ostream>
using namespace std;
// Return whether modulus of elem1 is equal to modulus of elem2
bool mod_equal ( int elem1, int elem2 )
{
if ( elem1 < 0 )
elem1 = - elem1;
if ( elem2 < 0 )
elem2 = - elem2;
return elem1 == elem2;
};
int main()
{
vector<int> v1;
vector<int>::iterator v1_Iter1, v1_Iter2, v1_Iter3,
v1_NewEnd1, v1_NewEnd2, v1_NewEnd3;
int i;
for ( i = 0 ; i <= 3 ; i++ )
{
v1.push_back( 5 );
v1.push_back( -5 );
}
int ii;
for ( ii = 0 ; ii <= 3 ; ii++ )
{
v1.push_back( 4 );
}
v1.push_back( 7 );
cout << "Vector v1 is ( " ;
for ( v1_Iter1 = v1.begin( ) ; v1_Iter1 != v1.end( ) ; v1_Iter1++ )
cout << *v1_Iter1 << " ";
cout << ")." << endl;
// Remove consecutive duplicates
v1_NewEnd1 = unique ( v1.begin( ), v1.end( ) );
cout << "Removing adjacent duplicates from vector v1 gives\n ( " ;
for ( v1_Iter1 = v1.begin( ) ; v1_Iter1 != v1_NewEnd1 ; v1_Iter1++ )
cout << *v1_Iter1 << " ";
cout << ")." << endl;
// Remove consecutive duplicates under the binary prediate mod_equals
v1_NewEnd2 = unique ( v1.begin( ), v1_NewEnd1 , mod_equal );
cout << "Removing adjacent duplicates from vector v1 under the\n "
<< " binary predicate mod_equal gives\n ( " ;
for ( v1_Iter2 = v1.begin( ) ; v1_Iter2 != v1_NewEnd2 ; v1_Iter2++ )
cout << *v1_Iter2 << " ";
cout << ")." << endl;
// Remove elements if preceded by an element that was greater
v1_NewEnd3 = unique ( v1.begin( ), v1_NewEnd2, greater<int>( ) );
cout << "Removing adjacent elements satisfying the binary\n "
<< " predicate mod_equal from vector v1 gives ( " ;
for ( v1_Iter3 = v1.begin( ) ; v1_Iter3 != v1_NewEnd3 ; v1_Iter3++ )
cout << *v1_Iter3 << " ";
cout << ")." << endl;
}
```

```
Vector v1 is ( 5 -5 5 -5 5 -5 5 -5 4 4 4 4 7 ).
Removing adjacent duplicates from vector v1 gives
( 5 -5 5 -5 5 -5 5 -5 4 7 ).
Removing adjacent duplicates from vector v1 under the
binary predicate mod_equal gives
( 5 4 7 ).
Removing adjacent elements satisfying the binary
predicate mod_equal from vector v1 gives ( 5 7 ).
```

## unique_copy

Copies elements from a source range into a destination range except for the duplicate elements that are adjacent to each other.

```
template<class InputIterator, class OutputIterator>
OutputIterator unique_copy(
InputIterator first,
InputIterator last,
OutputIterator result );
template<class InputIterator, class OutputIterator, class BinaryPredicate>
OutputIterator unique_copy(
InputIterator first,
InputIterator last,
OutputIterator result,
BinaryPredicate pred );
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2>
ForwardIterator2 unique_copy(
ExecutionPolicy&& exec,
ForwardIterator1 first,
ForwardIterator1 last,
ForwardIterator2 result);
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
class BinaryPredicate>
ForwardIterator2 unique_copy(ExecutionPolicy&& exec,
ForwardIterator1 first,
ForwardIterator1 last,
ForwardIterator2 result,
BinaryPredicate pred);
```

### Parameters

*exec*

The execution policy to use.

*first*

A forward iterator addressing the position of the first element in the source range to be copied.

*last*

A forward iterator addressing the position one past the final element in the source range to be copied.

*result*

An output iterator addressing the position of the first element in the destination range that is receiving the copy with consecutive duplicates removed.

*pred*

User-defined predicate function object that defines the condition to be satisfied if two elements are to be taken as equivalent. A binary predicate takes two arguments and returns **true** when satisfied and **false** when not satisfied.

### Return value

An output iterator addressing the position one past the final element in the destination range that is receiving the copy with consecutive duplicates removed.

### Remarks

Both forms of the algorithm remove the second duplicate of a consecutive pair of equal elements.

The operation of the algorithm is stable so that the relative order of the undeleted elements is not changed.

The ranges referenced must be valid; all pointers must be dereferenceable and within a sequence the last position is reachable from the first by incrementation.

The complexity is linear, requiring (`last`

- `first`

) comparisons.

### Example

```
// alg_unique_copy.cpp
// compile with: /EHsc
#include <vector>
#include <algorithm>
#include <functional>
#include <iostream>
#include <ostream>
using namespace std;
// Return whether modulus of elem1 is equal to modulus of elem2
bool mod_equal ( int elem1, int elem2 ) {
if ( elem1 < 0 )
elem1 = - elem1;
if ( elem2 < 0 )
elem2 = - elem2;
return elem1 == elem2;
};
int main() {
vector<int> v1;
vector<int>::iterator v1_Iter1, v1_Iter2,
v1_NewEnd1, v1_NewEnd2;
int i;
for ( i = 0 ; i <= 1 ; i++ ) {
v1.push_back( 5 );
v1.push_back( -5 );
}
int ii;
for ( ii = 0 ; ii <= 2 ; ii++ )
v1.push_back( 4 );
v1.push_back( 7 );
int iii;
for ( iii = 0 ; iii <= 5 ; iii++ )
v1.push_back( 10 );
cout << "Vector v1 is\n ( " ;
for ( v1_Iter1 = v1.begin( ) ; v1_Iter1 != v1.end( ) ; v1_Iter1++ )
cout << *v1_Iter1 << " ";
cout << ")." << endl;
// Copy first half to second, removing consecutive duplicates
v1_NewEnd1 = unique_copy ( v1.begin( ), v1.begin( ) + 8, v1.begin( ) + 8 );
cout << "Copying the first half of the vector to the second half\n "
<< "while removing adjacent duplicates gives\n ( " ;
for ( v1_Iter1 = v1.begin( ) ; v1_Iter1 != v1_NewEnd1 ; v1_Iter1++ )
cout << *v1_Iter1 << " ";
cout << ")." << endl;
int iv;
for ( iv = 0 ; iv <= 7 ; iv++ )
v1.push_back( 10 );
// Remove consecutive duplicates under the binary prediate mod_equals
v1_NewEnd2 = unique_copy ( v1.begin( ), v1.begin( ) + 14,
v1.begin( ) + 14 , mod_equal );
cout << "Copying the first half of the vector to the second half\n "
<< " removing adjacent duplicates under mod_equals gives\n ( " ;
for ( v1_Iter2 = v1.begin( ) ; v1_Iter2 != v1_NewEnd2 ; v1_Iter2++ )
cout << *v1_Iter2 << " ";
cout << ")." << endl;
}
```

## upper_bound

Finds the position of the first element in an ordered range that has a value that is greater than a specified value, where the ordering criterion may be specified by a binary predicate.

```
template<class ForwardIterator, class Type>
ForwardIterator upper_bound(
ForwardIterator first,
ForwardIterator last,
const Type& value);
template<class ForwardIterator, class Type, class Compare>
ForwardIterator upper_bound(
ForwardIterator first,
ForwardIterator last,
const Type& value,
Compare pred);
```

### Parameters

*first*

The position of the first element in the range to be searched.

*last*

The position one past the final element in the range to be searched.

*value*

The value in the ordered range that needs to be exceeded by the value of the element addressed by the iterator returned.

*pred*

User-defined comparison predicate function object that defines the sense in which one element is less than another. A comparison predicate takes two arguments and returns **true** when satisfied and **false** when not satisfied.

### Return value

A forward iterator to the position of the first element that has a value greater than a specified value.

### Remarks

The sorted source range referenced must be valid; all iterators must be dereferenceable and within the sequence the last position must be reachable from the first by incrementation.

A sorted range is a precondition of the use of `upper_bound`

and where the ordering criterion is the same as specified by the comparison predicate.

The range is not modified by `upper_bound`

.

The value types of the forward iterators need be less-than comparable to be ordered, so that, given two elements, it may be determined either that they are equivalent (in the sense that neither is less than the other) or that one is less than the other. This results in an ordering between the nonequivalent elements

`last - first`

).

### Example

```
// alg_upper_bound.cpp
// compile with: /EHsc
#include <vector>
#include <algorithm>
#include <functional> // greater<int>( )
#include <iostream>
// Return whether modulus of elem1 is less than modulus of elem2
bool mod_lesser( int elem1, int elem2 )
{
if ( elem1 < 0 )
elem1 = - elem1;
if ( elem2 < 0 )
elem2 = - elem2;
return elem1 < elem2;
}
int main()
{
using namespace std;
vector<int> v1;
// Constructing vector v1 with default less-than ordering
for ( auto i = -1 ; i <= 4 ; ++i )
{
v1.push_back( i );
}
for ( auto ii =-3 ; ii <= 0 ; ++ii )
{
v1.push_back( ii );
}
cout << "Starting vector v1 = ( " ;
for (const auto &Iter : v1)
cout << Iter << " ";
cout << ")." << endl;
sort(v1.begin(), v1.end());
cout << "Original vector v1 with range sorted by the\n "
<< "binary predicate less than is v1 = ( " ;
for (const auto &Iter : v1)
cout << Iter << " ";
cout << ")." << endl;
// Constructing vector v2 with range sorted by greater
vector<int> v2(v1);
sort(v2.begin(), v2.end(), greater<int>());
cout << "Original vector v2 with range sorted by the\n "
<< "binary predicate greater is v2 = ( " ;
for (const auto &Iter : v2)
cout << Iter << " ";
cout << ")." << endl;
// Constructing vectors v3 with range sorted by mod_lesser
vector<int> v3(v1);
sort(v3.begin(), v3.end(), mod_lesser);
cout << "Original vector v3 with range sorted by the\n "
<< "binary predicate mod_lesser is v3 = ( " ;
for (const auto &Iter : v3)
cout << Iter << " ";
cout << ")." << endl;
// Demonstrate upper_bound
vector<int>::iterator Result;
// upper_bound of 3 in v1 with default binary predicate less<int>()
Result = upper_bound(v1.begin(), v1.end(), 3);
cout << "The upper_bound in v1 for the element with a value of 3 is: "
<< *Result << "." << endl;
// upper_bound of 3 in v2 with the binary predicate greater<int>( )
Result = upper_bound(v2.begin(), v2.end(), 3, greater<int>());
cout << "The upper_bound in v2 for the element with a value of 3 is: "
<< *Result << "." << endl;
// upper_bound of 3 in v3 with the binary predicate mod_lesser
Result = upper_bound(v3.begin(), v3.end(), 3, mod_lesser);
cout << "The upper_bound in v3 for the element with a value of 3 is: "
<< *Result << "." << endl;
}
```

## Feedback

Loading feedback...