Home » C++ STL

std::includes() function with example in C++

In this article, we are going to see what is the usage of std::includes(), and how to use that efficiently in the program?
Submitted by Radib Kar, on July 18, 2020

std::includes()

includes() is a very helpful STL function which checks whether a sorted range includes another sorted range or not. In other words, it helps to check whether a set is a subset of another set or not considering the set is ordered. Needless to say, both range/set must be ordered in the same fashion, i.e., either both in ascending or both in descending order. Otherwise, it will fail to detect.

It has two kind of usages:

1) Default comparator

Syntax:

bool includes(
    InputIterator1 first1, 
    InputIterator1 last1,
    InputIterator2 first2, 
    InputIterator2 last2);

Where,

• InputIterator1 first1 - starting range of the container which will include
• InputIterator1 last1 - ending range of the container which will include
• InputIterator2 first2 - starting range of the container which will be included
• InputIterator2 last2 - starting range of the container which will be included

So basically [first1,last1] defines the container which will include contents and [first2, last2] defines the container whose contents will be included.

The function returns true if the container1 includes container 2, False otherwise. Since, default comparator is used, two elements, a and b are considered equivalent if (!(a<b) && !(b<a)).

For example:

If container1 is [3, 5, 7, 9] and container2 is [5, 9] then container1 includes container2 and thus the include function will return true;

But if the container was [9, 5] it would have retuned false because when 9 is found the range is already covered in container1, no 5 is there after 9 in container 1. Also, if container2 is [5,8] it will return false as container1 does not container 8 at all.

Below is the implementation:

Example 1

Case 1: arr1=[3,5,7,9], arr2=[5,9]

#include <bits/stdc++.h>
using namespace std;

int main()
{
    vector<int> arr1{ 3, 5, 7, 9 };
    vector<int> arr2{ 5, 9 };

    if (includes(arr1.begin(), arr1.end(), arr2.begin(), arr2.end()))
        cout << "arr1 contains arr2\n";
    else
        cout << "arr1 doesn't contain arr2\n";
    
    return 0;
}

Output

arr1 contains arr2

Example 2

Case 2: arr2=[3,5,7,9], arr2=[9,5]

#include <bits/stdc++.h>
using namespace std;

int main()
{
    vector<int> arr1{ 3, 5, 7, 9 };
    vector<int> arr2{ 9, 5 };

    if (includes(arr1.begin(), arr1.end(), arr2.begin(), arr2.end()))
        cout << "arr1 contains arr2\n";
    else
        cout << "arr1 doesn't contain arr2\n";

    return 0;
}

Output

arr1 doesn't contain arr2

Example 3

Case 3: arr2=[3,5,7,9], arr2=[5, 8]

#include <bits/stdc++.h>
using namespace std;

int main()
{
    vector<int> arr1{ 3, 5, 7, 9 };
    vector<int> arr2{ 5, 8 };

    if (includes(arr1.begin(), arr1.end(), arr2.begin(), arr2.end()))
        cout << "arr1 contains arr2\n";
    else
        cout << "arr1 doesn't contain arr2\n";

    return 0;
}

Output

arr1 doesn't contain arr2

Using user-defined comparator

We can use our user-defined comparator as well to extend the usage of the includes() function.

The syntax for include will be:

bool includes(
    InputIterator1 first1, 
    InputIterator1 last1,
    InputIterator2 first2, 
    InputIterator2 last2, 
    Compare comp );

Where all the arguments are the same as before except the additional argument which is the user-defined comparator function. Two elements a & b are said to be equal if (!comp(a, b) && !comp(b, a)) is true/

We can show the need for a user-defined comparator through an example.

Let's say we the elements are not any primitive data type, but rather some user-defined data type. In those cases to compare two objects(elements), we need to write our user-defined comparator.

Example

Sat for example below is the class structure:

class student {

    int score;
    int roll;
    string name;

public:
    student()
    {
        score = 0;
        roll = 0;
        name = "";
    }
    student(int sc, int ro, string nm)
    {
        score = sc;
        roll = ro;
        name = nm;
    }

    int get_score()
    {
        return score;
    }
    int get_roll()
    {
        return roll;
    }
    string get_name()
    {
        return name;
    }
};

In the above case, we can’t compare using '<' or '>' operators. Rather we need our user-defined comparator may be something like:

bool comp(student a, student b)
{
    //if all details are same then both elements are same otherwise false
    if (a.get_name() == b.get_name() && a.get_score() == b.get_score() && a.get_roll() == b.get_roll())
        return false;

    return true;
}

Now you must be wondering why we returned false when all details match. This is because both objects a & b are considered to be same if !comp(a,b) && !comp(b,a). Now can extend the logic as per your use cases.