C++ algorithm: std::includes Function Template

C++ std::includes

The std::includes function in C++ checks whether one sorted range is a subset of another sorted range. Both ranges must be sorted according to the same criteria for the function to work correctly. This is useful for determining whether all elements of one container are present in another.

---

Syntax of std::includes

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);

Parameters of std::includes

Parameter	Description
first1, last1	Input iterators defining the first (larger) range to check.
first2, last2	Input iterators defining the second (smaller) range to check as a subset of the first range.
comp (optional)	A binary comparison function that defines the criteria for comparison. Defaults to <.

---

Return Value of std::includes

Returns true if every element in the second range is contained in the first range. Returns false otherwise.

---

Examples for std::includes

Example 1: Basic Usage of std::includes

This example demonstrates checking whether a smaller set of numbers is a subset of a larger set:

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

int main() {
    std::vector<int> larger = {1, 2, 3, 4, 5};
    std::vector<int> smaller = {2, 3, 4};

    if (std::includes(larger.begin(), larger.end(), smaller.begin(), smaller.end())) {
        std::cout << "The larger set includes the smaller set." << std::endl;
    } else {
        std::cout << "The larger set does not include the smaller set." << std::endl;
    }

    return 0;
}

Explanation:

1. Include necessary headers:
   • <iostream>: Used for input/output operations.
   • <algorithm>: Includes the std::includes function.
   • <vector>: Used for the std::vector container.
2. Initialize two vectors:
   • A vector named larger is initialized with the elements {1, 2, 3, 4, 5}.
   • A vector named smaller is initialized with the elements {2, 3, 4}.
   • Both vectors must be sorted in ascending order for the std::includes function to work correctly.
3. Use std::includes to check inclusion:
   • The function std::includes checks whether all elements of the smaller vector are present in the larger vector.
   • It takes four arguments:
     • larger.begin(): Iterator pointing to the beginning of the larger vector.
     • larger.end(): Iterator pointing to the end of the larger vector.
     • smaller.begin(): Iterator pointing to the beginning of the smaller vector.
     • smaller.end(): Iterator pointing to the end of the smaller vector.
   • The function returns true if the larger vector includes all elements of the smaller vector; otherwise, it returns false.
4. Check the result:
   • If std::includes returns true, the program outputs: "The larger set includes the smaller set.".
   • If std::includes returns false, the program outputs: "The larger set does not include the smaller set.".
5. Output the result:
   • The program prints the result of the inclusion check to the console.

Output:

The larger set includes the smaller set.

Example 2: Using a Custom Comparison Function for std::includes

This example demonstrates checking inclusion using a custom comparison function:

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

bool descending(int a, int b) {
    return a > b;
}

int main() {
    std::vector<int> larger = {5, 4, 3, 2, 1};
    std::vector<int> smaller = {4, 3, 2};

    if (std::includes(larger.begin(), larger.end(), smaller.begin(), smaller.end(), descending)) {
        std::cout << "The larger set includes the smaller set in descending order." << std::endl;
    } else {
        std::cout << "The larger set does not include the smaller set in descending order." << std::endl;
    }

    return 0;
}

Explanation:

1. Define a custom comparison function:
   • The function descending takes two integers as input.
   • It returns true if the first integer is greater than the second, ensuring a descending order comparison.
2. Use std::includes to check inclusion:
   • The function std::includes checks whether all elements of the smaller vector are present in the larger vector, based on the custom descending comparison.
   • It takes five arguments:
     • larger.begin(): Iterator pointing to the beginning of the larger vector.
     • larger.end(): Iterator pointing to the end of the larger vector.
     • smaller.begin(): Iterator pointing to the beginning of the smaller vector.
     • smaller.end(): Iterator pointing to the end of the smaller vector.
     • descending: Custom comparison function to handle descending order.
   • The function returns true if the larger vector includes all elements of the smaller vector in descending order; otherwise, it returns false.

Output:

The larger set includes the smaller set in descending order.

Exception Handling in std::includes

The std::includes function does not throw exceptions itself. However, the comparison function passed as an argument may throw exceptions, which can be caught and handled appropriately.

Example 1: Exception in Custom Comparison Function

This example demonstrates how exceptions in a custom comparison function are handled:

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

bool faulty_compare(int a, int b) {
    if (a == 3 || b == 3) {
        throw std::runtime_error("Comparison involving 3 is not allowed.");
    }
    return a < b;
}

int main() {
    std::vector<int> larger = {1, 2, 3, 4, 5};
    std::vector<int> smaller = {2, 3, 4};

    try {
        if (std::includes(larger.begin(), larger.end(), smaller.begin(), smaller.end(), faulty_compare)) {
            std::cout << "The larger set includes the smaller set." << std::endl;
        } else {
            std::cout << "The larger set does not include the smaller set." << std::endl;
        }
    } catch (const std::exception& e) {
        std::cerr << "Exception caught: " << e.what() << std::endl;
    }

    return 0;
}

Explanation:

1. Define a custom comparison function:
   • The function descending takes two integers as input.
   • It returns true if the first integer is greater than the second, ensuring a descending order comparison.
2. Use std::includes to check inclusion:
   • The function std::includes checks whether all elements of the smaller vector are present in the larger vector, based on the custom descending comparison.
   • It takes five arguments:
     • larger.begin(): Iterator pointing to the beginning of the larger vector.
     • larger.end(): Iterator pointing to the end of the larger vector.
     • smaller.begin(): Iterator pointing to the beginning of the smaller vector.
     • smaller.end(): Iterator pointing to the end of the smaller vector.
     • descending: Custom comparison function to handle descending order.
   • The function returns true if the larger vector includes all elements of the smaller vector in descending order; otherwise, it returns false.

Output:

Exception caught: Comparison involving 3 is not allowed.