1 // Functor implementations -*- C++ -*-
3 // Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2009, 2010,
5 // Free Software Foundation, Inc.
7 // This file is part of the GNU ISO C++ Library. This library is free
8 // software; you can redistribute it and/or modify it under the
9 // terms of the GNU General Public License as published by the
10 // Free Software Foundation; either version 3, or (at your option)
13 // This library is distributed in the hope that it will be useful,
14 // but WITHOUT ANY WARRANTY; without even the implied warranty of
15 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 // GNU General Public License for more details.
18 // Under Section 7 of GPL version 3, you are granted additional
19 // permissions described in the GCC Runtime Library Exception, version
20 // 3.1, as published by the Free Software Foundation.
22 // You should have received a copy of the GNU General Public License and
23 // a copy of the GCC Runtime Library Exception along with this program;
24 // see the files COPYING3 and COPYING.RUNTIME respectively. If not, see
25 // <http://www.gnu.org/licenses/>.
30 * Hewlett-Packard Company
32 * Permission to use, copy, modify, distribute and sell this software
33 * and its documentation for any purpose is hereby granted without fee,
34 * provided that the above copyright notice appear in all copies and
35 * that both that copyright notice and this permission notice appear
36 * in supporting documentation. Hewlett-Packard Company makes no
37 * representations about the suitability of this software for any
38 * purpose. It is provided "as is" without express or implied warranty.
41 * Copyright (c) 1996-1998
42 * Silicon Graphics Computer Systems, Inc.
44 * Permission to use, copy, modify, distribute and sell this software
45 * and its documentation for any purpose is hereby granted without fee,
46 * provided that the above copyright notice appear in all copies and
47 * that both that copyright notice and this permission notice appear
48 * in supporting documentation. Silicon Graphics makes no
49 * representations about the suitability of this software for any
50 * purpose. It is provided "as is" without express or implied warranty.
53 /** @file bits/stl_function.h
54 * This is an internal header file, included by other library headers.
55 * Do not attempt to use it directly. @headername{functional}
58 #ifndef _STL_FUNCTION_H
59 #define _STL_FUNCTION_H 1
61 namespace std _GLIBCXX_VISIBILITY(default)
63 _GLIBCXX_BEGIN_NAMESPACE_VERSION
65 // 20.3.1 base classes
66 /** @defgroup functors Function Objects
69 * Function objects, or @e functors, are objects with an @c operator()
70 * defined and accessible. They can be passed as arguments to algorithm
71 * templates and used in place of a function pointer. Not only is the
72 * resulting expressiveness of the library increased, but the generated
73 * code can be more efficient than what you might write by hand. When we
74 * refer to @a functors, then, generally we include function pointers in
75 * the description as well.
77 * Often, functors are only created as temporaries passed to algorithm
78 * calls, rather than being created as named variables.
80 * Two examples taken from the standard itself follow. To perform a
81 * by-element addition of two vectors @c a and @c b containing @c double,
82 * and put the result in @c a, use
84 * transform (a.begin(), a.end(), b.begin(), a.begin(), plus<double>());
86 * To negate every element in @c a, use
88 * transform(a.begin(), a.end(), a.begin(), negate<double>());
90 * The addition and negation functions will be inlined directly.
92 * The standard functors are derived from structs named @c unary_function
93 * and @c binary_function. These two classes contain nothing but typedefs,
94 * to aid in generic (template) programming. If you write your own
95 * functors, you might consider doing the same.
100 * This is one of the @link functors functor base classes@endlink.
102 template<typename _Arg, typename _Result>
103 struct unary_function
105 /// @c argument_type is the type of the argument
106 typedef _Arg argument_type;
108 /// @c result_type is the return type
109 typedef _Result result_type;
113 * This is one of the @link functors functor base classes@endlink.
115 template<typename _Arg1, typename _Arg2, typename _Result>
116 struct binary_function
118 /// @c first_argument_type is the type of the first argument
119 typedef _Arg1 first_argument_type;
121 /// @c second_argument_type is the type of the second argument
122 typedef _Arg2 second_argument_type;
124 /// @c result_type is the return type
125 typedef _Result result_type;
130 /** @defgroup arithmetic_functors Arithmetic Classes
133 * Because basic math often needs to be done during an algorithm,
134 * the library provides functors for those operations. See the
135 * documentation for @link functors the base classes@endlink
136 * for examples of their use.
140 /// One of the @link arithmetic_functors math functors@endlink.
141 template<typename _Tp>
142 struct plus : public binary_function<_Tp, _Tp, _Tp>
145 operator()(const _Tp& __x, const _Tp& __y) const
146 { return __x + __y; }
149 /// One of the @link arithmetic_functors math functors@endlink.
150 template<typename _Tp>
151 struct minus : public binary_function<_Tp, _Tp, _Tp>
154 operator()(const _Tp& __x, const _Tp& __y) const
155 { return __x - __y; }
158 /// One of the @link arithmetic_functors math functors@endlink.
159 template<typename _Tp>
160 struct multiplies : public binary_function<_Tp, _Tp, _Tp>
163 operator()(const _Tp& __x, const _Tp& __y) const
164 { return __x * __y; }
167 /// One of the @link arithmetic_functors math functors@endlink.
168 template<typename _Tp>
169 struct divides : public binary_function<_Tp, _Tp, _Tp>
172 operator()(const _Tp& __x, const _Tp& __y) const
173 { return __x / __y; }
176 /// One of the @link arithmetic_functors math functors@endlink.
177 template<typename _Tp>
178 struct modulus : public binary_function<_Tp, _Tp, _Tp>
181 operator()(const _Tp& __x, const _Tp& __y) const
182 { return __x % __y; }
185 /// One of the @link arithmetic_functors math functors@endlink.
186 template<typename _Tp>
187 struct negate : public unary_function<_Tp, _Tp>
190 operator()(const _Tp& __x) const
195 // 20.3.3 comparisons
196 /** @defgroup comparison_functors Comparison Classes
199 * The library provides six wrapper functors for all the basic comparisons
204 /// One of the @link comparison_functors comparison functors@endlink.
205 template<typename _Tp>
206 struct equal_to : public binary_function<_Tp, _Tp, bool>
209 operator()(const _Tp& __x, const _Tp& __y) const
210 { return __x == __y; }
213 /// One of the @link comparison_functors comparison functors@endlink.
214 template<typename _Tp>
215 struct not_equal_to : public binary_function<_Tp, _Tp, bool>
218 operator()(const _Tp& __x, const _Tp& __y) const
219 { return __x != __y; }
222 /// One of the @link comparison_functors comparison functors@endlink.
223 template<typename _Tp>
224 struct greater : public binary_function<_Tp, _Tp, bool>
227 operator()(const _Tp& __x, const _Tp& __y) const
228 { return __x > __y; }
231 /// One of the @link comparison_functors comparison functors@endlink.
232 template<typename _Tp>
233 struct less : public binary_function<_Tp, _Tp, bool>
236 operator()(const _Tp& __x, const _Tp& __y) const
237 { return __x < __y; }
240 /// One of the @link comparison_functors comparison functors@endlink.
241 template<typename _Tp>
242 struct greater_equal : public binary_function<_Tp, _Tp, bool>
245 operator()(const _Tp& __x, const _Tp& __y) const
246 { return __x >= __y; }
249 /// One of the @link comparison_functors comparison functors@endlink.
250 template<typename _Tp>
251 struct less_equal : public binary_function<_Tp, _Tp, bool>
254 operator()(const _Tp& __x, const _Tp& __y) const
255 { return __x <= __y; }
259 // 20.3.4 logical operations
260 /** @defgroup logical_functors Boolean Operations Classes
263 * Here are wrapper functors for Boolean operations: @c &&, @c ||,
268 /// One of the @link logical_functors Boolean operations functors@endlink.
269 template<typename _Tp>
270 struct logical_and : public binary_function<_Tp, _Tp, bool>
273 operator()(const _Tp& __x, const _Tp& __y) const
274 { return __x && __y; }
277 /// One of the @link logical_functors Boolean operations functors@endlink.
278 template<typename _Tp>
279 struct logical_or : public binary_function<_Tp, _Tp, bool>
282 operator()(const _Tp& __x, const _Tp& __y) const
283 { return __x || __y; }
286 /// One of the @link logical_functors Boolean operations functors@endlink.
287 template<typename _Tp>
288 struct logical_not : public unary_function<_Tp, bool>
291 operator()(const _Tp& __x) const
296 // _GLIBCXX_RESOLVE_LIB_DEFECTS
297 // DR 660. Missing Bitwise Operations.
298 template<typename _Tp>
299 struct bit_and : public binary_function<_Tp, _Tp, _Tp>
302 operator()(const _Tp& __x, const _Tp& __y) const
303 { return __x & __y; }
306 template<typename _Tp>
307 struct bit_or : public binary_function<_Tp, _Tp, _Tp>
310 operator()(const _Tp& __x, const _Tp& __y) const
311 { return __x | __y; }
314 template<typename _Tp>
315 struct bit_xor : public binary_function<_Tp, _Tp, _Tp>
318 operator()(const _Tp& __x, const _Tp& __y) const
319 { return __x ^ __y; }
323 /** @defgroup negators Negators
326 * The functions @c not1 and @c not2 each take a predicate functor
327 * and return an instance of @c unary_negate or
328 * @c binary_negate, respectively. These classes are functors whose
329 * @c operator() performs the stored predicate function and then returns
330 * the negation of the result.
332 * For example, given a vector of integers and a trivial predicate,
334 * struct IntGreaterThanThree
335 * : public std::unary_function<int, bool>
337 * bool operator() (int x) { return x > 3; }
340 * std::find_if (v.begin(), v.end(), not1(IntGreaterThanThree()));
342 * The call to @c find_if will locate the first index (i) of @c v for which
343 * <code>!(v[i] > 3)</code> is true.
345 * The not1/unary_negate combination works on predicates taking a single
346 * argument. The not2/binary_negate combination works on predicates which
347 * take two arguments.
351 /// One of the @link negators negation functors@endlink.
352 template<typename _Predicate>
354 : public unary_function<typename _Predicate::argument_type, bool>
361 unary_negate(const _Predicate& __x) : _M_pred(__x) { }
364 operator()(const typename _Predicate::argument_type& __x) const
365 { return !_M_pred(__x); }
368 /// One of the @link negators negation functors@endlink.
369 template<typename _Predicate>
370 inline unary_negate<_Predicate>
371 not1(const _Predicate& __pred)
372 { return unary_negate<_Predicate>(__pred); }
374 /// One of the @link negators negation functors@endlink.
375 template<typename _Predicate>
377 : public binary_function<typename _Predicate::first_argument_type,
378 typename _Predicate::second_argument_type, bool>
385 binary_negate(const _Predicate& __x) : _M_pred(__x) { }
388 operator()(const typename _Predicate::first_argument_type& __x,
389 const typename _Predicate::second_argument_type& __y) const
390 { return !_M_pred(__x, __y); }
393 /// One of the @link negators negation functors@endlink.
394 template<typename _Predicate>
395 inline binary_negate<_Predicate>
396 not2(const _Predicate& __pred)
397 { return binary_negate<_Predicate>(__pred); }
400 // 20.3.7 adaptors pointers functions
401 /** @defgroup pointer_adaptors Adaptors for pointers to functions
404 * The advantage of function objects over pointers to functions is that
405 * the objects in the standard library declare nested typedefs describing
406 * their argument and result types with uniform names (e.g., @c result_type
407 * from the base classes @c unary_function and @c binary_function).
408 * Sometimes those typedefs are required, not just optional.
410 * Adaptors are provided to turn pointers to unary (single-argument) and
411 * binary (double-argument) functions into function objects. The
412 * long-winded functor @c pointer_to_unary_function is constructed with a
413 * function pointer @c f, and its @c operator() called with argument @c x
414 * returns @c f(x). The functor @c pointer_to_binary_function does the same
415 * thing, but with a double-argument @c f and @c operator().
417 * The function @c ptr_fun takes a pointer-to-function @c f and constructs
418 * an instance of the appropriate functor.
422 /// One of the @link pointer_adaptors adaptors for function pointers@endlink.
423 template<typename _Arg, typename _Result>
424 class pointer_to_unary_function : public unary_function<_Arg, _Result>
427 _Result (*_M_ptr)(_Arg);
430 pointer_to_unary_function() { }
433 pointer_to_unary_function(_Result (*__x)(_Arg))
437 operator()(_Arg __x) const
438 { return _M_ptr(__x); }
441 /// One of the @link pointer_adaptors adaptors for function pointers@endlink.
442 template<typename _Arg, typename _Result>
443 inline pointer_to_unary_function<_Arg, _Result>
444 ptr_fun(_Result (*__x)(_Arg))
445 { return pointer_to_unary_function<_Arg, _Result>(__x); }
447 /// One of the @link pointer_adaptors adaptors for function pointers@endlink.
448 template<typename _Arg1, typename _Arg2, typename _Result>
449 class pointer_to_binary_function
450 : public binary_function<_Arg1, _Arg2, _Result>
453 _Result (*_M_ptr)(_Arg1, _Arg2);
456 pointer_to_binary_function() { }
459 pointer_to_binary_function(_Result (*__x)(_Arg1, _Arg2))
463 operator()(_Arg1 __x, _Arg2 __y) const
464 { return _M_ptr(__x, __y); }
467 /// One of the @link pointer_adaptors adaptors for function pointers@endlink.
468 template<typename _Arg1, typename _Arg2, typename _Result>
469 inline pointer_to_binary_function<_Arg1, _Arg2, _Result>
470 ptr_fun(_Result (*__x)(_Arg1, _Arg2))
471 { return pointer_to_binary_function<_Arg1, _Arg2, _Result>(__x); }
474 template<typename _Tp>
476 #ifndef __GXX_EXPERIMENTAL_CXX0X__
477 // unary_function itself is deprecated in C++11 and deriving from
478 // it can even be a nuisance (see PR 52942).
479 : public unary_function<_Tp,_Tp>
483 operator()(_Tp& __x) const
487 operator()(const _Tp& __x) const
491 template<typename _Pair>
493 #ifndef __GXX_EXPERIMENTAL_CXX0X__
494 : public unary_function<_Pair, typename _Pair::first_type>
497 typename _Pair::first_type&
498 operator()(_Pair& __x) const
499 { return __x.first; }
501 const typename _Pair::first_type&
502 operator()(const _Pair& __x) const
503 { return __x.first; }
505 #ifdef __GXX_EXPERIMENTAL_CXX0X__
506 template<typename _Pair2>
507 typename _Pair2::first_type&
508 operator()(_Pair2& __x) const
509 { return __x.first; }
511 template<typename _Pair2>
512 const typename _Pair2::first_type&
513 operator()(const _Pair2& __x) const
514 { return __x.first; }
518 template<typename _Pair>
520 #ifndef __GXX_EXPERIMENTAL_CXX0X__
521 : public unary_function<_Pair, typename _Pair::second_type>
524 typename _Pair::second_type&
525 operator()(_Pair& __x) const
526 { return __x.second; }
528 const typename _Pair::second_type&
529 operator()(const _Pair& __x) const
530 { return __x.second; }
533 // 20.3.8 adaptors pointers members
534 /** @defgroup memory_adaptors Adaptors for pointers to members
537 * There are a total of 8 = 2^3 function objects in this family.
538 * (1) Member functions taking no arguments vs member functions taking
540 * (2) Call through pointer vs call through reference.
541 * (3) Const vs non-const member function.
543 * All of this complexity is in the function objects themselves. You can
544 * ignore it by using the helper function mem_fun and mem_fun_ref,
545 * which create whichever type of adaptor is appropriate.
549 /// One of the @link memory_adaptors adaptors for member
550 /// pointers@endlink.
551 template<typename _Ret, typename _Tp>
552 class mem_fun_t : public unary_function<_Tp*, _Ret>
556 mem_fun_t(_Ret (_Tp::*__pf)())
560 operator()(_Tp* __p) const
561 { return (__p->*_M_f)(); }
567 /// One of the @link memory_adaptors adaptors for member
568 /// pointers@endlink.
569 template<typename _Ret, typename _Tp>
570 class const_mem_fun_t : public unary_function<const _Tp*, _Ret>
574 const_mem_fun_t(_Ret (_Tp::*__pf)() const)
578 operator()(const _Tp* __p) const
579 { return (__p->*_M_f)(); }
582 _Ret (_Tp::*_M_f)() const;
585 /// One of the @link memory_adaptors adaptors for member
586 /// pointers@endlink.
587 template<typename _Ret, typename _Tp>
588 class mem_fun_ref_t : public unary_function<_Tp, _Ret>
592 mem_fun_ref_t(_Ret (_Tp::*__pf)())
596 operator()(_Tp& __r) const
597 { return (__r.*_M_f)(); }
603 /// One of the @link memory_adaptors adaptors for member
604 /// pointers@endlink.
605 template<typename _Ret, typename _Tp>
606 class const_mem_fun_ref_t : public unary_function<_Tp, _Ret>
610 const_mem_fun_ref_t(_Ret (_Tp::*__pf)() const)
614 operator()(const _Tp& __r) const
615 { return (__r.*_M_f)(); }
618 _Ret (_Tp::*_M_f)() const;
621 /// One of the @link memory_adaptors adaptors for member
622 /// pointers@endlink.
623 template<typename _Ret, typename _Tp, typename _Arg>
624 class mem_fun1_t : public binary_function<_Tp*, _Arg, _Ret>
628 mem_fun1_t(_Ret (_Tp::*__pf)(_Arg))
632 operator()(_Tp* __p, _Arg __x) const
633 { return (__p->*_M_f)(__x); }
636 _Ret (_Tp::*_M_f)(_Arg);
639 /// One of the @link memory_adaptors adaptors for member
640 /// pointers@endlink.
641 template<typename _Ret, typename _Tp, typename _Arg>
642 class const_mem_fun1_t : public binary_function<const _Tp*, _Arg, _Ret>
646 const_mem_fun1_t(_Ret (_Tp::*__pf)(_Arg) const)
650 operator()(const _Tp* __p, _Arg __x) const
651 { return (__p->*_M_f)(__x); }
654 _Ret (_Tp::*_M_f)(_Arg) const;
657 /// One of the @link memory_adaptors adaptors for member
658 /// pointers@endlink.
659 template<typename _Ret, typename _Tp, typename _Arg>
660 class mem_fun1_ref_t : public binary_function<_Tp, _Arg, _Ret>
664 mem_fun1_ref_t(_Ret (_Tp::*__pf)(_Arg))
668 operator()(_Tp& __r, _Arg __x) const
669 { return (__r.*_M_f)(__x); }
672 _Ret (_Tp::*_M_f)(_Arg);
675 /// One of the @link memory_adaptors adaptors for member
676 /// pointers@endlink.
677 template<typename _Ret, typename _Tp, typename _Arg>
678 class const_mem_fun1_ref_t : public binary_function<_Tp, _Arg, _Ret>
682 const_mem_fun1_ref_t(_Ret (_Tp::*__pf)(_Arg) const)
686 operator()(const _Tp& __r, _Arg __x) const
687 { return (__r.*_M_f)(__x); }
690 _Ret (_Tp::*_M_f)(_Arg) const;
693 // Mem_fun adaptor helper functions. There are only two:
694 // mem_fun and mem_fun_ref.
695 template<typename _Ret, typename _Tp>
696 inline mem_fun_t<_Ret, _Tp>
697 mem_fun(_Ret (_Tp::*__f)())
698 { return mem_fun_t<_Ret, _Tp>(__f); }
700 template<typename _Ret, typename _Tp>
701 inline const_mem_fun_t<_Ret, _Tp>
702 mem_fun(_Ret (_Tp::*__f)() const)
703 { return const_mem_fun_t<_Ret, _Tp>(__f); }
705 template<typename _Ret, typename _Tp>
706 inline mem_fun_ref_t<_Ret, _Tp>
707 mem_fun_ref(_Ret (_Tp::*__f)())
708 { return mem_fun_ref_t<_Ret, _Tp>(__f); }
710 template<typename _Ret, typename _Tp>
711 inline const_mem_fun_ref_t<_Ret, _Tp>
712 mem_fun_ref(_Ret (_Tp::*__f)() const)
713 { return const_mem_fun_ref_t<_Ret, _Tp>(__f); }
715 template<typename _Ret, typename _Tp, typename _Arg>
716 inline mem_fun1_t<_Ret, _Tp, _Arg>
717 mem_fun(_Ret (_Tp::*__f)(_Arg))
718 { return mem_fun1_t<_Ret, _Tp, _Arg>(__f); }
720 template<typename _Ret, typename _Tp, typename _Arg>
721 inline const_mem_fun1_t<_Ret, _Tp, _Arg>
722 mem_fun(_Ret (_Tp::*__f)(_Arg) const)
723 { return const_mem_fun1_t<_Ret, _Tp, _Arg>(__f); }
725 template<typename _Ret, typename _Tp, typename _Arg>
726 inline mem_fun1_ref_t<_Ret, _Tp, _Arg>
727 mem_fun_ref(_Ret (_Tp::*__f)(_Arg))
728 { return mem_fun1_ref_t<_Ret, _Tp, _Arg>(__f); }
730 template<typename _Ret, typename _Tp, typename _Arg>
731 inline const_mem_fun1_ref_t<_Ret, _Tp, _Arg>
732 mem_fun_ref(_Ret (_Tp::*__f)(_Arg) const)
733 { return const_mem_fun1_ref_t<_Ret, _Tp, _Arg>(__f); }
737 _GLIBCXX_END_NAMESPACE_VERSION
740 #if !defined(__GXX_EXPERIMENTAL_CXX0X__) || _GLIBCXX_USE_DEPRECATED
741 # include <backward/binders.h>
744 #endif /* _STL_FUNCTION_H */