Defined in header <algorithm>  

(1)  
template< class ForwardIt, class Size, class T > ForwardIt search_n( ForwardIt first, ForwardIt last, Size count, const T& value );  (until C++20)  
template< class ForwardIt, class Size, class T > constexpr ForwardIt search_n( ForwardIt first, ForwardIt last, Size count, const T& value );  (since C++20)  
template< class ExecutionPolicy, class ForwardIt, class Size, class T > ForwardIt search_n( ExecutionPolicy&& policy, ForwardIt first, ForwardIt last, Size count, const T& value );  (2)  (since C++17) 
(3)  
template< class ForwardIt, class Size, class T, class BinaryPredicate > ForwardIt search_n( ForwardIt first, ForwardIt last, Size count, const T& value, BinaryPredicate p );  (until C++20)  
template< class ForwardIt, class Size, class T, class BinaryPredicate > constexpr ForwardIt search_n( ForwardIt first, ForwardIt last, Size count, const T& value, BinaryPredicate p );  (since C++20)  
template< class ExecutionPolicy, class ForwardIt, class Size, class T, class BinaryPredicate > ForwardIt search_n( ExecutionPolicy&& policy, ForwardIt first, ForwardIt last, Size count, const T& value, BinaryPredicate p );  (4)  (since C++17) 
Searches the range [
first
,
last
)
for the first sequence of count
identical elements, each equal to the given value
.
operator==
.p
.policy
. These overloads do not participate in overload resolution unless
 (until C++20) 
 (since C++20) 
first, last    the range of elements to examine 
count    the length of the sequence to search for 
value    the value of the elements to search for 
policy    the execution policy to use. See execution policy for details. 
p    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:
While the signature does not need to have 
Type requirements  
ForwardIt must meet the requirements of LegacyForwardIterator. 

Size must be convertible to integral type. 
If count
is positive, returns an iterator to the beginning of the first sequence found in the range [
first
,
last
)
. Each iterator it
in the sequence should satisfy the following condition:
*it == value
is true
p(*it, value) != false
is true
If no such sequence is found, last
is returned.
If count
is zero or negative, first
is returned.
Given N
as std::distance(first, last)
:
N
comparisons with value using operator==
N
applications of the predicate p
The overloads with a template parameter named ExecutionPolicy
report errors as follows:
ExecutionPolicy
is one of the standard policies, std::terminate
is called. For any other ExecutionPolicy
, the behavior is implementationdefined. std::bad_alloc
is thrown. search_n (1) 

template<class ForwardIt, class Size, class T> ForwardIt search_n(ForwardIt first, ForwardIt last, Size count, const T& value) { if (count <= 0) return first; for (; first != last; ++first) { if (!(*first == value)) continue; ForwardIt candidate = first; for (Size cur_count = 1; true; ++cur_count) { if (cur_count >= count) return candidate; // success ++first; if (first == last) return last; // exhausted the list if (!(*first == value)) break; // too few in a row } } return last; } 
search_n (3) 
template<class ForwardIt, class Size, class T, class BinaryPredicate> ForwardIt search_n(ForwardIt first, ForwardIt last, Size count, const T& value, BinaryPredicate p) { if (count <= 0) return first; for (; first != last; ++first) { if (!p(*first, value)) continue; ForwardIt candidate = first; for (Size cur_count = 1; true; ++cur_count) { if (cur_count >= count) return candidate; // success ++first; if (first == last) return last; // exhausted the list if (!p(*first, value)) break; // too few in a row } } return last; } 
#include <algorithm> #include <iostream> #include <iterator> template<class Container, class Size, class T> [[nodiscard]] constexpr bool consecutive_values(const Container& c, Size count, const T& v) { return std::search_n(std::begin(c), std::end(c), count, v) != std::end(c); } int main() { constexpr char sequence[] = "1001010100010101001010101"; static_assert(consecutive_values(sequence, 3, '0')); std::cout << std::boolalpha << "Has 4 consecutive zeros: " << consecutive_values(sequence, 4, '0') << '\n' << "Has 3 consecutive zeros: " << consecutive_values(sequence, 3, '0') << '\n'; }
Output:
Has 4 consecutive zeros: false Has 3 consecutive zeros: true
The following behaviorchanging defect reports were applied retroactively to previously published C++ standards.
DR  Applied to  Behavior as published  Correct behavior 

LWG 283  C++98  T was required to be EqualityComparable, butthe value type of InputIt is not always T  removed the requirement 
LWG 426  C++98  the complexity upper limit was N·count ,it is negative if count is negative  the upper limit is 0 if count is nonpositive 
LWG 714  C++98  if count > 0 , the complexity upper limit was N·count , but inthe worst case the number of comparisons/operations is always N  changed the upper limit to N in this case 
finds the last sequence of elements in a certain range (function template) 

(C++11)  finds the first element satisfying specific criteria (function template) 
searches for a range of elements (function template) 

(C++20)  searches for a number consecutive copies of an element in a range (niebloid) 
© cppreference.com
Licensed under the Creative Commons AttributionShareAlike Unported License v3.0.
https://en.cppreference.com/w/cpp/algorithm/search_n