178 KiB
[function.objects]
22 General utilities library [utilities]
22.10 Function objects [function.objects]
22.10.1 General [function.objects.general]
A function object type is an object type ([basic.types.general]) that can be the type of thepostfix-expression in a function call ([expr.call], [over.match.call]).193
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 ([algorithms]), 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.
22.10.2 Header synopsis [functional.syn]
namespace std {// [func.invoke], invoketemplate<class F, class... Args>constexpr invoke_result_t<F, Args...> invoke(F&& f, Args&&... args) // freestandingnoexcept(is_nothrow_invocable_v<F, Args...>); template<class R, class F, class... Args>constexpr R invoke_r(F&& f, Args&&... args) // freestandingnoexcept(is_nothrow_invocable_r_v<R, F, Args...>); // [refwrap], reference_wrappertemplate class reference_wrapper; // freestandingtemplate constexpr reference_wrapper ref(T&) noexcept; // freestandingtemplate constexpr reference_wrapper cref(const T&) noexcept; // freestandingtemplate void ref(const T&&) = delete; // freestandingtemplate void cref(const T&&) = delete; // freestandingtemplateconstexpr reference_wrapper ref(reference_wrapper) noexcept; // freestandingtemplateconstexpr reference_wrapper cref(reference_wrapper) noexcept; // freestanding// [refwrap.common.ref], common_reference related specializationstemplate<class R, class T, template class RQual, template class TQual>requires see belowstruct basic_common_reference<R, T, RQual, TQual>; template<class T, class R, template class TQual, template class RQual>requires see belowstruct basic_common_reference<T, R, TQual, RQual>; // [arithmetic.operations], arithmetic operationstemplate struct plus; // freestandingtemplate struct minus; // freestandingtemplate struct multiplies; // freestandingtemplate struct divides; // freestandingtemplate struct modulus; // freestandingtemplate struct negate; // freestandingtemplate<> struct plus; // freestandingtemplate<> struct minus; // freestandingtemplate<> struct multiplies; // freestandingtemplate<> struct divides; // freestandingtemplate<> struct modulus; // freestandingtemplate<> struct negate; // freestanding// [comparisons], comparisonstemplate struct equal_to; // freestandingtemplate struct not_equal_to; // freestandingtemplate struct greater; // freestandingtemplate struct less; // freestandingtemplate struct greater_equal; // freestandingtemplate struct less_equal; // freestandingtemplate<> struct equal_to; // freestandingtemplate<> struct not_equal_to; // freestandingtemplate<> struct greater; // freestandingtemplate<> struct less; // freestandingtemplate<> struct greater_equal; // freestandingtemplate<> struct less_equal; // freestanding// [comparisons.three.way], class compare_three_waystruct compare_three_way; // freestanding// [logical.operations], logical operationstemplate struct logical_and; // freestandingtemplate struct logical_or; // freestandingtemplate struct logical_not; // freestandingtemplate<> struct logical_and; // freestandingtemplate<> struct logical_or; // freestandingtemplate<> struct logical_not; // freestanding// [bitwise.operations], bitwise operationstemplate struct bit_and; // freestandingtemplate struct bit_or; // freestandingtemplate struct bit_xor; // freestandingtemplate struct bit_not; // freestandingtemplate<> struct bit_and; // freestandingtemplate<> struct bit_or; // freestandingtemplate<> struct bit_xor; // freestandingtemplate<> struct bit_not; // freestanding// [func.identity], identitystruct identity; // freestanding// [func.not.fn], function template not_fntemplate constexpr unspecified not_fn(F&& f); // freestandingtemplate constexpr unspecified not_fn() noexcept; // freestanding// [func.bind.partial], function templates bind_front and bind_backtemplate<class F, class... Args>constexpr unspecified bind_front(F&&, Args&&...); // freestandingtemplate<auto f, class... Args>constexpr unspecified bind_front(Args&&...); // freestandingtemplate<class F, class... Args>constexpr unspecified bind_back(F&&, Args&&...); // freestandingtemplate<auto f, class... Args>constexpr unspecified bind_back(Args&&...); // freestanding// [func.bind], bindtemplate struct is_bind_expression; // freestandingtemplateconstexpr bool is_bind_expression_v = // freestanding is_bind_expression::value; template struct is_placeholder; // freestandingtemplateconstexpr int is_placeholder_v = // freestanding is_placeholder::value; template<class F, class... BoundArgs>constexpr unspecified bind(F&&, BoundArgs&&...); // freestandingtemplate<class R, class F, class... BoundArgs>constexpr unspecified bind(F&&, BoundArgs&&...); // freestandingnamespace placeholders {// M is the implementation-defined number of placeholderssee below _1; // freestandingsee below _2; // freestanding ⋮ see below _M; // freestanding}// [func.memfn], member function adaptorstemplate<class R, class T>constexpr unspecified mem_fn(R T::*) noexcept; // freestanding// [func.wrap], polymorphic function wrappers// [func.wrap.badcall], class bad_function_callclass bad_function_call; // [func.wrap.func], class template functiontemplate class function; // not definedtemplate<class R, class... ArgTypes> class function<R(ArgTypes...)>; // [func.wrap.func.alg], function specialized algorithmstemplate<class R, class... ArgTypes>void swap(function<R(ArgTypes...)>&, function<R(ArgTypes...)>&) noexcept; // [func.wrap.func.nullptr], function null pointer comparison operator functionstemplate<class R, class... ArgTypes>bool operator==(const function<R(ArgTypes...)>&, nullptr_t) noexcept; // [func.wrap.move], move-only wrappertemplate<class... S> class move_only_function; // not definedtemplate<class R, class... ArgTypes>class move_only_function<R(ArgTypes...) cv ref noexcept(noex)>; // see below// [func.wrap.copy], copyable wrappertemplate<class... S> class copyable_function; // not definedtemplate<class R, class... ArgTypes>class copyable_function<R(ArgTypes...) cv ref noexcept(noex)>; // see below// [func.wrap.ref], non-owning wrappertemplate<class... S> class function_ref; // freestanding, not definedtemplate<class R, class... ArgTypes>class function_ref<R(ArgTypes...) cv noexcept(noex)>; // freestanding, see below// [func.search], searcherstemplate<class ForwardIterator1, class BinaryPredicate = equal_to<>>class default_searcher; // freestandingtemplate<class RandomAccessIterator, class Hash = hash<typename iterator_traits::value_type>, class BinaryPredicate = equal_to<>>class boyer_moore_searcher; template<class RandomAccessIterator, class Hash = hash<typename iterator_traits::value_type>, class BinaryPredicate = equal_to<>>class boyer_moore_horspool_searcher; // [unord.hash], class template hashtemplatestruct hash; // freestandingnamespace ranges {// [range.cmp], concept-constrained comparisonsstruct equal_to; // freestandingstruct not_equal_to; // freestandingstruct greater; // freestandingstruct less; // freestandingstruct greater_equal; // freestandingstruct less_equal; // freestanding}template<class Fn, class... Args>concept callable = // exposition onlyrequires (Fn&& fn, Args&&... args) { std::forward(fn)(std::forward(args)...); }; template<class Fn, class... Args>concept nothrow-callable = // exposition onlycallable<Fn, Args...> &&requires (Fn&& fn, Args&&... args) {{ std::forward(fn)(std::forward(args)...) } noexcept; }; template<class Fn, class... Args>using call-result-t = decltype(declval()(declval()...)); // exposition onlytemplate<const auto& T>using decayed-typeof = decltype(auto(T)); // exposition only}
[Example 1:
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());
â end example]
[Example 2:
To negate every element of a:
transform(a.begin(), a.end(), a.begin(), negate()); â end example]
22.10.3 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 ([function.objects]) 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.
22.10.4 Requirements [func.require]
Define INVOKE(f, t1, t2, …, tN) as follows:
(t1.*f)(t2, …, tN) when f is a pointer to a member function of a class T andis_same_v<T, remove_cvref_t<decltype(t1)>> ||is_base_of_v<T, remove_cvref_t<decltype(t1)>> is true;
(t1.get().*f)(t2, …, tN) when f is a pointer to a member function of a class T and remove_cvref_t<decltype(t1)> is a specialization of reference_wrapper;
((*t1).*f)(t2, …, tN) when f is a pointer to a member function of a class T and t1 does not satisfy the previous two items;
t1.*f when N=1 and f is a pointer to data member of a class T andis_same_v<T, remove_cvref_t<decltype(t1)>> ||is_base_of_v<T, remove_cvref_t<decltype(t1)>> is true;
t1.get().*f when N=1 and f is a pointer to data member of a class T and remove_cvref_t<decltype(t1)> is a specialization of reference_wrapper;
(*t1).*f when N=1 and f is a pointer to data member of a class T and t1 does not satisfy the previous two items;
f(t1, t2, …, tN) in all other cases.
Define INVOKE(f, t1, t2, …, tN) asstatic_cast(INVOKE(f, t1, t2, …, tN)) if R is cv void, otherwiseINVOKE(f, t1, t2, …, tN) implicitly converted to R.
Ifreference_converts_from_temporary_v<R, decltype(INVOKE(f, t1, t2, …, tN))> is true,INVOKE(f, t1, t2, …, tN) is ill-formed.
Every call wrapper ([func.def]) meets the Cpp17MoveConstructible and Cpp17Destructible requirements.
An argument forwarding call wrapper is a call wrapper that can be called with an arbitrary argument list and delivers the arguments to the target object as references.
This forwarding step delivers rvalue arguments as rvalue references and lvalue arguments as lvalue references.
[Note 1:
In a typical implementation, argument forwarding call wrappers have an overloaded function call operator of the formtemplate<class... UnBoundArgs>constexpr 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.
A simple call wrapper is a perfect forwarding call wrapper that meets the Cpp17CopyConstructible and Cpp17CopyAssignable requirements and whose copy constructor, move constructor, and assignment operators are constexpr functions that do not throw exceptions.
The copy/move constructor of an argument forwarding call wrapper has the same apparent semantics as if memberwise copy/move of its state entities were performed ([class.copy.ctor]).
[Note 2:
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]
Argument 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.
22.10.5 invoke functions [func.invoke]
template<class F, class... Args> constexpr invoke_result_t<F, Args...> invoke(F&& f, Args&&... args) noexcept(is_nothrow_invocable_v<F, Args...>);
Constraints: is_invocable_v<F, Args...> is true.
Returns: INVOKE(std::forward(f), std::forward(args)...) ([func.require]).
template<class R, class F, class... Args> constexpr R invoke_r(F&& f, Args&&... args) noexcept(is_nothrow_invocable_r_v<R, F, Args...>);
Constraints: is_invocable_r_v<R, F, Args...> is true.
Returns: INVOKE(std::forward(f), std::forward(args)...) ([func.require]).
22.10.6 Class template reference_wrapper [refwrap]
22.10.6.1 General [refwrap.general]
namespace std {template class reference_wrapper {public:// typesusing type = T; // [refwrap.const], constructorstemplateconstexpr reference_wrapper(U&&) noexcept(see below); constexpr reference_wrapper(const reference_wrapper& x) noexcept; // [refwrap.assign], assignmentconstexpr reference_wrapper& operator=(const reference_wrapper& x) noexcept; // [refwrap.access], accessconstexpr operator T& () const noexcept; constexpr T& get() const noexcept; // [refwrap.invoke], invocationtemplate<class... ArgTypes>constexpr invoke_result_t<T&, ArgTypes...> operator()(ArgTypes&&...) constnoexcept(is_nothrow_invocable_v<T&, ArgTypes...>); // [refwrap.comparisons], comparisonsfriend constexpr bool operator==(reference_wrapper, reference_wrapper); friend constexpr bool operator==(reference_wrapper, const T&); friend constexpr bool operator==(reference_wrapper, reference_wrapper); friend constexpr auto operator<=>(reference_wrapper, reference_wrapper); friend constexpr auto operator<=>(reference_wrapper, const T&); friend constexpr auto operator<=>(reference_wrapper, reference_wrapper); }; template reference_wrapper(T&) -> reference_wrapper;}
reference_wrapper is a Cpp17CopyConstructible and Cpp17CopyAssignable wrapper around a reference to an object or function of type T.
reference_wrapper is a trivially copyable type ([basic.types.general]).
The template parameter T of reference_wrapper may be an incomplete type.
[Note 1:
Using the comparison operators described in [refwrap.comparisons] with T being an incomplete type can lead to an ill-formed program with no diagnostic required ([temp.point], [temp.constr.atomic]).
â end note]
22.10.6.2 Constructors [refwrap.const]
template<class U> constexpr reference_wrapper(U&& u) noexcept(see below);
Let FUN denote the exposition-only functionsvoid FUN(T&) noexcept;void FUN(T&&) = delete;
Constraints: The expression FUN(declval()) is well-formed andis_same_v<remove_cvref_t, reference_wrapper> is false.
Effects: Creates a variable r as if by T& r = std::forward(u), then constructs a reference_wrapper object that stores a reference to r.
Remarks: The exception specification is equivalent tonoexcept(FUN(declval())).
constexpr reference_wrapper(const reference_wrapper& x) noexcept;
Effects: Constructs a reference_wrapper object that stores a reference to x.get().
22.10.6.3 Assignment [refwrap.assign]
constexpr reference_wrapper& operator=(const reference_wrapper& x) noexcept;
Postconditions: *this stores a reference to x.get().
22.10.6.4 Access [refwrap.access]
constexpr operator T& () const noexcept;
Returns: The stored reference.
constexpr T& get() const noexcept;
Returns: The stored reference.
22.10.6.5 Invocation [refwrap.invoke]
template<class... ArgTypes> constexpr invoke_result_t<T&, ArgTypes...> operator()(ArgTypes&&... args) const noexcept(is_nothrow_invocable_v<T&, ArgTypes...>);
Mandates: T is a complete type.
Returns: INVOKE(get(), std::forward(args)...) ([func.require]).
22.10.6.6 Comparisons [refwrap.comparisons]
friend constexpr bool operator==(reference_wrapper x, reference_wrapper y);
Constraints: The expression x.get() == y.get() is well-formed and its result is convertible to bool.
Returns: x.get() == y.get().
friend constexpr bool operator==(reference_wrapper x, const T& y);
Constraints: The expression x.get() == y is well-formed and its result is convertible to bool.
Returns: x.get() == y.
friend constexpr bool operator==(reference_wrapper x, reference_wrapper<const T> y);
Constraints: is_const_v is false and the expression x.get() == y.get() is well-formed and its result is convertible to bool.
Returns: x.get() == y.get().
friend constexpr auto operator<=>(reference_wrapper x, reference_wrapper y);
Constraints: The expression synth-three-way(x.get(), y.get()) is well-formed.
Returns: synth-three-way(x.get(), y.get()).
friend constexpr auto operator<=>(reference_wrapper x, const T& y);
Constraints: The expression synth-three-way(x.get(), y) is well-formed.
Returns: synth-three-way(x.get(), y).
friend constexpr auto operator<=>(reference_wrapper x, reference_wrapper<const T> y);
Constraints: is_const_v is false.
The expression synth-three-way(x.get(), y.get()) is well-formed.
Returns: synth-three-way(x.get(), y.get()).
22.10.6.7 Helper functions [refwrap.helpers]
The template parameter T of the following ref and cref function templates may be an incomplete type.
template<class T> constexpr reference_wrapper<T> ref(T& t) noexcept;
Returns: reference_wrapper(t).
template<class T> constexpr reference_wrapper<T> ref(reference_wrapper<T> t) noexcept;
Returns: t.
template<class T> constexpr reference_wrapper<const T> cref(const T& t) noexcept;
Returns: reference_wrapper(t).
template<class T> constexpr reference_wrapper<const T> cref(reference_wrapper<T> t) noexcept;
Returns: t.
22.10.6.8 common_reference related specializations [refwrap.common.ref]
namespace std {templateconstexpr bool is-ref-wrapper = false; // exposition onlytemplateconstexpr bool is-ref-wrapper<reference_wrapper> = true; template<class R, class T, class RQ, class TQ>concept ref-wrap-common-reference-exists-with = // exposition only**is-ref-wrapper &&requires { typename common_reference_t<typename R::type&, TQ>; } &&convertible_to<RQ, common_reference_t<typename R::type&, TQ>>; template<class R, class T, template class RQual, template class TQual>requires (ref-wrap-common-reference-exists-with<R, T, RQual, TQual> &&
22.10.7 Arithmetic operations [arithmetic.operations]
22.10.7.1 General [arithmetic.operations.general]
The library provides basic function object classes for all of the arithmetic operators in the language ([expr.mul], [expr.add]).
22.10.7.2 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 { template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward(t) + std::forward(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) + std::forward(u).
22.10.7.3 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 { template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward(t) - std::forward(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) - std::forward(u).
22.10.7.4 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 { template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward(t) * std::forward(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) * std::forward(u).
22.10.7.5 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 { template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward(t) / std::forward(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) / std::forward(u).
22.10.7.6 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 { template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward(t) % std::forward(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) % std::forward(u).
22.10.7.7 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 { template constexpr auto operator()(T&& t) const -> decltype(-std::forward(t));
using is_transparent = unspecified; }; `
template<class T> constexpr auto operator()(T&& t) const -> decltype(-std::forward<T>(t));
Returns: -std::forward(t).
22.10.8 Comparisons [comparisons]
22.10.8.1 General [comparisons.general]
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, andgreater_equal, the specializations for any pointer type yield a result consistent with the implementation-defined strict total order over pointers ([defns.order.ptr]).
[Note 1:
If a < b is well-defined for pointers a and b of type P, then (a < b) == less
()(a, b),(a > b) == greater
()(a, b), and so forth.
â end note]
For template specializations less, greater,less_equal, and greater_equal, if the call operator calls a built-in operator comparing pointers, the call operator yields a result consistent with the implementation-defined strict total order over pointers.
22.10.8.2 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 { template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward(t) == std::forward(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) == std::forward(u).
22.10.8.3 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 { template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward(t) != std::forward(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) != std::forward(u).
22.10.8.4 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 { template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward(t) > std::forward(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) > std::forward(u).
22.10.8.5 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 { template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward(t) < std::forward(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) < std::forward(u).
22.10.8.6 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 { template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward(t) >= std::forward(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) >= std::forward(u).
22.10.8.7 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 { template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward(t) <= std::forward(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) <= std::forward(u).
22.10.8.8 Class compare_three_way [comparisons.three.way]
namespace std {struct compare_three_way {template<class T, class U>constexpr auto operator()(T&& t, U&& u) const; using is_transparent = unspecified; };}
template<class T, class U> constexpr auto operator()(T&& t, U&& u) const;
Constraints: T and U satisfy three_way_comparable_with.
Preconditions: If the expression std::forward(t) <=> std::forward(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 are equality-preserving ([concepts.equality]); otherwise, T and U model three_way_comparable_with.
Effects:
If the expression std::forward(t) <=> std::forward(u) results in a call to a built-in operator <=> comparing pointers of type P, returns strong_ordering::less if (the converted value of) t precedes u in the implementation-defined strict total order over pointers ([defns.order.ptr]), strong_ordering::greater if u precedes t, and otherwise strong_ordering::equal.
Otherwise, equivalent to: return std::forward(t) <=> std::forward(u);
22.10.9 Concept-constrained comparisons [range.cmp]
struct ranges::equal_to {template<class T, class U>constexpr bool operator()(T&& t, U&& u) const; using is_transparent = unspecified;};
template<class T, class U> constexpr bool operator()(T&& t, U&& u) const;
Constraints: T and U satisfy equality_comparable_with.
Preconditions: If the expression std::forward(t) == std::forward(u) results in a call to a built-in operator == comparing pointers of typeP, the conversion sequences from both T and U to P are equality-preserving ([concepts.equality]); otherwise, T and U model equality_comparable_with.
Effects:
If the expression std::forward(t) == std::forward(u) results in a call to a built-in operator == comparing pointers: returns false if either (the converted value of) t precedes u or u precedes t in the implementation-defined strict total order over pointers ([defns.order.ptr]) and otherwise true.
Otherwise, equivalent to: return std::forward(t) == std::forward(u);
struct ranges::not_equal_to {template<class T, class U>constexpr bool operator()(T&& t, U&& u) const; using is_transparent = unspecified;};
template<class T, class U> constexpr bool operator()(T&& t, U&& u) const;
Constraints: T and U satisfy equality_comparable_with.
Effects: Equivalent to:return !ranges::equal_to{}(std::forward(t), std::forward(u));
struct ranges::greater {template<class T, class U>constexpr bool operator()(T&& t, U&& u) const; using is_transparent = unspecified;};
template<class T, class U> constexpr bool operator()(T&& t, U&& u) const;
Constraints: T and U satisfy totally_ordered_with.
Effects: Equivalent to:return ranges::less{}(std::forward(u), std::forward(t));
struct ranges::less {template<class T, class U>constexpr bool operator()(T&& t, U&& u) const; using is_transparent = unspecified;};
template<class T, class U> constexpr bool operator()(T&& t, U&& u) const;
Constraints: T and U satisfy totally_ordered_with.
Preconditions: If the expression std::forward(t) < std::forward(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 are equality-preserving ([concepts.equality]); otherwise, T and U model totally_ordered_with.
For any expressionsET and EU such that decltype((ET)) is T anddecltype((EU)) is U, exactly one ofranges::less{}(ET, EU),ranges::less{}(EU, ET), orranges::equal_to{}(ET, EU) is true.
Effects:
If the expression std::forward(t) < std::forward(u) results in a call to a built-in operator < comparing pointers: returns true if (the converted value of) t precedes u in the implementation-defined strict total order over pointers ([defns.order.ptr]) and otherwise false.
Otherwise, equivalent to:return std::forward(t) < std::forward(u);
struct ranges::greater_equal {template<class T, class U>constexpr bool operator()(T&& t, U&& u) const; using is_transparent = unspecified;};
template<class T, class U> constexpr bool operator()(T&& t, U&& u) const;
Constraints: T and U satisfy totally_ordered_with.
Effects: Equivalent to:return !ranges::less{}(std::forward(t), std::forward(u));
`struct ranges::less_equal { template<class T, class U> constexpr bool operator()(T&& t, U&& u) const;
using is_transparent = unspecified; }; `
template<class T, class U> constexpr bool operator()(T&& t, U&& u) const;
Constraints: T and U satisfy totally_ordered_with.
Effects: Equivalent to:return !ranges::less{}(std::forward(u), std::forward(t));
22.10.10 Logical operations [logical.operations]
22.10.10.1 General [logical.operations.general]
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]).
22.10.10.2 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 { template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward(t) && std::forward(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) && std::forward(u).
22.10.10.3 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 { template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward(t) || std::forward(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) || std::forward(u).
22.10.10.4 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 { template constexpr auto operator()(T&& t) const -> decltype(!std::forward(t));
using is_transparent = unspecified; }; `
template<class T> constexpr auto operator()(T&& t) const -> decltype(!std::forward<T>(t));
Returns: !std::forward(t).
22.10.11 Bitwise operations [bitwise.operations]
22.10.11.1 General [bitwise.operations.general]
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]).
22.10.11.2 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 { template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward(t) & std::forward(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) & std::forward(u).
22.10.11.3 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 { template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward(t) | std::forward(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) | std::forward(u).
22.10.11.4 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 { template<class T, class U> constexpr auto operator()(T&& t, U&& u) const -> decltype(std::forward(t) ^ std::forward(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) ^ std::forward(u).
22.10.11.5 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 { template constexpr auto operator()(T&& t) const -> decltype(~std::forward(t));
using is_transparent = unspecified; }; `
template<class T> constexpr auto operator()(T&& t) const -> decltype(~std::forward<T>(t));
Returns: ~std::forward(t).
22.10.12 Class identity [func.identity]
`struct identity { template constexpr T&& operator()(T&& t) const noexcept;
using is_transparent = unspecified; };
template constexpr T&& operator()(T&& t) const noexcept; `
Effects: Equivalent to: return std::forward(t);
22.10.13 Function template not_fn [func.not.fn]
template<class F> constexpr unspecified not_fn(F&& f);
In the text that follows:
g is a value of the result of a not_fn invocation,
FD is the type decay_t,
fd is the target object of g ([func.def]) of type FD, direct-non-list-initialized with std::forward<F>(f),
call_args is an argument pack used in a function call expression ([expr.call]) of g.
Mandates: is_constructible_v<FD, F> && is_move_constructible_v is true.
Preconditions: FD meets the Cpp17MoveConstructible requirements.
Returns: A perfect forwarding call wrapper ([func.require]) g with call pattern !invoke(fd, call_args...).
Throws: Any exception thrown by the initialization of fd.
template<auto f> constexpr unspecified not_fn() noexcept;
In the text that follows:
F is the type of f,
g is a value of the result of a not_fn invocation,
call_args is an argument pack used in a function call expression ([expr.call]) of g.
Mandates: If is_pointer_v || is_member_pointer_v is true, then f != nullptr is true.
Returns: A perfect forwarding call wrapper ([func.require]) g that does not have state entities, and has the call pattern !invoke(f, call_args...).
22.10.14 Function templates bind_front and bind_back [func.bind.partial]
template<class F, class... Args> constexpr unspecified bind_front(F&& f, Args&&... args); template<class F, class... Args> constexpr unspecified bind_back(F&& f, Args&&... args);
Within this subclause:
g is a value of the result of a bind_front or bind_back invocation,
FD is the type decay_t,
fd is the target object of g ([func.def]) of type FD, direct-non-list-initialized with std::forward<F>(f),
BoundArgs is a pack that denotes decay_t...,
bound_args is a pack of bound argument entities of g ([func.def]) of types BoundArgs..., direct-non-list-initialized with std::forward(args)..., respectively, and
call_args is an argument pack used in a function call expression ([expr.call]) of g.
Mandates: is_constructible_v<FD, F> && is_move_constructible_v &&(is_constructible_v<BoundArgs, Args> && ...) &&(is_move_constructible_v && ...) is true.
Preconditions: FD meets the Cpp17MoveConstructible requirements.
For each Ti in BoundArgs, if Ti is an object type,Ti meets the Cpp17MoveConstructible requirements.
Returns: A perfect forwarding call wrapper ([func.require]) g with call pattern:
invoke(fd, bound_args..., call_args...) for a bind_front invocation, or
invoke(fd, call_args..., bound_args...) for a bind_back invocation.
Throws: Any exception thrown by the initialization of the state entities of g ([func.def]).
template<auto f, class... Args> constexpr unspecified bind_front(Args&&... args); template<auto f, class... Args> constexpr unspecified bind_back(Args&&... args);
Within this subclause:
F is the type of f,
g is a value of the result of a bind_front or bind_back invocation,
BoundArgs is a pack that denotes decay_t...,
bound_args is a pack of bound argument entities ofg ([func.def]) of types BoundArgs..., direct-non-list-initialized with std::forward(args)..., respectively, and
call_args is an argument pack used in a function call expression ([expr.call]) of g.
Mandates:
(is_constructible_v<BoundArgs, Args> && ...) is true, and
(is_move_constructible_v && ...) is true, and
if is_pointer_v || is_member_pointer_v is true, then f != nullptr is true.
Preconditions: For each Ti in BoundArgs,Ti meets the Cpp17MoveConstructible requirements.
Returns: A perfect forwarding call wrapper ([func.require]) g that does not have a target object, and has the call pattern:
invoke(f, bound_args..., call_args...) for a bind_front invocation, or
invoke(f, call_args..., bound_args...) for a bind_back invocation.
Throws: Any exception thrown by the initialization of bound_args.
22.10.15 Function object binders [func.bind]
22.10.15.1 General [func.bind.general]
Subclause [func.bind] describes a uniform mechanism for binding arguments of callable objects.
22.10.15.2 Class template is_bind_expression [func.bind.isbind]
namespace std {template 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.
Specializations of the is_bind_expression template shall meet the Cpp17UnaryTypeTrait requirements ([meta.rqmts]).
The implementation provides a definition that has a base characteristic oftrue_type if T is a type returned from bind, otherwise it has 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 thatT should be treated as a subexpression in a bind call.
22.10.15.3 Class template is_placeholder [func.bind.isplace]
namespace std {template struct is_placeholder; // see below}
The class template is_placeholder can be used to detect the standard placeholders_1, _2, and so on ([func.bind.place]).
The function template bind usesis_placeholder to detect placeholders.
Specializations of the is_placeholder template shall meet the Cpp17UnaryTypeTrait requirements ([meta.rqmts]).
The implementation provides a definition that has the base characteristic ofintegral_constant<int, J> if T is the type ofstd::placeholders::_J, otherwise it has 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.
22.10.15.4 Function template bind [func.bind.bind]
In the text that follows:
g is a value of the result of a bind invocation,
FD is the type decay_t,
fd is an lvalue that is a target object of g ([func.def]) of type FD direct-non-list-initialized with std::forward(f),
Ti is the ith type in the template parameter pack BoundArgs,
TDi is the type decay_t,
ti is the ith argument in the function parameter pack bound_args,
tdi is a bound argument entity of g ([func.def]) of type TDi direct-non-list-initialized with std::forward<Ti>(ti),
Uj is the jth deduced type of the UnBoundArgs&&... parameter of the argument forwarding call wrapper, and
uj is the jth argument associated with Uj.
template<class F, class... BoundArgs> constexpr unspecified bind(F&& f, BoundArgs&&... bound_args); template<class R, class F, class... BoundArgs> constexpr unspecified bind(F&& f, BoundArgs&&... bound_args);
Mandates: is_constructible_v<FD, F> is true.
For each Ti in BoundArgs, is_constructible_v<TDi, Ti> is true.
Preconditions: FD and each TDi meet the Cpp17MoveConstructible and Cpp17Destructible requirements.
INVOKE(fd, w1, w2, …,wN) ([func.require]) is a valid expression for some values w1, w2, …, wN, whereN has the value sizeof...(bound_args).
Returns: An argument forwarding call wrapper g ([func.require]).
A program that attempts to invoke a volatile-qualified g is ill-formed.
When g is not volatile-qualified, invocation ofg(u1, u2, …, uM) is expression-equivalent ([defns.expression.equivalent]) toINVOKE(static_cast(vfd), static_cast(v1), static_cast(v2), …, static_cast(vN)) for the first overload, andINVOKE(static_cast(vfd), static_cast(v1), static_cast(v2), …, static_cast(vN)) for the second overload, where the values and types of the target argument vfd and of the bound argumentsv1, v2, …, vN are determined as specified below.
Throws: Any exception thrown by the initialization of the state entities of g.
[Note 1:
If all of FD and TDi meet the requirements of Cpp17CopyConstructible, then the return type meets the requirements of Cpp17CopyConstructible.
â end note]
The values of the bound arguments v1, v2, …, vN and their corresponding types V1, V2, …, VN depend on the types TDi derived from the call to bind and the cv-qualifiers cv of the call wrapper g as follows:
if TDi is reference_wrapper, the argument is tdi.get() and its type Vi is T&;
if the value of is_bind_expression_v is true, the argument isstatic_cast<cv TDi&>(tdi)(std::forward(uj)...) and its type Vi isinvoke_result_t<cv TDi&, Uj...>&&;
if the value j of is_placeholder_v is not zero, the argument is std::forward(uj) and its type Vi is Uj&&;
otherwise, the value is tdi and its type Vi is cv TDi&.
The value of the target argument vfd is fd and its corresponding type Vfd is cv FD&.
22.10.15.5 Placeholders [func.bind.place]
namespace std::placeholders {// M is the number of placeholderssee below _1; see below _2; ⋮ see below _M;}
The number M of placeholders isimplementation-defined.
All placeholder types meet the Cpp17DefaultConstructible andCpp17CopyConstructible requirements, and their default constructors and copy/move constructors are constexpr functions that do not throw exceptions.
It is implementation-defined whether placeholder types meet the Cpp17CopyAssignable requirements, but if so, their copy assignment operators are constexpr functions that do not throw exceptions.
Placeholders should be defined as:inline constexpr unspecified _1{};
If they are not, they are declared as:extern unspecified _1;
Placeholders are freestanding items ([freestanding.item]).
22.10.16 Function template mem_fn [func.memfn]
template<class R, class T> constexpr unspecified mem_fn(R T::* pm) noexcept;
Returns: A simple call wrapper ([func.require]) fn with call pattern invoke(pmd, call_args...), wherepmd is the target object of fn of type R T::* direct-non-list-initialized with pm, andcall_args is an argument pack used in a function call expression ([expr.call]) of fn.
22.10.17 Polymorphic function wrappers [func.wrap]
22.10.17.1 General [func.wrap.general]
Subclause [func.wrap] describes polymorphic wrapper classes that encapsulate arbitrary callable objects.
Let t be an object of a type that is a specialization offunction, copyable_function, or move_only_function, such that the target object x of t has a type that is a specialization offunction, copyable_function, or move_only_function.
Each argument of the invocation of x evaluated as part of the invocation of t may alias an argument in the same position in the invocation of t that has the same type, even if the corresponding parameter is not of reference type.
[Example 1: move_only_function<void(T)> f{copyable_function<void(T)>{ {}}}; T t; f(t); // it is unspecified how many copies of T are made â end example]
Recommended practice: Implementations should avoid double wrapping when constructing polymorphic wrappers from one another.
22.10.17.2 Class bad_function_call [func.wrap.badcall]
An exception of type bad_function_call is thrown byfunction::operator() ([func.wrap.func.inv]) when the function wrapper object has no target.
namespace std {class bad_function_call : public exception {public:// see [exception] for the specification of the special member functionsconst char* what() const noexcept override; };}
const char* what() const noexcept override;
Returns: Animplementation-defined ntbs.
22.10.17.3 Class template function [func.wrap.func]
22.10.17.3.1 General [func.wrap.func.general]
namespace std {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 function(F&&);
function& operator=(const function&); function& operator=(function&&); function& operator=(nullptr_t) noexcept; template function& operator=(F&&); template function& operator=(reference_wrapper) noexcept; ~function(); // [func.wrap.func.mod], function modifiersvoid swap(function&) noexcept; // [func.wrap.func.cap], function capacityexplicit operator bool() const noexcept; // [func.wrap.func.inv], function invocation R operator()(ArgTypes...) const; // [func.wrap.func.targ], function target accessconst type_info& target_type() const noexcept; template T* target() noexcept; template const T* target() const noexcept; }; template<class R, class... ArgTypes> function(R(*)(ArgTypes...)) -> function<R(ArgTypes...)>; template function(F) -> function<see below>;}
The function class template provides polymorphic wrappers that generalize the notion of a function pointer.
Wrappers can store, copy, and call arbitrary callable objects ([func.def]), given a call signature ([func.def]).
The function class template is a call wrapper ([func.def]) whose call signature ([func.def]) is R(ArgTypes...).
[Note 1:
The types deduced by the deduction guides for function might change in future revisions of C++.
â end note]
22.10.17.3.2 Constructors and destructor [func.wrap.func.con]
function() noexcept;
Postconditions: !*this.
function(nullptr_t) noexcept;
Postconditions: !*this.
function(const function& f);
Postconditions: !*this if !f; otherwise, the target object of *this is a copy of the target object of f.
Throws: Nothing 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.
Recommended practice: Implementations should avoid the use of dynamically allocated memory for small callable objects, for example, wheref's target is an object holding only a pointer or reference to an object and a member function pointer.
function(function&& f) noexcept;
Postconditions: If !f, *this has no target; otherwise, the target of *this is equivalent to the target of f before the construction, andf is in a valid state with an unspecified value.
Recommended practice: 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.
template<class F> function(F&& f);
Let FD be decay_t.
Constraints:
is_same_v<remove_cvref_t, function> is false, and
is_invocable_r_v<R, FD&, ArgTypes...> is true.
Mandates:
is_copy_constructible_v is true, and
is_constructible_v<FD, F> is true.
Preconditions: FD meets the Cpp17CopyConstructible requirements.
Postconditions: !*this is true if any of the following hold:
-
f is a null function pointer value.
-
f is a null member pointer value.
-
remove_cvref_t is a specialization of the function class template, and!f is true.
Otherwise, *this has a target object of type FD direct-non-list-initialized with std::forward(f).
Throws: Nothing if FD is a specialization of reference_wrapper or a function pointer type.
Otherwise, may throw bad_alloc or any exception thrown by the initialization of the target object.
Recommended practice: Implementations should avoid the use of dynamically allocated memory for small callable objects, for example, where f refers to an object holding only a pointer or reference to an object and a member function pointer.
template<class F> function(F) -> function<see below>;
Constraints: &F::operator() is well-formed when treated as an unevaluated operand and either
F::operator() is a non-static member function anddecltype(&F::operator()) is either of the formR(G::*)(A...) cv &opt noexceptopt or of the formR(*)(G, A...) noexceptopt for a type G, or
F::operator() is a static member function anddecltype(&F::operator()) is of the formR(*)(A...) noexceptopt.
Remarks: The deduced type is function<R(A...)>.
[Example 1: void f() {int i{5}; function g = & { 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.
Postconditions: !(*this).
Returns: *this.
template<class F> function& operator=(F&& f);
Constraints: is_invocable_r_v<R, decay_t&, ArgTypes...> is true.
Effects: As if by: function(std::forward(f)).swap(*this);
Returns: *this.
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.
22.10.17.3.3 Modifiers [func.wrap.func.mod]
void swap(function& other) noexcept;
Effects: Interchanges the target objects of *this and other.
22.10.17.3.4 Capacity [func.wrap.func.cap]
explicit operator bool() const noexcept;
Returns: true if *this has a target, otherwise false.
22.10.17.3.5 Invocation [func.wrap.func.inv]
R operator()(ArgTypes... args) const;
Returns: INVOKE(f, std::forward(args)...) ([func.require]), where f is the target object ([func.def]) of *this.
Throws: bad_function_call if !*this; otherwise, any exception thrown by the target object.
22.10.17.3.6 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.
22.10.17.3.7 Null pointer comparison operator functions [func.wrap.func.nullptr]
template<class R, class... ArgTypes> bool operator==(const function<R(ArgTypes...)>& f, nullptr_t) noexcept;
Returns: !f.
22.10.17.3.8 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);
22.10.17.4 Move-only wrapper [func.wrap.move]
22.10.17.4.1 General [func.wrap.move.general]
The header provides partial specializations of move_only_function for each combination of the possible replacements of the placeholders cv, ref, and noex where
cv is either const or empty,
ref is either &, &&, or empty, and
noex is either true or false.
For each of the possible combinations of the placeholders mentioned above, there is a placeholder inv-quals defined as follows:
If ref is empty, let inv-quals be cv&,
otherwise, let inv-quals be cv ref.
22.10.17.4.2 Class template move_only_function [func.wrap.move.class]
namespace std {template<class R, class... ArgTypes>class move_only_function<R(ArgTypes...) cv ref noexcept(noex)> {public:using result_type = R; // [func.wrap.move.ctor], constructors, assignments, and destructor move_only_function() noexcept; move_only_function(nullptr_t) noexcept; move_only_function(move_only_function&&) noexcept; template move_only_function(F&&); template<class T, class... Args>explicit move_only_function(in_place_type_t, Args&&...); template<class T, class U, class... Args>explicit move_only_function(in_place_type_t, initializer_list, Args&&...);
move_only_function& operator=(move_only_function&&); move_only_function& operator=(nullptr_t) noexcept; template move_only_function& operator=(F&&); ~move_only_function(); // [func.wrap.move.inv], invocationexplicit operator bool() const noexcept; R operator()(ArgTypes...) cv ref noexcept(noex); // [func.wrap.move.util], utilityvoid swap(move_only_function&) noexcept; friend void swap(move_only_function&, move_only_function&) noexcept; friend bool operator==(const move_only_function&, nullptr_t) noexcept; private:templatestatic constexpr bool is-callable-from = see below; // exposition only};}
The move_only_function class template provides polymorphic wrappers that generalize the notion of a callable object ([func.def]).
These wrappers can store, move, and call arbitrary callable objects, given a call signature.
Recommended practice: Implementations should avoid the use of dynamically allocated memory for a small contained value.
[Note 1:
Such small-object optimization can only be applied to a type T for which is_nothrow_move_constructible_v is true.
â end note]
22.10.17.4.3 Constructors, assignments, and destructor [func.wrap.move.ctor]
template<class VT> static constexpr bool is-callable-from = see below;
If noex is true,is-callable-from is equal to:is_nothrow_invocable_r_v<R, VT cv ref, ArgTypes...> && is_nothrow_invocable_r_v<R, VT inv-quals, ArgTypes...>
Otherwise, is-callable-from is equal to:is_invocable_r_v<R, VT cv ref, ArgTypes...> && is_invocable_r_v<R, VT inv-quals, ArgTypes...>
move_only_function() noexcept; move_only_function(nullptr_t) noexcept;
Postconditions: *this has no target object.
move_only_function(move_only_function&& f) noexcept;
Postconditions: The target object of *this is the target object f had before construction, andf is in a valid state with an unspecified value.
template<class F> move_only_function(F&& f);
Let VT be decay_t.
Constraints:
remove_cvref_t is not the same type as move_only_function, and
remove_cvref_t is not a specialization of in_place_type_t, and
is-callable-from is true.
Mandates: is_constructible_v<VT, F> is true.
Preconditions: VT meets the Cpp17Destructible requirements, and if is_move_constructible_v is true,VT meets the Cpp17MoveConstructible requirements.
Postconditions: *this has no target object if any of the following hold:
f is a null function pointer value, or
f is a null member pointer value, or
remove_cvref_t is a specialization of the move_only_function class template, and f has no target object.
Otherwise, *this has a target object of type VT direct-non-list-initialized with std::forward(f).
Throws: Any exception thrown by the initialization of the target object.
May throw bad_alloc unless VT is a function pointer or a specialization of reference_wrapper.
template<class T, class... Args> explicit move_only_function(in_place_type_t<T>, Args&&... args);
Let VT be decay_t.
Constraints:
is_constructible_v<VT, Args...> is true, and
is-callable-from is true.
Mandates: VT is the same type as T.
Preconditions: VT meets the Cpp17Destructible requirements, and if is_move_constructible_v is true,VT meets the Cpp17MoveConstructible requirements.
Postconditions: *this has a target object of type VT direct-non-list-initialized with std::forward(args)....
Throws: Any exception thrown by the initialization of the target object.
May throw bad_alloc unless VT is a function pointer or a specialization of reference_wrapper.
template<class T, class U, class... Args> explicit move_only_function(in_place_type_t<T>, initializer_list<U> ilist, Args&&... args);
Let VT be decay_t.
Constraints:
is_constructible_v<VT, initializer_list&, Args...> istrue, and
is-callable-from is true.
Mandates: VT is the same type as T.
Preconditions: VT meets the Cpp17Destructible requirements, and if is_move_constructible_v is true,VT meets the Cpp17MoveConstructible requirements.
Postconditions: *this has a target object of type VT direct-non-list-initialized withilist, std::forward(args)....
Throws: Any exception thrown by the initialization of the target object.
May throw bad_alloc unless VT is a function pointer or a specialization of reference_wrapper.
move_only_function& operator=(move_only_function&& f);
Effects: Equivalent to: move_only_function(std::move(f)).swap(*this);
Returns: *this.
move_only_function& operator=(nullptr_t) noexcept;
Effects: Destroys the target object of *this, if any.
Returns: *this.
template<class F> move_only_function& operator=(F&& f);
Effects: Equivalent to: move_only_function(std::forward(f)).swap(*this);
Returns: *this.
~move_only_function();
Effects: Destroys the target object of *this, if any.
22.10.17.4.4 Invocation [func.wrap.move.inv]
explicit operator bool() const noexcept;
Returns: true if *this has a target object, otherwise false.
R operator()(ArgTypes... args) cv ref noexcept(noex);
Preconditions: *this has a target object.
Effects: Equivalent to:return INVOKE(static_cast<F inv-quals>(f), std::forward(args)...); where f is an lvalue designating the target object of *this andF is the type of f.
22.10.17.4.5 Utility [func.wrap.move.util]
void swap(move_only_function& other) noexcept;
Effects: Exchanges the target objects of *this and other.
friend void swap(move_only_function& f1, move_only_function& f2) noexcept;
Effects: Equivalent to f1.swap(f2).
friend bool operator==(const move_only_function& f, nullptr_t) noexcept;
Returns: true if f has no target object, otherwise false.
22.10.17.5 Copyable wrapper [func.wrap.copy]
22.10.17.5.1 General [func.wrap.copy.general]
The header provides partial specializations of copyable_function for each combination of the possible replacements of the placeholders cv, ref, and noex where
cv is either const or empty,
ref is either &, &&, or empty, and
noex is either true or false.
For each of the possible combinations of the placeholders mentioned above, there is a placeholder inv-quals defined as follows:
If ref is empty, let inv-quals be cv&,
otherwise, let inv-quals be cv ref.
22.10.17.5.2 Class template copyable_function [func.wrap.copy.class]
namespace std {template<class R, class... ArgTypes>class copyable_function<R(ArgTypes...) cv ref noexcept(noex)> {public:using result_type = R; // [func.wrap.copy.ctor], constructors, assignments, and destructor copyable_function() noexcept; copyable_function(nullptr_t) noexcept; copyable_function(const copyable_function&); copyable_function(copyable_function&&) noexcept; template copyable_function(F&&); template<class T, class... Args>explicit copyable_function(in_place_type_t, Args&&...); template<class T, class U, class... Args>explicit copyable_function(in_place_type_t, initializer_list, Args&&...);
copyable_function& operator=(const copyable_function&); copyable_function& operator=(copyable_function&&); copyable_function& operator=(nullptr_t) noexcept; template copyable_function& operator=(F&&); ~copyable_function(); // [func.wrap.copy.inv], invocationexplicit operator bool() const noexcept; R operator()(ArgTypes...) cv ref noexcept(noex); // [func.wrap.copy.util], utilityvoid swap(copyable_function&) noexcept; friend void swap(copyable_function&, copyable_function&) noexcept; friend bool operator==(const copyable_function&, nullptr_t) noexcept; private:templatestatic constexpr bool is-callable-from = see below; // exposition only};}
The copyable_function class template provides polymorphic wrappers that generalize the notion of a callable object ([func.def]).
These wrappers can store, copy, move, and call arbitrary callable objects, given a call signature.
Recommended practice: Implementations should avoid the use of dynamically allocated memory for a small contained value.
[Note 1:
Such small-object optimization can only be applied to a type T for which is_nothrow_move_constructible_v is true.
â end note]
22.10.17.5.3 Constructors, assignments, and destructor [func.wrap.copy.ctor]
template<class VT> static constexpr bool is-callable-from = see below;
If noex is true,is-callable-from is equal to:is_nothrow_invocable_r_v<R, VT cv ref, ArgTypes...> && is_nothrow_invocable_r_v<R, VT inv-quals, ArgTypes...>
Otherwise, is-callable-from is equal to:is_invocable_r_v<R, VT cv ref, ArgTypes...> && is_invocable_r_v<R, VT inv-quals, ArgTypes...>
copyable_function() noexcept; copyable_function(nullptr_t) noexcept;
Postconditions: *this has no target object.
copyable_function(const copyable_function& f);
Postconditions: *this has no target object if f had no target object.
Otherwise, the target object of *this is a copy of the target object of f.
Throws: Any exception thrown by the initialization of the target object.
May throw bad_alloc.
copyable_function(copyable_function&& f) noexcept;
Postconditions: The target object of *this is the target object f had before construction, andf is in a valid state with an unspecified value.
template<class F> copyable_function(F&& f);
Let VT be decay_t.
Constraints:
remove_cvref_t is not the same type as copyable_function, and
remove_cvref_t is not a specialization of in_place_type_t, and
is-callable-from is true.
Mandates:
is_constructible_v<VT, F> is true, and
is_copy_constructible_v is true.
Preconditions: VT meets the Cpp17Destructible andCpp17CopyConstructible requirements.
Postconditions: *this has no target object if any of the following hold:
f is a null function pointer value, or
f is a null member pointer value, or
remove_cvref_t is a specialization of the copyable_function class template, and f has no target object.
Otherwise, *this has a target object of type VT direct-non-list-initialized with std::forward(f).
Throws: Any exception thrown by the initialization of the target object.
May throw bad_alloc unless VT is a function pointer or a specialization of reference_wrapper.
template<class T, class... Args> explicit copyable_function(in_place_type_t<T>, Args&&... args);
Let VT be decay_t.
Constraints:
is_constructible_v<VT, Args...> is true, and
is-callable-from is true.
Mandates:
VT is the same type as T, and
is_copy_constructible_v is true.
Preconditions: VT meets the Cpp17Destructible andCpp17CopyConstructible requirements.
Postconditions: *this has a target object of type VT direct-non-list-initialized with std::forward(args)....
Throws: Any exception thrown by the initialization of the target object.
May throw bad_alloc unless VT is a pointer or a specialization of reference_wrapper.
template<class T, class U, class... Args> explicit copyable_function(in_place_type_t<T>, initializer_list<U> ilist, Args&&... args);
Let VT be decay_t.
Constraints:
is_constructible_v<VT, initializer_list&, Args...> istrue, and
is-callable-from is true.
Mandates:
VT is the same type as T, and
is_copy_constructible_v is true.
Preconditions: VT meets the Cpp17Destructible andCpp17CopyConstructible requirements.
Postconditions: *this has a target object of type VT direct-non-list-initialized withilist, std::forward(args)....
Throws: Any exception thrown by the initialization of the target object.
May throw bad_alloc unless VT is a pointer or a specialization of reference_wrapper.
copyable_function& operator=(const copyable_function& f);
Effects: Equivalent to: copyable_function(f).swap(*this);
Returns: *this.
copyable_function& operator=(copyable_function&& f);
Effects: Equivalent to: copyable_function(std::move(f)).swap(*this);
Returns: *this.
copyable_function& operator=(nullptr_t) noexcept;
Effects: Destroys the target object of *this, if any.
Returns: *this.
template<class F> copyable_function& operator=(F&& f);
Effects: Equivalent to: copyable_function(std::forward(f)).swap(*this);
Returns: *this.
~copyable_function();
Effects: Destroys the target object of *this, if any.
22.10.17.5.4 Invocation [func.wrap.copy.inv]
explicit operator bool() const noexcept;
Returns: true if *this has a target object, otherwise false.
R operator()(ArgTypes... args) cv ref noexcept(noex);
Preconditions: *this has a target object.
Effects: Equivalent to:return INVOKE(static_cast<F inv-quals>(f), std::forward(args)...); where f is an lvalue designating the target object of *this andF is the type of f.
22.10.17.5.5 Utility [func.wrap.copy.util]
void swap(copyable_function& other) noexcept;
Effects: Exchanges the target objects of *this and other.
friend void swap(copyable_function& f1, copyable_function& f2) noexcept;
Effects: Equivalent to f1.swap(f2).
friend bool operator==(const copyable_function& f, nullptr_t) noexcept;
Returns: true if f has no target object, otherwise false.
22.10.17.6 Non-owning wrapper [func.wrap.ref]
22.10.17.6.1 General [func.wrap.ref.general]
The header provides partial specializations of function_ref for each combination of the possible replacements of the placeholders cv and noex where:
cv is either const or empty, and
noex is either true or false.
22.10.17.6.2 Class template function_ref [func.wrap.ref.class]
namespace std {template<class R, class... ArgTypes>class function_ref<R(ArgTypes...) cv noexcept(noex)> {public:// [func.wrap.ref.ctor], constructors and assignment operatorstemplate function_ref(F*) noexcept; template constexpr function_ref(F&&) noexcept; template constexpr function_ref(nontype_t) noexcept; template<auto f, class U> constexpr function_ref(nontype_t, U&&) noexcept; template<auto f, class T> constexpr function_ref(nontype_t, cv T*) noexcept; constexpr function_ref(const function_ref&) noexcept = default; constexpr function_ref& operator=(const function_ref&) noexcept = default; template function_ref& operator=(T) = delete; // [func.wrap.ref.inv], invocation R operator()(ArgTypes...) const noexcept(noex); private:template<class... T>static constexpr bool is-invocable-using = see below; // exposition only R (thunk-ptr)(BoundEntityType, Args&&...) noexcept(noex); // *exposition only*BoundEntityType* bound-entity; // exposition only}; // [func.wrap.ref.deduct], deduction guidestemplate function_ref(F*) -> function_ref; template function_ref(nontype_t) -> function_ref<see below>; template<auto f, class T> function_ref(nontype_t, T&&) -> function_ref<see below>;}
An object of classfunction_ref<R(Args...) cv noexcept(noex)> stores a pointer to function thunk-ptr and an object bound-entity.
bound-entity has an unspecified trivially copyable type BoundEntityType, that models copyable and is capable of storing a pointer to object value or a pointer to function value.
The type of thunk-ptr isR(*)(BoundEntityType, Args&&...) noexcept(noex).
Each specialization of function_ref is a trivially copyable type ([basic.types.general]) that models copyable.
Within [func.wrap.ref],call-args is an argument pack with elements such thatdecltype((call-args))... denoteArgs&&... respectively.
22.10.17.6.3 Constructors and assignment operators [func.wrap.ref.ctor]
template<class... T> static constexpr bool is-invocable-using = see below;
If noex is true,is-invocable-using<T...> is equal to:is_nothrow_invocable_r_v<R, T..., ArgTypes...>
Otherwise, is-invocable-using<T...> is equal to:is_invocable_r_v<R, T..., ArgTypes...>
template<class F> function_ref(F* f) noexcept;
Constraints:
is_function_v is true, and
is-invocable-using is true.
Preconditions: f is not a null pointer.
Effects: Initializesbound-entity with f, andthunk-ptr with the address of a function thunk such thatthunk(bound-entity, call-args...) is expression-equivalent ([defns.expression.equivalent]) toinvoke_r(f, call-args...).
template<class F> constexpr function_ref(F&& f) noexcept;
Let T be remove_reference_t.
Constraints:
remove_cvref_t is not the same type as function_ref,
is_member_pointer_v is false, and
is-invocable-using<cv T&> is true.
Effects: Initializesbound-entity with addressof(f), andthunk-ptr with the address of a function thunk such thatthunk(bound-entity, call-args...) is expression-equivalent ([defns.expression.equivalent]) toinvoke_r(static_cast<cv T&>(f), call-args...).
template<auto f> constexpr function_ref(nontype_t<f>) noexcept;
Let F be decltype(f).
Constraints: is-invocable-using is true.
Mandates: If is_pointer_v || is_member_pointer_v is true, then f != nullptr is true.
Effects: Initializesbound-entity with a pointer to an unspecified object or null pointer value, andthunk-ptr with the address of a function thunk such thatthunk(bound-entity, call-args...) is expression-equivalent ([defns.expression.equivalent]) toinvoke_r(f, call-args...).
template<auto f, class U> constexpr function_ref(nontype_t<f>, U&& obj) noexcept;
Let T be remove_reference_t andF be decltype(f).
Constraints:
is_rvalue_reference_v<U&&> is false, and
is-invocable-using<F, cv T&> is true.
Mandates: If is_pointer_v || is_member_pointer_v is true, then f != nullptr is true.
Effects: Initializesbound-entity with addressof(obj), andthunk-ptr with the address of a function thunk such thatthunk(bound-entity, call-args...) is expression-equivalent ([defns.expression.equivalent]) toinvoke_r(f, static_cast<cv T&>(obj), call-args...).
template<auto f, class T> constexpr function_ref(nontype_t<f>, cv T* obj) noexcept;
Let F be decltype(f).
Constraints: is-invocable-using<F, cv T*> is true.
Mandates: If is_pointer_v || is_member_pointer_v is true, then f != nullptr is true.
Preconditions: If is_member_pointer_v is true,obj is not a null pointer.
Effects: Initializesbound-entity with obj, andthunk-ptr with the address of a function thunk such thatthunk(bound-entity, call-args...) is expression-equivalent ([defns.expression.equivalent]) toinvoke_r(f, obj, call-args...).
template<class T> function_ref& operator=(T) = delete;
Constraints:
T is not the same type as function_ref,
is_pointer_v is false, and
T is not a specialization of nontype_t.
22.10.17.6.4 Invocation [func.wrap.ref.inv]
R operator()(ArgTypes... args) const noexcept(noex);
Effects: Equivalent to:return thunk-ptr(bound-entity, std::forward(args)...);
22.10.17.6.5 Deduction guides [func.wrap.ref.deduct]
template<class F> function_ref(F*) -> function_ref<F>;
Constraints: is_function_v is true.
template<auto f> function_ref(nontype_t<f>) -> function_ref<see below>;
Let F be remove_pointer_t<decltype(f)>.
Constraints: is_function_v is true.
Remarks: The deduced type is function_ref.
template<auto f, class T> function_ref(nontype_t<f>, T&&) -> function_ref<see below>;
Let F be decltype(f).
Constraints:
F is of the formR(G::*)(A...) cv &opt noexcept(E) for a type G, or
F is of the formM G::* for a type G and an object type M, in which case let R be invoke_result_t<F, T&>,A... be an empty pack, andE be false, or
F is of the formR(*)(G, A...) noexcept(E) for a type G.
Remarks: The deduced type is function_ref<R(A...) noexcept(E)>.
22.10.18 Searchers [func.search]
22.10.18.1 General [func.search.general]
Subclause [func.search] provides function object types ([function.objects]) 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 [func.search] shall meet the Cpp17CopyConstructible and Cpp17CopyAssignable requirements.
Template parameters named
ForwardIterator,
ForwardIterator1,
ForwardIterator2,
RandomAccessIterator,
RandomAccessIterator1,
RandomAccessIterator2, and
BinaryPredicate
of templates specified in[func.search] shall meet the same requirements and semantics as specified in [algorithms.general].
Template parameters named Hash shall meet the Cpp17Hash requirements (Table 37).
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.
22.10.18.2 Class template default_searcher [func.search.default]
namespace std {template<class ForwardIterator1, class BinaryPredicate = equal_to<>>class default_searcher {public:constexpr default_searcher(ForwardIterator1 pat_first, ForwardIterator1 pat_last, BinaryPredicate pred = BinaryPredicate()); templateconstexpr 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(ForwardIterator1 pat_first, ForwardIterator1 pat_last, BinaryPredicate pred = BinaryPredicate());
Effects: Constructs a default_searcher object, initializing pat_first_ with pat_first, pat_last_ with pat_last, andpred_ with pred.
Throws: Any exception thrown by the copy constructor of BinaryPredicate orForwardIterator1.
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_)).
22.10.18.3 Class template boyer_moore_searcher [func.search.bm]
namespace std {template<class RandomAccessIterator1, class Hash = hash<typename iterator_traits::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 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());
Preconditions: The value type of RandomAccessIterator1 meets the Cpp17DefaultConstructible,Cpp17CopyConstructible, andCpp17CopyAssignable requirements.
Let V be iterator_traits::value_type.
For any two values A and B of type V, if pred(A, B) == true, then hf(A) == hf(B) is true.
Effects: Initializespat_first_ with pat_first,pat_last_ with pat_last,hash_ with hf, andpred_ 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;
Mandates: RandomAccessIterator1 and RandomAccessIterator2 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.
22.10.18.4 Class template boyer_moore_horspool_searcher [func.search.bmh]
namespace std {template<class RandomAccessIterator1, class Hash = hash<typename iterator_traits::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 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());
Preconditions: The value type of RandomAccessIterator1 meets the Cpp17DefaultConstructible,Cpp17CopyConstructible, and Cpp17CopyAssignable requirements.
Let V be iterator_traits::value_type.
For any two values A and B of type V, if pred(A, B) == true, then hf(A) == hf(B) is true.
Effects: Initializespat_first_ with pat_first,pat_last_ with pat_last,hash_ with hf, andpred_ 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;
Mandates: RandomAccessIterator1 and RandomAccessIterator2 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.
22.10.19 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 1:
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 is disabled.
If the library provides an explicit or partial specialization of hash, 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,is_copy_constructible_v,is_move_constructible_v,is_copy_assignable_v, andis_move_assignable_v.
Disabled specializations of hash are not function object types ([function.objects]).
[Note 2:
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 will:
meet the Cpp17Hash requirements (Table 37), with Key as the function call argument type, the Cpp17DefaultConstructible requirements (Table 30), the Cpp17CopyAssignable requirements (Table 34), the Cpp17Swappable requirements ([swappable.requirements]),
meet the requirement that if k1 == k2 is true, h(k1) == h(k2) is also true, where h is an object of type hash and k1 and k2 are objects of type Key;
meet the requirement that the expression h(k), where h is an object of type hash and k is an object of typeKey, shall not throw an exception unless hash is a program-defined specialization.