C++ Algorithm is_heap()

C++ Algorithm is_heap() function is used to check whether the elements in the range [first, last) form a heap. It returns true if the elements in the specified range forms a heap.

Elements are compared using operator < for the first version or using the given binary comparison function comp for the second version.

Syntax

default (1)           template <class RandomAccessIterator>
                  bool is_heap (RandomAccessIterator first, RandomAccessIterator last);

custom (2)      template <class RandomAccessIterator, class Compare>
                bool is_heap (RandomAccessIterator first, RandomAccessIterator last,
                                          Compare comp);

Parameter

first: A random access iterator pointing to the first element of a range to chaeck for a heap.

last: A random access iterator pointing to the past last element in the range to check for a heap.

comp: A user-defined binary predicate function that accepts two arguments and returns true if the two arguments are in order and false otherwise. It follows the strict weak ordering to order the elements.

Return value

It returns true if the elements in the specified range forms a heap otherwise it returns false.

Complexity

Complexity is up to linear in one less than the distance between first and last: compares pairs of elements until a mismatch is found.

Data races

The objects in the range [first, last) are accessed.

Exceptions

This function throws an exception if either an element comparisons or an operation on iterator throws an exception.

Note: The invalid parameters cause an undefined behavior.

Example 1

Let's see the simple example to demonstrate the use of is_heap():

#include <iostream>
#include <vector>
#include <algorithm>

using namespace std;

int main()
{
  vector<int> v = {3, 1, 4};

  cout << boolalpha;

  cout << "before: is heap? "
            << is_heap(v.begin(), v.end()) << endl;

  make_heap(v.begin(), v.end());
  cout << " after: is heap? "
            << is_heap(v.begin(), v.end()) << endl;
            
return 0;
}

Output:

before: is heap? false
 after: is heap? true

Example 2

Let's see another simple example:

#include <iostream>
#include <algorithm>
#include <vector>

using namespace std;
 
int main()
{
    vector<int> v { 2, 3, 4, 1, 5, 9 };
 
    cout << "initially, v: ";
    for (auto i : v) cout << i << ' ';
    cout << '\n';
 
    if (!is_heap(v.begin(), v.end())) {
        cout << "making heap...\n";
        make_heap(v.begin(), v.end());
    }
 
    cout << "after make_heap, v: ";
    for (auto i : v) cout << i << ' ';
    cout << '\n';
    
    return 0;
}

Output:

initially, v: 2 3 4 1 5 9 
making heap...
after make_heap, v: 9 5 4 1 3 2

Example 3

Let's see another simple example:

#include <iostream>
#include <vector>
#include <algorithm>

using namespace std;

bool ignore_case(char a, char b) {
   return (tolower(a) == tolower(b));
}

int main(void) {
   vector<char> v = {'E', 'd', 'C', 'b', 'A'};
   bool result;

   result = is_heap(v.begin(), v.end());

   if (result == false)
      cout << "Given sequence is not a max heap." << endl;

   result = is_heap(v.begin(), v.end(), ignore_case);

   if (result == true)
      cout << "Given sequence is a max heap." << endl;
      
      return 0;
}

Output:

Given sequence is not a max heap.
Given sequence is a max heap.

Example 4

Let's see a simple example:

#include <iostream>     // std::cout
#include <algorithm>    // std::is_heap, std::make_heap, std::pop_heap
#include <vector>       // std::vector

using namespace std;

int main () {
  vector<int> foo {9,5,2,6,4,1,3,8,7};

  if (!is_heap(foo.begin(),foo.end()))
    make_heap(foo.begin(),foo.end());

  cout << "Popping out elements:";
  while (!foo.empty()) {
    pop_heap(foo.begin(),foo.end());   // moves largest element to back
    cout << ' ' << foo.back();         // prints back
    foo.pop_back();                         // pops element out of container
  }
  cout << '\n';

  return 0;
}

Output: