The includes function in C++ returns a boolean value of true if each element in the sorted range [first2, last2) is present in the sorted range [first1, last1).
It also returns true if [first2, last2) is empty.
Elements are compared using the < operator in the initial version or by utilizing the specified binary evaluation function comp in the alternate version.
Syntax
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 comp);
Parameter
An input iterator indicating the initial element in the first of two orderly input sequences to be examined for the presence of all elements from the second sequence.
An input iterator pointing to the element before the last one in the initial sorted sequence is used to check if all elements from the second sequence are present in the first one.
An initial iterator pointing to the first item in the second orderly origin sequence to be examined for the presence of all elements from the second sequence within the first sequence.
last2: An input iterator indicating the position after the last element in the second sorted origin sequence that will be checked to verify if all its elements are present in the first sequence.
comp: A custom binary predicate function that validates the order of two arguments, returning true if they are sequential and false otherwise. It adheres to the strict weak ordering principle for element arrangement.
Return value
This function will output true if all elements within the range [first2, last2) are present in the range [first1, last1); otherwise, it will output false.
Complexity
Complexity increases linearly with the separation between the ranges [first1, last1) and [first2, last2): executing a maximum of 2*(count1+count2)-1 comparisons. Here, count1 is calculated as last1 - first1, and count2 is determined as last2 - first2.
Data races
The elements within the range [first1, last1) and [first2, last2) are being accessed.
Exceptions
This function will raise an exception if there is an exception thrown during element comparisons or iterator operations.
Note: The invalid parameters cause an undefined behavior.
Example 1
Let's explore a straightforward example to showcase the functionality of includes:
#include <iostream>
#include <set>
#include <algorithm>
using namespace std;
int main()
{
set<int> a = {0, 2, 3, 4, 5, 6};
set<int> b = {2, 4, 6};
set<int> c = {2, 4, 7};
cout << boolalpha;
cout << includes(a.begin(), a.end(), b.begin(), b.end()) << endl;
cout << includes(a.begin(), a.end(), c.begin(), c.end()) << endl;
return 0;
}
Output:
true
false
Example 2
Let's see another simple example:
#include <iostream>
#include <algorithm>
#include <cctype>
#include <vector>
using namespace std;
int main()
{
vector<char> v1 {'a', 'b', 'c', 'f', 'h', 'x'};
vector<char> v2 {'a', 'b', 'c'};
vector<char> v3 {'a', 'c'};
vector<char> v4 {'g'};
vector<char> v5 {'a', 'c', 'g'};
for (auto i : v1) cout << i << ' ';
cout << "\nincludes:\n" << boolalpha;
for (auto i : v2) cout << i << ' ';
cout << ": " << includes(v1.begin(), v1.end(), v2.begin(), v2.end()) << '\n';
for (auto i : v3) cout << i << ' ';
cout << ": " << includes(v1.begin(), v1.end(), v3.begin(), v3.end()) << '\n';
for (auto i : v4) cout << i << ' ';
cout << ": " << includes(v1.begin(), v1.end(), v4.begin(), v4.end()) << '\n';
for (auto i : v5) cout << i << ' ';
cout << ": " << includes(v1.begin(), v1.end(), v5.begin(), v5.end()) << '\n';
auto cmp_nocase = [](char a, char b) {
return std::tolower(a) < std::tolower(b);
};
vector<char> v6 {'A', 'B', 'C'};
for (auto i : v6) cout << i << ' ';
cout << ": (case-insensitive) "
<< includes(v1.begin(), v1.end(), v6.begin(), v6.end(), cmp_nocase)
<< '\n';
return 0;
}
Output:
a b c f h x
includes:
a b c : true
a c : true
g : false
a c g : false
A B C : (case-insensitive) true
Example 3
Let's see another simple example:
#include <iostream> // std::cout
#include <algorithm> // std::includes, std::sort
using namespace std;
bool myfunction (int i, int j) { return i<j; }
int main () {
int container[] = {5,10,15,20,25,30,35,40,45,50};
int continent[] = {40,30,20,10};
sort (container,container+10);
sort (continent,continent+4);
// using default comparison:
if ( includes(container,container+10,continent,continent+4) )
cout << "container includes continent!\n";
// using myfunction as comp:
if ( includes(container,container+10,continent,continent+4, myfunction) )
cout << "container includes continent!\n";
return 0;
}
Output:
container includes continent!
container includes continent!
Example 4
Let's see a simple example:
#include <iostream> // std::cout
#include <algorithm> // std::includes, std::sort
using namespace std;
int main()
{
// lottery numbers
vector<int> lottery = { 1, 4, 6, 3, 2, 54 , 32 };
// Numbers in user's card
vector<int> user = { 1, 2, 4, 6 };
// sorting initial containers
sort(lottery.begin(), lottery.end());
sort(user.begin(), user.end());
// using include() check if all elements
// of user are present as lottery numbers
if(includes(lottery.begin(), lottery.end(), user.begin(), user.end()))
cout << "User has won lottery ( all numbers are lottey numbers )";
else
cout << "User has not won the lottery";
return 0;
}
Output:
User has won lottery ( all numbers are lottey numbers )
