1 // Iterators -*- C++ -*-
3 // Copyright (C) 2001, 2002 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, 59 Temple Place - Suite 330, Boston, MA 02111-1307,
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.
65 #ifndef __GLIBCPP_INTERNAL_ITERATOR_H
66 #define __GLIBCPP_INTERNAL_ITERATOR_H
70 // 24.4.1 Reverse iterators
72 * "Bidirectional and random access iterators have corresponding reverse
73 * %iterator adaptors that iterate through the data structure in the
74 * opposite direction. They have the same signatures as the corresponding
75 * iterators. The fundamental relation between a reverse %iterator and its
76 * corresponding %iterator @c i is established by the identity:
78 * &*(reverse_iterator(i)) == &*(i - 1)
81 * This mapping is dictated by the fact that while there is always a
82 * pointer past the end of an array, there might not be a valid pointer
83 * before the beginning of an array." [24.4.1]/1,2
85 * Reverse iterators can be tricky and surprising at first. Their
86 * semantics make sense, however, and the trickiness is a side effect of
87 * the requirement that the iterators must be safe.
89 template<typename _Iterator
>
90 class reverse_iterator
91 : public iterator
<typename iterator_traits
<_Iterator
>::iterator_category
,
92 typename iterator_traits
<_Iterator
>::value_type
,
93 typename iterator_traits
<_Iterator
>::difference_type
,
94 typename iterator_traits
<_Iterator
>::pointer
,
95 typename iterator_traits
<_Iterator
>::reference
>
101 typedef _Iterator iterator_type
;
102 typedef typename iterator_traits
<_Iterator
>::difference_type
104 typedef typename iterator_traits
<_Iterator
>::reference reference
;
105 typedef typename iterator_traits
<_Iterator
>::pointer pointer
;
109 * The default constructor gives an undefined state to this %iterator.
111 reverse_iterator() { }
114 * This %iterator will move in the opposite direction that @p x does.
117 reverse_iterator(iterator_type __x
) : current(__x
) { }
120 * The copy constructor is normal.
122 reverse_iterator(const reverse_iterator
& __x
)
123 : current(__x
.current
) { }
126 * A reverse_iterator across other types can be copied in the normal
129 template<typename _Iter
>
130 reverse_iterator(const reverse_iterator
<_Iter
>& __x
)
131 : current(__x
.base()) { }
134 * @return @c current, the %iterator used for underlying work.
137 base() const { return current
; }
147 _Iterator __tmp
= current
;
157 operator->() const { return &(operator*()); }
179 reverse_iterator __tmp
= *this;
201 reverse_iterator
operator--(int)
203 reverse_iterator __tmp
= *this;
214 operator+(difference_type __n
) const
215 { return reverse_iterator(current
- __n
); }
223 operator+=(difference_type __n
)
235 operator-(difference_type __n
) const
236 { return reverse_iterator(current
+ __n
); }
244 operator-=(difference_type __n
)
256 operator[](difference_type __n
) const { return *(*this + __n
); }
261 * @param x A %reverse_iterator.
262 * @param y A %reverse_iterator.
263 * @return A simple bool.
265 * Reverse iterators forward many operations to their underlying base()
266 * iterators. Others are implemented in terms of one another.
269 template<typename _Iterator
>
271 operator==(const reverse_iterator
<_Iterator
>& __x
,
272 const reverse_iterator
<_Iterator
>& __y
)
273 { return __x
.base() == __y
.base(); }
275 template<typename _Iterator
>
277 operator<(const reverse_iterator
<_Iterator
>& __x
,
278 const reverse_iterator
<_Iterator
>& __y
)
279 { return __y
.base() < __x
.base(); }
281 template<typename _Iterator
>
283 operator!=(const reverse_iterator
<_Iterator
>& __x
,
284 const reverse_iterator
<_Iterator
>& __y
)
285 { return !(__x
== __y
); }
287 template<typename _Iterator
>
289 operator>(const reverse_iterator
<_Iterator
>& __x
,
290 const reverse_iterator
<_Iterator
>& __y
)
291 { return __y
< __x
; }
293 template<typename _Iterator
>
295 operator<=(const reverse_iterator
<_Iterator
>& __x
,
296 const reverse_iterator
<_Iterator
>& __y
)
297 { return !(__y
< __x
); }
299 template<typename _Iterator
>
301 operator>=(const reverse_iterator
<_Iterator
>& __x
,
302 const reverse_iterator
<_Iterator
>& __y
)
303 { return !(__x
< __y
); }
305 template<typename _Iterator
>
306 inline typename reverse_iterator
<_Iterator
>::difference_type
307 operator-(const reverse_iterator
<_Iterator
>& __x
,
308 const reverse_iterator
<_Iterator
>& __y
)
309 { return __y
.base() - __x
.base(); }
311 template<typename _Iterator
>
312 inline reverse_iterator
<_Iterator
>
313 operator+(typename reverse_iterator
<_Iterator
>::difference_type __n
,
314 const reverse_iterator
<_Iterator
>& __x
)
315 { return reverse_iterator
<_Iterator
>(__x
.base() - __n
); }
318 // 24.4.2.2.1 back_insert_iterator
320 * @brief Turns assignment into insertion.
322 * These are output iterators, constructed from a container-of-T.
323 * Assigning a T to the iterator appends it to the container using
326 * Tip: Using the back_inserter function to create these iterators can
329 template<typename _Container
>
330 class back_insert_iterator
331 : public iterator
<output_iterator_tag
, void, void, void, void>
334 _Container
* container
;
337 /// A nested typedef for the type of whatever container you used.
338 typedef _Container container_type
;
340 /// The only way to create this %iterator is with a container.
342 back_insert_iterator(_Container
& __x
) : container(&__x
) { }
345 * @param value An instance of whatever type
346 * container_type::const_reference is; presumably a
347 * reference-to-const T for container<T>.
348 * @return This %iterator, for chained operations.
350 * This kind of %iterator doesn't really have a "position" in the
351 * container (you can think of the position as being permanently at
352 * the end, if you like). Assigning a value to the %iterator will
353 * always append the value to the end of the container.
355 back_insert_iterator
&
356 operator=(typename
_Container::const_reference __value
)
358 container
->push_back(__value
);
362 /// Simply returns *this.
363 back_insert_iterator
&
364 operator*() { return *this; }
366 /// Simply returns *this. (This %iterator does not "move".)
367 back_insert_iterator
&
368 operator++() { return *this; }
370 /// Simply returns *this. (This %iterator does not "move".)
372 operator++(int) { return *this; }
376 * @param x A container of arbitrary type.
377 * @return An instance of back_insert_iterator working on @p x.
379 * This wrapper function helps in creating back_insert_iterator instances.
380 * Typing the name of the %iterator requires knowing the precise full
381 * type of the container, which can be tedious and impedes generic
382 * programming. Using this function lets you take advantage of automatic
383 * template parameter deduction, making the compiler match the correct
386 template<typename _Container
>
387 inline back_insert_iterator
<_Container
>
388 back_inserter(_Container
& __x
)
389 { return back_insert_iterator
<_Container
>(__x
); }
392 * @brief Turns assignment into insertion.
394 * These are output iterators, constructed from a container-of-T.
395 * Assigning a T to the iterator prepends it to the container using
398 * Tip: Using the front_inserter function to create these iterators can
401 template<typename _Container
>
402 class front_insert_iterator
403 : public iterator
<output_iterator_tag
, void, void, void, void>
406 _Container
* container
;
409 /// A nested typedef for the type of whatever container you used.
410 typedef _Container container_type
;
412 /// The only way to create this %iterator is with a container.
413 explicit front_insert_iterator(_Container
& __x
) : container(&__x
) { }
416 * @param value An instance of whatever type
417 * container_type::const_reference is; presumably a
418 * reference-to-const T for container<T>.
419 * @return This %iterator, for chained operations.
421 * This kind of %iterator doesn't really have a "position" in the
422 * container (you can think of the position as being permanently at
423 * the front, if you like). Assigning a value to the %iterator will
424 * always prepend the value to the front of the container.
426 front_insert_iterator
&
427 operator=(typename
_Container::const_reference __value
)
429 container
->push_front(__value
);
433 /// Simply returns *this.
434 front_insert_iterator
&
435 operator*() { return *this; }
437 /// Simply returns *this. (This %iterator does not "move".)
438 front_insert_iterator
&
439 operator++() { return *this; }
441 /// Simply returns *this. (This %iterator does not "move".)
442 front_insert_iterator
443 operator++(int) { return *this; }
447 * @param x A container of arbitrary type.
448 * @return An instance of front_insert_iterator working on @p x.
450 * This wrapper function helps in creating front_insert_iterator instances.
451 * Typing the name of the %iterator requires knowing the precise full
452 * type of the container, which can be tedious and impedes generic
453 * programming. Using this function lets you take advantage of automatic
454 * template parameter deduction, making the compiler match the correct
457 template<typename _Container
>
458 inline front_insert_iterator
<_Container
>
459 front_inserter(_Container
& __x
)
460 { return front_insert_iterator
<_Container
>(__x
); }
463 * @brief Turns assignment into insertion.
465 * These are output iterators, constructed from a container-of-T.
466 * Assigning a T to the iterator inserts it in the container at the
467 * %iterator's position, rather than overwriting the value at that
470 * (Sequences will actually insert a @e copy of the value before the
471 * %iterator's position.)
473 * Tip: Using the inserter function to create these iterators can
476 template<typename _Container
>
477 class insert_iterator
478 : public iterator
<output_iterator_tag
, void, void, void, void>
481 _Container
* container
;
482 typename
_Container::iterator iter
;
485 /// A nested typedef for the type of whatever container you used.
486 typedef _Container container_type
;
489 * The only way to create this %iterator is with a container and an
490 * initial position (a normal %iterator into the container).
492 insert_iterator(_Container
& __x
, typename
_Container::iterator __i
)
493 : container(&__x
), iter(__i
) {}
496 * @param value An instance of whatever type
497 * container_type::const_reference is; presumably a
498 * reference-to-const T for container<T>.
499 * @return This %iterator, for chained operations.
501 * This kind of %iterator maintains its own position in the
502 * container. Assigning a value to the %iterator will insert the
503 * value into the container at the place before the %iterator.
505 * The position is maintained such that subsequent assignments will
506 * insert values immediately after one another. For example,
508 * // vector v contains A and Z
510 * insert_iterator i (v, ++v.begin());
515 * // vector v contains A, 1, 2, 3, and Z
519 operator=(const typename
_Container::const_reference __value
)
521 iter
= container
->insert(iter
, __value
);
526 /// Simply returns *this.
528 operator*() { return *this; }
530 /// Simply returns *this. (This %iterator does not "move".)
532 operator++() { return *this; }
534 /// Simply returns *this. (This %iterator does not "move".)
536 operator++(int) { return *this; }
540 * @param x A container of arbitrary type.
541 * @return An instance of insert_iterator working on @p x.
543 * This wrapper function helps in creating insert_iterator instances.
544 * Typing the name of the %iterator requires knowing the precise full
545 * type of the container, which can be tedious and impedes generic
546 * programming. Using this function lets you take advantage of automatic
547 * template parameter deduction, making the compiler match the correct
550 template<typename _Container
, typename _Iterator
>
551 inline insert_iterator
<_Container
>
552 inserter(_Container
& __x
, _Iterator __i
)
554 return insert_iterator
<_Container
>(__x
,
555 typename
_Container::iterator(__i
));
561 // This iterator adapter is 'normal' in the sense that it does not
562 // change the semantics of any of the operators of its iterator
563 // parameter. Its primary purpose is to convert an iterator that is
564 // not a class, e.g. a pointer, into an iterator that is a class.
565 // The _Container parameter exists solely so that different containers
566 // using this template can instantiate different types, even if the
567 // _Iterator parameter is the same.
568 using std::iterator_traits
;
570 template<typename _Iterator
, typename _Container
>
571 class __normal_iterator
572 : public iterator
<typename iterator_traits
<_Iterator
>::iterator_category
,
573 typename iterator_traits
<_Iterator
>::value_type
,
574 typename iterator_traits
<_Iterator
>::difference_type
,
575 typename iterator_traits
<_Iterator
>::pointer
,
576 typename iterator_traits
<_Iterator
>::reference
>
579 _Iterator _M_current
;
582 typedef typename iterator_traits
<_Iterator
>::difference_type
584 typedef typename iterator_traits
<_Iterator
>::reference reference
;
585 typedef typename iterator_traits
<_Iterator
>::pointer pointer
;
587 __normal_iterator() : _M_current(_Iterator()) { }
590 __normal_iterator(const _Iterator
& __i
) : _M_current(__i
) { }
592 // Allow iterator to const_iterator conversion
593 template<typename _Iter
>
594 inline __normal_iterator(const __normal_iterator
<_Iter
, _Container
>& __i
)
595 : _M_current(__i
.base()) { }
597 // Forward iterator requirements
599 operator*() const { return *_M_current
; }
602 operator->() const { return _M_current
; }
605 operator++() { ++_M_current
; return *this; }
608 operator++(int) { return __normal_iterator(_M_current
++); }
610 // Bidirectional iterator requirements
612 operator--() { --_M_current
; return *this; }
615 operator--(int) { return __normal_iterator(_M_current
--); }
617 // Random access iterator requirements
619 operator[](const difference_type
& __n
) const
620 { return _M_current
[__n
]; }
623 operator+=(const difference_type
& __n
)
624 { _M_current
+= __n
; return *this; }
627 operator+(const difference_type
& __n
) const
628 { return __normal_iterator(_M_current
+ __n
); }
631 operator-=(const difference_type
& __n
)
632 { _M_current
-= __n
; return *this; }
635 operator-(const difference_type
& __n
) const
636 { return __normal_iterator(_M_current
- __n
); }
639 base() const { return _M_current
; }
642 // Note: In what follows, the left- and right-hand-side iterators are
643 // allowed to vary in types (conceptually in cv-qualification) so that
644 // comparaison between cv-qualified and non-cv-qualified iterators be
645 // valid. However, the greedy and unfriendly operators in std::rel_ops
646 // will make overload resolution ambiguous (when in scope) if we don't
647 // provide overloads whose operands are of the same type. Can someone
648 // remind me what generic programming is about? -- Gaby
650 // Forward iterator requirements
651 template<typename _IteratorL
, typename _IteratorR
, typename _Container
>
653 operator==(const __normal_iterator
<_IteratorL
, _Container
>& __lhs
,
654 const __normal_iterator
<_IteratorR
, _Container
>& __rhs
)
655 { return __lhs
.base() == __rhs
.base(); }
657 template<typename _Iterator
, typename _Container
>
659 operator==(const __normal_iterator
<_Iterator
, _Container
>& __lhs
,
660 const __normal_iterator
<_Iterator
, _Container
>& __rhs
)
661 { return __lhs
.base() == __rhs
.base(); }
663 template<typename _IteratorL
, typename _IteratorR
, typename _Container
>
665 operator!=(const __normal_iterator
<_IteratorL
, _Container
>& __lhs
,
666 const __normal_iterator
<_IteratorR
, _Container
>& __rhs
)
667 { return __lhs
.base() != __rhs
.base(); }
669 template<typename _Iterator
, typename _Container
>
671 operator!=(const __normal_iterator
<_Iterator
, _Container
>& __lhs
,
672 const __normal_iterator
<_Iterator
, _Container
>& __rhs
)
673 { return __lhs
.base() != __rhs
.base(); }
675 // Random access iterator requirements
676 template<typename _IteratorL
, typename _IteratorR
, typename _Container
>
678 operator<(const __normal_iterator
<_IteratorL
, _Container
>& __lhs
,
679 const __normal_iterator
<_IteratorR
, _Container
>& __rhs
)
680 { return __lhs
.base() < __rhs
.base(); }
682 template<typename _Iterator
, typename _Container
>
684 operator<(const __normal_iterator
<_Iterator
, _Container
>& __lhs
,
685 const __normal_iterator
<_Iterator
, _Container
>& __rhs
)
686 { return __lhs
.base() < __rhs
.base(); }
688 template<typename _IteratorL
, typename _IteratorR
, typename _Container
>
690 operator>(const __normal_iterator
<_IteratorL
, _Container
>& __lhs
,
691 const __normal_iterator
<_IteratorR
, _Container
>& __rhs
)
692 { return __lhs
.base() > __rhs
.base(); }
694 template<typename _Iterator
, typename _Container
>
696 operator>(const __normal_iterator
<_Iterator
, _Container
>& __lhs
,
697 const __normal_iterator
<_Iterator
, _Container
>& __rhs
)
698 { return __lhs
.base() > __rhs
.base(); }
700 template<typename _IteratorL
, typename _IteratorR
, typename _Container
>
702 operator<=(const __normal_iterator
<_IteratorL
, _Container
>& __lhs
,
703 const __normal_iterator
<_IteratorR
, _Container
>& __rhs
)
704 { return __lhs
.base() <= __rhs
.base(); }
706 template<typename _Iterator
, typename _Container
>
708 operator<=(const __normal_iterator
<_Iterator
, _Container
>& __lhs
,
709 const __normal_iterator
<_Iterator
, _Container
>& __rhs
)
710 { return __lhs
.base() <= __rhs
.base(); }
712 template<typename _IteratorL
, typename _IteratorR
, typename _Container
>
714 operator>=(const __normal_iterator
<_IteratorL
, _Container
>& __lhs
,
715 const __normal_iterator
<_IteratorR
, _Container
>& __rhs
)
716 { return __lhs
.base() >= __rhs
.base(); }
718 template<typename _Iterator
, typename _Container
>
720 operator>=(const __normal_iterator
<_Iterator
, _Container
>& __lhs
,
721 const __normal_iterator
<_Iterator
, _Container
>& __rhs
)
722 { return __lhs
.base() >= __rhs
.base(); }
724 // _GLIBCPP_RESOLVE_LIB_DEFECTS
725 // According to the resolution of DR179 not only the various comparison
726 // operators but also operator- must accept mixed iterator/const_iterator
728 template<typename _IteratorL
, typename _IteratorR
, typename _Container
>
729 inline typename __normal_iterator
<_IteratorL
, _Container
>::difference_type
730 operator-(const __normal_iterator
<_IteratorL
, _Container
>& __lhs
,
731 const __normal_iterator
<_IteratorR
, _Container
>& __rhs
)
732 { return __lhs
.base() - __rhs
.base(); }
734 template<typename _Iterator
, typename _Container
>
735 inline __normal_iterator
<_Iterator
, _Container
>
736 operator+(typename __normal_iterator
<_Iterator
, _Container
>::difference_type __n
,
737 const __normal_iterator
<_Iterator
, _Container
>& __i
)
738 { return __normal_iterator
<_Iterator
, _Container
>(__i
.base() + __n
); }
739 } // namespace __gnu_cxx