A function object type is an object type ([basic.types]) that can be the type of the postfix-expression in a function call ([expr.call], [over.match.call]).223 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 (Clause [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.
Header <functional> synopsis
namespace std {
// [func.invoke], invoke
template <class F, class... Args> result_of_t<F&&(Args&&...)> invoke(F&& f, Args&&... 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;
// [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.not_fn], function template not_fn
template <class F> unspecified not_fn(F&& f);
// [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;
template<class ForwardIterator, class BinaryPredicate = equal_to<>>
default_searcher<ForwardIterator, BinaryPredicate>
make_default_searcher(ForwardIterator pat_first, ForwardIterator pat_last,
BinaryPredicate pred = BinaryPredicate());
template<class RandomAccessIterator,
class Hash = hash<typename iterator_traits<RandomAccessIterator>::value_type>,
class BinaryPredicate = equal_to<>>
boyer_moore_searcher<RandomAccessIterator, Hash, BinaryPredicate>
make_boyer_moore_searcher(
RandomAccessIterator pat_first, RandomAccessIterator pat_last,
Hash hf = Hash(), BinaryPredicate pred = BinaryPredicate());
template<class RandomAccessIterator,
class Hash = hash<typename iterator_traits<RandomAccessIterator>::value_type>,
class BinaryPredicate = equal_to<>>
boyer_moore_horspool_searcher<RandomAccessIterator, Hash, BinaryPredicate>
make_boyer_moore_horspool_searcher(
RandomAccessIterator pat_first, RandomAccessIterator pat_last,
Hash hf = Hash(), BinaryPredicate pred = BinaryPredicate());
// [unord.hash], hash function primary template
template <class T> struct hash;
// [func.default.traits], default functor traits
template <class T = void>
struct default_order;
template <class T = void>
using default_order_t = typename default_order<T>::type;
// [func.bind], function object binders
template <class T> constexpr bool is_bind_expression_v
= is_bind_expression<T>::value;
template <class T> constexpr int is_placeholder_v
= is_placeholder<T>::value;
}
[ 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 ]
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.
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.
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 and is_base_of_v<T, decay_t<decltype(t1)>> is true;
(t1.get().*f)(t2, ..., tN) when f is a pointer to a member function of a class T and decay_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 and is_base_of_v<T, decay_t<decltype(t1)>> is true;
t1.get().*f when N == 1 and f is a pointer to data member of a class T and decay_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, R) as static_cast<void>(INVOKE(f, t1, t2, ..., tN)) if R is cv void, otherwise INVOKE(f, t1, t2, ..., tN) implicitly converted to R.
Every call wrapper ([func.def]) shall be MoveConstructible. A 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 shall ensure that rvalue arguments are delivered as rvalue references and lvalue arguments are delivered as lvalue references. A simple call wrapper is a forwarding call wrapper that is CopyConstructible and CopyAssignable and whose copy constructor, move constructor, and assignment operator do not throw exceptions. [ Note: In a typical implementation forwarding call wrappers have an overloaded function call operator of the form
template<class... UnBoundArgs> R operator()(UnBoundArgs&&... unbound_args) cv-qual;
— end note ]
template <class F, class... Args>
result_of_t<F&&(Args&&...)> invoke(F&& f, Args&&... args);
Returns: INVOKE(std::forward<F>(f), std::forward<Args>(args)...) ([func.require]).
namespace std {
template <class T> class reference_wrapper {
public :
// types
using type = T;
// construct/copy/destroy
reference_wrapper(T&) noexcept;
reference_wrapper(T&&) = delete; // do not bind to temporary objects
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>
result_of_t<T&(ArgTypes&&...)>
operator() (ArgTypes&&...) const;
};
}
reference_wrapper<T> is a CopyConstructible and CopyAssignable wrapper around a reference to an object or function of type T.
reference_wrapper<T> shall be a trivially copyable type ([basic.types]).
reference_wrapper(T& t) noexcept;
Effects: Constructs a reference_wrapper object that stores a reference to t.
reference_wrapper(const reference_wrapper& x) noexcept;
Effects: Constructs a reference_wrapper object that stores a reference to x.get().
reference_wrapper& operator=(const reference_wrapper& x) noexcept;
Postconditions: *this stores a reference to x.get().
operator T& () const noexcept;
Returns: The stored reference.
Returns: The stored reference.
template <class... ArgTypes>
result_of_t<T&(ArgTypes&&... )>
operator()(ArgTypes&&... args) const;
Returns: INVOKE(get(), std::forward<ArgTypes>(args)...). ([func.require])
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()).
The library provides basic function object classes for all of the arithmetic operators in the language ([expr.mul], [expr.add]).
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).
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).
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).
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).
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).
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).
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.
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).
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).
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).
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).
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).
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).
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]).
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).
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).
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).
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]).
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).
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).
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).
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).
template <class F> unspecified not_fn(F&& f);
Effects: Equivalent to return call_wrapper(std::forward<F>(f)); where call_wrapper is an exposition only class defined as follows:
class call_wrapper{
using FD = decay_t<F>;
explicit call_wrapper(F&& f);
public:
call_wrapper(call_wrapper&&) = default;
call_wrapper(const call_wrapper&) = default;
template<class... Args>
auto operator()(Args&&...) &
-> decltype(!declval<result_of_t<FD&(Args&&...)>>());
template<class... Args>
auto operator()(Args&&...) const&
-> decltype(!declval<result_of_t<const FD&(Args&&...)>>());
template<class... Args>
auto operator()(Args&&...) &&
-> decltype(!declval<result_of_t<FD(Args&&...)>>());
template<class... Args>
auto operator()(Args&&...) const&&
-> decltype(!declval<result_of_t<const FD(Args&&...)>>());
private:
FD fd;
};
explicit call_wrapper(F&& f);
Requires: FD shall satisfy the requirements of MoveConstructible. is_constructible_v<FD, F> shall be true. fd shall be a callable object ([func.def]).
Effects: Initializes fd from std::forward<F>(f).
Throws: Any exception thrown by construction of fd.
template<class... Args>
auto operator()(Args&&... args) &
-> decltype(!declval<result_of_t<FD&(Args&&...)>>());
template<class... Args>
auto operator()(Args&&... args) const&
-> decltype(!declval<result_of_t<const FD&(Args&&...)>>());
Effects: Equivalent to: return !INVOKE(fd, std::forward<Args>(args)...); ([func.require]).
template<class... Args>
auto operator()(Args&&... args) &&
-> decltype(!declval<result_of_t<FD(Args&&...)>>());
template<class... Args>
auto operator()(Args&&... args) const&&
-> decltype(!declval<result_of_t<const FD(Args&&...)>>());
Effects: Equivalent to: return !INVOKE(std::move(fd), std::forward<Args>(args)...); ([func.require]).
This subclause describes a uniform mechanism for binding arguments of callable objects.
namespace std {
template<class T> struct is_bind_expression; // see below
}
is_bind_expression can be used to detect function objects generated by bind. bind uses is_bind_expression to detect subexpressions.
Instantiations of the is_bind_expression template shall meet the UnaryTypeTrait requirements ([meta.rqmts]). The implementation shall provide a definition that has a BaseCharacteristic of true_type if T is a type returned from bind, otherwise it shall have a BaseCharacteristic of false_type. A program may specialize this template for a user-defined type T to have a BaseCharacteristic of true_type to indicate that T should be treated as a subexpression in a bind call.
namespace std {
template<class T> struct is_placeholder; // see below
}
is_placeholder can be used to detect the standard placeholders _1, _2, and so on. bind uses is_placeholder to detect placeholders.
Instantiations of the is_placeholder template shall meet the UnaryTypeTrait requirements ([meta.rqmts]). The implementation shall provide a definition that has the BaseCharacteristic of integral_constant<int, J> if T is the type of std::placeholders::_J, otherwise it shall have a BaseCharacteristic of integral_constant<int, 0>. A program may specialize this template for a user-defined type T to have a BaseCharacteristic of integral_constant<int, N> with N > 0 to indicate that T should be treated as a placeholder type.
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),
Ti is the ith type in the template parameter pack BoundArgs,
TiD is the type decay_t<Ti>,
ti is the ith argument in the function parameter pack bound_args,
tid is an lvalue of type TiD constructed from std::forward<Ti>(ti),
Uj is the jth deduced type of the UnBoundArgs&&... parameter of the forwarding call wrapper, and
uj is the jth argument associated with Uj.
template<class F, class... BoundArgs>
unspecified bind(F&& f, BoundArgs&&... bound_args);
Requires: is_constructible_v<FD, F> shall be true. For each Ti in BoundArgs, is_constructible_v<TiD, Ti> shall be true. INVOKE (fd, w1, w2, ..., wN) ([func.require]) shall be a valid expression for some values w1, w2, ..., wN, where N == sizeof...(bound_args). The cv-qualifiers cv of the call wrapper g, as specified below, shall be neither volatile nor const volatile.
Returns: A forwarding call wrapper g ([func.require]). The effect of g(u1, u2, ..., uM) shall be INVOKE(fd, std::forward<V1>(v1), std::forward<V2>(v2), ..., std::forward<VN>(vN)), where the values and types of the bound arguments v1, v2, ..., vN are determined as specified below. The copy constructor and move constructor of the forwarding call wrapper shall throw an exception if and only if the corresponding constructor of FD or of any of the types TiD throws an exception.
Throws: Nothing unless the construction of fd or of one of the values tid throws an exception.
Remarks: The return type shall satisfy the requirements of MoveConstructible. If all of FD and TiD satisfy the requirements of CopyConstructible, then the return type shall satisfy the requirements of CopyConstructible. [ Note: This implies that all of FD and TiD are MoveConstructible. — 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 Ti in BoundArgs, is_constructible_v<TiD, Ti> shall be true. INVOKE(fd, w1, w2, ..., wN) shall be a valid expression for some values w1, w2, ..., wN, where N == sizeof...(bound_args). The cv-qualifiers cv of the call wrapper g, as specified below, shall be neither volatile nor const volatile.
Returns: A forwarding call wrapper g ([func.require]). The effect of g(u1, u2, ..., uM) shall be INVOKE(fd, std::forward<V1>(v1), std::forward<V2>(v2), ..., std::forward<VN>(vN), R), where the values and types of the bound arguments v1, v2, ..., vN are determined as specified below. The copy constructor and move constructor of the forwarding call wrapper shall throw an exception if and only if the corresponding constructor of FD or of any of the types TiD throws an exception.
Throws: Nothing unless the construction of fd or of one of the values tid throws an exception.
Remarks: The return type shall satisfy the requirements of MoveConstructible. If all of FD and TiD satisfy the requirements of CopyConstructible, then the return type shall satisfy the requirements of CopyConstructible. [ Note: This implies that all of FD and TiD are MoveConstructible. — end note ]
The values of the bound arguments v1, v2, ..., vN and their corresponding types V1, V2, ..., VN depend on the types TiD derived from the call to bind and the cv-qualifiers cv of the call wrapper g as follows:
if TiD is reference_wrapper<T>, the argument is tid.get() and its type Vi is T&;
if the value of is_bind_expression_v<TiD> is true, the argument is tid(std::forward<Uj>(uj)...) and its type Vi is result_of_t<TiD cv & (Uj&&...)>&&;
if the value j of is_placeholder_v<TiD> is not zero, the argument is std::forward<Uj>(uj) and its type Vi is Uj&&;
otherwise, the value is tid and its type Vi is TiD cv &.
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 DefaultConstructible and CopyConstructible, and their default constructors and copy/move constructors shall not throw exceptions. It is implementation-defined whether placeholder types are CopyAssignable. CopyAssignable placeholders' copy assignment operators shall not throw exceptions.
Placeholders should be defined as:
constexpr unspecified _1{};
If they are not, they shall be declared as:
extern unspecified _1;
template<class R, class T> unspecified mem_fn(R T::* pm) noexcept;
Returns: A simple call wrapper ([func.def]) fn such that the expression fn(t, a2, ..., aN) is equivalent to INVOKE(pm, t, a2, ..., aN) ([func.require]).
This subclause describes a polymorphic wrapper class that encapsulates arbitrary callable objects.
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;
};
}
Effects: Constructs a bad_function_call object.
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&&);
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;
};
// [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 ([func.def]), given a call signature ([func.def]), allowing functions to be first-class objects.
A callable type ([func.def]) F is Lvalue-Callable for argument types ArgTypes and return type R if the expression INVOKE(declval<F&>(), declval<ArgTypes>()..., R), considered as an unevaluated operand (Clause [expr]), is well formed ([func.require]).
The function class template is a call wrapper ([func.def]) whose call signature ([func.def]) is R(ArgTypes...).
Postconditions: !*this.
Postconditions: !*this.
Postconditions: !*this if !f; otherwise, *this targets a copy of f.target().
Throws: shall not throw exceptions if f's target is a callable object passed via 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 are encouraged to 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 ]
Effects: If !f, *this has no target; otherwise, move constructs the target of f into the target of *this, leaving f in a valid state with an unspecified value.
Throws: shall not throw exceptions if f's target is a callable object passed via reference_wrapper or a function pointer. Otherwise, may throw bad_alloc or any exception thrown by the copy or move constructor of the stored callable object. [ Note: Implementations are encouraged to 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 CopyConstructible.
Remarks: This constructor template shall not participate in overload resolution unless F is Lvalue-Callable ([func.wrap.func]) for argument types ArgTypes... and return type R.
Otherwise, *this targets a copy of f initialized with std::move(f). [ Note: Implementations are encouraged to 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.
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);
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 ([func.wrap.func]) 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.
Effects: If *this != nullptr, destroys the target of this.
void swap(function& other) noexcept;
Effects: interchanges the targets of *this and other.
explicit operator bool() const noexcept;
Returns: true if *this has a target, otherwise false.
R operator()(ArgTypes... args) const;
Returns: INVOKE(f, std::forward<ArgTypes>(args)..., R) ([func.require]), where f is the target object ([func.def]) of *this.
Throws: bad_function_call if !*this; otherwise, any exception thrown by the wrapped callable object.
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.
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.
template<class R, class... ArgTypes>
void swap(function<R(ArgTypes...)>& f1, function<R(ArgTypes...)>& f2) noexcept;
Effects: As if by: f1.swap(f2);
This subclause 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 this subclause [func.search] shall meet the CopyConstructible and CopyAssignable requirements. Template parameters named
ForwardIterator,
ForwardIterator1,
ForwardIterator2,
RandomAccessIterator,
RandomAccessIterator1,
RandomAccessIterator2, and
BinaryPredicate
of templates specified in this subclause [func.search] shall meet the same requirements and semantics as specified in [algorithms.general]. Template parameters named Hash shall meet the requirements as specified in [hash.requirements].
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
template <class ForwardIterator1, class BinaryPredicate = equal_to<>>
class default_searcher {
public:
default_searcher(ForwardIterator1 pat_first, ForwardIterator1 pat_last,
BinaryPredicate pred = BinaryPredicate());
template <class ForwardIterator2>
pair<ForwardIterator2, ForwardIterator2>
operator()(ForwardIterator2 first, ForwardIterator2 last) const;
private:
ForwardIterator1 pat_first_; // exposition only
ForwardIterator1 pat_last_; // exposition only
BinaryPredicate pred_; // exposition only
};
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>
pair<ForwardIterator2, ForwardIterator2>
operator()(ForwardIterator2 first, ForwardIterator2 last) const;
template <class ForwardIterator, class BinaryPredicate = equal_to<>>
default_searcher<ForwardIterator, BinaryPredicate>
make_default_searcher(ForwardIterator pat_first, ForwardIterator pat_last,
BinaryPredicate pred = BinaryPredicate());
Effects: Equivalent to:
return default_searcher<ForwardIterator, BinaryPredicate>(pat_first, pat_last, pred);
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 meet the DefaultConstructible requirements, the CopyConstructible requirements, and the CopyAssignable 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.
template <class RandomAccessIterator,
class Hash = hash<typename iterator_traits<RandomAccessIterator>::value_type>,
class BinaryPredicate = equal_to<>>
boyer_moore_searcher<RandomAccessIterator, Hash, BinaryPredicate>
make_boyer_moore_searcher(RandomAccessIterator pat_first,
RandomAccessIterator pat_last, Hash hf = Hash(),
BinaryPredicate pred = BinaryPredicate());
Effects: Equivalent to:
return boyer_moore_searcher<RandomAccessIterator, Hash, BinaryPredicate>(
pat_first, pat_last, hf, pred);
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 meet the DefaultConstructible, CopyConstructible, and CopyAssignable 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.
template <class RandomAccessIterator,
class Hash = hash<typename iterator_traits<RandomAccessIterator>::value_type>,
class BinaryPredicate = equal_to<>>
boyer_moore_horspool_searcher<RandomAccessIterator, Hash, BinaryPredicate>
make_boyer_moore_horspool_searcher(
RandomAccessIterator pat_first, RandomAccessIterator pat_last,
Hash hf = Hash(), BinaryPredicate pred = BinaryPredicate());
Effects: Equivalent to:
return boyer_moore_horspool_searcher<RandomAccessIterator, Hash, BinaryPredicate>(
pat_first, pat_last, hf, pred);
The unordered associative containers defined in [unord] use specializations of the class template hash as the default hash function.
Each specialization of hash is either enabled or disabled, as described below. [ Note: Enabled specializations meet the requirements of Hash, 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.
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 ([function.objects]). [ Note: This means that the specialization of hash exists, but any attempts to use it as a Hash will be ill-formed. — end note ]
An enabled specialization hash<Key> will:
satisfy the Hash requirements ([hash.requirements]), with Key as the function call argument type, the DefaultConstructible requirements (Table [tab:defaultconstructible]), the CopyAssignable requirements (Table [tab:copyassignable]),
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 user-defined specialization that depends on at least one user-defined type.
namespace std {
template <class T = void>
struct default_order {
using type = less<T>;
};
}
The class template default_order provides a trait that users can specialize for user-defined types to provide a strict weak ordering for that type, which the library can use where a default strict weak order is needed. For example, the associative containers ([associative]) and priority_queue ([priority.queue]) use this trait.
[ Example:
namespace sales {
struct account {
int id;
std::string name;
};
struct order_accounts {
bool operator()(const Account& lhs, const Account& rhs) const {
return lhs.id < rhs.id;
}
};
}
namespace std {
template<>
struct default_order<sales::account> {
using type = sales::order_accounts;
};
}
— end example ]