std::find_end (3) - Linux Manuals

std::find_end: std::find_end

Command to display std::find_end manual in Linux: $ man 3 std::find_end

NAME

std::find_end - std::find_end

Synopsis

Defined in header <algorithm>
template< class ForwardIt1, class ForwardIt2 >
ForwardIt1 find_end( ForwardIt1 first, ForwardIt1 last, (until C++20)
ForwardIt2 s_first, ForwardIt2 s_last );
template< class ForwardIt1, class ForwardIt2 >
constexpr ForwardIt1 find_end( ForwardIt1 first, ForwardIt1 last, (since C++20)
ForwardIt2 s_first, ForwardIt2 s_last );
template< class ExecutionPolicy, class ForwardIt1, class ForwardIt2 >
ForwardIt1 find_end( ExecutionPolicy&& policy, ForwardIt1 first, ForwardIt1 last, (2) (since C++17)
ForwardIt2 s_first, ForwardIt2 s_last ); (1)
template< class ForwardIt1, class ForwardIt2, class BinaryPredicate >
ForwardIt1 find_end( ForwardIt1 first, ForwardIt1 last, (until C++20)
ForwardIt2 s_first, ForwardIt2 s_last, BinaryPredicate p );
template< class ForwardIt1, class ForwardIt2, class BinaryPredicate >
constexpr ForwardIt1 find_end( ForwardIt1 first, ForwardIt1 last, (3) (since C++20)
ForwardIt2 s_first, ForwardIt2 s_last, BinaryPredicate p );
template< class ExecutionPolicy, class ForwardIt1, class ForwardIt2, class BinaryPredicate >
ForwardIt1 find_end( ExecutionPolicy&& policy, ForwardIt1 first, ForwardIt1 last, (4) (since C++17)
ForwardIt2 s_first, ForwardIt2 s_last, BinaryPredicate p );

Searches for the last occurrence of the sequence [s_first, s_last) in the range [first, last).
1) Elements are compared using operator==.
3) Elements are compared using the given binary predicate p.
2,4) Same as (1,3), but executed according to policy. These overloads do not participate in overload resolution unless std::is_execution_policy_v<std::decay_t<ExecutionPolicy>> is true

Parameters

first, last - the range of elements to examine
s_first, s_last - the range of elements to search for
policy - the execution policy to use. See execution_policy for details.
                  binary predicate which returns true if the elements should be treated as equal.
                  The signature of the predicate function should be equivalent to the following:
                  bool pred(const Type1 &a, const Type2 &b);
p - While the signature does not need to have const &, the function must not modify the objects passed to it and must be able to accept all values of type (possibly const) Type1 and Type2 regardless of value_category (thus, Type1 & is not allowed
                  , nor is Type1 unless for Type1 a move is equivalent to a copy
                  (since C++11)).
                  The types Type1 and Type2 must be such that objects of types ForwardIt1 and ForwardIt2 can be dereferenced and then implicitly converted to Type1 and Type2 respectively.

Type requirements

-
ForwardIt1 must meet the requirements of LegacyForwardIterator.
-
ForwardIt2 must meet the requirements of LegacyForwardIterator.

Return value

Iterator to the beginning of last occurrence of the sequence [s_first, s_last) in range [first, last).

If no such sequence is found, last is returned. (until C++11)
If [s_first, s_last) is empty or if no such sequence is found, last is returned. (since C++11)

Complexity

Does at most S*(N-S+1) comparisons where S = distance(s_first, s_last) and N = distance(first, last).

Exceptions

The overloads with a template parameter named ExecutionPolicy report errors as follows:

* If execution of a function invoked as part of the algorithm throws an exception and ExecutionPolicy is one of the standard_policies, std::terminate is called. For any other ExecutionPolicy, the behavior is implementation-defined.
* If the algorithm fails to allocate memory, std::bad_alloc is thrown.

Possible implementation

First version

  template<class ForwardIt1, class ForwardIt2>
  ForwardIt1 find_end(ForwardIt1 first, ForwardIt1 last,
                      ForwardIt2 s_first, ForwardIt2 s_last)
  {
      if (s_first == s_last)
          return last;
      ForwardIt1 result = last;
      while (true) {
          ForwardIt1 new_result = std::search(first, last, s_first, s_last);
          if (new_result == last) {
              break;
          } else {
              result = new_result;
              first = result;
              ++first;
          }
      }
      return result;
  }

Second version

  template<class ForwardIt1, class ForwardIt2, class BinaryPredicate>
  ForwardIt1 find_end(ForwardIt1 first, ForwardIt1 last,
                      ForwardIt2 s_first, ForwardIt2 s_last,
                      BinaryPredicate p)
  {
      if (s_first == s_last)
          return last;
      ForwardIt1 result = last;
      while (true) {
          ForwardIt1 new_result = std::search(first, last, s_first, s_last, p);
          if (new_result == last) {
              break;
          } else {
              result = new_result;
              first = result;
              ++first;
          }
      }
      return result;
  }

Example

The following code uses find_end() to search for two different sequences of numbers.
// Run this code

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

  int main()
  {
      std::vector<int> v{1, 2, 3, 4, 1, 2, 3, 4, 1, 2, 3, 4};
      std::vector<int>::iterator result;

std::vector<int> t1{1, 2, 3};

      result = std::find_end(v.begin(), v.end(), t1.begin(), t1.end());
      if (result == v.end()) {
          std::cout << "sequence not found\n";
      } else {
          std::cout << "last occurrence is at: "
                    << std::distance(v.begin(), result) << "\n";
      }

      std::vector<int> t2{4, 5, 6};
      result = std::find_end(v.begin(), v.end(), t2.begin(), t2.end());
      if (result == v.end()) {
          std::cout << "sequence not found\n";
      } else {
          std::cout << "last occurrence is at: "
                    << std::distance(v.begin(), result) << "\n";
      }
  }

Output:

last occurrence is at: 8
sequence not found