1 // Functor implementations -*- C++ -*-
3 // Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2009, 2010
4 // Free Software Foundation, Inc.
6 // This file is part of the GNU ISO C++ Library. This library is free
7 // software; you can redistribute it and/or modify it under the
8 // terms of the GNU General Public License as published by the
9 // Free Software Foundation; either version 3, or (at your option)
12 // This library is distributed in the hope that it will be useful,
13 // but WITHOUT ANY WARRANTY; without even the implied warranty of
14 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 // GNU General Public License for more details.
17 // Under Section 7 of GPL version 3, you are granted additional
18 // permissions described in the GCC Runtime Library Exception, version
19 // 3.1, as published by the Free Software Foundation.
21 // You should have received a copy of the GNU General Public License and
22 // a copy of the GCC Runtime Library Exception along with this program;
23 // see the files COPYING3 and COPYING.RUNTIME respectively. If not, see
24 // <http://www.gnu.org/licenses/>.
29 * Hewlett-Packard Company
31 * Permission to use, copy, modify, distribute and sell this software
32 * and its documentation for any purpose is hereby granted without fee,
33 * provided that the above copyright notice appear in all copies and
34 * that both that copyright notice and this permission notice appear
35 * in supporting documentation. Hewlett-Packard Company makes no
36 * representations about the suitability of this software for any
37 * purpose. It is provided "as is" without express or implied warranty.
40 * Copyright (c) 1996-1998
41 * Silicon Graphics Computer Systems, Inc.
43 * Permission to use, copy, modify, distribute and sell this software
44 * and its documentation for any purpose is hereby granted without fee,
45 * provided that the above copyright notice appear in all copies and
46 * that both that copyright notice and this permission notice appear
47 * in supporting documentation. Silicon Graphics makes no
48 * representations about the suitability of this software for any
49 * purpose. It is provided "as is" without express or implied warranty.
52 /** @file stl_function.h
53 * This is an internal header file, included by other library headers.
54 * You should not attempt to use it directly.
57 #ifndef _STL_FUNCTION_H
58 #define _STL_FUNCTION_H 1
60 _GLIBCXX_BEGIN_NAMESPACE(std
)
62 // 20.3.1 base classes
63 /** @defgroup functors Function Objects
66 * Function objects, or @e functors, are objects with an @c operator()
67 * defined and accessible. They can be passed as arguments to algorithm
68 * templates and used in place of a function pointer. Not only is the
69 * resulting expressiveness of the library increased, but the generated
70 * code can be more efficient than what you might write by hand. When we
71 * refer to @a functors, then, generally we include function pointers in
72 * the description as well.
74 * Often, functors are only created as temporaries passed to algorithm
75 * calls, rather than being created as named variables.
77 * Two examples taken from the standard itself follow. To perform a
78 * by-element addition of two vectors @c a and @c b containing @c double,
79 * and put the result in @c a, use
81 * transform (a.begin(), a.end(), b.begin(), a.begin(), plus<double>());
83 * To negate every element in @c a, use
85 * transform(a.begin(), a.end(), a.begin(), negate<double>());
87 * The addition and negation functions will be inlined directly.
89 * The standard functors are derived from structs named @c unary_function
90 * and @c binary_function. These two classes contain nothing but typedefs,
91 * to aid in generic (template) programming. If you write your own
92 * functors, you might consider doing the same.
97 * This is one of the @link functors functor base classes@endlink.
99 template<typename _Arg
, typename _Result
>
100 struct unary_function
102 typedef _Arg argument_type
; ///< @c argument_type is the type of the
103 /// argument (no surprises here)
105 typedef _Result result_type
; ///< @c result_type is the return type
109 * This is one of the @link functors functor base classes@endlink.
111 template<typename _Arg1
, typename _Arg2
, typename _Result
>
112 struct binary_function
114 typedef _Arg1 first_argument_type
; ///< the type of the first argument
115 /// (no surprises here)
117 typedef _Arg2 second_argument_type
; ///< the type of the second argument
118 typedef _Result result_type
; ///< type of the return type
123 /** @defgroup arithmetic_functors Arithmetic Classes
126 * Because basic math often needs to be done during an algorithm,
127 * the library provides functors for those operations. See the
128 * documentation for @link functors the base classes@endlink
129 * for examples of their use.
133 /// One of the @link arithmetic_functors math functors@endlink.
134 template<typename _Tp
>
135 struct plus
: public binary_function
<_Tp
, _Tp
, _Tp
>
138 operator()(const _Tp
& __x
, const _Tp
& __y
) const
139 { return __x
+ __y
; }
142 /// One of the @link arithmetic_functors math functors@endlink.
143 template<typename _Tp
>
144 struct minus
: public binary_function
<_Tp
, _Tp
, _Tp
>
147 operator()(const _Tp
& __x
, const _Tp
& __y
) const
148 { return __x
- __y
; }
151 /// One of the @link arithmetic_functors math functors@endlink.
152 template<typename _Tp
>
153 struct multiplies
: public binary_function
<_Tp
, _Tp
, _Tp
>
156 operator()(const _Tp
& __x
, const _Tp
& __y
) const
157 { return __x
* __y
; }
160 /// One of the @link arithmetic_functors math functors@endlink.
161 template<typename _Tp
>
162 struct divides
: public binary_function
<_Tp
, _Tp
, _Tp
>
165 operator()(const _Tp
& __x
, const _Tp
& __y
) const
166 { return __x
/ __y
; }
169 /// One of the @link arithmetic_functors math functors@endlink.
170 template<typename _Tp
>
171 struct modulus
: public binary_function
<_Tp
, _Tp
, _Tp
>
174 operator()(const _Tp
& __x
, const _Tp
& __y
) const
175 { return __x
% __y
; }
178 /// One of the @link arithmetic_functors math functors@endlink.
179 template<typename _Tp
>
180 struct negate
: public unary_function
<_Tp
, _Tp
>
183 operator()(const _Tp
& __x
) const
188 // 20.3.3 comparisons
189 /** @defgroup comparison_functors Comparison Classes
192 * The library provides six wrapper functors for all the basic comparisons
197 /// One of the @link comparison_functors comparison functors@endlink.
198 template<typename _Tp
>
199 struct equal_to
: public binary_function
<_Tp
, _Tp
, bool>
202 operator()(const _Tp
& __x
, const _Tp
& __y
) const
203 { return __x
== __y
; }
206 /// One of the @link comparison_functors comparison functors@endlink.
207 template<typename _Tp
>
208 struct not_equal_to
: public binary_function
<_Tp
, _Tp
, bool>
211 operator()(const _Tp
& __x
, const _Tp
& __y
) const
212 { return __x
!= __y
; }
215 /// One of the @link comparison_functors comparison functors@endlink.
216 template<typename _Tp
>
217 struct greater
: public binary_function
<_Tp
, _Tp
, bool>
220 operator()(const _Tp
& __x
, const _Tp
& __y
) const
221 { return __x
> __y
; }
224 /// One of the @link comparison_functors comparison functors@endlink.
225 template<typename _Tp
>
226 struct less
: public binary_function
<_Tp
, _Tp
, bool>
229 operator()(const _Tp
& __x
, const _Tp
& __y
) const
230 { return __x
< __y
; }
233 /// One of the @link comparison_functors comparison functors@endlink.
234 template<typename _Tp
>
235 struct greater_equal
: public binary_function
<_Tp
, _Tp
, bool>
238 operator()(const _Tp
& __x
, const _Tp
& __y
) const
239 { return __x
>= __y
; }
242 /// One of the @link comparison_functors comparison functors@endlink.
243 template<typename _Tp
>
244 struct less_equal
: public binary_function
<_Tp
, _Tp
, bool>
247 operator()(const _Tp
& __x
, const _Tp
& __y
) const
248 { return __x
<= __y
; }
252 // 20.3.4 logical operations
253 /** @defgroup logical_functors Boolean Operations Classes
256 * Here are wrapper functors for Boolean operations: @c &&, @c ||,
261 /// One of the @link logical_functors Boolean operations functors@endlink.
262 template<typename _Tp
>
263 struct logical_and
: public binary_function
<_Tp
, _Tp
, bool>
266 operator()(const _Tp
& __x
, const _Tp
& __y
) const
267 { return __x
&& __y
; }
270 /// One of the @link logical_functors Boolean operations functors@endlink.
271 template<typename _Tp
>
272 struct logical_or
: public binary_function
<_Tp
, _Tp
, bool>
275 operator()(const _Tp
& __x
, const _Tp
& __y
) const
276 { return __x
|| __y
; }
279 /// One of the @link logical_functors Boolean operations functors@endlink.
280 template<typename _Tp
>
281 struct logical_not
: public unary_function
<_Tp
, bool>
284 operator()(const _Tp
& __x
) const
289 // _GLIBCXX_RESOLVE_LIB_DEFECTS
290 // DR 660. Missing Bitwise Operations.
291 template<typename _Tp
>
292 struct bit_and
: public binary_function
<_Tp
, _Tp
, _Tp
>
295 operator()(const _Tp
& __x
, const _Tp
& __y
) const
296 { return __x
& __y
; }
299 template<typename _Tp
>
300 struct bit_or
: public binary_function
<_Tp
, _Tp
, _Tp
>
303 operator()(const _Tp
& __x
, const _Tp
& __y
) const
304 { return __x
| __y
; }
307 template<typename _Tp
>
308 struct bit_xor
: public binary_function
<_Tp
, _Tp
, _Tp
>
311 operator()(const _Tp
& __x
, const _Tp
& __y
) const
312 { return __x
^ __y
; }
316 /** @defgroup negators Negators
319 * The functions @c not1 and @c not2 each take a predicate functor
320 * and return an instance of @c unary_negate or
321 * @c binary_negate, respectively. These classes are functors whose
322 * @c operator() performs the stored predicate function and then returns
323 * the negation of the result.
325 * For example, given a vector of integers and a trivial predicate,
327 * struct IntGreaterThanThree
328 * : public std::unary_function<int, bool>
330 * bool operator() (int x) { return x > 3; }
333 * std::find_if (v.begin(), v.end(), not1(IntGreaterThanThree()));
335 * The call to @c find_if will locate the first index (i) of @c v for which
336 * <code>!(v[i] > 3)</code> is true.
338 * The not1/unary_negate combination works on predicates taking a single
339 * argument. The not2/binary_negate combination works on predicates which
340 * take two arguments.
344 /// One of the @link negators negation functors@endlink.
345 template<typename _Predicate
>
347 : public unary_function
<typename
_Predicate::argument_type
, bool>
354 unary_negate(const _Predicate
& __x
) : _M_pred(__x
) { }
357 operator()(const typename
_Predicate::argument_type
& __x
) const
358 { return !_M_pred(__x
); }
361 /// One of the @link negators negation functors@endlink.
362 template<typename _Predicate
>
363 inline unary_negate
<_Predicate
>
364 not1(const _Predicate
& __pred
)
365 { return unary_negate
<_Predicate
>(__pred
); }
367 /// One of the @link negators negation functors@endlink.
368 template<typename _Predicate
>
370 : public binary_function
<typename
_Predicate::first_argument_type
,
371 typename
_Predicate::second_argument_type
, bool>
378 binary_negate(const _Predicate
& __x
) : _M_pred(__x
) { }
381 operator()(const typename
_Predicate::first_argument_type
& __x
,
382 const typename
_Predicate::second_argument_type
& __y
) const
383 { return !_M_pred(__x
, __y
); }
386 /// One of the @link negators negation functors@endlink.
387 template<typename _Predicate
>
388 inline binary_negate
<_Predicate
>
389 not2(const _Predicate
& __pred
)
390 { return binary_negate
<_Predicate
>(__pred
); }
393 // 20.3.7 adaptors pointers functions
394 /** @defgroup pointer_adaptors Adaptors for pointers to functions
397 * The advantage of function objects over pointers to functions is that
398 * the objects in the standard library declare nested typedefs describing
399 * their argument and result types with uniform names (e.g., @c result_type
400 * from the base classes @c unary_function and @c binary_function).
401 * Sometimes those typedefs are required, not just optional.
403 * Adaptors are provided to turn pointers to unary (single-argument) and
404 * binary (double-argument) functions into function objects. The
405 * long-winded functor @c pointer_to_unary_function is constructed with a
406 * function pointer @c f, and its @c operator() called with argument @c x
407 * returns @c f(x). The functor @c pointer_to_binary_function does the same
408 * thing, but with a double-argument @c f and @c operator().
410 * The function @c ptr_fun takes a pointer-to-function @c f and constructs
411 * an instance of the appropriate functor.
415 /// One of the @link pointer_adaptors adaptors for function pointers@endlink.
416 template<typename _Arg
, typename _Result
>
417 class pointer_to_unary_function
: public unary_function
<_Arg
, _Result
>
420 _Result (*_M_ptr
)(_Arg
);
423 pointer_to_unary_function() { }
426 pointer_to_unary_function(_Result (*__x
)(_Arg
))
430 operator()(_Arg __x
) const
431 { return _M_ptr(__x
); }
434 /// One of the @link pointer_adaptors adaptors for function pointers@endlink.
435 template<typename _Arg
, typename _Result
>
436 inline pointer_to_unary_function
<_Arg
, _Result
>
437 ptr_fun(_Result (*__x
)(_Arg
))
438 { return pointer_to_unary_function
<_Arg
, _Result
>(__x
); }
440 /// One of the @link pointer_adaptors adaptors for function pointers@endlink.
441 template<typename _Arg1
, typename _Arg2
, typename _Result
>
442 class pointer_to_binary_function
443 : public binary_function
<_Arg1
, _Arg2
, _Result
>
446 _Result (*_M_ptr
)(_Arg1
, _Arg2
);
449 pointer_to_binary_function() { }
452 pointer_to_binary_function(_Result (*__x
)(_Arg1
, _Arg2
))
456 operator()(_Arg1 __x
, _Arg2 __y
) const
457 { return _M_ptr(__x
, __y
); }
460 /// One of the @link pointer_adaptors adaptors for function pointers@endlink.
461 template<typename _Arg1
, typename _Arg2
, typename _Result
>
462 inline pointer_to_binary_function
<_Arg1
, _Arg2
, _Result
>
463 ptr_fun(_Result (*__x
)(_Arg1
, _Arg2
))
464 { return pointer_to_binary_function
<_Arg1
, _Arg2
, _Result
>(__x
); }
467 template<typename _Tp
>
468 struct _Identity
: public unary_function
<_Tp
,_Tp
>
471 operator()(_Tp
& __x
) const
475 operator()(const _Tp
& __x
) const
479 template<typename _Pair
>
480 struct _Select1st
: public unary_function
<_Pair
,
481 typename
_Pair::first_type
>
483 typename
_Pair::first_type
&
484 operator()(_Pair
& __x
) const
485 { return __x
.first
; }
487 const typename
_Pair::first_type
&
488 operator()(const _Pair
& __x
) const
489 { return __x
.first
; }
491 #ifdef __GXX_EXPERIMENTAL_CXX0X__
492 template<typename _Pair2
>
493 typename
_Pair2::first_type
&
494 operator()(_Pair2
& __x
) const
495 { return __x
.first
; }
497 template<typename _Pair2
>
498 const typename
_Pair2::first_type
&
499 operator()(const _Pair2
& __x
) const
500 { return __x
.first
; }
504 template<typename _Pair
>
505 struct _Select2nd
: public unary_function
<_Pair
,
506 typename
_Pair::second_type
>
508 typename
_Pair::second_type
&
509 operator()(_Pair
& __x
) const
510 { return __x
.second
; }
512 const typename
_Pair::second_type
&
513 operator()(const _Pair
& __x
) const
514 { return __x
.second
; }
517 // 20.3.8 adaptors pointers members
518 /** @defgroup memory_adaptors Adaptors for pointers to members
521 * There are a total of 8 = 2^3 function objects in this family.
522 * (1) Member functions taking no arguments vs member functions taking
524 * (2) Call through pointer vs call through reference.
525 * (3) Const vs non-const member function.
527 * All of this complexity is in the function objects themselves. You can
528 * ignore it by using the helper function mem_fun and mem_fun_ref,
529 * which create whichever type of adaptor is appropriate.
533 /// One of the @link memory_adaptors adaptors for member
534 /// pointers@endlink.
535 template<typename _Ret
, typename _Tp
>
536 class mem_fun_t
: public unary_function
<_Tp
*, _Ret
>
540 mem_fun_t(_Ret (_Tp::*__pf
)())
544 operator()(_Tp
* __p
) const
545 { return (__p
->*_M_f
)(); }
551 /// One of the @link memory_adaptors adaptors for member
552 /// pointers@endlink.
553 template<typename _Ret
, typename _Tp
>
554 class const_mem_fun_t
: public unary_function
<const _Tp
*, _Ret
>
558 const_mem_fun_t(_Ret (_Tp::*__pf
)() const)
562 operator()(const _Tp
* __p
) const
563 { return (__p
->*_M_f
)(); }
566 _Ret (_Tp::*_M_f
)() const;
569 /// One of the @link memory_adaptors adaptors for member
570 /// pointers@endlink.
571 template<typename _Ret
, typename _Tp
>
572 class mem_fun_ref_t
: public unary_function
<_Tp
, _Ret
>
576 mem_fun_ref_t(_Ret (_Tp::*__pf
)())
580 operator()(_Tp
& __r
) const
581 { return (__r
.*_M_f
)(); }
587 /// One of the @link memory_adaptors adaptors for member
588 /// pointers@endlink.
589 template<typename _Ret
, typename _Tp
>
590 class const_mem_fun_ref_t
: public unary_function
<_Tp
, _Ret
>
594 const_mem_fun_ref_t(_Ret (_Tp::*__pf
)() const)
598 operator()(const _Tp
& __r
) const
599 { return (__r
.*_M_f
)(); }
602 _Ret (_Tp::*_M_f
)() const;
605 /// One of the @link memory_adaptors adaptors for member
606 /// pointers@endlink.
607 template<typename _Ret
, typename _Tp
, typename _Arg
>
608 class mem_fun1_t
: public binary_function
<_Tp
*, _Arg
, _Ret
>
612 mem_fun1_t(_Ret (_Tp::*__pf
)(_Arg
))
616 operator()(_Tp
* __p
, _Arg __x
) const
617 { return (__p
->*_M_f
)(__x
); }
620 _Ret (_Tp::*_M_f
)(_Arg
);
623 /// One of the @link memory_adaptors adaptors for member
624 /// pointers@endlink.
625 template<typename _Ret
, typename _Tp
, typename _Arg
>
626 class const_mem_fun1_t
: public binary_function
<const _Tp
*, _Arg
, _Ret
>
630 const_mem_fun1_t(_Ret (_Tp::*__pf
)(_Arg
) const)
634 operator()(const _Tp
* __p
, _Arg __x
) const
635 { return (__p
->*_M_f
)(__x
); }
638 _Ret (_Tp::*_M_f
)(_Arg
) const;
641 /// One of the @link memory_adaptors adaptors for member
642 /// pointers@endlink.
643 template<typename _Ret
, typename _Tp
, typename _Arg
>
644 class mem_fun1_ref_t
: public binary_function
<_Tp
, _Arg
, _Ret
>
648 mem_fun1_ref_t(_Ret (_Tp::*__pf
)(_Arg
))
652 operator()(_Tp
& __r
, _Arg __x
) const
653 { return (__r
.*_M_f
)(__x
); }
656 _Ret (_Tp::*_M_f
)(_Arg
);
659 /// One of the @link memory_adaptors adaptors for member
660 /// pointers@endlink.
661 template<typename _Ret
, typename _Tp
, typename _Arg
>
662 class const_mem_fun1_ref_t
: public binary_function
<_Tp
, _Arg
, _Ret
>
666 const_mem_fun1_ref_t(_Ret (_Tp::*__pf
)(_Arg
) const)
670 operator()(const _Tp
& __r
, _Arg __x
) const
671 { return (__r
.*_M_f
)(__x
); }
674 _Ret (_Tp::*_M_f
)(_Arg
) const;
677 // Mem_fun adaptor helper functions. There are only two:
678 // mem_fun and mem_fun_ref.
679 template<typename _Ret
, typename _Tp
>
680 inline mem_fun_t
<_Ret
, _Tp
>
681 mem_fun(_Ret (_Tp::*__f
)())
682 { return mem_fun_t
<_Ret
, _Tp
>(__f
); }
684 template<typename _Ret
, typename _Tp
>
685 inline const_mem_fun_t
<_Ret
, _Tp
>
686 mem_fun(_Ret (_Tp::*__f
)() const)
687 { return const_mem_fun_t
<_Ret
, _Tp
>(__f
); }
689 template<typename _Ret
, typename _Tp
>
690 inline mem_fun_ref_t
<_Ret
, _Tp
>
691 mem_fun_ref(_Ret (_Tp::*__f
)())
692 { return mem_fun_ref_t
<_Ret
, _Tp
>(__f
); }
694 template<typename _Ret
, typename _Tp
>
695 inline const_mem_fun_ref_t
<_Ret
, _Tp
>
696 mem_fun_ref(_Ret (_Tp::*__f
)() const)
697 { return const_mem_fun_ref_t
<_Ret
, _Tp
>(__f
); }
699 template<typename _Ret
, typename _Tp
, typename _Arg
>
700 inline mem_fun1_t
<_Ret
, _Tp
, _Arg
>
701 mem_fun(_Ret (_Tp::*__f
)(_Arg
))
702 { return mem_fun1_t
<_Ret
, _Tp
, _Arg
>(__f
); }
704 template<typename _Ret
, typename _Tp
, typename _Arg
>
705 inline const_mem_fun1_t
<_Ret
, _Tp
, _Arg
>
706 mem_fun(_Ret (_Tp::*__f
)(_Arg
) const)
707 { return const_mem_fun1_t
<_Ret
, _Tp
, _Arg
>(__f
); }
709 template<typename _Ret
, typename _Tp
, typename _Arg
>
710 inline mem_fun1_ref_t
<_Ret
, _Tp
, _Arg
>
711 mem_fun_ref(_Ret (_Tp::*__f
)(_Arg
))
712 { return mem_fun1_ref_t
<_Ret
, _Tp
, _Arg
>(__f
); }
714 template<typename _Ret
, typename _Tp
, typename _Arg
>
715 inline const_mem_fun1_ref_t
<_Ret
, _Tp
, _Arg
>
716 mem_fun_ref(_Ret (_Tp::*__f
)(_Arg
) const)
717 { return const_mem_fun1_ref_t
<_Ret
, _Tp
, _Arg
>(__f
); }
721 _GLIBCXX_END_NAMESPACE
723 #if !defined(__GXX_EXPERIMENTAL_CXX0X__) || _GLIBCXX_DEPRECATED
724 # include <backward/binders.h>
727 #endif /* _STL_FUNCTION_H */