20 General utilities library [utilities]

20.14 Function objects [function.objects]

A function object type is an object type that can be the type of the postfix-expression in a function call ([expr.call], [over.match.call]).224
A function object is an object of a function object type.
In the places where one would expect to pass a pointer to a function to an algorithmic template, the interface is specified to accept a function object.
This not only makes algorithmic templates work with pointers to functions, but also enables them to work with arbitrary function objects.
Such a type is a function pointer or a class type which has a member operator() or a class type which has a conversion to a pointer to function.

20.14.1 Header <functional> synopsis [functional.syn]

namespace std {
  // [func.invoke], invoke
  template<class F, class... Args>
    invoke_result_t<F, Args...> invoke(F&& f, Args&&... args)
      noexcept(is_nothrow_invocable_v<F, Args...>);

  // [refwrap], reference_­wrapper
  template<class T> class reference_wrapper;

  template<class T> reference_wrapper<T> ref(T&) noexcept;
  template<class T> reference_wrapper<const T> cref(const T&) noexcept;
  template<class T> void ref(const T&&) = delete;
  template<class T> void cref(const T&&) = delete;

  template<class T> reference_wrapper<T> ref(reference_wrapper<T>) noexcept;
  template<class T> reference_wrapper<const T> cref(reference_wrapper<T>) noexcept;

  template<class T> struct unwrap_reference;
  template<class T> struct unwrap_ref_decay : unwrap_reference<decay_t<T>> {};
  template<class T> using unwrap_ref_decay_t = typename unwrap_ref_decay<T>::type;

  // [arithmetic.operations], arithmetic operations
  template<class T = void> struct plus;
  template<class T = void> struct minus;
  template<class T = void> struct multiplies;
  template<class T = void> struct divides;
  template<class T = void> struct modulus;
  template<class T = void> struct negate;
  template<> struct plus<void>;
  template<> struct minus<void>;
  template<> struct multiplies<void>;
  template<> struct divides<void>;
  template<> struct modulus<void>;
  template<> struct negate<void>;

  // [comparisons], comparisons
  template<class T = void> struct equal_to;
  template<class T = void> struct not_equal_to;
  template<class T = void> struct greater;
  template<class T = void> struct less;
  template<class T = void> struct greater_equal;
  template<class T = void> struct less_equal;
  template<> struct equal_to<void>;
  template<> struct not_equal_to<void>;
  template<> struct greater<void>;
  template<> struct less<void>;
  template<> struct greater_equal<void>;
  template<> struct less_equal<void>;

  // [logical.operations], logical operations
  template<class T = void> struct logical_and;
  template<class T = void> struct logical_or;
  template<class T = void> struct logical_not;
  template<> struct logical_and<void>;
  template<> struct logical_or<void>;
  template<> struct logical_not<void>;

  // [bitwise.operations], bitwise operations
  template<class T = void> struct bit_and;
  template<class T = void> struct bit_or;
  template<class T = void> struct bit_xor;
  template<class T = void> struct bit_not;
  template<> struct bit_and<void>;
  template<> struct bit_or<void>;
  template<> struct bit_xor<void>;
  template<> struct bit_not<void>;

  // [func.identity], identity
  struct identity;

  // [func.not.fn], function template not_­fn
  template<class F> unspecified not_fn(F&& f);

  // [func.bind.front], function template bind_­front
  template<class F, class... Args> unspecified bind_front(F&&, Args&&...);

  // [func.bind], bind
  template<class T> struct is_bind_expression;
  template<class T> struct is_placeholder;

  template<class F, class... BoundArgs>
    unspecified bind(F&&, BoundArgs&&...);
  template<class R, class F, class... BoundArgs>
    unspecified bind(F&&, BoundArgs&&...);

  namespace placeholders {
    // M is the implementation-defined number of placeholders
    see below _1;
    see below _2;
               .
               .
               .
    see below _M;
  }

  // [func.memfn], member function adaptors
  template<class R, class T>
    unspecified mem_fn(R T::*) noexcept;

  // [func.wrap], polymorphic function wrappers
  class bad_function_call;

  template<class> class function; // not defined
  template<class R, class... ArgTypes> class function<R(ArgTypes...)>;

  template<class R, class... ArgTypes>
    void swap(function<R(ArgTypes...)>&, function<R(ArgTypes...)>&) noexcept;

  template<class R, class... ArgTypes>
    bool operator==(const function<R(ArgTypes...)>&, nullptr_t) noexcept;
  template<class R, class... ArgTypes>
    bool operator==(nullptr_t, const function<R(ArgTypes...)>&) noexcept;
  template<class R, class... ArgTypes>
    bool operator!=(const function<R(ArgTypes...)>&, nullptr_t) noexcept;
  template<class R, class... ArgTypes>
    bool operator!=(nullptr_t, const function<R(ArgTypes...)>&) noexcept;

  // [func.search], searchers
  template<class ForwardIterator, class BinaryPredicate = equal_to<>>
    class default_searcher;

  template<class RandomAccessIterator,
           class Hash = hash<typename iterator_traits<RandomAccessIterator>::value_type>,
           class BinaryPredicate = equal_to<>>
    class boyer_moore_searcher;

  template<class RandomAccessIterator,
           class Hash = hash<typename iterator_traits<RandomAccessIterator>::value_type>,
           class BinaryPredicate = equal_to<>>
    class boyer_moore_horspool_searcher;

  // [unord.hash], hash function primary template
  template<class T>
    struct hash;

  // [func.bind], function object binders
  template<class T>
    inline constexpr bool is_bind_expression_v = is_bind_expression<T>::value;
  template<class T>
    inline constexpr int is_placeholder_v = is_placeholder<T>::value;

  namespace ranges {
    // [range.cmp], concept-constrained comparisons
    struct equal_to;
    struct not_equal_to;
    struct greater;
    struct less;
    struct greater_equal;
    struct less_equal;
  }
}
[Example
:
If a C++ program wants to have a by-element addition of two vectors a and b containing double and put the result into a, it can do:
transform(a.begin(), a.end(), b.begin(), a.begin(), plus<double>());
end example
]
[Example
:
To negate every element of a:
transform(a.begin(), a.end(), a.begin(), negate<double>());
end example
]

20.14.2 Definitions [func.def]

The following definitions apply to this Clause:
A call signature is the name of a return type followed by a parenthesized comma-separated list of zero or more argument types.
A callable type is a function object type or a pointer to member.
A callable object is an object of a callable type.
A call wrapper type is a type that holds a callable object and supports a call operation that forwards to that object.
A call wrapper is an object of a call wrapper type.
A target object is the callable object held by a call wrapper.
A call wrapper type may additionally hold a sequence of objects and references that may be passed as arguments to the target object.
These entities are collectively referred to as bound argument entities.
The target object and bound argument entities of the call wrapper are collectively referred to as state entities.

20.14.3 Requirements [func.require]

Define INVOKE(f, t, t, , t) as follows:
  • (t.*f)(t, , t) when f is a pointer to a member function of a class T and is_­base_­of_­v<T, remove_­reference_­t<decltype(t)>> is true;
  • (t.get().*f)(t, , t) when f is a pointer to a member function of a class T and remove_­cvref_­t<decltype(t)> is a specialization of reference_­wrapper;
  • ((*t).*f)(t, , t) when f is a pointer to a member function of a class T and t does not satisfy the previous two items;
  • t.*f when N == 1 and f is a pointer to data member of a class T and is_­base_­of_­v<T, remove_­reference_­t<decltype(t)>> is true;
  • t.get().*f when N == 1 and f is a pointer to data member of a class T and remove_­cvref_­t<decltype(t)> is a specialization of reference_­wrapper;
  • (*t).*f when N == 1 and f is a pointer to data member of a class T and t does not satisfy the previous two items;
  • f(t, t, , t) in all other cases.
Define INVOKE<R>(f, t, t, , t) as static_­cast<void>(INVOKE(f, t, t, , t)) if R is cv void, otherwise INVOKE(f, t, t, , t) implicitly converted to R.
Every call wrapper ([func.def]) is Cpp17MoveConstructible.
A argument forwarding call wrapper is a call wrapper that can be called with an arbitrary argument list and delivers the arguments to the wrapped callable object as references.
This forwarding step delivers rvalue arguments as rvalue references and lvalue arguments as lvalue references.
A simple call wrapper is an argument forwarding call wrapper that is Cpp17CopyConstructible and Cpp17CopyAssignable and whose copy constructor, move constructor, copy assignment operator, and move assignment operator do not throw exceptions.
[Note
:
In a typical implementation, argument forwarding call wrappers have an overloaded function call operator of the form
template<class... UnBoundArgs>
  R operator()(UnBoundArgs&&... unbound_args) cv-qual;
end note
]
A perfect forwarding call wrapper is an argument forwarding call wrapper that forwards its state entities to the underlying call expression.
This forwarding step delivers a state entity of type T as cv T& when the call is performed on an lvalue of the call wrapper type and as cv T&& otherwise, where cv represents the cv-qualifiers of the call wrapper and where cv shall be neither volatile nor const volatile.
A call pattern defines the semantics of invoking a perfect forwarding call wrapper.
A postfix call performed on a perfect forwarding call wrapper is expression-equivalent ([defns.expression-equivalent]) to an expression e determined from its call pattern cp by replacing all occurrences of the arguments of the call wrapper and its state entities with references as described in the corresponding forwarding steps.
The copy/move constructor of a perfect forwarding call wrapper has the same apparent semantics as if memberwise copy/move of its state entities were performed ([class.copy.ctor]).
[Note
:
This implies that each of the copy/move constructors has the same exception-specification as the corresponding implicit definition and is declared as constexpr if the corresponding implicit definition would be considered to be constexpr.
end note
]
Perfect forwarding call wrappers returned by a given standard library function template have the same type if the types of their corresponding state entities are the same.

20.14.4 Function template invoke [func.invoke]

template<class F, class... Args> invoke_result_t<F, Args...> invoke(F&& f, Args&&... args) noexcept(is_nothrow_invocable_v<F, Args...>);
Returns: INVOKE(std::forward<F>(f), std::forward<Args>(args)...).

20.14.5 Class template reference_­wrapper [refwrap]

namespace std {
  template<class T> class reference_wrapper {
  public:
    // types
    using type = T;

    // construct/copy/destroy
    template<class U>
      reference_wrapper(U&&) noexcept(see below);
    reference_wrapper(const reference_wrapper& x) noexcept;

    // assignment
    reference_wrapper& operator=(const reference_wrapper& x) noexcept;

    // access
    operator T& () const noexcept;
    T& get() const noexcept;

    // invocation
    template<class... ArgTypes>
      invoke_result_t<T&, ArgTypes...> operator()(ArgTypes&&...) const;
  };
  template<class T>
    reference_wrapper(T&) -> reference_wrapper<T>;
}
reference_­wrapper<T> is a Cpp17CopyConstructible and Cpp17CopyAssignable wrapper around a reference to an object or function of type T.
reference_­wrapper<T> is a trivially copyable type.
The template parameter T of reference_­wrapper may be an incomplete type.

20.14.5.1 Constructors and destructor [refwrap.const]

template<class U> reference_wrapper(U&& u) noexcept(see below);
Remarks: Let FUN denote the exposition-only functions
void FUN(T&) noexcept;
void FUN(T&&) = delete;
This constructor shall not participate in overload resolution unless the expression FUN(declval<U>()) is well-formed and is_­same_­v<remove_­cvref_­t<U>, reference_­wrapper> is false.
The expression inside noexcept is equivalent to noexcept(FUN(declval<U>())).
Effects: Creates a variable r as if by T& r = std::forward<U>(u), then constructs a reference_­wrapper object that stores a reference to r.
reference_wrapper(const reference_wrapper& x) noexcept;
Effects: Constructs a reference_­wrapper object that stores a reference to x.get().

20.14.5.2 Assignment [refwrap.assign]

reference_wrapper& operator=(const reference_wrapper& x) noexcept;
Ensures: *this stores a reference to x.get().

20.14.5.3 Access [refwrap.access]

operator T& () const noexcept;
Returns: The stored reference.
T& get() const noexcept;
Returns: The stored reference.

20.14.5.4 Invocation [refwrap.invoke]

template<class... ArgTypes> invoke_result_t<T&, ArgTypes...> operator()(ArgTypes&&... args) const;
Mandates: T is a complete type.
Returns: INVOKE(get(), std::forward<ArgTypes>(args)...).

20.14.5.5 Helper functions [refwrap.helpers]

The template parameter T of the following ref and cref function templates may be an incomplete type.
template<class T> reference_wrapper<T> ref(T& t) noexcept;
Returns: reference_­wrapper<T>(t).
template<class T> reference_wrapper<T> ref(reference_wrapper<T> t) noexcept;
Returns: ref(t.get()).
template<class T> reference_wrapper<const T> cref(const T& t) noexcept;
Returns: reference_­wrapper <const T>(t).
template<class T> reference_wrapper<const T> cref(reference_wrapper<T> t) noexcept;
Returns: cref(t.get()).

20.14.5.6 Transformation type trait unwrap_­reference [refwrap.unwrapref]

template<class T> struct unwrap_reference;
If T is a specialization reference_­wrapper<X> for some type X, the member typedef type of unwrap_­reference<T> is X&, otherwise it is T.

20.14.6 Arithmetic operations [arithmetic.operations]

The library provides basic function object classes for all of the arithmetic operators in the language ([expr.mul], [expr.add]).

20.14.6.1 Class template plus [arithmetic.operations.plus]

template<class T = void> struct plus { constexpr T operator()(const T& x, const T& y) const; };
constexpr T operator()(const T& x, const T& y) const;
Returns: x + y.
template<> struct plus<void> { template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) + std::forward<U>(u)); using is_transparent = unspecified; };
template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) + std::forward<U>(u));
Returns: std::forward<T>(t) + std::forward<U>(u).

20.14.6.2 Class template minus [arithmetic.operations.minus]

template<class T = void> struct minus { constexpr T operator()(const T& x, const T& y) const; };
constexpr T operator()(const T& x, const T& y) const;
Returns: x - y.
template<> struct minus<void> { template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) - std::forward<U>(u)); using is_transparent = unspecified; };
template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) - std::forward<U>(u));
Returns: std::forward<T>(t) - std::forward<U>(u).

20.14.6.3 Class template multiplies [arithmetic.operations.multiplies]

template<class T = void> struct multiplies { constexpr T operator()(const T& x, const T& y) const; };
constexpr T operator()(const T& x, const T& y) const;
Returns: x * y.
template<> struct multiplies<void> { template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) * std::forward<U>(u)); using is_transparent = unspecified; };
template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) * std::forward<U>(u));
Returns: std::forward<T>(t) * std::forward<U>(u).

20.14.6.4 Class template divides [arithmetic.operations.divides]

template<class T = void> struct divides { constexpr T operator()(const T& x, const T& y) const; };
constexpr T operator()(const T& x, const T& y) const;
Returns: x / y.
template<> struct divides<void> { template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) / std::forward<U>(u)); using is_transparent = unspecified; };
template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) / std::forward<U>(u));
Returns: std::forward<T>(t) / std::forward<U>(u).

20.14.6.5 Class template modulus [arithmetic.operations.modulus]

template<class T = void> struct modulus { constexpr T operator()(const T& x, const T& y) const; };
constexpr T operator()(const T& x, const T& y) const;
Returns: x % y.
template<> struct modulus<void> { template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) % std::forward<U>(u)); using is_transparent = unspecified; };
template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) % std::forward<U>(u));
Returns: std::forward<T>(t) % std::forward<U>(u).

20.14.6.6 Class template negate [arithmetic.operations.negate]

template<class T = void> struct negate { constexpr T operator()(const T& x) const; };
constexpr T operator()(const T& x) const;
Returns: -x.
template<> struct negate<void> { template<class T> constexpr auto operator()(T&& t) const -> decltype(-std::forward<T>(t)); using is_transparent = unspecified; };
template<class T> constexpr auto operator()(T&& t) const -> decltype(-std::forward<T>(t));
Returns: -std::forward<T>(t).

20.14.7 Comparisons [comparisons]

The library provides basic function object classes for all of the comparison operators in the language ([expr.rel], [expr.eq]).
For templates less, greater, less_­equal, and greater_­equal, the specializations for any pointer type yield a strict total order that is consistent among those specializations and is also consistent with the partial order imposed by the built-in operators <, >, <=, >=.
[Note
:
When a < b is well-defined for pointers a and b of type P, this implies (a < b) == less<P>()(a, b), (a > b) == greater<P>()(a, b), and so forth.
end note
]
For template specializations less<void>, greater<void>, less_­equal<void>, and greater_­equal<void>, if the call operator calls a built-in operator comparing pointers, the call operator yields a strict total order that is consistent among those specializations and is also consistent with the partial order imposed by those built-in operators.

20.14.7.1 Class template equal_­to [comparisons.equal.to]

template<class T = void> struct equal_to { constexpr bool operator()(const T& x, const T& y) const; };
constexpr bool operator()(const T& x, const T& y) const;
Returns: x == y.
template<> struct equal_to<void> { template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) == std::forward<U>(u)); using is_transparent = unspecified; };
template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) == std::forward<U>(u));
Returns: std::forward<T>(t) == std::forward<U>(u).

20.14.7.2 Class template not_­equal_­to [comparisons.not.equal.to]

template<class T = void> struct not_equal_to { constexpr bool operator()(const T& x, const T& y) const; };
constexpr bool operator()(const T& x, const T& y) const;
Returns: x != y.
template<> struct not_equal_to<void> { template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) != std::forward<U>(u)); using is_transparent = unspecified; };
template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) != std::forward<U>(u));
Returns: std::forward<T>(t) != std::forward<U>(u).

20.14.7.3 Class template greater [comparisons.greater]

template<class T = void> struct greater { constexpr bool operator()(const T& x, const T& y) const; };
constexpr bool operator()(const T& x, const T& y) const;
Returns: x > y.
template<> struct greater<void> { template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) > std::forward<U>(u)); using is_transparent = unspecified; };
template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) > std::forward<U>(u));
Returns: std::forward<T>(t) > std::forward<U>(u).

20.14.7.4 Class template less [comparisons.less]

template<class T = void> struct less { constexpr bool operator()(const T& x, const T& y) const; };
constexpr bool operator()(const T& x, const T& y) const;
Returns: x < y.
template<> struct less<void> { template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) < std::forward<U>(u)); using is_transparent = unspecified; };
template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) < std::forward<U>(u));
Returns: std::forward<T>(t) < std::forward<U>(u).

20.14.7.5 Class template greater_­equal [comparisons.greater.equal]

template<class T = void> struct greater_equal { constexpr bool operator()(const T& x, const T& y) const; };
constexpr bool operator()(const T& x, const T& y) const;
Returns: x >= y.
template<> struct greater_equal<void> { template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) >= std::forward<U>(u)); using is_transparent = unspecified; };
template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) >= std::forward<U>(u));
Returns: std::forward<T>(t) >= std::forward<U>(u).

20.14.7.6 Class template less_­equal [comparisons.less.equal]

template<class T = void> struct less_equal { constexpr bool operator()(const T& x, const T& y) const; };
constexpr bool operator()(const T& x, const T& y) const;
Returns: x <= y.
template<> struct less_equal<void> { template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) <= std::forward<U>(u)); using is_transparent = unspecified; };
template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) <= std::forward<U>(u));
Returns: std::forward<T>(t) <= std::forward<U>(u).

20.14.8 Concept-constrained comparisons [range.cmp]

In this subclause, BUILTIN_­PTR_­CMP(T, op, U) for types T and U and where op is an equality ([expr.eq]) or relational operator ([expr.rel]) is a boolean constant expression.
BUILTIN_­PTR_­CMP(T, op, U) is true if and only if op in the expression declval<T>() op declval<U>() resolves to a built-in operator comparing pointers.
There is an implementation-defined strict total ordering over all pointer values of a given type.
This total ordering is consistent with the partial order imposed by the builtin operators <, >, <=, and >=.
struct ranges::equal_to { template<class T, class U> requires EqualityComparableWith<T, U> || BUILTIN_PTR_CMP(T, ==, U) constexpr bool operator()(T&& t, U&& u) const; using is_transparent = unspecified; };
Expects: If the expression std::forward<T>(t) == std::forward<U>(u) results in a call to a built-in operator == comparing pointers of type P, the conversion sequences from both T and U to P shall be equality-preserving ([concepts.equality]).
Effects:
  • If the expression std::forward<T>(t) == std::forward<U>(u) results in a call to a built-in operator == comparing pointers of type P: returns false if either (the converted value of) t precedes u or u precedes t in the implementation-defined strict total order over pointers of type P and otherwise true.
  • Otherwise, equivalent to: return std::forward<T>(t) == std::forward<U>(u);
struct ranges::not_equal_to { template<class T, class U> requires EqualityComparableWith<T, U> || BUILTIN_PTR_CMP(T, ==, U) constexpr bool operator()(T&& t, U&& u) const; using is_transparent = unspecified; };
operator() has effects equivalent to:
return !ranges::equal_to{}(std::forward<T>(t), std::forward<U>(u));
struct ranges::greater { template<class T, class U> requires StrictTotallyOrderedWith<T, U> || BUILTIN_PTR_CMP(U, <, T) constexpr bool operator()(T&& t, U&& u) const; using is_transparent = unspecified; };
operator() has effects equivalent to:
return ranges::less{}(std::forward<U>(u), std::forward<T>(t));
struct ranges::less { template<class T, class U> requires StrictTotallyOrderedWith<T, U> || BUILTIN_PTR_CMP(T, <, U) constexpr bool operator()(T&& t, U&& u) const; using is_transparent = unspecified; };
Expects: If the expression std::forward<T>(t) < std::forward<U>(u) results in a call to a built-in operator < comparing pointers of type P, the conversion sequences from both T and U to P shall be equality-preserving ([concepts.equality]).
For any expressions ET and EU such that decltype((ET)) is T and decltype((EU)) is U, exactly one of ranges::less{}(ET, EU), ranges::less{}(EU, ET), or ranges::equal_­to{}(ET, EU) shall be true.
Effects:
  • If the expression std::forward<T>(t) < std::forward<U>(u) results in a call to a built-in operator < comparing pointers of type P: returns true if (the converted value of) t precedes u in the implementation-defined strict total order over pointers of type P and otherwise false.
  • Otherwise, equivalent to: return std::forward<T>(t) < std::forward<U>(u);
struct ranges::greater_equal { template<class T, class U> requires StrictTotallyOrderedWith<T, U> || BUILTIN_PTR_CMP(T, <, U) constexpr bool operator()(T&& t, U&& u) const; using is_transparent = unspecified; };
operator() has effects equivalent to:
return !ranges::less{}(std::forward<T>(t), std::forward<U>(u));
struct ranges::less_equal { template<class T, class U> requires StrictTotallyOrderedWith<T, U> || BUILTIN_PTR_CMP(U, <, T) constexpr bool operator()(T&& t, U&& u) const; using is_transparent = unspecified; };
operator() has effects equivalent to:
return !ranges::less{}(std::forward<U>(u), std::forward<T>(t));

20.14.9 Logical operations [logical.operations]

The library provides basic function object classes for all of the logical operators in the language ([expr.log.and], [expr.log.or], [expr.unary.op]).

20.14.9.1 Class template logical_­and [logical.operations.and]

template<class T = void> struct logical_and { constexpr bool operator()(const T& x, const T& y) const; };
constexpr bool operator()(const T& x, const T& y) const;
Returns: x && y.
template<> struct logical_and<void> { template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) && std::forward<U>(u)); using is_transparent = unspecified; };
template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) && std::forward<U>(u));
Returns: std::forward<T>(t) && std::forward<U>(u).

20.14.9.2 Class template logical_­or [logical.operations.or]

template<class T = void> struct logical_or { constexpr bool operator()(const T& x, const T& y) const; };
constexpr bool operator()(const T& x, const T& y) const;
Returns: x || y.
template<> struct logical_or<void> { template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) || std::forward<U>(u)); using is_transparent = unspecified; };
template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) || std::forward<U>(u));
Returns: std::forward<T>(t) || std::forward<U>(u).

20.14.9.3 Class template logical_­not [logical.operations.not]

template<class T = void> struct logical_not { constexpr bool operator()(const T& x) const; };
constexpr bool operator()(const T& x) const;
Returns: !x.
template<> struct logical_not<void> { template<class T> constexpr auto operator()(T&& t) const -> decltype(!std::forward<T>(t)); using is_transparent = unspecified; };
template<class T> constexpr auto operator()(T&& t) const -> decltype(!std::forward<T>(t));
Returns: !std::forward<T>(t).

20.14.10 Bitwise operations [bitwise.operations]

The library provides basic function object classes for all of the bitwise operators in the language ([expr.bit.and], [expr.or], [expr.xor], [expr.unary.op]).

20.14.10.1 Class template bit_­and [bitwise.operations.and]

template<class T = void> struct bit_and { constexpr T operator()(const T& x, const T& y) const; };
constexpr T operator()(const T& x, const T& y) const;
Returns: x & y.
template<> struct bit_and<void> { template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) & std::forward<U>(u)); using is_transparent = unspecified; };
template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) & std::forward<U>(u));
Returns: std::forward<T>(t) & std::forward<U>(u).

20.14.10.2 Class template bit_­or [bitwise.operations.or]

template<class T = void> struct bit_or { constexpr T operator()(const T& x, const T& y) const; };
constexpr T operator()(const T& x, const T& y) const;
Returns: x | y.
template<> struct bit_or<void> { template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) | std::forward<U>(u)); using is_transparent = unspecified; };
template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) | std::forward<U>(u));
Returns: std::forward<T>(t) | std::forward<U>(u).

20.14.10.3 Class template bit_­xor [bitwise.operations.xor]

template<class T = void> struct bit_xor { constexpr T operator()(const T& x, const T& y) const; };
constexpr T operator()(const T& x, const T& y) const;
Returns: x ^ y.
template<> struct bit_xor<void> { template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) ^ std::forward<U>(u)); using is_transparent = unspecified; };
template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward<T>(t) ^ std::forward<U>(u));
Returns: std::forward<T>(t) ^ std::forward<U>(u).

20.14.10.4 Class template bit_­not [bitwise.operations.not]

template<class T = void> struct bit_not { constexpr T operator()(const T& x) const; };
constexpr T operator()(const T& x) const;
Returns: ~x.
template<> struct bit_not<void> { template<class T> constexpr auto operator()(T&& t) const -> decltype(~std::forward<T>(t)); using is_transparent = unspecified; };
template<class T> constexpr auto operator()(T&&) const -> decltype(~std::forward<T>(t));
Returns: ~std::forward<T>(t).

20.14.11 Class identity [func.identity]

struct identity { template<class T> constexpr T&& operator()(T&& t) const noexcept; using is_transparent = unspecified; }; template<class T> constexpr T&& operator()(T&& t) const noexcept;
Effects: Equivalent to: return std::forward<T>(t);

20.14.12 Function template not_­fn [func.not.fn]

template<class F> unspecified not_fn(F&& f);
In the text that follows:
Mandates: is_­constructible_­v<FD, F> && is_­move_­constructible_­v<FD> is true.
Expects: FD meets the Cpp17MoveConstructible requirements.
Returns: A perfect forwarding call wrapper g with call pattern !invoke(fd, call_­args...).
Throws: Any exception thrown by the initialization of fd.

20.14.13 Function template bind_­front [func.bind.front]

template<class F, class... Args> unspecified bind_front(F&& f, Args&&... args);
In the text that follows:
  • g is a value of the result of a bind_­front invocation,
  • FD is the type decay_­t<F>,
  • fd is the target object of g ([func.def]) of type FD initialized with the initializer (std::forward<F>(​f)) ([dcl.init]),
  • BoundArgs is a pack that denotes std::unwrap_­ref_­decay_­t<Args>...,
  • bound_­args is a pack of bound argument entities of g ([func.def]) of types BoundArgs..., initialized with initializers (std::forward<Args>(args))..., respectively, and
  • call_­args is an argument pack used in a function call expression ([expr.call]) of g.
Mandates:
conjunction_v<is_constructible<FD, F>, is_move_constructible<FD>,
              is_constructible<BoundArgs, Args>..., is_move_constructible<BoundArgs>...>
is true.
Expects: FD meets the Cpp17MoveConstructible requirements.
For each in BoundArgs, if is an object type, meets the Cpp17MoveConstructible requirements.
Returns: A perfect forwarding call wrapper g with call pattern invoke(fd, bound_­args..., call_­args...).
Throws: Any exception thrown by the initialization of the state entities of g ([func.def]).

20.14.14 Function object binders [func.bind]

This subclause describes a uniform mechanism for binding arguments of callable objects.

20.14.14.1 Class template is_­bind_­expression [func.bind.isbind]

namespace std {
  template<class T> struct is_bind_expression;  // see below
}
The class template is_­bind_­expression can be used to detect function objects generated by bind.
The function template bind uses is_­bind_­expression to detect subexpressions.
Instantiations of the is_­bind_­expression template shall satisfy the Cpp17UnaryTypeTrait requirements ([meta.rqmts]).
The implementation shall provide a definition that has a base characteristic of true_­type if T is a type returned from bind, otherwise it shall have a base characteristic of false_­type.
A program may specialize this template for a program-defined type T to have a base characteristic of true_­type to indicate that T should be treated as a subexpression in a bind call.

20.14.14.2 Class template is_­placeholder [func.bind.isplace]

namespace std {
  template<class T> struct is_placeholder;      // see below
}
The class template is_­placeholder can be used to detect the standard placeholders _­1, _­2, and so on.
The function template bind uses is_­placeholder to detect placeholders.
Instantiations of the is_­placeholder template shall satisfy the Cpp17UnaryTypeTrait requirements ([meta.rqmts]).
The implementation shall provide a definition that has the base characteristic of integral_­constant<int, J> if T is the type of std::placeholders::J, otherwise it shall have a base characteristic of integral_­constant<int, 0>.
A program may specialize this template for a program-defined type T to have a base characteristic of integral_­constant<int, N> with N > 0 to indicate that T should be treated as a placeholder type.

20.14.14.3 Function template bind [func.bind.bind]

In the text that follows:
  • FD is the type decay_­t<F>,
  • fd is an lvalue of type FD constructed from std::forward<F>(f),
  • is the type in the template parameter pack BoundArgs,
  • is the type decay_­t<>,
  • is the argument in the function parameter pack bound_­args,
  • is an lvalue of type constructed from std::forward<>(),
  • is the deduced type of the UnBoundArgs&&... parameter of the argument forwarding call wrapper, and
  • is the argument associated with .
template<class F, class... BoundArgs> unspecified bind(F&& f, BoundArgs&&... bound_args);
Requires: is_­constructible_­v<FD, F> shall be true.
For each in BoundArgs, is_­constructible_­v<, > shall be true.
INVOKE(fd, , , , ) ([func.require]) shall be a valid expression for some values , , , , where N has the value sizeof...(bound_­args).
The cv-qualifiers cv of the call wrapper g, as specified below, shall be neither volatile nor const volatile.
Returns: An argument forwarding call wrapper g ([func.require]).
The effect of g(, , , ) shall be
INVOKE(fd, std::forward<>(), std::forward<>(), , std::forward<>())
where the values and types of the bound arguments , , , are determined as specified below.
The copy constructor and move constructor of the argument forwarding call wrapper shall throw an exception if and only if the corresponding constructor of FD or of any of the types throws an exception.
Throws: Nothing unless the construction of fd or of one of the values throws an exception.
Remarks: The return type shall satisfy the Cpp17MoveConstructible requirements.
If all of FD and satisfy the Cpp17CopyConstructible requirements, then the return type shall satisfy the Cpp17CopyConstructible requirements.
[Note
:
This implies that all of FD and are Cpp17MoveConstructible.
end note
]
template<class R, class F, class... BoundArgs> unspecified bind(F&& f, BoundArgs&&... bound_args);
Requires: is_­constructible_­v<FD, F> shall be true.
For each in BoundArgs, is_­constructible_­v<, > shall be true.
INVOKE(fd, , , , ) shall be a valid expression for some values , , , , where N has the value sizeof...(bound_­args).
The cv-qualifiers cv of the call wrapper g, as specified below, shall be neither volatile nor const volatile.
Returns: An argument forwarding call wrapper g ([func.require]).
The effect of g(, , , ) shall be
INVOKE<R>(fd, std::forward<>(), std::forward<>(), , std::forward<>())
where the values and types of the bound arguments , , , are determined as specified below.
The copy constructor and move constructor of the argument forwarding call wrapper shall throw an exception if and only if the corresponding constructor of FD or of any of the types throws an exception.
Throws: Nothing unless the construction of fd or of one of the values throws an exception.
Remarks: The return type shall satisfy the Cpp17MoveConstructible requirements.
If all of FD and satisfy the Cpp17CopyConstructible requirements, then the return type shall satisfy the Cpp17CopyConstructible requirements.
[Note
:
This implies that all of FD and are Cpp17MoveConstructible.
end note
]
The values of the bound arguments , , , and their corresponding types , , , depend on the types derived from the call to bind and the cv-qualifiers cv of the call wrapper g as follows:
  • if is reference_­wrapper<T>, the argument is .get() and its type is T&;
  • if the value of is_­bind_­expression_­v<> is true, the argument is (std::forward<>()...) and its type is invoke_­result_­t< cv &, ...>&&;
  • if the value j of is_­placeholder_­v<> is not zero, the argument is std::forward<>() and its type is &&;
  • otherwise, the value is and its type is cv &.

20.14.14.4 Placeholders [func.bind.place]

namespace std::placeholders {
  // M is the implementation-defined number of placeholders
  see below _1;
  see below _2;
              .
              .
              .
  see below _M;
}
All placeholder types shall be Cpp17DefaultConstructible and Cpp17CopyConstructible, and their default constructors and copy/move constructors shall not throw exceptions.
It is implementation-defined whether placeholder types are Cpp17CopyAssignable.
Cpp17CopyAssignable placeholders' copy assignment operators shall not throw exceptions.
Placeholders should be defined as:
inline constexpr unspecified _1{};
If they are not, they shall be declared as:
extern unspecified _1;

20.14.15 Function template mem_­fn [func.memfn]

template<class R, class T> unspecified mem_fn(R T::* pm) noexcept;
Returns: A simple call wrapper fn such that the expression fn(t, a, , a) is equivalent to INVOKE(pm, t, a, , a) ([func.require]).

20.14.16 Polymorphic function wrappers [func.wrap]

This subclause describes a polymorphic wrapper class that encapsulates arbitrary callable objects.

20.14.16.1 Class bad_­function_­call [func.wrap.badcall]

An exception of type bad_­function_­call is thrown by function::operator() ([func.wrap.func.inv]) when the function wrapper object has no target.
namespace std {
  class bad_function_call : public exception {
  public:
    // [func.wrap.badcall.const], constructor
    bad_function_call() noexcept;
  };
}

20.14.16.1.1 Constructor [func.wrap.badcall.const]

bad_function_call() noexcept;
Effects: Constructs a bad_­function_­call object.
Ensures: what() returns an implementation-defined ntbs.

20.14.16.2 Class template function [func.wrap.func]

namespace std {
  template<class> class function; // not defined

  template<class R, class... ArgTypes>
  class function<R(ArgTypes...)> {
  public:
    using result_type = R;

    // [func.wrap.func.con], construct/copy/destroy
    function() noexcept;
    function(nullptr_t) noexcept;
    function(const function&);
    function(function&&) noexcept;
    template<class F> function(F);

    function& operator=(const function&);
    function& operator=(function&&);
    function& operator=(nullptr_t) noexcept;
    template<class F> function& operator=(F&&);
    template<class F> function& operator=(reference_wrapper<F>) noexcept;

    ~function();

    // [func.wrap.func.mod], function modifiers
    void swap(function&) noexcept;

    // [func.wrap.func.cap], function capacity
    explicit operator bool() const noexcept;

    // [func.wrap.func.inv], function invocation
    R operator()(ArgTypes...) const;

    // [func.wrap.func.targ], function target access
    const type_info& target_type() const noexcept;
    template<class T>       T* target() noexcept;
    template<class T> const T* target() const noexcept;
  };

  template<class R, class... ArgTypes>
    function(R(*)(ArgTypes...)) -> function<R(ArgTypes...)>;

  template<class F> function(F) -> function<see below>;

  // [func.wrap.func.nullptr], Null pointer comparisons
  template<class R, class... ArgTypes>
    bool operator==(const function<R(ArgTypes...)>&, nullptr_t) noexcept;

  template<class R, class... ArgTypes>
    bool operator==(nullptr_t, const function<R(ArgTypes...)>&) noexcept;

  template<class R, class... ArgTypes>
    bool operator!=(const function<R(ArgTypes...)>&, nullptr_t) noexcept;

  template<class R, class... ArgTypes>
    bool operator!=(nullptr_t, const function<R(ArgTypes...)>&) noexcept;

  // [func.wrap.func.alg], specialized algorithms
  template<class R, class... ArgTypes>
    void swap(function<R(ArgTypes...)>&, function<R(ArgTypes...)>&) noexcept;
}
The function class template provides polymorphic wrappers that generalize the notion of a function pointer.
Wrappers can store, copy, and call arbitrary callable objects, given a call signature, allowing functions to be first-class objects.
A callable type F is Lvalue-Callable for argument types ArgTypes and return type R if the expression INVOKE<R>(declval<F&>(), declval<ArgTypes>()...), considered as an unevaluated operand, is well-formed ([func.require]).
The function class template is a call wrapper whose call signature is R(ArgTypes...).
[Note
:
The types deduced by the deduction guides for function may change in future versions of this International Standard.
end note
]

20.14.16.2.1 Constructors and destructor [func.wrap.func.con]

function() noexcept;
Ensures: !*this.
function(nullptr_t) noexcept;
Ensures: !*this.
function(const function& f);
Ensures: !*this if !f; otherwise, *this targets a copy of f.target().
Throws: Shall not throw exceptions if f's target is a specialization of reference_­wrapper or a function pointer.
Otherwise, may throw bad_­alloc or any exception thrown by the copy constructor of the stored callable object.
[Note
:
Implementations should avoid the use of dynamically allocated memory for small callable objects, for example, where f's target is an object holding only a pointer or reference to an object and a member function pointer.
end note
]
function(function&& f) noexcept;
Ensures: If !f, *this has no target; otherwise, the target of *this is equivalent to the target of f before the construction, and f is in a valid state with an unspecified value.
[Note
:
Implementations should avoid the use of dynamically allocated memory for small callable objects, for example, where f's target is an object holding only a pointer or reference to an object and a member function pointer.
end note
]
template<class F> function(F f);
Requires: F shall be Cpp17CopyConstructible.
Remarks: This constructor template shall not participate in overload resolution unless F is Lvalue-Callable for argument types ArgTypes... and return type R.
Ensures: !*this if any of the following hold:
  • f is a null function pointer value.
  • f is a null member pointer value.
  • F is an instance of the function class template, and !f.
Otherwise, *this targets a copy of f initialized with std::move(f).
[Note
:
Implementations should avoid the use of dynamically allocated memory for small callable objects, for example, where f is an object holding only a pointer or reference to an object and a member function pointer.
end note
]
Throws: Shall not throw exceptions when f is a function pointer or a reference_­wrapper<T> for some T.
Otherwise, may throw bad_­alloc or any exception thrown by F's copy or move constructor.
template<class F> function(F) -> function<see below>;
Remarks: This deduction guide participates in overload resolution only if &F::operator() is well-formed when treated as an unevaluated operand.
In that case, if decltype(&F::operator()) is of the form R(G::*)(A...) cv & noexcept for a class type G, then the deduced type is function<R(A...)>.
[Example
:
void f() {
  int i{5};
  function g = [&](double) { return i; }; // deduces function<int(double)>
}
end example
]
function& operator=(const function& f);
Effects: As if by function(f).swap(*this);
Returns: *this.
function& operator=(function&& f);
Effects: Replaces the target of *this with the target of f.
Returns: *this.
function& operator=(nullptr_t) noexcept;
Effects: If *this != nullptr, destroys the target of this.
Ensures: !(*this).
Returns: *this.
template<class F> function& operator=(F&& f);
Effects: As if by: function(std::forward<F>(f)).swap(*this);
Returns: *this.
Remarks: This assignment operator shall not participate in overload resolution unless decay_­t<F> is Lvalue-Callable for argument types ArgTypes... and return type R.
template<class F> function& operator=(reference_wrapper<F> f) noexcept;
Effects: As if by: function(f).swap(*this);
Returns: *this.
~function();
Effects: If *this != nullptr, destroys the target of this.

20.14.16.2.2 Modifiers [func.wrap.func.mod]

void swap(function& other) noexcept;
Effects: Interchanges the targets of *this and other.

20.14.16.2.3 Capacity [func.wrap.func.cap]

explicit operator bool() const noexcept;
Returns: true if *this has a target, otherwise false.

20.14.16.2.4 Invocation [func.wrap.func.inv]

R operator()(ArgTypes... args) const;
Returns: INVOKE<R>(f, std::forward<ArgTypes>(args)...) ([func.require]), where f is the target object of *this.
Throws: bad_­function_­call if !*this; otherwise, any exception thrown by the wrapped callable object.

20.14.16.2.5 Target access [func.wrap.func.targ]

const type_info& target_type() const noexcept;
Returns: If *this has a target of type T, typeid(T); otherwise, typeid(void).
template<class T> T* target() noexcept; template<class T> const T* target() const noexcept;
Returns: If target_­type() == typeid(T) a pointer to the stored function target; otherwise a null pointer.

20.14.16.2.6 Null pointer comparison functions [func.wrap.func.nullptr]

template<class R, class... ArgTypes> bool operator==(const function<R(ArgTypes...)>& f, nullptr_t) noexcept; template<class R, class... ArgTypes> bool operator==(nullptr_t, const function<R(ArgTypes...)>& f) noexcept;
Returns: !f.
template<class R, class... ArgTypes> bool operator!=(const function<R(ArgTypes...)>& f, nullptr_t) noexcept; template<class R, class... ArgTypes> bool operator!=(nullptr_t, const function<R(ArgTypes...)>& f) noexcept;
Returns: (bool)f.

20.14.16.2.7 Specialized algorithms [func.wrap.func.alg]

template<class R, class... ArgTypes> void swap(function<R(ArgTypes...)>& f1, function<R(ArgTypes...)>& f2) noexcept;
Effects: As if by: f1.swap(f2);

20.14.17 Searchers [func.search]

This subclause provides function object types for operations that search for a sequence [pat_first, pat_­last) in another sequence [first, last) that is provided to the object's function call operator.
The first sequence (the pattern to be searched for) is provided to the object's constructor, and the second (the sequence to be searched) is provided to the function call operator.
Each specialization of a class template specified in this subclause [func.search] shall satisfy the Cpp17CopyConstructible and Cpp17CopyAssignable requirements.
Template parameters named of templates specified in this subclause [func.search] shall satisfy the same requirements and semantics as specified in [algorithms.general].
Template parameters named Hash shall satisfy the Cpp17Hash requirements (Table 32).
The Boyer-Moore searcher implements the Boyer-Moore search algorithm.
The Boyer-Moore-Horspool searcher implements the Boyer-Moore-Horspool search algorithm.
In general, the Boyer-Moore searcher will use more memory and give better runtime performance than Boyer-Moore-Horspool.

20.14.17.1 Class template default_­searcher [func.search.default]

template<class ForwardIterator1, class BinaryPredicate = equal_to<>>
  class default_searcher {
  public:
    constexpr default_searcher(ForwardIterator1 pat_first, ForwardIterator1 pat_last,
                               BinaryPredicate pred = BinaryPredicate());

    template<class ForwardIterator2>
      constexpr pair<ForwardIterator2, ForwardIterator2>
        operator()(ForwardIterator2 first, ForwardIterator2 last) const;

  private:
    ForwardIterator1 pat_first_;        // exposition only
    ForwardIterator1 pat_last_;         // exposition only
    BinaryPredicate pred_;              // exposition only
  };
constexpr default_searcher(ForwardIterator pat_first, ForwardIterator pat_last, BinaryPredicate pred = BinaryPredicate());
Effects: Constructs a default_­searcher object, initializing pat_­first_­ with pat_­first, pat_­last_­ with pat_­last, and pred_­ with pred.
Throws: Any exception thrown by the copy constructor of BinaryPredicate or ForwardIterator1.
template<class ForwardIterator2> constexpr pair<ForwardIterator2, ForwardIterator2> operator()(ForwardIterator2 first, ForwardIterator2 last) const;
Effects: Returns a pair of iterators i and j such that
  • i == search(first, last, pat_­first_­, pat_­last_­, pred_­), and
  • if i == last, then j == last, otherwise j == next(i, distance(pat_­first_­, pat_­last_­)).

20.14.17.2 Class template boyer_­moore_­searcher [func.search.bm]

template<class RandomAccessIterator1,
         class Hash = hash<typename iterator_traits<RandomAccessIterator1>::value_type>,
         class BinaryPredicate = equal_to<>>
  class boyer_moore_searcher {
  public:
    boyer_moore_searcher(RandomAccessIterator1 pat_first,
                         RandomAccessIterator1 pat_last,
                         Hash hf = Hash(),
                         BinaryPredicate pred = BinaryPredicate());

    template<class RandomAccessIterator2>
      pair<RandomAccessIterator2, RandomAccessIterator2>
        operator()(RandomAccessIterator2 first, RandomAccessIterator2 last) const;

  private:
    RandomAccessIterator1 pat_first_;   // exposition only
    RandomAccessIterator1 pat_last_;    // exposition only
    Hash hash_;                         // exposition only
    BinaryPredicate pred_;              // exposition only
  };
boyer_moore_searcher(RandomAccessIterator1 pat_first, RandomAccessIterator1 pat_last, Hash hf = Hash(), BinaryPredicate pred = BinaryPredicate());
Requires: The value type of RandomAccessIterator1 shall satisfy the Cpp17DefaultConstructible requirements, the Cpp17CopyConstructible requirements, and the Cpp17CopyAssignable requirements.
Requires: For any two values A and B of the type iterator_­traits<RandomAccessIterator1>::value_­type, if pred(A, B) == true, then hf(A) == hf(B) shall be true.
Effects: Constructs a boyer_­moore_­searcher object, initializing pat_­first_­ with pat_­first, pat_­last_­ with pat_­last, hash_­ with hf, and pred_­ with pred.
Throws: Any exception thrown by the copy constructor of RandomAccessIterator1, or by the default constructor, copy constructor, or the copy assignment operator of the value type of RandomAccessIterator1, or the copy constructor or operator() of BinaryPredicate or Hash.
May throw bad_­alloc if additional memory needed for internal data structures cannot be allocated.
template<class RandomAccessIterator2> pair<RandomAccessIterator2, RandomAccessIterator2> operator()(RandomAccessIterator2 first, RandomAccessIterator2 last) const;
Requires: RandomAccessIterator1 and RandomAccessIterator2 shall have the same value type.
Effects: Finds a subsequence of equal values in a sequence.
Returns: A pair of iterators i and j such that
  • i is the first iterator in the range [first, last - (pat_­last_­ - pat_­first_­)) such that for every non-negative integer n less than pat_­last_­ - pat_­first_­ the following condition holds: pred(*(i + n), *(pat_­first_­ + n)) != false, and
  • j == next(i, distance(pat_­first_­, pat_­last_­)).
Returns make_­pair(first, first) if [pat_­first_­, pat_­last_­) is empty, otherwise returns make_­pair(last, last) if no such iterator is found.
Complexity: At most (last - first) * (pat_­last_­ - pat_­first_­) applications of the predicate.

20.14.17.3 Class template boyer_­moore_­horspool_­searcher [func.search.bmh]

template<class RandomAccessIterator1,
         class Hash = hash<typename iterator_traits<RandomAccessIterator1>::value_type>,
         class BinaryPredicate = equal_to<>>
  class boyer_moore_horspool_searcher {
  public:
    boyer_moore_horspool_searcher(RandomAccessIterator1 pat_first,
                                  RandomAccessIterator1 pat_last,
                                  Hash hf = Hash(),
                                  BinaryPredicate pred = BinaryPredicate());

    template<class RandomAccessIterator2>
      pair<RandomAccessIterator2, RandomAccessIterator2>
        operator()(RandomAccessIterator2 first, RandomAccessIterator2 last) const;

  private:
    RandomAccessIterator1 pat_first_;   // exposition only
    RandomAccessIterator1 pat_last_;    // exposition only
    Hash hash_;                         // exposition only
    BinaryPredicate pred_;              // exposition only
  };
boyer_moore_horspool_searcher(RandomAccessIterator1 pat_first, RandomAccessIterator1 pat_last, Hash hf = Hash(), BinaryPredicate pred = BinaryPredicate());
Requires: The value type of RandomAccessIterator1 shall satisfy the Cpp17DefaultConstructible, Cpp17CopyConstructible, and Cpp17CopyAssignable requirements.
Requires: For any two values A and B of the type iterator_­traits<RandomAccessIterator1>::value_­type, if pred(A, B) == true, then hf(A) == hf(B) shall be true.
Effects: Constructs a boyer_­moore_­horspool_­searcher object, initializing pat_­first_­ with pat_­first, pat_­last_­ with pat_­last, hash_­ with hf, and pred_­ with pred.
Throws: Any exception thrown by the copy constructor of RandomAccessIterator1, or by the default constructor, copy constructor, or the copy assignment operator of the value type of RandomAccessIterator1 or the copy constructor or operator() of BinaryPredicate or Hash.
May throw bad_­alloc if additional memory needed for internal data structures cannot be allocated.
template<class RandomAccessIterator2> pair<RandomAccessIterator2, RandomAccessIterator2> operator()(RandomAccessIterator2 first, RandomAccessIterator2 last) const;
Requires: RandomAccessIterator1 and RandomAccessIterator2 shall have the same value type.
Effects: Finds a subsequence of equal values in a sequence.
Returns: A pair of iterators i and j such that
  • i is the first iterator i in the range [first, last - (pat_­last_­ - pat_­first_­)) such that for every non-negative integer n less than pat_­last_­ - pat_­first_­ the following condition holds: pred(*(i + n), *(pat_­first_­ + n)) != false, and
  • j == next(i, distance(pat_­first_­, pat_­last_­)).
Returns make_­pair(first, first) if [pat_­first_­, pat_­last_­) is empty, otherwise returns make_­pair(last, last) if no such iterator is found.
Complexity: At most (last - first) * (pat_­last_­ - pat_­first_­) applications of the predicate.

20.14.18 Class template hash [unord.hash]

The unordered associative containers defined in [unord] use specializations of the class template hash ([functional.syn]) as the default hash function.
Each specialization of hash is either enabled or disabled, as described below.
[Note
:
Enabled specializations meet the Cpp17Hash requirements, and disabled specializations do not.
end note
]
Each header that declares the template hash provides enabled specializations of hash for nullptr_­t and all cv-unqualified arithmetic, enumeration, and pointer types.
For any type Key for which neither the library nor the user provides an explicit or partial specialization of the class template hash, hash<Key> is disabled.
If the library provides an explicit or partial specialization of hash<Key>, that specialization is enabled except as noted otherwise, and its member functions are noexcept except as noted otherwise.
If H is a disabled specialization of hash, these values are false: is_­default_­constructible_­v<H>, is_­copy_­constructible_­v<H>, is_­move_­constructible_­v<H>, is_­copy_­assignable_­v<H>, and is_­move_­assignable_­v<H>.
Disabled specializations of hash are not function object types.
[Note
:
This means that the specialization of hash exists, but any attempts to use it as a Cpp17Hash will be ill-formed.
end note
]
An enabled specialization hash<Key> will:
  • satisfy the Cpp17Hash requirements (Table 32), with Key as the function call argument type, the Cpp17DefaultConstructible requirements (Table 25), the Cpp17CopyAssignable requirements (Table 29),
  • be swappable ([swappable.requirements]) for lvalues,
  • satisfy the requirement that if k1 == k2 is true, h(k1) == h(k2) is also true, where h is an object of type hash<Key> and k1 and k2 are objects of type Key;
  • satisfy the requirement that the expression h(k), where h is an object of type hash<Key> and k is an object of type Key, shall not throw an exception unless hash<Key> is a program-defined specialization that depends on at least one program-defined type.