1 // Iterators -*- C++ -*-
3 // Copyright (C) 2001, 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
5 // This file is part of the GNU ISO C++ Library. This library is free
6 // software; you can redistribute it and/or modify it under the
7 // terms of the GNU General Public License as published by the
8 // Free Software Foundation; either version 2, or (at your option)
11 // This library is distributed in the hope that it will be useful,
12 // but WITHOUT ANY WARRANTY; without even the implied warranty of
13 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 // GNU General Public License for more details.
16 // You should have received a copy of the GNU General Public License along
17 // with this library; see the file COPYING. If not, write to the Free
18 // Software Foundation, 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
21 // As a special exception, you may use this file as part of a free software
22 // library without restriction. Specifically, if other files instantiate
23 // templates or use macros or inline functions from this file, or you compile
24 // this file and link it with other files to produce an executable, this
25 // file does not by itself cause the resulting executable to be covered by
26 // the GNU General Public License. This exception does not however
27 // invalidate any other reasons why the executable file might be covered by
28 // the GNU General Public License.
33 * Hewlett-Packard Company
35 * Permission to use, copy, modify, distribute and sell this software
36 * and its documentation for any purpose is hereby granted without fee,
37 * provided that the above copyright notice appear in all copies and
38 * that both that copyright notice and this permission notice appear
39 * in supporting documentation. Hewlett-Packard Company makes no
40 * representations about the suitability of this software for any
41 * purpose. It is provided "as is" without express or implied warranty.
44 * Copyright (c) 1996-1998
45 * Silicon Graphics Computer Systems, Inc.
47 * Permission to use, copy, modify, distribute and sell this software
48 * and its documentation for any purpose is hereby granted without fee,
49 * provided that the above copyright notice appear in all copies and
50 * that both that copyright notice and this permission notice appear
51 * in supporting documentation. Silicon Graphics makes no
52 * representations about the suitability of this software for any
53 * purpose. It is provided "as is" without express or implied warranty.
56 /** @file stl_iterator.h
57 * This is an internal header file, included by other library headers.
58 * You should not attempt to use it directly.
60 * This file implements reverse_iterator, back_insert_iterator,
61 * front_insert_iterator, insert_iterator, __normal_iterator, and their
62 * supporting functions and overloaded operators.
68 #include <bits/cpp_type_traits.h>
70 _GLIBCXX_BEGIN_NAMESPACE(std
)
72 // 24.4.1 Reverse iterators
74 * "Bidirectional and random access iterators have corresponding reverse
75 * %iterator adaptors that iterate through the data structure in the
76 * opposite direction. They have the same signatures as the corresponding
77 * iterators. The fundamental relation between a reverse %iterator and its
78 * corresponding %iterator @c i is established by the identity:
80 * &*(reverse_iterator(i)) == &*(i - 1)
83 * This mapping is dictated by the fact that while there is always a
84 * pointer past the end of an array, there might not be a valid pointer
85 * before the beginning of an array." [24.4.1]/1,2
87 * Reverse iterators can be tricky and surprising at first. Their
88 * semantics make sense, however, and the trickiness is a side effect of
89 * the requirement that the iterators must be safe.
91 template<typename _Iterator
>
92 class reverse_iterator
93 : public iterator
<typename iterator_traits
<_Iterator
>::iterator_category
,
94 typename iterator_traits
<_Iterator
>::value_type
,
95 typename iterator_traits
<_Iterator
>::difference_type
,
96 typename iterator_traits
<_Iterator
>::pointer
,
97 typename iterator_traits
<_Iterator
>::reference
>
103 typedef _Iterator iterator_type
;
104 typedef typename iterator_traits
<_Iterator
>::difference_type
106 typedef typename iterator_traits
<_Iterator
>::reference reference
;
107 typedef typename iterator_traits
<_Iterator
>::pointer pointer
;
111 * The default constructor default-initializes member @p current.
112 * If it is a pointer, that means it is zero-initialized.
114 // _GLIBCXX_RESOLVE_LIB_DEFECTS
115 // 235 No specification of default ctor for reverse_iterator
116 reverse_iterator() : current() { }
119 * This %iterator will move in the opposite direction that @p x does.
122 reverse_iterator(iterator_type __x
) : current(__x
) { }
125 * The copy constructor is normal.
127 reverse_iterator(const reverse_iterator
& __x
)
128 : current(__x
.current
) { }
131 * A reverse_iterator across other types can be copied in the normal
134 template<typename _Iter
>
135 reverse_iterator(const reverse_iterator
<_Iter
>& __x
)
136 : current(__x
.base()) { }
139 * @return @c current, the %iterator used for underlying work.
153 _Iterator __tmp
= current
;
164 { return &(operator*()); }
186 reverse_iterator __tmp
= *this;
211 reverse_iterator __tmp
= *this;
222 operator+(difference_type __n
) const
223 { return reverse_iterator(current
- __n
); }
231 operator+=(difference_type __n
)
243 operator-(difference_type __n
) const
244 { return reverse_iterator(current
+ __n
); }
252 operator-=(difference_type __n
)
264 operator[](difference_type __n
) const
265 { return *(*this + __n
); }
270 * @param x A %reverse_iterator.
271 * @param y A %reverse_iterator.
272 * @return A simple bool.
274 * Reverse iterators forward many operations to their underlying base()
275 * iterators. Others are implemented in terms of one another.
278 template<typename _Iterator
>
280 operator==(const reverse_iterator
<_Iterator
>& __x
,
281 const reverse_iterator
<_Iterator
>& __y
)
282 { return __x
.base() == __y
.base(); }
284 template<typename _Iterator
>
286 operator<(const reverse_iterator
<_Iterator
>& __x
,
287 const reverse_iterator
<_Iterator
>& __y
)
288 { return __y
.base() < __x
.base(); }
290 template<typename _Iterator
>
292 operator!=(const reverse_iterator
<_Iterator
>& __x
,
293 const reverse_iterator
<_Iterator
>& __y
)
294 { return !(__x
== __y
); }
296 template<typename _Iterator
>
298 operator>(const reverse_iterator
<_Iterator
>& __x
,
299 const reverse_iterator
<_Iterator
>& __y
)
300 { return __y
< __x
; }
302 template<typename _Iterator
>
304 operator<=(const reverse_iterator
<_Iterator
>& __x
,
305 const reverse_iterator
<_Iterator
>& __y
)
306 { return !(__y
< __x
); }
308 template<typename _Iterator
>
310 operator>=(const reverse_iterator
<_Iterator
>& __x
,
311 const reverse_iterator
<_Iterator
>& __y
)
312 { return !(__x
< __y
); }
314 template<typename _Iterator
>
315 inline typename reverse_iterator
<_Iterator
>::difference_type
316 operator-(const reverse_iterator
<_Iterator
>& __x
,
317 const reverse_iterator
<_Iterator
>& __y
)
318 { return __y
.base() - __x
.base(); }
320 template<typename _Iterator
>
321 inline reverse_iterator
<_Iterator
>
322 operator+(typename reverse_iterator
<_Iterator
>::difference_type __n
,
323 const reverse_iterator
<_Iterator
>& __x
)
324 { return reverse_iterator
<_Iterator
>(__x
.base() - __n
); }
326 // _GLIBCXX_RESOLVE_LIB_DEFECTS
327 // DR 280. Comparison of reverse_iterator to const reverse_iterator.
328 template<typename _IteratorL
, typename _IteratorR
>
330 operator==(const reverse_iterator
<_IteratorL
>& __x
,
331 const reverse_iterator
<_IteratorR
>& __y
)
332 { return __x
.base() == __y
.base(); }
334 template<typename _IteratorL
, typename _IteratorR
>
336 operator<(const reverse_iterator
<_IteratorL
>& __x
,
337 const reverse_iterator
<_IteratorR
>& __y
)
338 { return __y
.base() < __x
.base(); }
340 template<typename _IteratorL
, typename _IteratorR
>
342 operator!=(const reverse_iterator
<_IteratorL
>& __x
,
343 const reverse_iterator
<_IteratorR
>& __y
)
344 { return !(__x
== __y
); }
346 template<typename _IteratorL
, typename _IteratorR
>
348 operator>(const reverse_iterator
<_IteratorL
>& __x
,
349 const reverse_iterator
<_IteratorR
>& __y
)
350 { return __y
< __x
; }
352 template<typename _IteratorL
, typename _IteratorR
>
354 operator<=(const reverse_iterator
<_IteratorL
>& __x
,
355 const reverse_iterator
<_IteratorR
>& __y
)
356 { return !(__y
< __x
); }
358 template<typename _IteratorL
, typename _IteratorR
>
360 operator>=(const reverse_iterator
<_IteratorL
>& __x
,
361 const reverse_iterator
<_IteratorR
>& __y
)
362 { return !(__x
< __y
); }
364 template<typename _IteratorL
, typename _IteratorR
>
365 inline typename reverse_iterator
<_IteratorL
>::difference_type
366 operator-(const reverse_iterator
<_IteratorL
>& __x
,
367 const reverse_iterator
<_IteratorR
>& __y
)
368 { return __y
.base() - __x
.base(); }
371 // 24.4.2.2.1 back_insert_iterator
373 * @brief Turns assignment into insertion.
375 * These are output iterators, constructed from a container-of-T.
376 * Assigning a T to the iterator appends it to the container using
379 * Tip: Using the back_inserter function to create these iterators can
382 template<typename _Container
>
383 class back_insert_iterator
384 : public iterator
<output_iterator_tag
, void, void, void, void>
387 _Container
* container
;
390 /// A nested typedef for the type of whatever container you used.
391 typedef _Container container_type
;
393 /// The only way to create this %iterator is with a container.
395 back_insert_iterator(_Container
& __x
) : container(&__x
) { }
398 * @param value An instance of whatever type
399 * container_type::const_reference is; presumably a
400 * reference-to-const T for container<T>.
401 * @return This %iterator, for chained operations.
403 * This kind of %iterator doesn't really have a "position" in the
404 * container (you can think of the position as being permanently at
405 * the end, if you like). Assigning a value to the %iterator will
406 * always append the value to the end of the container.
408 back_insert_iterator
&
409 operator=(typename
_Container::const_reference __value
)
411 container
->push_back(__value
);
415 /// Simply returns *this.
416 back_insert_iterator
&
420 /// Simply returns *this. (This %iterator does not "move".)
421 back_insert_iterator
&
425 /// Simply returns *this. (This %iterator does not "move".)
432 * @param x A container of arbitrary type.
433 * @return An instance of back_insert_iterator working on @p x.
435 * This wrapper function helps in creating back_insert_iterator instances.
436 * Typing the name of the %iterator requires knowing the precise full
437 * type of the container, which can be tedious and impedes generic
438 * programming. Using this function lets you take advantage of automatic
439 * template parameter deduction, making the compiler match the correct
442 template<typename _Container
>
443 inline back_insert_iterator
<_Container
>
444 back_inserter(_Container
& __x
)
445 { return back_insert_iterator
<_Container
>(__x
); }
448 * @brief Turns assignment into insertion.
450 * These are output iterators, constructed from a container-of-T.
451 * Assigning a T to the iterator prepends it to the container using
454 * Tip: Using the front_inserter function to create these iterators can
457 template<typename _Container
>
458 class front_insert_iterator
459 : public iterator
<output_iterator_tag
, void, void, void, void>
462 _Container
* container
;
465 /// A nested typedef for the type of whatever container you used.
466 typedef _Container container_type
;
468 /// The only way to create this %iterator is with a container.
469 explicit front_insert_iterator(_Container
& __x
) : container(&__x
) { }
472 * @param value An instance of whatever type
473 * container_type::const_reference is; presumably a
474 * reference-to-const T for container<T>.
475 * @return This %iterator, for chained operations.
477 * This kind of %iterator doesn't really have a "position" in the
478 * container (you can think of the position as being permanently at
479 * the front, if you like). Assigning a value to the %iterator will
480 * always prepend the value to the front of the container.
482 front_insert_iterator
&
483 operator=(typename
_Container::const_reference __value
)
485 container
->push_front(__value
);
489 /// Simply returns *this.
490 front_insert_iterator
&
494 /// Simply returns *this. (This %iterator does not "move".)
495 front_insert_iterator
&
499 /// Simply returns *this. (This %iterator does not "move".)
500 front_insert_iterator
506 * @param x A container of arbitrary type.
507 * @return An instance of front_insert_iterator working on @p x.
509 * This wrapper function helps in creating front_insert_iterator instances.
510 * Typing the name of the %iterator requires knowing the precise full
511 * type of the container, which can be tedious and impedes generic
512 * programming. Using this function lets you take advantage of automatic
513 * template parameter deduction, making the compiler match the correct
516 template<typename _Container
>
517 inline front_insert_iterator
<_Container
>
518 front_inserter(_Container
& __x
)
519 { return front_insert_iterator
<_Container
>(__x
); }
522 * @brief Turns assignment into insertion.
524 * These are output iterators, constructed from a container-of-T.
525 * Assigning a T to the iterator inserts it in the container at the
526 * %iterator's position, rather than overwriting the value at that
529 * (Sequences will actually insert a @e copy of the value before the
530 * %iterator's position.)
532 * Tip: Using the inserter function to create these iterators can
535 template<typename _Container
>
536 class insert_iterator
537 : public iterator
<output_iterator_tag
, void, void, void, void>
540 _Container
* container
;
541 typename
_Container::iterator iter
;
544 /// A nested typedef for the type of whatever container you used.
545 typedef _Container container_type
;
548 * The only way to create this %iterator is with a container and an
549 * initial position (a normal %iterator into the container).
551 insert_iterator(_Container
& __x
, typename
_Container::iterator __i
)
552 : container(&__x
), iter(__i
) {}
555 * @param value An instance of whatever type
556 * container_type::const_reference is; presumably a
557 * reference-to-const T for container<T>.
558 * @return This %iterator, for chained operations.
560 * This kind of %iterator maintains its own position in the
561 * container. Assigning a value to the %iterator will insert the
562 * value into the container at the place before the %iterator.
564 * The position is maintained such that subsequent assignments will
565 * insert values immediately after one another. For example,
567 * // vector v contains A and Z
569 * insert_iterator i (v, ++v.begin());
574 * // vector v contains A, 1, 2, 3, and Z
578 operator=(const typename
_Container::const_reference __value
)
580 iter
= container
->insert(iter
, __value
);
585 /// Simply returns *this.
590 /// Simply returns *this. (This %iterator does not "move".)
595 /// Simply returns *this. (This %iterator does not "move".)
602 * @param x A container of arbitrary type.
603 * @return An instance of insert_iterator working on @p x.
605 * This wrapper function helps in creating insert_iterator instances.
606 * Typing the name of the %iterator requires knowing the precise full
607 * type of the container, which can be tedious and impedes generic
608 * programming. Using this function lets you take advantage of automatic
609 * template parameter deduction, making the compiler match the correct
612 template<typename _Container
, typename _Iterator
>
613 inline insert_iterator
<_Container
>
614 inserter(_Container
& __x
, _Iterator __i
)
616 return insert_iterator
<_Container
>(__x
,
617 typename
_Container::iterator(__i
));
620 _GLIBCXX_END_NAMESPACE
622 _GLIBCXX_BEGIN_NAMESPACE(__gnu_cxx
)
624 // This iterator adapter is 'normal' in the sense that it does not
625 // change the semantics of any of the operators of its iterator
626 // parameter. Its primary purpose is to convert an iterator that is
627 // not a class, e.g. a pointer, into an iterator that is a class.
628 // The _Container parameter exists solely so that different containers
629 // using this template can instantiate different types, even if the
630 // _Iterator parameter is the same.
631 using std::iterator_traits
;
633 template<typename _Iterator
, typename _Container
>
634 class __normal_iterator
637 _Iterator _M_current
;
640 typedef typename iterator_traits
<_Iterator
>::iterator_category
642 typedef typename iterator_traits
<_Iterator
>::value_type value_type
;
643 typedef typename iterator_traits
<_Iterator
>::difference_type
645 typedef typename iterator_traits
<_Iterator
>::reference reference
;
646 typedef typename iterator_traits
<_Iterator
>::pointer pointer
;
648 __normal_iterator() : _M_current(_Iterator()) { }
651 __normal_iterator(const _Iterator
& __i
) : _M_current(__i
) { }
653 // Allow iterator to const_iterator conversion
654 template<typename _Iter
>
655 __normal_iterator(const __normal_iterator
<_Iter
,
656 typename
std::__enable_if
<_Container
,
657 (std::__are_same
<_Iter
,
658 typename
_Container::pointer
>::__value
)
660 : _M_current(__i
.base()) { }
662 // Forward iterator requirements
665 { return *_M_current
; }
669 { return _M_current
; }
680 { return __normal_iterator(_M_current
++); }
682 // Bidirectional iterator requirements
692 { return __normal_iterator(_M_current
--); }
694 // Random access iterator requirements
696 operator[](const difference_type
& __n
) const
697 { return _M_current
[__n
]; }
700 operator+=(const difference_type
& __n
)
701 { _M_current
+= __n
; return *this; }
704 operator+(const difference_type
& __n
) const
705 { return __normal_iterator(_M_current
+ __n
); }
708 operator-=(const difference_type
& __n
)
709 { _M_current
-= __n
; return *this; }
712 operator-(const difference_type
& __n
) const
713 { return __normal_iterator(_M_current
- __n
); }
717 { return _M_current
; }
720 // Note: In what follows, the left- and right-hand-side iterators are
721 // allowed to vary in types (conceptually in cv-qualification) so that
722 // comparaison between cv-qualified and non-cv-qualified iterators be
723 // valid. However, the greedy and unfriendly operators in std::rel_ops
724 // will make overload resolution ambiguous (when in scope) if we don't
725 // provide overloads whose operands are of the same type. Can someone
726 // remind me what generic programming is about? -- Gaby
728 // Forward iterator requirements
729 template<typename _IteratorL
, typename _IteratorR
, typename _Container
>
731 operator==(const __normal_iterator
<_IteratorL
, _Container
>& __lhs
,
732 const __normal_iterator
<_IteratorR
, _Container
>& __rhs
)
733 { return __lhs
.base() == __rhs
.base(); }
735 template<typename _Iterator
, typename _Container
>
737 operator==(const __normal_iterator
<_Iterator
, _Container
>& __lhs
,
738 const __normal_iterator
<_Iterator
, _Container
>& __rhs
)
739 { return __lhs
.base() == __rhs
.base(); }
741 template<typename _IteratorL
, typename _IteratorR
, typename _Container
>
743 operator!=(const __normal_iterator
<_IteratorL
, _Container
>& __lhs
,
744 const __normal_iterator
<_IteratorR
, _Container
>& __rhs
)
745 { return __lhs
.base() != __rhs
.base(); }
747 template<typename _Iterator
, typename _Container
>
749 operator!=(const __normal_iterator
<_Iterator
, _Container
>& __lhs
,
750 const __normal_iterator
<_Iterator
, _Container
>& __rhs
)
751 { return __lhs
.base() != __rhs
.base(); }
753 // Random access iterator requirements
754 template<typename _IteratorL
, typename _IteratorR
, typename _Container
>
756 operator<(const __normal_iterator
<_IteratorL
, _Container
>& __lhs
,
757 const __normal_iterator
<_IteratorR
, _Container
>& __rhs
)
758 { return __lhs
.base() < __rhs
.base(); }
760 template<typename _Iterator
, typename _Container
>
762 operator<(const __normal_iterator
<_Iterator
, _Container
>& __lhs
,
763 const __normal_iterator
<_Iterator
, _Container
>& __rhs
)
764 { return __lhs
.base() < __rhs
.base(); }
766 template<typename _IteratorL
, typename _IteratorR
, typename _Container
>
768 operator>(const __normal_iterator
<_IteratorL
, _Container
>& __lhs
,
769 const __normal_iterator
<_IteratorR
, _Container
>& __rhs
)
770 { return __lhs
.base() > __rhs
.base(); }
772 template<typename _Iterator
, typename _Container
>
774 operator>(const __normal_iterator
<_Iterator
, _Container
>& __lhs
,
775 const __normal_iterator
<_Iterator
, _Container
>& __rhs
)
776 { return __lhs
.base() > __rhs
.base(); }
778 template<typename _IteratorL
, typename _IteratorR
, typename _Container
>
780 operator<=(const __normal_iterator
<_IteratorL
, _Container
>& __lhs
,
781 const __normal_iterator
<_IteratorR
, _Container
>& __rhs
)
782 { return __lhs
.base() <= __rhs
.base(); }
784 template<typename _Iterator
, typename _Container
>
786 operator<=(const __normal_iterator
<_Iterator
, _Container
>& __lhs
,
787 const __normal_iterator
<_Iterator
, _Container
>& __rhs
)
788 { return __lhs
.base() <= __rhs
.base(); }
790 template<typename _IteratorL
, typename _IteratorR
, typename _Container
>
792 operator>=(const __normal_iterator
<_IteratorL
, _Container
>& __lhs
,
793 const __normal_iterator
<_IteratorR
, _Container
>& __rhs
)
794 { return __lhs
.base() >= __rhs
.base(); }
796 template<typename _Iterator
, typename _Container
>
798 operator>=(const __normal_iterator
<_Iterator
, _Container
>& __lhs
,
799 const __normal_iterator
<_Iterator
, _Container
>& __rhs
)
800 { return __lhs
.base() >= __rhs
.base(); }
802 // _GLIBCXX_RESOLVE_LIB_DEFECTS
803 // According to the resolution of DR179 not only the various comparison
804 // operators but also operator- must accept mixed iterator/const_iterator
806 template<typename _IteratorL
, typename _IteratorR
, typename _Container
>
807 inline typename __normal_iterator
<_IteratorL
, _Container
>::difference_type
808 operator-(const __normal_iterator
<_IteratorL
, _Container
>& __lhs
,
809 const __normal_iterator
<_IteratorR
, _Container
>& __rhs
)
810 { return __lhs
.base() - __rhs
.base(); }
812 template<typename _Iterator
, typename _Container
>
813 inline typename __normal_iterator
<_Iterator
, _Container
>::difference_type
814 operator-(const __normal_iterator
<_Iterator
, _Container
>& __lhs
,
815 const __normal_iterator
<_Iterator
, _Container
>& __rhs
)
816 { return __lhs
.base() - __rhs
.base(); }
818 template<typename _Iterator
, typename _Container
>
819 inline __normal_iterator
<_Iterator
, _Container
>
820 operator+(typename __normal_iterator
<_Iterator
, _Container
>::difference_type
821 __n
, const __normal_iterator
<_Iterator
, _Container
>& __i
)
822 { return __normal_iterator
<_Iterator
, _Container
>(__i
.base() + __n
); }
824 _GLIBCXX_END_NAMESPACE