Skip to content

Commit a35c6fc

Browse files
author
Colin Robertson
committed
Add invoke, invoke_result, invoke predicates
1 parent 1d9c6ec commit a35c6fc

File tree

6 files changed

+306
-42
lines changed

6 files changed

+306
-42
lines changed

‎docs/standard-library/functional-functions.md‎

Lines changed: 133 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -11,23 +11,23 @@ ms.assetid: c34d0b45-50a7-447a-9368-2210d06339a4
1111
|-|-|-|
1212
| [bind](#bind) | [bit_and](#bit_and) | [bit_not](#bit_not) |
1313
| [bit_or](#bit_or) | [bit_xor](#bit_xor) | [cref](#cref) |
14-
| [mem_fn](#mem_fn) | [not_fn](#not_fn) | [ref](#ref) |
15-
| [swap](#swap) | | |
14+
| [invoke](#invoke) | [mem_fn](#mem_fn) | [not_fn](#not_fn) |
15+
| [ref](#ref) | [swap](#swap) | |
1616

17-
The following functions are deprecated in C++11 and removed in C++17:
17+
These functions are deprecated in C++11 and removed in C++17:
1818

1919
||||
2020
|-|-|-|
21-
|[bind1st](#bind1st)|[bind2nd](#bind2nd)|[mem_fun](#mem_fun)|
22-
|[mem_fun_ref](#mem_fun_ref)|[ptr_fun](#ptr_fun)||
21+
| [bind1st](#bind1st) | [bind2nd](#bind2nd) | [mem_fun](#mem_fun) |
22+
| [mem_fun_ref](#mem_fun_ref) | [ptr_fun](#ptr_fun) | |
2323

24-
The following functions are deprecated in C++17:
24+
These functions are deprecated in C++17:
2525

2626
|||
2727
|-|-|
28-
|[not1](#not1)|[not2](#not2)|
28+
| [not1](#not1) | [not2](#not2) |
2929

30-
## <a name="bind"></a> bind
30+
## <a name="bind"></a> bind
3131

3232
Binds arguments to a callable object.
3333

@@ -57,7 +57,7 @@ The Nth call argument.
5757
5858
The types `Fty, T1, T2, ..., TN` must be copy constructible, and `INVOKE(fn, t1, ..., tN)` must be a valid expression for some values `w1, w2, ..., wN`.
5959
60-
The first template function returns a forwarding call wrapper `g` with a weak result type. The effect of `g(u1, u2, ..., uM)` is `INVOKE(f, v1, v2, ..., vN, `[result_of](../standard-library/result-of-class.md)`<Fty cv (V1, V2, ..., VN)>::type)`, where `cv` is the cv-qualifiers of `g` and the values and types of the bound arguments `v1, v2, ..., vN` are determined as specified below. You use it to bind arguments to a callable object to make a callable object with a tailored argument list.
60+
The first template function returns a forwarding call wrapper `g` with a weak result type. The effect of `g(u1, u2, ..., uM)` is `INVOKE(f, v1, v2, ..., vN, `[invoke_result](../standard-library/invoke-result-class.md)`<Fty cv (V1, V2, ..., VN)>::type)`, where `cv` is the cv-qualifiers of `g` and the values and types of the bound arguments `v1, v2, ..., vN` are determined as specified below. You use it to bind arguments to a callable object to make a callable object with a tailored argument list.
6161
6262
The second template function returns a forwarding call wrapper `g` with a nested type `result_type` that is a synonym for `Ret`. The effect of `g(u1, u2, ..., uM)` is `INVOKE(f, v1, v2, ..., vN, Ret)`, where `cv` is the cv-qualifiers of `g` and the values and types of the bound arguments `v1, v2, ..., vN` are determined as specified below. You use it to bind arguments to a callable object to make a callable object with a tailored argument list and with a specified return type.
6363
@@ -128,7 +128,7 @@ int main()
128128
3^2 == 9
129129
```
130130

131-
## <a name="bind1st"></a> bind1st
131+
## <a name="bind1st"></a> bind1st
132132

133133
A helper template function that creates an adaptor to convert a binary function object into a unary function object by binding the first argument of the binary function to a specified value. Deprecated in C++11, removed in C++17.
134134

@@ -222,7 +222,7 @@ The number of elements in v1 greater than 5 is: 4.
222222
The number of elements in v1 less than 10 is: 2.
223223
```
224224

225-
## <a name="bind2nd"></a> bind2nd
225+
## <a name="bind2nd"></a> bind2nd
226226

227227
A helper template function that creates an adaptor to convert a binary function object into a unary function object by binding the second argument of the binary function to a specified value. Deprecated in C++11, removed in C++17.
228228

@@ -316,7 +316,7 @@ The number of elements in v1 greater than 15 is: 2.
316316
The number of elements in v1 less than 10 is: 2.
317317
```
318318

319-
## <a name="bit_and"></a> bit_and
319+
## <a name="bit_and"></a> bit_and
320320

321321
A predefined function object that performs the bitwise AND operation (binary `operator&`) on its arguments.
322322

@@ -357,7 +357,7 @@ The result of `Left & Right`. The specialized template does perfect forwarding o
357357
358358
The `bit_and` functor is restricted to integral types for the basic data types, or to user-defined types that implement binary `operator&`.
359359
360-
## <a name="bit_not"></a> bit_not
360+
## <a name="bit_not"></a> bit_not
361361
362362
A predefined function object that performs the bitwise complement (NOT) operation (unary `operator~`) on its argument. Added in C++14.
363363
@@ -373,7 +373,7 @@ template <>
373373
struct bit_not<void>
374374
{
375375
template <class Type>
376-
auto operator()(Type&& Right) const -> decltype(~std::forward<Type>(Right));
376+
auto operator()(Type&& Right) const -> decltype(~std::forward<Type>(Right));
377377
};
378378
```
379379

@@ -393,7 +393,7 @@ The result of `~ Right`. The specialized template does perfect forwarding of the
393393

394394
The `bit_not` functor is restricted to integral types for the basic data types, or to user-defined types that implement binary `operator~`.
395395

396-
## <a name="bit_or"></a> bit_or
396+
## <a name="bit_or"></a> bit_or
397397

398398
A predefined function object that performs the bitwise OR operation (`operator|`) on its arguments.
399399

@@ -411,7 +411,7 @@ struct bit_or<void>
411411
{
412412
template <class T, class U>
413413
auto operator()(T&& Left, U&& Right) const
414-
-> decltype(std::forward<T>(Left) | std::forward<U>(Right));
414+
-> decltype(std::forward<T>(Left) | std::forward<U>(Right));
415415
};
416416
```
417417

@@ -434,7 +434,7 @@ The result of `Left | Right`. The specialized template does perfect forwarding o
434434

435435
The `bit_or` functor is restricted to integral types for the basic data types, or to user-defined types that implement `operator|`.
436436

437-
## <a name="bit_xor"></a> bit_xor
437+
## <a name="bit_xor"></a> bit_xor
438438

439439
A predefined function object that performs the bitwise XOR operation (binary `operator^`) on its arguments.
440440

@@ -475,7 +475,7 @@ The result of `Left ^ Right`. The specialized template does perfect forwarding o
475475

476476
The `bit_xor` functor is restricted to integral types for the basic data types, or to user-defined types that implement binary `operator^`.
477477

478-
## <a name="cref"></a> cref
478+
## <a name="cref"></a> cref
479479

480480
Constructs a const `reference_wrapper` from an argument.
481481

@@ -531,7 +531,7 @@ cref(i) = 1
531531
cref(neg)(i) = -1
532532
```
533533

534-
## <a name="mem_fn"></a> mem_fn
534+
## <a name="mem_fn"></a> mem_fn
535535

536536
Generates a simple call wrapper.
537537

@@ -594,7 +594,114 @@ int main()
594594
3*2 == 6
595595
```
596596

597-
## <a name="mem_fun"></a> mem_fun
597+
## <a name="invoke"></a> invoke
598+
599+
Invokes any callable object with the given arguments. Added in C++17.
600+
601+
```cpp
602+
template <class Callable, class... Args>
603+
invoke_result_t<Callable, Args...>
604+
invoke(Callable&& fn, Args&&... args) noexcept(/* specification */);
605+
```
606+
607+
### Parameters
608+
609+
*Callable*<br/>
610+
The type of the object to call.
611+
612+
*Args*<br/>
613+
The types of the call arguments.
614+
615+
*fn*<br/>
616+
The object to call.
617+
618+
*args*<br/>
619+
The call arguments.
620+
621+
*specification*<br/>
622+
The **noexcept** specification `std::is_nothrow_invocable_v<Callable, Args>)`.
623+
624+
### Remarks
625+
626+
Invokes the callable object *fn* using the parameters *args*. Effectively, `INVOKE(std::forward<Callable>(fn), std::forward<Args>(args)...)`, where the pseudo-function `INVOKE(f, t1, t2, ..., tN)` means one of the following things:
627+
628+
- `(t1.*f)(t2, ..., tN)` when `f` is a pointer to member function of class `T` and `t1` is an object of type `T` or a reference to an object of type `T` or a reference to an object of a type derived from `T`. That is, when `std::is_base_of<T, std::decay_t<decltype(t1)>>::value` is true.
629+
630+
- `(t1.get().*f)(t2, ..., tN)` when `f` is a pointer to member function of class `T` and `std::decay_t<decltype(t1)>` is a specialization of `std::reference_wrapper`.
631+
632+
- `((*t1).*f)(t2, ..., tN)` when `f` is a pointer to member function of class `T` and `t1` is not one of the previous types.
633+
634+
- `t1.*f` when N == 1 and `f` is a pointer to member data of a class `T` and `t1` is an object of type `T` or a reference to an object of type `T` or a reference to an object of a type derived from `T`. That is, when `std::is_base_of<T, std::decay_t<decltype(t1)>>::value` is true.
635+
636+
- `t1.get().*f` when N == 1 and `f` is a pointer to member data of a class `T` and `std::decay_t<decltype(t1)>` is a specialization of `std::reference_wrapper`.
637+
638+
- `(*t1).*f` when N == 1 and `f` is a pointer to member data of a class `T` and `t1` is not one of the previous types.
639+
640+
- `f(t1, t2, ..., tN)` in all other cases.
641+
642+
For information on the result type of a callable object, see [invoke_result](invoke-result-class.md). For predicates on callable types, see [is_invocable, is_invocable_r, is_nothrow_invocable, is_nothrow_invocable_r classes](is-invocable-classes.md).
643+
644+
### Example
645+
646+
```cpp
647+
// functional_invoke.cpp
648+
// compile using: cl /EHsc /std:c++17 functional_invoke.cpp
649+
#include <functional>
650+
#include <iostream>
651+
652+
struct Demo
653+
{
654+
int n_;
655+
656+
Demo(int const n) : n_{n} {}
657+
658+
void operator()(int const i, int const j) const
659+
{
660+
std::cout << "Demo operator( " << i << ", "
661+
<< j << " ) is " << i * j << std::endl;
662+
}
663+
664+
void difference(int const i) const
665+
{
666+
std::cout << "Demo.difference( " << i << " ) is "
667+
<< n_ - i << std::endl;
668+
}
669+
};
670+
671+
void divisible_by_3(int const i)
672+
{
673+
std::cout << i;
674+
(i % 3) ? std::cout << " isn't divisible by 3."
675+
: std::cout << " is divisible by 3.";
676+
std::cout << std::endl;
677+
}
678+
679+
int main()
680+
{
681+
// Invoke a function object (call operator).
682+
Demo d{ 42 };
683+
std::invoke( d, 3, -7 );
684+
685+
// Invoke a member function.
686+
std::invoke(&Demo::difference, d, 29);
687+
688+
// Invoke a data member.
689+
std::cout << "n_: " << std::invoke(&Demo::n_, d) << '\n';
690+
691+
// Invoke a stand-alone (free) function.
692+
std::invoke( divisible_by_3, 42 );
693+
694+
// Invoke a lambda.
695+
std::invoke( [](int const i){
696+
std::cout << i;
697+
(i % 7) ? std::cout << " isn't divisible by 7."
698+
: std::cout << " is divisible by 7.";
699+
std::cout << std::endl;
700+
}, 42 );
701+
}
702+
```
703+
704+
## <a name="mem_fun"></a> mem_fun
598705

599706
Helper template functions used to construct function object adaptors for member functions when initialized with pointer arguments. Deprecated in C++11, removed in C++17.
600707

@@ -681,7 +788,7 @@ int main( )
681788
}
682789
```
683790

684-
## <a name="mem_fun_ref"></a> mem_fun_ref
791+
## <a name="mem_fun_ref"></a> mem_fun_ref
685792

686793
Helper template functions used to construct function object adaptors for member functions when initialized by using reference arguments. Deprecated in C++11, removed in C++17.
687794

@@ -786,7 +893,7 @@ The original values stored in v2 are: 1 2 3 4 5 6 7 8 9 10 11 12 13
786893
With the even numbers removed, the remaining values are: 1 3 5 7 9 11 13
787894
```
788895

789-
## <a name="not1"></a> not1
896+
## <a name="not1"></a> not1
790897

791898
Returns the complement of a unary predicate. Deprecated in favor of [not_fn](#not_fn) in C++17.
792899

@@ -858,7 +965,7 @@ The number of elements in v1 greater than 10 is: 5.
858965
The number of elements in v1 not greater than 10 is: 3.
859966
```
860967

861-
## <a name="not2"></a> not2
968+
## <a name="not2"></a> not2
862969

863970
Returns the complement of a binary predicate. Deprecated in favor of [not_fn](#not_fn) in C++17.
864971

@@ -1034,7 +1141,7 @@ Elements divisible by three: 2
10341141
Elements not divisible by three: 5
10351142
```
10361143

1037-
## <a name="ptr_fun"></a> ptr_fun
1144+
## <a name="ptr_fun"></a> ptr_fun
10381145

10391146
Helper template functions used to convert unary and binary function pointers, respectively, into unary and binary adaptable functions. Deprecated in C++11, removed in C++17.
10401147

@@ -1065,7 +1172,7 @@ A function pointer is a function object and may be passed to any C++ Standard Li
10651172
10661173
[!code-cpp[functional_ptr_fun#1](../standard-library/codesnippet/CPP/functional-functions_1.cpp)]
10671174
1068-
## <a name="ref"></a> ref
1175+
## <a name="ref"></a> ref
10691176
10701177
Constructs a `reference_wrapper` from an argument.
10711178
@@ -1157,7 +1264,7 @@ tiger lion cougar
11571264
tiger cougar
11581265
```
11591266

1160-
## <a name="swap"></a> swap
1267+
## <a name="swap"></a> swap
11611268

11621269
Swaps two `function` objects.
11631270

‎docs/standard-library/invoke-result-class.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
title: "invoke_result Class"
3+
ms.date: "02/21/2019"
4+
f1_keywords: ["type_traits/std::invoke_result", "type_traits/std::invoke_result_t", "type_traits/std::invoke_result::type"]
5+
helpviewer_keywords: ["std::invoke_result", "std::invoke_result_t", "std::invoke_result::type"]
6+
---
7+
# invoke_result Class
8+
9+
Determines the return type of the callable type that takes the specified argument types at compile time. Added in C++17.
10+
11+
## Syntax
12+
13+
```cpp
14+
template <class Callable, class... Args>
15+
struct invoke_result<Callable(Args...)>;
16+
17+
// Helper type
18+
template<lass Callable, class... Args>
19+
using invoke_result_t = typename invoke_result<Callable, Args...>::type;
20+
```
21+
22+
### Parameters
23+
24+
*Callable*<br/>
25+
The callable type to query.
26+
27+
*Args*<br/>
28+
The types of the argument list to the callable type to query.
29+
30+
## Remarks
31+
32+
Use this template to determine the result type of *Callable*(*Args*...) at compile time, where *Callable* and all types in *Args* are any complete type, an array of unknown bound, or a possibly cv-qualified `void`. The `type` member of the template class names the return type of *Callable* when invoked using the arguments *Args*.... The `type` member is only defined if *Callable* can be called when invoked using the arguments *Args*... in an unevaluated context. Otherwise, the template class has no member `type`, which allows SFINAE tests on a particular set of argument types at compile time.
33+
34+
## Requirements
35+
36+
**Header:** \<type_traits>
37+
38+
**Namespace:** std
39+
40+
## See also
41+
42+
[<type_traits>](../standard-library/type-traits.md)<br/>
43+
[invoke](functional-functions.md#invoke)

‎docs/standard-library/is-function-class.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
---
22
title: "is_function Class"
3-
ms.date: "11/04/2016"
4-
f1_keywords: ["type_traits/std::is"]
5-
helpviewer_keywords: ["is_function class", "is"]
3+
ms.date: "02/21/2019"
4+
f1_keywords: ["type_traits/std::is_function"]
5+
helpviewer_keywords: ["is_function class", "is_function"]
66
ms.assetid: e5c0dbcd-829b-415f-853f-8c5be47c5040
77
---
88
# is_function Class

0 commit comments

Comments
 (0)