libcxx/include/functional

   1 // -*- C++ -*-
   2 //===----------------------------------------------------------------------===//
   3 //
   4 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
   5 // See https://llvm.org/LICENSE.txt for license information.
   6 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   7 //
   8 //===----------------------------------------------------------------------===//
   9
  10 #ifndef _LIBCPP_FUNCTIONAL
  11 #define _LIBCPP_FUNCTIONAL
  12
  13 /*
  14     functional synopsis
  15
  16 namespace std
  17 {
  18
  19 template <class Arg, class Result>
  20 struct unary_function
  21 {
  22     typedef Arg    argument_type;
  23     typedef Result result_type;
  24 };
  25
  26 template <class Arg1, class Arg2, class Result>
  27 struct binary_function
  28 {
  29     typedef Arg1   first_argument_type;
  30     typedef Arg2   second_argument_type;
  31     typedef Result result_type;
  32 };
  33
  34 template <class T>
  35 class reference_wrapper
  36     : public unary_function<T1, R> // if wrapping a unary functor
  37     : public binary_function<T1, T2, R> // if wrapping a binary functor
  38 {
  39 public:
  40     // types
  41     typedef T type;
  42     typedef see below result_type; // Not always defined
  43
  44     // construct/copy/destroy
  45     template<class U>
  46       constexpr reference_wrapper(U&&);                                   // constexpr since C++20
  47     constexpr reference_wrapper(const reference_wrapper<T>& x) noexcept;  // constexpr since C++20
  48
  49     // assignment
  50     constexpr reference_wrapper&
  51     operator=(const reference_wrapper<T>& x) noexcept;                    // constexpr since C++20
  52
  53     // access
  54     constexpr operator T& () const noexcept;                              // constexpr since C++20
  55     constexpr T& get() const noexcept;                                    // constexpr since C++20
  56
  57     // invoke
  58     template <class... ArgTypes>
  59       constexpr typename result_of<T&(ArgTypes&&...)>::type               // constexpr since C++20
  60           operator() (ArgTypes&&...) const
  61               noexcept(is_nothrow_invocable_v<T&, ArgTypes...>);          // noexcept since C++17
  62 };
  63
  64 template <class T>
  65   reference_wrapper(T&) -> reference_wrapper<T>;
  66
  67 template <class T> reference_wrapper<T> ref(T& t) noexcept;
  68 template <class T> void ref(const T&& t) = delete;
  69 template <class T> reference_wrapper<T> ref(reference_wrapper<T>t) noexcept;
  70
  71 template <class T> reference_wrapper<const T> cref(const T& t) noexcept;
  72 template <class T> void cref(const T&& t) = delete;
  73 template <class T> reference_wrapper<const T> cref(reference_wrapper<T> t) noexcept;
  74
  75 template <class T> struct unwrap_reference;                                       // since C++20
  76 template <class T> struct unwrap_ref_decay : unwrap_reference<decay_t<T>> { };    // since C++20
  77 template <class T> using unwrap_reference_t = typename unwrap_reference<T>::type; // since C++20
  78 template <class T> using unwrap_ref_decay_t = typename unwrap_ref_decay<T>::type; // since C++20
  79
  80 template <class T> // <class T=void> in C++14
  81 struct plus {
  82     T operator()(const T& x, const T& y) const;
  83 };
  84
  85 template <class T> // <class T=void> in C++14
  86 struct minus {
  87     T operator()(const T& x, const T& y) const;
  88 };
  89
  90 template <class T> // <class T=void> in C++14
  91 struct multiplies {
  92     T operator()(const T& x, const T& y) const;
  93 };
  94
  95 template <class T> // <class T=void> in C++14
  96 struct divides {
  97     T operator()(const T& x, const T& y) const;
  98 };
  99
 100 template <class T> // <class T=void> in C++14
 101 struct modulus {
 102     T operator()(const T& x, const T& y) const;
 103 };
 104
 105 template <class T> // <class T=void> in C++14
 106 struct negate {
 107     T operator()(const T& x) const;
 108 };
 109
 110 template <class T> // <class T=void> in C++14
 111 struct equal_to {
 112     bool operator()(const T& x, const T& y) const;
 113 };
 114
 115 template <class T> // <class T=void> in C++14
 116 struct not_equal_to {
 117     bool operator()(const T& x, const T& y) const;
 118 };
 119
 120 template <class T> // <class T=void> in C++14
 121 struct greater {
 122     bool operator()(const T& x, const T& y) const;
 123 };
 124
 125 template <class T> // <class T=void> in C++14
 126 struct less {
 127     bool operator()(const T& x, const T& y) const;
 128 };
 129
 130 template <class T> // <class T=void> in C++14
 131 struct greater_equal {
 132     bool operator()(const T& x, const T& y) const;
 133 };
 134
 135 template <class T> // <class T=void> in C++14
 136 struct less_equal {
 137     bool operator()(const T& x, const T& y) const;
 138 };
 139
 140 // [comparisons.three.way], class compare_three_way
 141 struct compare_three_way;
 142
 143 template <class T> // <class T=void> in C++14
 144 struct logical_and {
 145     bool operator()(const T& x, const T& y) const;
 146 };
 147
 148 template <class T> // <class T=void> in C++14
 149 struct logical_or {
 150     bool operator()(const T& x, const T& y) const;
 151 };
 152
 153 template <class T> // <class T=void> in C++14
 154 struct logical_not {
 155     bool operator()(const T& x) const;
 156 };
 157
 158 template <class T> // <class T=void> in C++14
 159 struct bit_and {
 160     T operator()(const T& x, const T& y) const;
 161 };
 162
 163 template <class T> // <class T=void> in C++14
 164 struct bit_or {
 165     T operator()(const T& x, const T& y) const;
 166 };
 167
 168 template <class T> // <class T=void> in C++14
 169 struct bit_xor {
 170     T operator()(const T& x, const T& y) const;
 171 };
 172
 173 template <class T=void> // C++14
 174 struct bit_not {
 175     T operator()(const T& x) const;
 176 };
 177
 178 struct identity; // C++20
 179
 180 template <class Predicate>
 181 class unary_negate // deprecated in C++17, removed in C++20
 182     : public unary_function<typename Predicate::argument_type, bool>
 183 {
 184 public:
 185     explicit unary_negate(const Predicate& pred);
 186     bool operator()(const typename Predicate::argument_type& x) const;
 187 };
 188
 189 template <class Predicate> // deprecated in C++17, removed in C++20
 190 unary_negate<Predicate> not1(const Predicate& pred);
 191
 192 template <class Predicate>
 193 class binary_negate // deprecated in C++17, removed in C++20
 194     : public binary_function<typename Predicate::first_argument_type,
 195                              typename Predicate::second_argument_type,
 196                              bool>
 197 {
 198 public:
 199     explicit binary_negate(const Predicate& pred);
 200     bool operator()(const typename Predicate::first_argument_type& x,
 201                     const typename Predicate::second_argument_type& y) const;
 202 };
 203
 204 template <class Predicate> // deprecated in C++17, removed in C++20
 205 binary_negate<Predicate> not2(const Predicate& pred);
 206
 207 template <class F>
 208 constexpr unspecified not_fn(F&& f); // C++17, constexpr in C++20
 209
 210 template<class T> struct is_bind_expression;
 211 template<class T> struct is_placeholder;
 212
 213     // See C++14 20.9.9, Function object binders
 214 template <class T> inline constexpr bool is_bind_expression_v
 215   = is_bind_expression<T>::value; // C++17
 216 template <class T> inline constexpr int is_placeholder_v
 217   = is_placeholder<T>::value; // C++17
 218
 219
 220 template<class Fn, class... BoundArgs>
 221   constexpr unspecified bind(Fn&&, BoundArgs&&...);  // constexpr in C++20
 222 template<class R, class Fn, class... BoundArgs>
 223   constexpr unspecified bind(Fn&&, BoundArgs&&...);  // constexpr in C++20
 224
 225 // [func.invoke]
 226 template<class F, class... Args>
 227  constexpr // constexpr in C++20
 228  invoke_result_t<F, Args...> invoke(F&& f, Args&&... args) // C++17
 229     noexcept(is_nothrow_invocable_v<F, Args...>);
 230
 231 template<class R, class F, class... Args>
 232   constexpr R invoke_r(F&& f, Args&&... args)              // C++23
 233     noexcept(is_nothrow_invocable_r_v<R, F, Args...>);
 234
 235 namespace placeholders {
 236   // M is the implementation-defined number of placeholders
 237   extern unspecified _1;
 238   extern unspecified _2;
 239   .
 240   .
 241   .
 242   extern unspecified _Mp;
 243 }
 244
 245 template <class Operation>
 246 class binder1st     // deprecated in C++11, removed in C++17
 247     : public unary_function<typename Operation::second_argument_type,
 248                             typename Operation::result_type>
 249 {
 250 protected:
 251     Operation                               op;
 252     typename Operation::first_argument_type value;
 253 public:
 254     binder1st(const Operation& x, const typename Operation::first_argument_type y);
 255     typename Operation::result_type operator()(      typename Operation::second_argument_type& x) const;
 256     typename Operation::result_type operator()(const typename Operation::second_argument_type& x) const;
 257 };
 258
 259 template <class Operation, class T>
 260 binder1st<Operation> bind1st(const Operation& op, const T& x);                  // deprecated in C++11, removed in C++17
 261
 262 template <class Operation>
 263 class binder2nd                                                                 // deprecated in C++11, removed in C++17
 264     : public unary_function<typename Operation::first_argument_type,
 265                             typename Operation::result_type>
 266 {
 267 protected:
 268     Operation                                op;
 269     typename Operation::second_argument_type value;
 270 public:
 271     binder2nd(const Operation& x, const typename Operation::second_argument_type y);
 272     typename Operation::result_type operator()(      typename Operation::first_argument_type& x) const;
 273     typename Operation::result_type operator()(const typename Operation::first_argument_type& x) const;
 274 };
 275
 276 template <class Operation, class T>
 277 binder2nd<Operation> bind2nd(const Operation& op, const T& x);                  // deprecated in C++11, removed in C++17
 278
 279 template <class Arg, class Result>                                              // deprecated in C++11, removed in C++17
 280 class pointer_to_unary_function : public unary_function<Arg, Result>
 281 {
 282 public:
 283     explicit pointer_to_unary_function(Result (*f)(Arg));
 284     Result operator()(Arg x) const;
 285 };
 286
 287 template <class Arg, class Result>
 288 pointer_to_unary_function<Arg,Result> ptr_fun(Result (*f)(Arg));                // deprecated in C++11, removed in C++17
 289
 290 template <class Arg1, class Arg2, class Result>                                 // deprecated in C++11, removed in C++17
 291 class pointer_to_binary_function : public binary_function<Arg1, Arg2, Result>
 292 {
 293 public:
 294     explicit pointer_to_binary_function(Result (*f)(Arg1, Arg2));
 295     Result operator()(Arg1 x, Arg2 y) const;
 296 };
 297
 298 template <class Arg1, class Arg2, class Result>
 299 pointer_to_binary_function<Arg1,Arg2,Result> ptr_fun(Result (*f)(Arg1,Arg2));   // deprecated in C++11, removed in C++17
 300
 301 template<class S, class T>                                                      // deprecated in C++11, removed in C++17
 302 class mem_fun_t : public unary_function<T*, S>
 303 {
 304 public:
 305     explicit mem_fun_t(S (T::*p)());
 306     S operator()(T* p) const;
 307 };
 308
 309 template<class S, class T, class A>
 310 class mem_fun1_t : public binary_function<T*, A, S>                             // deprecated in C++11, removed in C++17
 311 {
 312 public:
 313     explicit mem_fun1_t(S (T::*p)(A));
 314     S operator()(T* p, A x) const;
 315 };
 316
 317 template<class S, class T>          mem_fun_t<S,T>    mem_fun(S (T::*f)());     // deprecated in C++11, removed in C++17
 318 template<class S, class T, class A> mem_fun1_t<S,T,A> mem_fun(S (T::*f)(A));    // deprecated in C++11, removed in C++17
 319
 320 template<class S, class T>
 321 class mem_fun_ref_t : public unary_function<T, S>                               // deprecated in C++11, removed in C++17
 322 {
 323 public:
 324     explicit mem_fun_ref_t(S (T::*p)());
 325     S operator()(T& p) const;
 326 };
 327
 328 template<class S, class T, class A>
 329 class mem_fun1_ref_t : public binary_function<T, A, S>                          // deprecated in C++11, removed in C++17
 330 {
 331 public:
 332     explicit mem_fun1_ref_t(S (T::*p)(A));
 333     S operator()(T& p, A x) const;
 334 };
 335
 336 template<class S, class T>
 337 mem_fun_ref_t<S,T>    mem_fun_ref(S (T::*f)());                                 // deprecated in C++11, removed in C++17
 338 template<class S, class T, class A>
 339 mem_fun1_ref_t<S,T,A> mem_fun_ref(S (T::*f)(A));                                // deprecated in C++11, removed in C++17
 340
 341 template <class S, class T>
 342 class const_mem_fun_t : public unary_function<const T*, S>                      // deprecated in C++11, removed in C++17
 343 {
 344 public:
 345     explicit const_mem_fun_t(S (T::*p)() const);
 346     S operator()(const T* p) const;
 347 };
 348
 349 template <class S, class T, class A>
 350 class const_mem_fun1_t : public binary_function<const T*, A, S>                 // deprecated in C++11, removed in C++17
 351 {
 352 public:
 353     explicit const_mem_fun1_t(S (T::*p)(A) const);
 354     S operator()(const T* p, A x) const;
 355 };
 356
 357 template <class S, class T>
 358 const_mem_fun_t<S,T>    mem_fun(S (T::*f)() const);                             // deprecated in C++11, removed in C++17
 359 template <class S, class T, class A>
 360 const_mem_fun1_t<S,T,A> mem_fun(S (T::*f)(A) const);                            // deprecated in C++11, removed in C++17
 361
 362 template <class S, class T>
 363 class const_mem_fun_ref_t : public unary_function<T, S>                         // deprecated in C++11, removed in C++17
 364 {
 365 public:
 366     explicit const_mem_fun_ref_t(S (T::*p)() const);
 367     S operator()(const T& p) const;
 368 };
 369
 370 template <class S, class T, class A>
 371 class const_mem_fun1_ref_t : public binary_function<T, A, S>                    // deprecated in C++11, removed in C++17
 372 {
 373 public:
 374     explicit const_mem_fun1_ref_t(S (T::*p)(A) const);
 375     S operator()(const T& p, A x) const;
 376 };
 377
 378 template <class S, class T>
 379 const_mem_fun_ref_t<S,T>    mem_fun_ref(S (T::*f)() const);                     // deprecated in C++11, removed in C++17
 380 template <class S, class T, class A>
 381 const_mem_fun1_ref_t<S,T,A> mem_fun_ref(S (T::*f)(A) const);                    // deprecated in C++11, removed in C++17
 382
 383 template<class R, class T> constexpr unspecified mem_fn(R T::*);                // constexpr in C++20
 384
 385 class bad_function_call
 386     : public exception
 387 {
 388 };
 389
 390 template<class> class function; // undefined
 391
 392 template<class R, class... ArgTypes>
 393 class function<R(ArgTypes...)>
 394   : public unary_function<T1, R>      // iff sizeof...(ArgTypes) == 1 and
 395                                       // ArgTypes contains T1
 396   : public binary_function<T1, T2, R> // iff sizeof...(ArgTypes) == 2 and
 397                                       // ArgTypes contains T1 and T2
 398 {
 399 public:
 400     typedef R result_type;
 401
 402     // construct/copy/destroy:
 403     function() noexcept;
 404     function(nullptr_t) noexcept;
 405     function(const function&);
 406     function(function&&) noexcept;
 407     template<class F>
 408       function(F);
 409     template<Allocator Alloc>
 410       function(allocator_arg_t, const Alloc&) noexcept;            // removed in C++17
 411     template<Allocator Alloc>
 412       function(allocator_arg_t, const Alloc&, nullptr_t) noexcept; // removed in C++17
 413     template<Allocator Alloc>
 414       function(allocator_arg_t, const Alloc&, const function&);    // removed in C++17
 415     template<Allocator Alloc>
 416       function(allocator_arg_t, const Alloc&, function&&);         // removed in C++17
 417     template<class F, Allocator Alloc>
 418       function(allocator_arg_t, const Alloc&, F);                  // removed in C++17
 419
 420     function& operator=(const function&);
 421     function& operator=(function&&) noexcept;
 422     function& operator=(nullptr_t) noexcept;
 423     template<class F>
 424       function& operator=(F&&);
 425     template<class F>
 426       function& operator=(reference_wrapper<F>) noexcept;
 427
 428     ~function();
 429
 430     // function modifiers:
 431     void swap(function&) noexcept;
 432     template<class F, class Alloc>
 433       void assign(F&&, const Alloc&);                 // Removed in C++17
 434
 435     // function capacity:
 436     explicit operator bool() const noexcept;
 437
 438     // function invocation:
 439     R operator()(ArgTypes...) const;
 440
 441     // function target access:
 442     const std::type_info& target_type() const noexcept;
 443     template <typename T>       T* target() noexcept;
 444     template <typename T> const T* target() const noexcept;
 445 };
 446
 447 // Deduction guides
 448 template<class R, class ...Args>
 449 function(R(*)(Args...)) -> function<R(Args...)>; // since C++17
 450
 451 template<class F>
 452 function(F) -> function<see-below>; // since C++17
 453
 454 // Null pointer comparisons:
 455 template <class R, class ... ArgTypes>
 456   bool operator==(const function<R(ArgTypes...)>&, nullptr_t) noexcept;
 457
 458 template <class R, class ... ArgTypes>
 459   bool operator==(nullptr_t, const function<R(ArgTypes...)>&) noexcept; // removed in C++20
 460
 461 template <class R, class ... ArgTypes>
 462   bool operator!=(const function<R(ArgTypes...)>&, nullptr_t) noexcept; // removed in C++20
 463
 464 template <class  R, class ... ArgTypes>
 465   bool operator!=(nullptr_t, const function<R(ArgTypes...)>&) noexcept; // removed in C++20
 466
 467 // specialized algorithms:
 468 template <class  R, class ... ArgTypes>
 469   void swap(function<R(ArgTypes...)>&, function<R(ArgTypes...)>&) noexcept;
 470
 471 template <class T> struct hash;
 472
 473 template <> struct hash<bool>;
 474 template <> struct hash<char>;
 475 template <> struct hash<signed char>;
 476 template <> struct hash<unsigned char>;
 477 template <> struct hash<char8_t>; // since C++20
 478 template <> struct hash<char16_t>;
 479 template <> struct hash<char32_t>;
 480 template <> struct hash<wchar_t>;
 481 template <> struct hash<short>;
 482 template <> struct hash<unsigned short>;
 483 template <> struct hash<int>;
 484 template <> struct hash<unsigned int>;
 485 template <> struct hash<long>;
 486 template <> struct hash<long long>;
 487 template <> struct hash<unsigned long>;
 488 template <> struct hash<unsigned long long>;
 489
 490 template <> struct hash<float>;
 491 template <> struct hash<double>;
 492 template <> struct hash<long double>;
 493
 494 template<class T> struct hash<T*>;
 495 template <> struct hash<nullptr_t>;  // C++17
 496
 497 namespace ranges {
 498   // [range.cmp], concept-constrained comparisons
 499   struct equal_to;
 500   struct not_equal_to;
 501   struct greater;
 502   struct less;
 503   struct greater_equal;
 504   struct less_equal;
 505 }
 506
 507 }  // std
 508
 509 POLICY:  For non-variadic implementations, the number of arguments is limited
 510          to 3.  It is hoped that the need for non-variadic implementations
 511          will be minimal.
 512
 513 */
 514
 515 #include <__algorithm/search.h>
 516 #include <__assert> // all public C++ headers provide the assertion handler
 517 #include <__compare/compare_three_way.h>
 518 #include <__config>
 519 #include <__functional/binary_function.h>
 520 #include <__functional/binary_negate.h>
 521 #include <__functional/bind.h>
 522 #include <__functional/bind_back.h>
 523 #include <__functional/bind_front.h>
 524 #include <__functional/binder1st.h>
 525 #include <__functional/binder2nd.h>
 526 #include <__functional/boyer_moore_searcher.h>
 527 #include <__functional/compose.h>
 528 #include <__functional/default_searcher.h>
 529 #include <__functional/function.h>
 530 #include <__functional/hash.h>
 531 #include <__functional/identity.h>
 532 #include <__functional/invoke.h>
 533 #include <__functional/mem_fn.h> // TODO: deprecate
 534 #include <__functional/mem_fun_ref.h>
 535 #include <__functional/not_fn.h>
 536 #include <__functional/operations.h>
 537 #include <__functional/pointer_to_binary_function.h>
 538 #include <__functional/pointer_to_unary_function.h>
 539 #include <__functional/ranges_operations.h>
 540 #include <__functional/reference_wrapper.h>
 541 #include <__functional/unary_function.h>
 542 #include <__functional/unary_negate.h>
 543 #include <__type_traits/unwrap_ref.h>
 544 #include <__utility/forward.h>
 545 #include <version>
 546
 547 #if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)
 548 #  pragma GCC system_header
 549 #endif
 550
 551 #if !defined(_LIBCPP_REMOVE_TRANSITIVE_INCLUDES) && _LIBCPP_STD_VER <= 20
 552 #  include <atomic>
 553 #  include <concepts>
 554 #  include <cstdlib>
 555 #  include <exception>
 556 #  include <iosfwd>
 557 #  include <memory>
 558 #  include <stdexcept>
 559 #  include <tuple>
 560 #  include <type_traits>
 561 #  include <typeinfo>
 562 #  include <utility>
 563 #endif
 564
 565 #endif // _LIBCPP_FUNCTIONAL