1 // Functor implementations -*- C++ -*-
3 // Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007
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 2, 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 // You should have received a copy of the GNU General Public License along
18 // with this library; see the file COPYING. If not, write to the Free
19 // Software Foundation, 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
22 // As a special exception, you may use this file as part of a free software
23 // library without restriction. Specifically, if other files instantiate
24 // templates or use macros or inline functions from this file, or you compile
25 // this file and link it with other files to produce an executable, this
26 // file does not by itself cause the resulting executable to be covered by
27 // the GNU General Public License. This exception does not however
28 // invalidate any other reasons why the executable file might be covered by
29 // the GNU General Public License.
34 * Hewlett-Packard Company
36 * Permission to use, copy, modify, distribute and sell this software
37 * and its documentation for any purpose is hereby granted without fee,
38 * provided that the above copyright notice appear in all copies and
39 * that both that copyright notice and this permission notice appear
40 * in supporting documentation. Hewlett-Packard Company makes no
41 * representations about the suitability of this software for any
42 * purpose. It is provided "as is" without express or implied warranty.
45 * Copyright (c) 1996-1998
46 * Silicon Graphics Computer Systems, Inc.
48 * Permission to use, copy, modify, distribute and sell this software
49 * and its documentation for any purpose is hereby granted without fee,
50 * provided that the above copyright notice appear in all copies and
51 * that both that copyright notice and this permission notice appear
52 * in supporting documentation. Silicon Graphics makes no
53 * representations about the suitability of this software for any
54 * purpose. It is provided "as is" without express or implied warranty.
57 /** @file stl_function.h
58 * This is an internal header file, included by other library headers.
59 * You should not attempt to use it directly.
62 #ifndef _STL_FUNCTION_H
63 #define _STL_FUNCTION_H 1
65 _GLIBCXX_BEGIN_NAMESPACE(std
)
67 // 20.3.1 base classes
68 /** @defgroup s20_3_1_base Functor Base Classes
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 "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 s20_3_1_base functor base classes@endlink.
102 template<typename _Arg
, typename _Result
>
103 struct unary_function
105 typedef _Arg argument_type
; ///< @c argument_type is the type of the
106 /// argument (no surprises here)
108 typedef _Result result_type
; ///< @c result_type is the return type
112 * This is one of the @link s20_3_1_base functor base classes@endlink.
114 template<typename _Arg1
, typename _Arg2
, typename _Result
>
115 struct binary_function
117 typedef _Arg1 first_argument_type
; ///< the type of the first argument
118 /// (no surprises here)
120 typedef _Arg2 second_argument_type
; ///< the type of the second argument
121 typedef _Result result_type
; ///< type of the return type
126 /** @defgroup s20_3_2_arithmetic Arithmetic Classes
128 * Because basic math often needs to be done during an algorithm,
129 * the library provides functors for those operations. See the
130 * documentation for @link s20_3_1_base the base classes@endlink
131 * for examples of their use.
135 /// One of the @link s20_3_2_arithmetic math functors@endlink.
136 template<typename _Tp
>
137 struct plus
: public binary_function
<_Tp
, _Tp
, _Tp
>
140 operator()(const _Tp
& __x
, const _Tp
& __y
) const
141 { return __x
+ __y
; }
144 /// One of the @link s20_3_2_arithmetic math functors@endlink.
145 template<typename _Tp
>
146 struct minus
: public binary_function
<_Tp
, _Tp
, _Tp
>
149 operator()(const _Tp
& __x
, const _Tp
& __y
) const
150 { return __x
- __y
; }
153 /// One of the @link s20_3_2_arithmetic math functors@endlink.
154 template<typename _Tp
>
155 struct multiplies
: public binary_function
<_Tp
, _Tp
, _Tp
>
158 operator()(const _Tp
& __x
, const _Tp
& __y
) const
159 { return __x
* __y
; }
162 /// One of the @link s20_3_2_arithmetic math functors@endlink.
163 template<typename _Tp
>
164 struct divides
: public binary_function
<_Tp
, _Tp
, _Tp
>
167 operator()(const _Tp
& __x
, const _Tp
& __y
) const
168 { return __x
/ __y
; }
171 /// One of the @link s20_3_2_arithmetic math functors@endlink.
172 template<typename _Tp
>
173 struct modulus
: public binary_function
<_Tp
, _Tp
, _Tp
>
176 operator()(const _Tp
& __x
, const _Tp
& __y
) const
177 { return __x
% __y
; }
180 /// One of the @link s20_3_2_arithmetic math functors@endlink.
181 template<typename _Tp
>
182 struct negate
: public unary_function
<_Tp
, _Tp
>
185 operator()(const _Tp
& __x
) const
190 // 20.3.3 comparisons
191 /** @defgroup s20_3_3_comparisons Comparison Classes
192 * The library provides six wrapper functors for all the basic comparisons
197 /// One of the @link s20_3_3_comparisons 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 s20_3_3_comparisons 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 s20_3_3_comparisons 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 s20_3_3_comparisons 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 s20_3_3_comparisons 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 s20_3_3_comparisons 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 s20_3_4_logical Boolean Operations Classes
254 * Here are wrapper functors for Boolean operations: @c &&, @c ||,
259 /// One of the @link s20_3_4_logical Boolean operations functors@endlink.
260 template<typename _Tp
>
261 struct logical_and
: public binary_function
<_Tp
, _Tp
, bool>
264 operator()(const _Tp
& __x
, const _Tp
& __y
) const
265 { return __x
&& __y
; }
268 /// One of the @link s20_3_4_logical Boolean operations functors@endlink.
269 template<typename _Tp
>
270 struct logical_or
: public binary_function
<_Tp
, _Tp
, bool>
273 operator()(const _Tp
& __x
, const _Tp
& __y
) const
274 { return __x
|| __y
; }
277 /// One of the @link s20_3_4_logical Boolean operations functors@endlink.
278 template<typename _Tp
>
279 struct logical_not
: public unary_function
<_Tp
, bool>
282 operator()(const _Tp
& __x
) const
287 // _GLIBCXX_RESOLVE_LIB_DEFECTS
288 // DR 660. Missing Bitwise Operations.
289 template<typename _Tp
>
290 struct bit_and
: public binary_function
<_Tp
, _Tp
, _Tp
>
293 operator()(const _Tp
& __x
, const _Tp
& __y
) const
294 { return __x
& __y
; }
297 template<typename _Tp
>
298 struct bit_or
: public binary_function
<_Tp
, _Tp
, _Tp
>
301 operator()(const _Tp
& __x
, const _Tp
& __y
) const
302 { return __x
| __y
; }
305 template<typename _Tp
>
306 struct bit_xor
: public binary_function
<_Tp
, _Tp
, _Tp
>
309 operator()(const _Tp
& __x
, const _Tp
& __y
) const
310 { return __x
^ __y
; }
314 /** @defgroup s20_3_5_negators Negators
315 * The functions @c not1 and @c not2 each take a predicate functor
316 * and return an instance of @c unary_negate or
317 * @c binary_negate, respectively. These classes are functors whose
318 * @c operator() performs the stored predicate function and then returns
319 * the negation of the result.
321 * For example, given a vector of integers and a trivial predicate,
323 * struct IntGreaterThanThree
324 * : public std::unary_function<int, bool>
326 * bool operator() (int x) { return x > 3; }
329 * std::find_if (v.begin(), v.end(), not1(IntGreaterThanThree()));
331 * The call to @c find_if will locate the first index (i) of @c v for which
332 * "!(v[i] > 3)" is true.
334 * The not1/unary_negate combination works on predicates taking a single
335 * argument. The not2/binary_negate combination works on predicates which
336 * take two arguments.
340 /// One of the @link s20_3_5_negators negation functors@endlink.
341 template<typename _Predicate
>
343 : public unary_function
<typename
_Predicate::argument_type
, bool>
350 unary_negate(const _Predicate
& __x
) : _M_pred(__x
) { }
353 operator()(const typename
_Predicate::argument_type
& __x
) const
354 { return !_M_pred(__x
); }
357 /// One of the @link s20_3_5_negators negation functors@endlink.
358 template<typename _Predicate
>
359 inline unary_negate
<_Predicate
>
360 not1(const _Predicate
& __pred
)
361 { return unary_negate
<_Predicate
>(__pred
); }
363 /// One of the @link s20_3_5_negators negation functors@endlink.
364 template<typename _Predicate
>
366 : public binary_function
<typename
_Predicate::first_argument_type
,
367 typename
_Predicate::second_argument_type
, bool>
374 binary_negate(const _Predicate
& __x
) : _M_pred(__x
) { }
377 operator()(const typename
_Predicate::first_argument_type
& __x
,
378 const typename
_Predicate::second_argument_type
& __y
) const
379 { return !_M_pred(__x
, __y
); }
382 /// One of the @link s20_3_5_negators negation functors@endlink.
383 template<typename _Predicate
>
384 inline binary_negate
<_Predicate
>
385 not2(const _Predicate
& __pred
)
386 { return binary_negate
<_Predicate
>(__pred
); }
389 // 20.3.7 adaptors pointers functions
390 /** @defgroup s20_3_7_adaptors Adaptors for pointers to functions
391 * The advantage of function objects over pointers to functions is that
392 * the objects in the standard library declare nested typedefs describing
393 * their argument and result types with uniform names (e.g., @c result_type
394 * from the base classes @c unary_function and @c binary_function).
395 * Sometimes those typedefs are required, not just optional.
397 * Adaptors are provided to turn pointers to unary (single-argument) and
398 * binary (double-argument) functions into function objects. The
399 * long-winded functor @c pointer_to_unary_function is constructed with a
400 * function pointer @c f, and its @c operator() called with argument @c x
401 * returns @c f(x). The functor @c pointer_to_binary_function does the same
402 * thing, but with a double-argument @c f and @c operator().
404 * The function @c ptr_fun takes a pointer-to-function @c f and constructs
405 * an instance of the appropriate functor.
409 /// One of the @link s20_3_7_adaptors adaptors for function pointers@endlink.
410 template<typename _Arg
, typename _Result
>
411 class pointer_to_unary_function
: public unary_function
<_Arg
, _Result
>
414 _Result (*_M_ptr
)(_Arg
);
417 pointer_to_unary_function() { }
420 pointer_to_unary_function(_Result (*__x
)(_Arg
))
424 operator()(_Arg __x
) const
425 { return _M_ptr(__x
); }
428 /// One of the @link s20_3_7_adaptors adaptors for function pointers@endlink.
429 template<typename _Arg
, typename _Result
>
430 inline pointer_to_unary_function
<_Arg
, _Result
>
431 ptr_fun(_Result (*__x
)(_Arg
))
432 { return pointer_to_unary_function
<_Arg
, _Result
>(__x
); }
434 /// One of the @link s20_3_7_adaptors adaptors for function pointers@endlink.
435 template<typename _Arg1
, typename _Arg2
, typename _Result
>
436 class pointer_to_binary_function
437 : public binary_function
<_Arg1
, _Arg2
, _Result
>
440 _Result (*_M_ptr
)(_Arg1
, _Arg2
);
443 pointer_to_binary_function() { }
446 pointer_to_binary_function(_Result (*__x
)(_Arg1
, _Arg2
))
450 operator()(_Arg1 __x
, _Arg2 __y
) const
451 { return _M_ptr(__x
, __y
); }
454 /// One of the @link s20_3_7_adaptors adaptors for function pointers@endlink.
455 template<typename _Arg1
, typename _Arg2
, typename _Result
>
456 inline pointer_to_binary_function
<_Arg1
, _Arg2
, _Result
>
457 ptr_fun(_Result (*__x
)(_Arg1
, _Arg2
))
458 { return pointer_to_binary_function
<_Arg1
, _Arg2
, _Result
>(__x
); }
461 template<typename _Tp
>
462 struct _Identity
: public unary_function
<_Tp
,_Tp
>
465 operator()(_Tp
& __x
) const
469 operator()(const _Tp
& __x
) const
473 template<typename _Pair
>
474 struct _Select1st
: public unary_function
<_Pair
,
475 typename
_Pair::first_type
>
477 typename
_Pair::first_type
&
478 operator()(_Pair
& __x
) const
479 { return __x
.first
; }
481 const typename
_Pair::first_type
&
482 operator()(const _Pair
& __x
) const
483 { return __x
.first
; }
486 template<typename _Pair
>
487 struct _Select2nd
: public unary_function
<_Pair
,
488 typename
_Pair::second_type
>
490 typename
_Pair::second_type
&
491 operator()(_Pair
& __x
) const
492 { return __x
.second
; }
494 const typename
_Pair::second_type
&
495 operator()(const _Pair
& __x
) const
496 { return __x
.second
; }
499 // 20.3.8 adaptors pointers members
500 /** @defgroup s20_3_8_memadaptors Adaptors for pointers to members
501 * There are a total of 8 = 2^3 function objects in this family.
502 * (1) Member functions taking no arguments vs member functions taking
504 * (2) Call through pointer vs call through reference.
505 * (3) Const vs non-const member function.
507 * All of this complexity is in the function objects themselves. You can
508 * ignore it by using the helper function mem_fun and mem_fun_ref,
509 * which create whichever type of adaptor is appropriate.
513 /// One of the @link s20_3_8_memadaptors adaptors for member
514 /// pointers@endlink.
515 template<typename _Ret
, typename _Tp
>
516 class mem_fun_t
: public unary_function
<_Tp
*, _Ret
>
520 mem_fun_t(_Ret (_Tp::*__pf
)())
524 operator()(_Tp
* __p
) const
525 { return (__p
->*_M_f
)(); }
531 /// One of the @link s20_3_8_memadaptors adaptors for member
532 /// pointers@endlink.
533 template<typename _Ret
, typename _Tp
>
534 class const_mem_fun_t
: public unary_function
<const _Tp
*, _Ret
>
538 const_mem_fun_t(_Ret (_Tp::*__pf
)() const)
542 operator()(const _Tp
* __p
) const
543 { return (__p
->*_M_f
)(); }
546 _Ret (_Tp::*_M_f
)() const;
549 /// One of the @link s20_3_8_memadaptors adaptors for member
550 /// pointers@endlink.
551 template<typename _Ret
, typename _Tp
>
552 class mem_fun_ref_t
: public unary_function
<_Tp
, _Ret
>
556 mem_fun_ref_t(_Ret (_Tp::*__pf
)())
560 operator()(_Tp
& __r
) const
561 { return (__r
.*_M_f
)(); }
567 /// One of the @link s20_3_8_memadaptors adaptors for member
568 /// pointers@endlink.
569 template<typename _Ret
, typename _Tp
>
570 class const_mem_fun_ref_t
: public unary_function
<_Tp
, _Ret
>
574 const_mem_fun_ref_t(_Ret (_Tp::*__pf
)() const)
578 operator()(const _Tp
& __r
) const
579 { return (__r
.*_M_f
)(); }
582 _Ret (_Tp::*_M_f
)() const;
585 /// One of the @link s20_3_8_memadaptors adaptors for member
586 /// pointers@endlink.
587 template<typename _Ret
, typename _Tp
, typename _Arg
>
588 class mem_fun1_t
: public binary_function
<_Tp
*, _Arg
, _Ret
>
592 mem_fun1_t(_Ret (_Tp::*__pf
)(_Arg
))
596 operator()(_Tp
* __p
, _Arg __x
) const
597 { return (__p
->*_M_f
)(__x
); }
600 _Ret (_Tp::*_M_f
)(_Arg
);
603 /// One of the @link s20_3_8_memadaptors adaptors for member
604 /// pointers@endlink.
605 template<typename _Ret
, typename _Tp
, typename _Arg
>
606 class const_mem_fun1_t
: public binary_function
<const _Tp
*, _Arg
, _Ret
>
610 const_mem_fun1_t(_Ret (_Tp::*__pf
)(_Arg
) const)
614 operator()(const _Tp
* __p
, _Arg __x
) const
615 { return (__p
->*_M_f
)(__x
); }
618 _Ret (_Tp::*_M_f
)(_Arg
) const;
621 /// One of the @link s20_3_8_memadaptors adaptors for member
622 /// pointers@endlink.
623 template<typename _Ret
, typename _Tp
, typename _Arg
>
624 class mem_fun1_ref_t
: public binary_function
<_Tp
, _Arg
, _Ret
>
628 mem_fun1_ref_t(_Ret (_Tp::*__pf
)(_Arg
))
632 operator()(_Tp
& __r
, _Arg __x
) const
633 { return (__r
.*_M_f
)(__x
); }
636 _Ret (_Tp::*_M_f
)(_Arg
);
639 /// One of the @link s20_3_8_memadaptors adaptors for member
640 /// pointers@endlink.
641 template<typename _Ret
, typename _Tp
, typename _Arg
>
642 class const_mem_fun1_ref_t
: public binary_function
<_Tp
, _Arg
, _Ret
>
646 const_mem_fun1_ref_t(_Ret (_Tp::*__pf
)(_Arg
) const)
650 operator()(const _Tp
& __r
, _Arg __x
) const
651 { return (__r
.*_M_f
)(__x
); }
654 _Ret (_Tp::*_M_f
)(_Arg
) const;
657 // Mem_fun adaptor helper functions. There are only two:
658 // mem_fun and mem_fun_ref.
659 template<typename _Ret
, typename _Tp
>
660 inline mem_fun_t
<_Ret
, _Tp
>
661 mem_fun(_Ret (_Tp::*__f
)())
662 { return mem_fun_t
<_Ret
, _Tp
>(__f
); }
664 template<typename _Ret
, typename _Tp
>
665 inline const_mem_fun_t
<_Ret
, _Tp
>
666 mem_fun(_Ret (_Tp::*__f
)() const)
667 { return const_mem_fun_t
<_Ret
, _Tp
>(__f
); }
669 template<typename _Ret
, typename _Tp
>
670 inline mem_fun_ref_t
<_Ret
, _Tp
>
671 mem_fun_ref(_Ret (_Tp::*__f
)())
672 { return mem_fun_ref_t
<_Ret
, _Tp
>(__f
); }
674 template<typename _Ret
, typename _Tp
>
675 inline const_mem_fun_ref_t
<_Ret
, _Tp
>
676 mem_fun_ref(_Ret (_Tp::*__f
)() const)
677 { return const_mem_fun_ref_t
<_Ret
, _Tp
>(__f
); }
679 template<typename _Ret
, typename _Tp
, typename _Arg
>
680 inline mem_fun1_t
<_Ret
, _Tp
, _Arg
>
681 mem_fun(_Ret (_Tp::*__f
)(_Arg
))
682 { return mem_fun1_t
<_Ret
, _Tp
, _Arg
>(__f
); }
684 template<typename _Ret
, typename _Tp
, typename _Arg
>
685 inline const_mem_fun1_t
<_Ret
, _Tp
, _Arg
>
686 mem_fun(_Ret (_Tp::*__f
)(_Arg
) const)
687 { return const_mem_fun1_t
<_Ret
, _Tp
, _Arg
>(__f
); }
689 template<typename _Ret
, typename _Tp
, typename _Arg
>
690 inline mem_fun1_ref_t
<_Ret
, _Tp
, _Arg
>
691 mem_fun_ref(_Ret (_Tp::*__f
)(_Arg
))
692 { return mem_fun1_ref_t
<_Ret
, _Tp
, _Arg
>(__f
); }
694 template<typename _Ret
, typename _Tp
, typename _Arg
>
695 inline const_mem_fun1_ref_t
<_Ret
, _Tp
, _Arg
>
696 mem_fun_ref(_Ret (_Tp::*__f
)(_Arg
) const)
697 { return const_mem_fun1_ref_t
<_Ret
, _Tp
, _Arg
>(__f
); }
701 _GLIBCXX_END_NAMESPACE
703 #if !defined(__GXX_EXPERIMENTAL_CXX0X__) || _GLIBCXX_DEPRECATED
704 # include <backward/binders.h>
707 #endif /* _STL_FUNCTION_H */