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