std::not_fn(3)

📦 version 2024.07.05, in nixpkgs unstable, opensuse-leap 16.0

`std::not_fn` 💅✨

This is the std::not_fn page from the C++ Standard Libary manual, and bestie, it's lowkey a whole forwarding-call-wrapper situation. No cap, we're keeping every detail. 🫶

NAME

std::not_fn — std::not_fn. That's literally the name, periodt. 👑

Synopsis

Defined in header <functional>
template< class F >                            (1) (since C++17)
/* unspecified */ not_fn( F&& f );                 (constexpr since C++20)
template< auto ConstFn >                       (2) (since C++26)
constexpr /* unspecified */ not_fn() noexcept;

Creates a forwarding call wrapper that returns the negation of the callable object it holds. ✨
Creates a forwarding call wrapper that returns the negation of the statically determined callable target. The program is ill-formed if ConstFn is a null pointer or null pointer-to-member. 💀

Parameters

f — the object from which the Callable object held by the wrapper is constructed.

Type requirements

std::decay_t<F> must meet the requirements of Callable and MoveConstructible. 🫶
std::is_constructible_v<std::decay_t<F>, F> is required to be true.

Return value

A function object of unspecified type T. It has the following members. 👑

std::not_fn return type

Member objects

The return type of std::not_fn holds a member object of type std::decay_t<F>. 🎀

Constructors

These are (since C++17):

explicit T( F&& f );       (1) (constexpr since C++20)
                                (exposition only*)
T( T&& f ) = default;      (2) (since C++17)
T( const T& f ) = default;

The constructor direct-non-list-initializes the member object (of type std::decay_t<F>) from std::forward<F>(f). Throws any exception thrown by the constructor selected.
Because std::decay_t<F> is required to be MoveConstructible, the returned call wrapper is always MoveConstructible, and is CopyConstructible if std::decay_t<F> is CopyConstructible. 💖

The explicitly defaulted definitions make the return type not assignable (until C++20). It is unspecified whether these constructors are explicitly defaulted (since C++20) and whether the return type is assignable.

Member function `operator()` 🌀

The (since C++17) / (until C++20) overloads:

template< class... Args >
auto operator()( Args&&... args ) &
-> decltype(!std::declval<
    std::invoke_result_t<std::decay_t<F>&, Args...>>());

template< class... Args >
auto operator()( Args&&... args ) const&
-> decltype(!std::declval<
    std::invoke_result_t<std::decay_t<F> const&, Args...>>());

The (since C++20) overloads — the & / const& pair is (1):

template< class... Args >
constexpr auto operator()( Args&&... args ) &
    noexcept(/* see below */)
-> decltype(!std::invoke(
    std::declval<std::decay_t<F>&>(),
std::declval<Args>()...));

template< class... Args >
constexpr auto operator()( Args&&... args ) const&
    noexcept(/* see below */)
-> decltype(!std::invoke(
    std::declval<std::decay_t<F> const&>(),
std::declval<Args>()...));                                   (1)

The (since C++17) / (until C++20) overloads for the rvalue-ish side:

template< class... Args >
auto operator()( Args&&... args ) &&
-> decltype(!std::declval<
    std::invoke_result_t<std::decay_t<F>, Args...>>());

template< class... Args >
auto operator()( Args&&... args ) const&&
-> decltype(!std::declval<
    std::invoke_result_t<std::decay_t<F> const, Args...>>());

The (since C++20) overloads — the && one is (2):

template< class... Args >
constexpr auto operator()( Args&&... args ) &&
    noexcept(/* see below */)
-> decltype(!std::invoke(
    std::declval<std::decay_t<F>>(),
std::declval<Args>()...));                                   (2)

template< class... Args >
constexpr auto operator()( Args&&... args ) const&&
    noexcept(/* see below */)
-> decltype(!std::invoke(
    std::declval<std::decay_t<F> const>(),
std::declval<Args>()...));

Let fd be the member object of type std::decay_t<F>. 🫡

Equivalent to return !std::invoke(fd, std::forward<Args>(args)...);
Equivalent to return !std::invoke(std::move(fd), std::forward<Args>(args)...);

(since C++17) / (until C++20): while invoking the result, if the substitution into the return type of the originally selected operator() overload fails, another overload may be selected.

(since C++20):

Expression-equivalent to !std::invoke(fd, std::forward<Args>(args)...)
Expression-equivalent to !std::invoke(std::move(fd), std::forward<Args>(args)...)

While invoking the result, if the substitution into the return type of the originally selected operator() overload fails, the invocation is ill-formed, which can also be a substitution failure. 😭

A value of the following type. ⭐

std::not_fn stateless return type

The return type is a CopyConstructible stateless class. It is unspecified whether the return type is assignable.

Member function `operator()` 🌸

template< class... Args >
constexpr auto operator()( Args&&... args ) const             (since C++26)
    noexcept(/* see below */)
-> decltype(!std::invoke(ConstFn, std::declval<Args>()...));

Expression-equivalent to !std::invoke(ConstFn, std::forward<Args>(args)...). 💜

Exceptions

Throws no exceptions, unless the construction of fd throws. 🎀

Possible implementation

Okay bestie, this is the long part. Stay with me. 💀

(1) not_fn

namespace detail
{
    template<class V, class F, class... Args>
    constexpr bool negate_invocable_impl = false;
    template<class F, class... Args>
    constexpr bool negate_invocable_impl<std::void_t<decltype(
        !std::invoke(std::declval<F>(), std::declval<Args>()...))>,
        F, Args...> = true;

    template<class F, class... Args>
    constexpr bool negate_invocable_v = negate_invocable_impl<void, F, Args...>;

    template<class F>
    struct not_fn_t
    {
        F f;

        template<class... Args,
            std::enable_if_t<negate_invocable_v<F&, Args...>, int> = 0>
        constexpr decltype(auto) operator()(Args&&... args) &
            noexcept(noexcept(!std::invoke(f, std::forward<Args>(args)...)))
        {
            return !std::invoke(f, std::forward<Args>(args)...);
        }

        template<class... Args,
            std::enable_if_t<negate_invocable_v<const F&, Args...>, int> = 0>
        constexpr decltype(auto) operator()(Args&&... args) const&
            noexcept(noexcept(!std::invoke(f, std::forward<Args>(args)...)))
        {
            return !std::invoke(f, std::forward<Args>(args)...);
        }

        template<class... Args,
            std::enable_if_t<negate_invocable_v<F, Args...>, int> = 0>
        constexpr decltype(auto) operator()(Args&&... args) &&
            noexcept(noexcept(!std::invoke(std::move(f), std::forward<Args>(args)...)))
        {
            return !std::invoke(std::move(f), std::forward<Args>(args)...);
        }

        template<class... Args,
            std::enable_if_t<negate_invocable_v<const F, Args...>, int> = 0>
        constexpr decltype(auto) operator()(Args&&... args) const&&
            noexcept(noexcept(!std::invoke(std::move(f), std::forward<Args>(args)...)))
        {
            return !std::invoke(std::move(f), std::forward<Args>(args)...);
        }

        // Deleted overloads are needed since C++20
        // for preventing a non-equivalent but well-formed overload to be selected.

        template<class... Args,
            std::enable_if_t<!negate_invocable_v<F&, Args...>, int> = 0>
        void operator()(Args&&...) & = delete;

        template<class... Args,
            std::enable_if_t<!negate_invocable_v<const F&, Args...>, int> = 0>
        void operator()(Args&&...) const& = delete;

        template<class... Args,
            std::enable_if_t<!negate_invocable_v<F, Args...>, int> = 0>
        void operator()(Args&&...) && = delete;

        template<class... Args,
            std::enable_if_t<!negate_invocable_v<const F, Args...>, int> = 0>
        void operator()(Args&&...) const&& = delete;
    };
}

template<class F>
constexpr detail::not_fn_t<std::decay_t<F>> not_fn(F&& f)
{
    return {std::forward<F>(f)};
}

(2) not_fn

namespace detail
{
    template<auto ConstFn>
    struct stateless_not_fn
    {
        template<class... Args>
        constexpr auto operator()(Args&&... args) const
            noexcept(noexcept(!std::invoke(ConstFn, std::forward<Args>(args)...)))
            -> decltype(!std::invoke(ConstFn, std::forward<Args>(args)...))
        {
            return !std::invoke(ConstFn, std::forward<Args>(args)...);
        }
    };
}

template<auto ConstFn>
constexpr detail::stateless_not_fn<ConstFn> not_fn() noexcept
{
    if constexpr (std::is_pointer_v<decltype(ConstFn)> ||
                  std::is_member_pointer_v<decltype(ConstFn)>)
        static_assert(ConstFn != nullptr);

    return {};
}

Notes

std::not_fn is intended to replace the C++03-era negators std::not1 and std::not2. 🔥

Feature-test macro tea ☕:

__cpp_lib_not_fn — value 201603L (C++17): std::not_fn(), (1)
__cpp_lib_not_fn — value 202306L (C++26): Allow passing callable objects as non-type template arguments to std::not_fn, (2) 💅

✨ Example ✨

okay bestie, this is the part where it all clicks 💖 here's the full little program — run it, poke at it, break it, whatever — and watch std::not_fn do its one (1) job: flipping your callable's answer upside down 🙃

// Run this code

#include <cassert>
#include <functional>

bool is_same(int a, int b) noexcept
{
    return a == b;
}

struct S
{
    int val;
    bool is_same(int arg) const noexcept { return val == arg; }
};

int main()
{
    // Using with a free function:
    auto is_differ = std::not_fn(is_same);
    assert(is_differ(8, 8) == false); // equivalent to: !is_same(8, 8) == false
    assert(is_differ(6, 9) == true); // equivalent to: !is_same(8, 0) == true

    // Using with a member function:
    auto member_differ = std::not_fn(&S::is_same);
    assert(member_differ(S{3}, 3) == false); //: S tmp{6}; !tmp.is_same(6) == false

    // Noexcept-specification is preserved:
    static_assert(noexcept(is_differ) == noexcept(is_same));
    static_assert(noexcept(member_differ) == noexcept(&S::is_same));

    // Using with a function object:
    auto same = [](int a, int b) { return a == b; };
    auto differ = std::not_fn(same);
    assert(differ(1, 2) == true); //: !same(1, 2) == true
    assert(differ(2, 2) == false); //: !same(2, 2) == false

#if __cpp_lib_not_fn >= 202306L
    auto is_differ_cpp26 = std::not_fn<is_same>();
    assert(is_differ_cpp26(8, 8) == false);
    assert(is_differ_cpp26(6, 9) == true);

    auto member_differ_cpp26 = std::not_fn<&S::is_same>();
    assert(member_differ_cpp26(S{3}, 3) == false);

    auto differ_cpp26 = std::not_fn<same>();
    static_assert(differ_cpp26(1, 2) == true);
    static_assert(differ_cpp26(2, 2) == false);
#endif
}

so what's actually going down in there 👀

free function era — auto is_differ = std::not_fn(is_same); wraps the plain function is_same, and then is_differ(8, 8) gives you false (same numbers, so is_same said true, so the not-version says false — literally !is_same(8, 8) == false). and is_differ(6, 9) is true, i.e. !is_same(8, 0) == true. that's it. that's the whole personality 💅
member function era — auto member_differ = std::not_fn(&S::is_same); takes a pointer-to-member-function, and then you call it like member_differ(S{3}, 3), which comes out false, i.e. !tmp.is_same(6) == false for S tmp{6};. yes you pass the object first, it's giving very "you first, bestie" energy 🫶
noexcept glow-up — the static_asserts check that noexcept(is_differ) == noexcept(is_same) and noexcept(member_differ) == noexcept(&S::is_same). so the noexcept-ness of the original gets preserved, it does not get lost in the mail 📬✨
function object / lambda era — auto same = [](int a, int b) { return a == b; }; then auto differ = std::not_fn(same);. differ(1, 2) is true (!same(1, 2) == true) and differ(2, 2) is false (!same(2, 2) == false). iconic, no notes 🌸
C++26 era — inside #if __cpp_lib_not_fn >= 202306L, you get the fancy explicit-template-argument flavour: std::not_fn<is_same>(), std::not_fn<&S::is_same>(), and std::not_fn<same>(), with the matching asserts and static_asserts. it's the same not-fn goodness, just wearing the new outfit 👑

ngl the static_assert(differ_cpp26(1, 2) == true); bits are flexing that the call is constant-evaluable — the original literally puts it in a static_assert, so that's the vibe fr fr 🔥

👀 See also 👀

couple of ancestors you should know about, both of them very much retired 🙈

not1 — constructs a custom std::unary_negate object. it's a function template, deprecated in C++17, and removed in C++20 💀
not2 — constructs a custom std::binary_negate object. also a function template, also deprecated in C++17, also removed in C++20 💀

like… they served their purpose, they ate, and then they got yeeted. respect the elders but use std::not_fn bestie, that's the main character now 👑✨

and that's the whole page, we made it 🎀 this one came from cppreference.com, dated 2024.06.10, and it's the std::not_fn(3) page, part 2 of 2. go flip some booleans bestie, you got this 💖🦋

📦 where this page comes from

nixpkgs unstable: stdman 2024.07.05
opensuse-leap 16.0: stdman 2024.07.05-bp160.1.9 · MIT
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms