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& _Val
   );
template<class ForwardIterator, class Type, class Predicate>
   ForwardIterator upper_bound(
      ForwardIterator _First, 
      ForwardIterator _Last,
      const Type& _Val,
            Predicate _Comp
   );

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.

  • _Val
    The value in the ordered range that needs to be exceeded by the value of the element addressed by the iterator returned.

  • _Comp
    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 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 binary 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

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

Example

// alg_upper_bound.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, Result1;

   // Constructing vectors v1a & v1b with default less-than ordering
   int i;
   for ( i = -1 ; i <= 4 ; i++ )
   {
      v1.push_back(  i );
   }

   int ii;
   for ( ii =-3 ; ii <= 0 ; ii++ )
   {
      v1.push_back(  ii  );
   }

   sort ( v1.begin ( ) , v1.end ( ) );
   cout << "Original vector v1 with range sorted by the\n "
        << "binary predicate less than is  v1 = ( " ;
   for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ )
      cout << *Iter1 << " ";
   cout << ")." << endl;
   
   // Constructing vectors v2 with range sorted by greater
   vector <int> v2 ( v1 );
   vector <int>::iterator Iter2, Result2;
   sort ( v2.begin ( ) , v2.end ( ) , greater<int> ( ) );
   
   cout << "Original vector v2 with range sorted by the\n "
        <<  "binary predicate greater is    v2 = ( " ;
   for ( Iter2 = v2.begin ( ) ; Iter2 != v2.end ( ) ; Iter2++ )
      cout << *Iter2 << " ";
   cout << ")." << endl;

   // Constructing vectors v3 with range sorted by mod_lesser
   vector <int> v3 ( v1 );
   vector <int>::iterator Iter3, Result3;
   sort ( v3.begin ( ) , v3.end ( ) , mod_lesser );

   cout << "Original vector v3 with range sorted by the\n "
        <<  "binary predicate mod_lesser is v3 = ( " ;
   for ( Iter3 = v3.begin ( ) ; Iter3 != v3.end ( ) ; Iter3++ )
      cout << *Iter3 << " ";
   cout << ")." << endl;

   // upper_bound of 3 in v1 with default binary predicate less <int> ( )
   Result1 = upper_bound ( v1.begin ( ) , v1.end ( ) , 3 );
   cout << "The upper_bound in v2 for the element with a value of 3 is: "
        << *Result1 << "." << endl;

   // upper_bound of 3 in v2 with the binary predicate greater <int> ( )
   Result2 = upper_bound ( v2.begin ( ) , v2.end ( ) , 3, greater <int> ( ) );
   cout << "The upper_bound in v2 for the element with a value of 3 is: "
        << *Result2 << "." << endl;

   // upper_bound of 3 in v3 with the binary predicate  mod_lesser
   Result3 = upper_bound ( v3.begin ( ) , v3.end ( ) , 3,mod_lesser );
   cout << "The upper_bound in v3 for the element with a value of 3 is: "
        << *Result3 << "." << endl;
}

Original vector v1 with range sorted by the
 binary predicate less than is  v1 = ( -3 -2 -1 -1 0 0 1 2 3 4 ).
Original vector v2 with range sorted by the
 binary predicate greater is    v2 = ( 4 3 2 1 0 0 -1 -1 -2 -3 ).
Original vector v3 with range sorted by the
 binary predicate mod_lesser is v3 = ( 0 0 -1 -1 1 -2 2 -3 3 4 ).
The upper_bound in v2 for the element with a value of 3 is: 4.
The upper_bound in v2 for the element with a value of 3 is: 2.
The upper_bound in v3 for the element with a value of 3 is: 4.

Requirements

Header: <algorithm>

Namespace: std

See Also

Concepts

<algorithm> Members

Predicate Version of upper_bound

upper_bound (STL Samples)

Standard Template Library