Add not_fn per TC workitem 1203081

Colin Robertson · Colin Robertson · commit cec4487024b3 · 2019-01-17T17:31:09.000-08:00
diff --git a/docs/standard-library/functional-functions.md b/docs/standard-library/functional-functions.md
@@ -1,7 +1,7 @@
 ---
 title: "&lt;functional&gt; functions"
-ms.date: "11/04/2016"
-f1_keywords: ["functional/std::bind", "xfunctional/std::bind1st", "xfunctional/std::bind2nd", "xfunctional/std::bit_and", "xfunctional/std::bit_not", "xfunctional/std::bit_or", "xfunctional/std::bit_xor", "functional/std::cref", "type_traits/std::cref", "xfunctional/std::mem_fn", "xfunctional/std::mem_fun_ref", "xfunctional/std::not1", "xfunctional/std::not2", "xfunctional/std::ptr_fun", "functional/std::ref", "functional/std::swap"]
+ms.date: "01/17/2019"
+f1_keywords: ["functional/std::bind", "xfunctional/std::bind1st", "xfunctional/std::bind2nd", "xfunctional/std::bit_and", "xfunctional/std::bit_not", "xfunctional/std::bit_or", "xfunctional/std::bit_xor", "functional/std::cref", "type_traits/std::cref", "xfunctional/std::mem_fn", "xfunctional/std::mem_fun_ref", "xfunctional/std::not1", "xfunctional/std::not2", "functional/std::not_fn", "xfunctional/std::ptr_fun", "functional/std::ref", "functional/std::swap"]
 helpviewer_keywords: ["std::bind [C++]", "std::bind1st", "std::bind2nd", "std::bit_and [C++]", "std::bit_not [C++]", "std::bit_or [C++]", "std::bit_xor [C++]", "std::cref [C++]"]
 ms.assetid: c34d0b45-50a7-447a-9368-2210d06339a4
 ---
@@ -13,8 +13,8 @@ ms.assetid: c34d0b45-50a7-447a-9368-2210d06339a4
 |[bit_and](#bit_and)|[bit_not](#bit_not)|[bit_or](#bit_or)|
 |[bit_xor](#bit_xor)|[cref](#cref)|[mem_fn](#mem_fn)|
 |[mem_fun](#mem_fun)|[mem_fun_ref](#mem_fun_ref)|[not1](#not1)|
-|[not2](#not2)|[ptr_fun](#ptr_fun)|[ref](#ref)|
-|[swap](#swap)|
+|[not2](#not2)|[not_fn](#not_fn)|[ptr_fun](#ptr_fun)|
+|[ref](#ref)|[swap](#swap)|
 
 ## <a name="bind"></a>  bind
 
@@ -777,7 +777,7 @@ With the even numbers removed, the remaining values are: 1 3 5 7 9 11 13
 
 ## <a name="not1"></a>  not1
 
-Returns the complement of a unary predicate.
+Returns the complement of a unary predicate. Deprecated in favor of [not_fn](#not_fn) in C++17.
 
 ```cpp
 template <class UnaryPredicate>
@@ -849,7 +849,7 @@ The number of elements in v1 not greater than 10 is: 3.
 
 ## <a name="not2"></a>  not2
 
-Returns the complement of a binary predicate.
+Returns the complement of a binary predicate. Deprecated in favor of [not_fn](#not_fn) in C++17.
 
 ```cpp
 template <class BinaryPredicate>
@@ -923,6 +923,117 @@ Sorted vector v1 = ( 41 6262 6262 6334 18467 19169 26500 )
 Resorted vector v1 = ( 26500 19169 18467 6334 6262 6262 41 )
 ```
 
+## <a name="not_fn"></a> not_fn
+
+Intended as a generic replacement for negation function wrappers `std::not1` and `std::not2`, this function template creates a forwarding call wrapper that returns the logical negation of the result of its contained callable object. It preserves the const qualification and value category behavior of the wrapped function object. This template function is new in C++17, and replaces the deprecated `std::not1`, `std::not2`, `std::unary_negate` and `std::binary_negate`.
+
+```cpp
+template <class Callable>
+unspecified not_fn(Callable&& func);
+```
+
+### Parameters
+
+*func*<br/>
+A callable object used to construct the forwarding call wrapper.
+
+### Remarks
+
+The template function returns a call wrapper equivalent to `return call_wrapper(std::forward<Callable>(func))` based on this exposition-only class:
+
+```cpp
+class call_wrapper
+{
+   using FD = decay_t<Callable>;
+   explicit call_wrapper(Callable&& func);
+
+public:
+   call_wrapper(call_wrapper&&) = default;
+   call_wrapper(call_wrapper const&) = 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<FD const&(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<FD const(Args...)>>());
+
+private:
+  FD fd;
+};
+```
+
+The explicit constructor on the callable object *func* requires type `std::decay_t<Callable>` to satisfy the requirements of `MoveConstructible`, and `is_constructible_v<FD, Callable>` must be true. It initializes the wrapped callable object `fd` from `std::forward<Callable>(func)`, and throws any exception thrown by construction of `fd`.
+
+The wrapper exposes call operators distinguished by lvalue or rvalue reference category and const qualification as shown here,
+
+```cpp
+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<FD const&(Args...)>>());
+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<FD const(Args...)>>());
+```
+
+The first two are equivalent to `return !INVOKE(fd, std::forward<Args>(args)...)`, and the second two are equivalent to `return !INVOKE(std::move(fd), std::forward<Args>(args)...)`.
+
+### Example
+
+```cpp
+// functional_not_fn_.cpp
+// compile with: /EHsc /std:c++17
+#include <vector>
+#include <algorithm>
+#include <functional>
+#include <cstdlib>
+#include <iostream>
+
+int main()
+{
+    using namespace std;
+    vector <int> v1;
+
+    int i;
+    v1.push_back( 6262 );
+    v1.push_back( 6262 );
+    for ( i = 0 ; i < 5 ; i++ )
+    {
+        v1.push_back(rand());
+    }
+
+    cout << "Original vector v1 = ( " ;
+    for (const auto& item : v1)
+        cout << item << " ";
+    cout << ")" << endl;
+
+    // To sort in ascending order,
+    // use default binary predicate less<>()
+    sort(v1.begin(), v1.end());
+    cout << "Sorted vector v1 = ( " ;
+    for (const auto& item : v1)
+        cout << item << " ";
+    cout << ")" << endl;
+
+    // To sort in descending order,
+    // use the helper function not_fn
+    sort(v1.begin(), v1.end(), not_fn(less<>()));
+    cout << "Resorted vector v1 = ( " ;
+    for (const auto& item : v1)
+        cout << item << " ";
+    cout << ")" << endl;
+}
+```
+
+```Output
+Original vector v1 = ( 6262 6262 41 18467 6334 26500 19169 )
+Sorted vector v1 = ( 41 6262 6262 6334 18467 19169 26500 )
+Resorted vector v1 = ( 26500 19169 18467 6334 6262 6262 41 )
+```
+
 ## <a name="ptr_fun"></a>  ptr_fun
 
 Helper template functions used to convert unary and binary function pointers, respectively, into unary and binary adaptable functions.
diff --git a/docs/standard-library/functional.md b/docs/standard-library/functional.md
@@ -1,13 +1,13 @@
 ---
 title: "&lt;functional&gt;"
-ms.date: "11/04/2016"
+ms.date: "01/17/2019"
 f1_keywords: ["<functional>", "functional/std::<functional>", "std::<functional>"]
 helpviewer_keywords: ["functors", "functional header"]
 ms.assetid: 7dd463e8-a29f-49bc-aedd-8fa53b54bfbc
 ---
 # &lt;functional&gt;
 
-Defines C++ Standard Library functions that help construct *function objects*—also known as functors—and their binders. A function object is an object of a type that defines `operator()`. A function object can be a function pointer, but more typically, the object is used to store additional information that can be accessed during a function call.
+Defines C++ Standard Library functions that help construct *function objects*, also known as *functors*, and their binders. A function object is an object of a type that defines `operator()`. A function object can be a function pointer, but more typically, the object is used to store additional information that can be accessed during a function call.
 
 ## Syntax
 
@@ -17,9 +17,9 @@ Defines C++ Standard Library functions that help construct *function objects*—
 
 ## Remarks
 
-Algorithms require two types of function objects: unary and binary. Unary function objects require one argument, and binary function objects require two arguments. A function object and function pointers can be passed as a predicate to an algorithm, but function objects are also adaptable and increase the scope, flexibility, and efficiency of the C++ Standard Library. If, for example, a value needed to be bound to a function before being passed to an algorithm, then a function pointer could not be used. Function adaptors convert function pointers into adaptable function objects that can be bound to a value. The header \<functional> also contains member function adaptors that allow member functions to be called as adaptable function objects. Functions are adaptable if they have nested type declarations specifying their argument and return types. The C++ Standard requires that this adaptability is implemented by having all standard object classes inherit from the unary_function or binary_function base classes. Function objects and their adaptors allow the C++ Standard Library to upgrade existing applications and help integrate the library into the C++ programming environment.
+Algorithms require two types of function objects: *unary* and *binary*. Unary function objects require one argument, and binary function objects require two arguments. A function object and function pointers can be passed as a predicate to an algorithm, but function objects are also adaptable and increase the scope, flexibility, and efficiency of the C++ Standard Library. If, for example, a value needed to be bound to a function before being passed to an algorithm, then a function pointer could not be used. Function adaptors convert function pointers into adaptable function objects that can be bound to a value. The header \<functional> also contains member function adaptors that allow member functions to be called as adaptable function objects. Functions are adaptable if they have nested type declarations specifying their argument and return types. The C++ Standard requires that this adaptability is implemented by having all standard object classes inherit from the unary_function or binary_function base classes. Function objects and their adaptors allow the C++ Standard Library to upgrade existing applications and help integrate the library into the C++ programming environment.
 
-The Visual C++ implementation of the function objects in \<functional> includes *transparent operator functors*, which are specializations of standard function objects and take no template parameters, and perform perfect forwarding of the function arguments and perfect return of the result. This feature is part of the C++14 Draft Standard specification. These template specializations do not require that you specify argument types when you invoke arithmetic, comparison, logical, and bitwise operator functors. You can overload arithmetic, comparison, logical, or bitwise operators for your own types, or for heterogeneous combinations of types, and then use the transparent operator functors as function arguments. For example, if your type *MyType* implements `operator<`, you can call `sort(my_collection.begin(), my_collection.end(), less<>())` instead of explicitly specifying the type `sort(my_collection.begin(), my_collection.end(), less<MyType>())`.
+The Visual C++ implementation of the function objects in \<functional> includes *transparent operator functors*. which are specializations of standard function objects and take no template parameters, and perform perfect forwarding of the function arguments and perfect return of the result. This feature is part of the C++14 Draft Standard specification. These template specializations do not require that you specify argument types when you invoke arithmetic, comparison, logical, and bitwise operator functors. You can overload arithmetic, comparison, logical, or bitwise operators for your own types, or for heterogeneous combinations of types, and then use the transparent operator functors as function arguments. For example, if your type *MyType* implements `operator<`, you can call `sort(my_collection.begin(), my_collection.end(), less<>())` instead of explicitly specifying the type `sort(my_collection.begin(), my_collection.end(), less<MyType>())`.
 
 ## C++11/C++14 Implementation
 
@@ -68,7 +68,7 @@ Every call wrapper has a move constructor and a copy constructor. A *simple call
 |Class|Description|
 |-|-|
 |[bad_function_call](../standard-library/bad-function-call-class.md)|A class that describes an exception thrown to indicate that a call to `operator()` on a [function](../standard-library/function-class.md) object failed because the object was empty.|
-|[binary_negate](../standard-library/binary-negate-class.md)|A template class providing a member function that negates the return value of a specified binary function.|
+|[binary_negate](../standard-library/binary-negate-class.md)|A template class providing a member function that negates the return value of a specified binary function. Deprecated in C++17. |
 |[binder1st](../standard-library/binder1st-class.md)|A template class providing a constructor that converts a binary function object into a unary function object by binding the first argument of the binary function to a specified value.|
 |[binder2nd](../standard-library/binder2nd-class.md)|A template class providing a constructor that converts a binary function object into a unary function object by binding the second argument of the binary function to a specified value.|
 |[const_mem_fun_ref_t](../standard-library/const-mem-fun-ref-t-class.md)|An adapter class that allows a const member function that takes no arguments to be called as a unary function object when initialized with a reference argument.|
@@ -86,7 +86,7 @@ Every call wrapper has a move constructor and a copy constructor. A *simple call
 |[pointer_to_binary_function](../standard-library/pointer-to-binary-function-class.md)|Converts a binary function pointer into an adaptable binary function.|
 |[pointer_to_unary_function](../standard-library/pointer-to-unary-function-class.md)|Converts a unary function pointer into an adaptable unary function.|
 |[reference_wrapper](../standard-library/reference-wrapper-class.md)|A class that wraps a reference.|
-|[unary_negate](../standard-library/unary-negate-class.md)|A template class providing a member function that negates the return value of a specified unary function.|
+|[unary_negate](../standard-library/unary-negate-class.md)|A template class providing a member function that negates the return value of a specified unary function. Deprecated in C++17. |
 
 ### Functions
 
@@ -103,8 +103,9 @@ Every call wrapper has a move constructor and a copy constructor. A *simple call
 |[mem_fn](../standard-library/functional-functions.md#mem_fn)|Generates a simple call wrapper.|
 |[mem_fun](../standard-library/functional-functions.md#mem_fun)|Helper template functions used to construct function object adaptors for member functions when initialized with pointer arguments.|
 |[mem_fun_ref](../standard-library/functional-functions.md#mem_fun_ref)|A helper template function used to construct function object adaptors for member functions when initialized with reference arguments.|
-|[not1](../standard-library/functional-functions.md#not1)|Returns the complement of a unary predicate.|
-|[not2](../standard-library/functional-functions.md#not2)|Returns the complement of a binary predicate.|
+|[not1](../standard-library/functional-functions.md#not1)|Returns the complement of a unary predicate. Deprecated in C++17. |
+|[not2](../standard-library/functional-functions.md#not2)|Returns the complement of a binary predicate. Deprecated in C++17. |
+|[not_fn](../standard-library/functional-functions.md#not_fn)|Returns the complement of the result of its function object. New in C++17. |
 |[ptr_fun](../standard-library/functional-functions.md#ptr_fun)|A helper template function used to convert unary and binary function pointers, respectively, into unary and binary adaptable functions.|
 |[ref](../standard-library/functional-functions.md#ref)|Constructs a `reference_wrapper` from an argument.|
 |[swap](../standard-library/functional-functions.md#swap)|Swaps two `function` objects.|
