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