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 : public unary_function
<_Tp
,_Tp
>
479 operator()(_Tp
& __x
) const
483 operator()(const _Tp
& __x
) const
487 template<typename _Pair
>
489 : public unary_function
<_Pair
, typename
_Pair::first_type
>
491 typename
_Pair::first_type
&
492 operator()(_Pair
& __x
) const
493 { return __x
.first
; }
495 const typename
_Pair::first_type
&
496 operator()(const _Pair
& __x
) const
497 { return __x
.first
; }
499 #if __cplusplus >= 201103L
500 template<typename _Pair2
>
501 typename
_Pair2::first_type
&
502 operator()(_Pair2
& __x
) const
503 { return __x
.first
; }
505 template<typename _Pair2
>
506 const typename
_Pair2::first_type
&
507 operator()(const _Pair2
& __x
) const
508 { return __x
.first
; }
512 template<typename _Pair
>
514 : public unary_function
<_Pair
, typename
_Pair::second_type
>
516 typename
_Pair::second_type
&
517 operator()(_Pair
& __x
) const
518 { return __x
.second
; }
520 const typename
_Pair::second_type
&
521 operator()(const _Pair
& __x
) const
522 { return __x
.second
; }
525 // 20.3.8 adaptors pointers members
526 /** @defgroup memory_adaptors Adaptors for pointers to members
529 * There are a total of 8 = 2^3 function objects in this family.
530 * (1) Member functions taking no arguments vs member functions taking
532 * (2) Call through pointer vs call through reference.
533 * (3) Const vs non-const member function.
535 * All of this complexity is in the function objects themselves. You can
536 * ignore it by using the helper function mem_fun and mem_fun_ref,
537 * which create whichever type of adaptor is appropriate.
541 /// One of the @link memory_adaptors adaptors for member
542 /// pointers@endlink.
543 template<typename _Ret
, typename _Tp
>
544 class mem_fun_t
: public unary_function
<_Tp
*, _Ret
>
548 mem_fun_t(_Ret (_Tp::*__pf
)())
552 operator()(_Tp
* __p
) const
553 { return (__p
->*_M_f
)(); }
559 /// One of the @link memory_adaptors adaptors for member
560 /// pointers@endlink.
561 template<typename _Ret
, typename _Tp
>
562 class const_mem_fun_t
: public unary_function
<const _Tp
*, _Ret
>
566 const_mem_fun_t(_Ret (_Tp::*__pf
)() const)
570 operator()(const _Tp
* __p
) const
571 { return (__p
->*_M_f
)(); }
574 _Ret (_Tp::*_M_f
)() const;
577 /// One of the @link memory_adaptors adaptors for member
578 /// pointers@endlink.
579 template<typename _Ret
, typename _Tp
>
580 class mem_fun_ref_t
: public unary_function
<_Tp
, _Ret
>
584 mem_fun_ref_t(_Ret (_Tp::*__pf
)())
588 operator()(_Tp
& __r
) const
589 { return (__r
.*_M_f
)(); }
595 /// One of the @link memory_adaptors adaptors for member
596 /// pointers@endlink.
597 template<typename _Ret
, typename _Tp
>
598 class const_mem_fun_ref_t
: public unary_function
<_Tp
, _Ret
>
602 const_mem_fun_ref_t(_Ret (_Tp::*__pf
)() const)
606 operator()(const _Tp
& __r
) const
607 { return (__r
.*_M_f
)(); }
610 _Ret (_Tp::*_M_f
)() const;
613 /// One of the @link memory_adaptors adaptors for member
614 /// pointers@endlink.
615 template<typename _Ret
, typename _Tp
, typename _Arg
>
616 class mem_fun1_t
: public binary_function
<_Tp
*, _Arg
, _Ret
>
620 mem_fun1_t(_Ret (_Tp::*__pf
)(_Arg
))
624 operator()(_Tp
* __p
, _Arg __x
) const
625 { return (__p
->*_M_f
)(__x
); }
628 _Ret (_Tp::*_M_f
)(_Arg
);
631 /// One of the @link memory_adaptors adaptors for member
632 /// pointers@endlink.
633 template<typename _Ret
, typename _Tp
, typename _Arg
>
634 class const_mem_fun1_t
: public binary_function
<const _Tp
*, _Arg
, _Ret
>
638 const_mem_fun1_t(_Ret (_Tp::*__pf
)(_Arg
) const)
642 operator()(const _Tp
* __p
, _Arg __x
) const
643 { return (__p
->*_M_f
)(__x
); }
646 _Ret (_Tp::*_M_f
)(_Arg
) const;
649 /// One of the @link memory_adaptors adaptors for member
650 /// pointers@endlink.
651 template<typename _Ret
, typename _Tp
, typename _Arg
>
652 class mem_fun1_ref_t
: public binary_function
<_Tp
, _Arg
, _Ret
>
656 mem_fun1_ref_t(_Ret (_Tp::*__pf
)(_Arg
))
660 operator()(_Tp
& __r
, _Arg __x
) const
661 { return (__r
.*_M_f
)(__x
); }
664 _Ret (_Tp::*_M_f
)(_Arg
);
667 /// One of the @link memory_adaptors adaptors for member
668 /// pointers@endlink.
669 template<typename _Ret
, typename _Tp
, typename _Arg
>
670 class const_mem_fun1_ref_t
: public binary_function
<_Tp
, _Arg
, _Ret
>
674 const_mem_fun1_ref_t(_Ret (_Tp::*__pf
)(_Arg
) const)
678 operator()(const _Tp
& __r
, _Arg __x
) const
679 { return (__r
.*_M_f
)(__x
); }
682 _Ret (_Tp::*_M_f
)(_Arg
) const;
685 // Mem_fun adaptor helper functions. There are only two:
686 // mem_fun and mem_fun_ref.
687 template<typename _Ret
, typename _Tp
>
688 inline mem_fun_t
<_Ret
, _Tp
>
689 mem_fun(_Ret (_Tp::*__f
)())
690 { return mem_fun_t
<_Ret
, _Tp
>(__f
); }
692 template<typename _Ret
, typename _Tp
>
693 inline const_mem_fun_t
<_Ret
, _Tp
>
694 mem_fun(_Ret (_Tp::*__f
)() const)
695 { return const_mem_fun_t
<_Ret
, _Tp
>(__f
); }
697 template<typename _Ret
, typename _Tp
>
698 inline mem_fun_ref_t
<_Ret
, _Tp
>
699 mem_fun_ref(_Ret (_Tp::*__f
)())
700 { return mem_fun_ref_t
<_Ret
, _Tp
>(__f
); }
702 template<typename _Ret
, typename _Tp
>
703 inline const_mem_fun_ref_t
<_Ret
, _Tp
>
704 mem_fun_ref(_Ret (_Tp::*__f
)() const)
705 { return const_mem_fun_ref_t
<_Ret
, _Tp
>(__f
); }
707 template<typename _Ret
, typename _Tp
, typename _Arg
>
708 inline mem_fun1_t
<_Ret
, _Tp
, _Arg
>
709 mem_fun(_Ret (_Tp::*__f
)(_Arg
))
710 { return mem_fun1_t
<_Ret
, _Tp
, _Arg
>(__f
); }
712 template<typename _Ret
, typename _Tp
, typename _Arg
>
713 inline const_mem_fun1_t
<_Ret
, _Tp
, _Arg
>
714 mem_fun(_Ret (_Tp::*__f
)(_Arg
) const)
715 { return const_mem_fun1_t
<_Ret
, _Tp
, _Arg
>(__f
); }
717 template<typename _Ret
, typename _Tp
, typename _Arg
>
718 inline mem_fun1_ref_t
<_Ret
, _Tp
, _Arg
>
719 mem_fun_ref(_Ret (_Tp::*__f
)(_Arg
))
720 { return mem_fun1_ref_t
<_Ret
, _Tp
, _Arg
>(__f
); }
722 template<typename _Ret
, typename _Tp
, typename _Arg
>
723 inline const_mem_fun1_ref_t
<_Ret
, _Tp
, _Arg
>
724 mem_fun_ref(_Ret (_Tp::*__f
)(_Arg
) const)
725 { return const_mem_fun1_ref_t
<_Ret
, _Tp
, _Arg
>(__f
); }
729 _GLIBCXX_END_NAMESPACE_VERSION
732 #if (__cplusplus < 201103L) || _GLIBCXX_USE_DEPRECATED
733 # include <backward/binders.h>
736 #endif /* _STL_FUNCTION_H */