---
name: "__gnu_debug::Safe_iterator"
section: "3"
platform: "linux"
package: "libstdc++6-doc"
version: "3.4.6-5"
release: "Debian 4.0 (Etch)"
platforms: ["linux"]
url: "https://new.carta.tech/__gnu_debug::Safe_iterator"
---

# \_\_gnu\_debug::Safe\_iterator(3)

Safe iterator wrapper.

## NAME

\_\_gnu\_debug::Safe\_iterator - Safe iterator wrapper.

## SYNOPSIS

`#include <safe_iterator.h>`

Inherits **\_\_gnu\_debug::Safe\_iterator\_base**.

### Public Types

typedef Iterator **Base\_iterator**\
 typedef **Traits::iterator\_category** **iterator\_category**\
 typedef **Traits::value\_type** **value\_type**\
 typedef **Traits::difference\_type** **difference\_type**\
 typedef **Traits::reference** **reference**\
 typedef **Traits::pointer** **pointer**\

### Public Member Functions

**Safe\_iterator** ()\
 **Postcondition:**

the iterator is singular and unattached

**"** **Safe\_iterator** (const Iterator &\_\_i, const Sequence \*seq)\
 *Safe iterator construction from an unsafe iterator and its sequence.*  **Safe\_iterator** (const **Safe\_iterator** &x)\
 *Copy construction.*  template\<typename MutableIterator\> **Safe\_iterator** (const **Safe\_iterator**\< MutableIterator, typename **std::\_\_enable\_if**\< Sequence,(**std::are\_same**\< MutableIterator, typename Sequence::iterator::Base\_iterator \>::M\_type) \>::M\_type \> &x)\
 *Converting constructor from a mutable iterator to a constant iterator.*  **Safe\_iterator** & **operator=** (const **Safe\_iterator** &x)\
 *Copy assignment.*  **reference** **operator \*** () const\
 *Iterator dereference.*  **pointer** **operator-\>** () const\
 *Iterator dereference.*  **Safe\_iterator** & **operator++** ()\
 *Iterator preincrement.*  **Safe\_iterator** **operator++** (int)\
 *Iterator postincrement.*  **Safe\_iterator** & **operator--** ()\
 *Iterator predecrement.*  **Safe\_iterator** **operator--** (int)\
 *Iterator postdecrement.*  **reference** **operator\[\]** (const **difference\_type** &n) const\
 **Safe\_iterator** & **operator+=** (const **difference\_type** &n)\
 **Safe\_iterator** **operator+** (const **difference\_type** &n) const\
 **Safe\_iterator** & **operator-=** (const **difference\_type** &n)\
 **Safe\_iterator** **operator-** (const **difference\_type** &n) const\
 Iterator **base** () const\
 *Return the underlying iterator.*  **operator Iterator** () const\
 *Conversion to underlying non-debug iterator to allow better interaction with non-debug containers.*  void **M\_attach** (const Sequence \*seq)\
 void **M\_invalidate** ()\
 bool **M\_dereferenceable** () const\
 *Is the iterator dereferenceable?*  bool **M\_incrementable** () const\
 *Is the iterator incrementable?*  bool **M\_decrementable** () const\
 bool **M\_can\_advance** (const **difference\_type** &n) const\
 template\<typename Other\> bool **M\_valid\_range** (const **Safe\_iterator**\< Other, Sequence \> &\_\_rhs) const\
 const Sequence \* **M\_get\_sequence** () const\
 bool **M\_is\_begin** () const\
 *Is this iterator equal to the sequence's begin() iterator?*  bool **M\_is\_end** () const\
 *Is this iterator equal to the sequence's end() iterator?*  void **M\_attach** (**Safe\_sequence\_base** \*seq, bool constant)\
 void **M\_detach** ()\
 bool **M\_attached\_to** (const **Safe\_sequence\_base** \*seq) const \
 bool **M\_singular** () const\
 bool **M\_can\_compare** (const **Safe\_iterator\_base** &x) const\

### Static Public Member Functions

template\<typename Iterator1, typename Iterator2\> static **pair**\< **difference\_type**, **Distance\_precision** \> **M\_get\_distance** (const Iterator1 &\_\_lhs, const Iterator2 &\_\_rhs)\
 template\<typename Iterator1, typename Iterator2\> static **pair**\< **difference\_type**, **Distance\_precision** \> **M\_get\_distance** (const Iterator1 &\_\_lhs, const Iterator2 &\_\_rhs, **std::random\_access\_iterator\_tag**)\
 template\<typename Iterator1, typename Iterator2\> static **pair**\< **difference\_type**, **Distance\_precision** \> **M\_get\_distance** (const Iterator1 &\_\_lhs, const Iterator2 &\_\_rhs, **std::forward\_iterator\_tag**)\

### Public Attributes

**Safe\_sequence\_base** \* **M\_sequence**\
 unsigned int **M\_version**\
 **Safe\_iterator\_base** \* **M\_prior**\
 **Safe\_iterator\_base** \* **M\_next**\

### Private Types

enum **Distance\_precision** \
 typedef **Safe\_iterator** **Self**\
 typedef **iterator\_traits**\< Iterator \> **Traits**\

### Private Member Functions

bool **M\_constant** () const\
 *Determine if this is a constant iterator.*

### Private Attributes

Iterator **M\_current**\
 *The underlying iterator.*

## Detailed Description

### template\<typename Iterator, typename Sequence\> class \_\_gnu\_debug::Safe\_iterator\< Iterator, Sequence \>

**Safe iterator wrapper.**

**The class template Safe\_iterator is a wrapper around an iterator that tracks the iterator's movement among sequences and checks that operations performed on the 'safe' iterator are legal. In additional to the basic iterator operations (which are validated, and then passed to the underlying iterator), Safe\_iterator has member functions for iterator invalidation, attaching/detaching the iterator from sequences, and querying the iterator's state.**

**Definition at line 64 of file safe\_iterator.h.**

## Member Enumeration Documentation

### template\<typename Iterator, typename Sequence\> enum \_\_gnu\_debug::Safe\_iterator::Distance\_precision` [private]`

**The precision to which we can calculate the distance between two iterators.**

**Definition at line 71 of file safe\_iterator.h.**

## Constructor & Destructor Documentation

### template\<typename Iterator, typename Sequence\> \_\_gnu\_debug::Safe\_iterator\< Iterator, Sequence \>::Safe\_iterator ()` [inline]`

**Postcondition:**

**the iterator is singular and unattached**

**Definition at line 100 of file safe\_iterator.h.**

### template\<typename Iterator, typename Sequence\> \_\_gnu\_debug::Safe\_iterator\< Iterator, Sequence \>::Safe\_iterator (const Iterator & \_\_i, const Sequence \* seq)` [inline]`

**Safe iterator construction from an unsafe iterator and its sequence.**

**Precondition:**

`seq` **is not NULL**

**Postcondition:**

**this is not singular**

**Definition at line 109 of file safe\_iterator.h.**

### template\<typename Iterator, typename Sequence\> \_\_gnu\_debug::Safe\_iterator\< Iterator, Sequence \>::Safe\_iterator (const Safe\_iterator\< Iterator, Sequence \> & x)` [inline]`

**Copy construction.**

**Precondition:**

`x` **is not singular**

**Definition at line 121 of file safe\_iterator.h.**

### template\<typename Iterator, typename Sequence\> template\<typename MutableIterator\> \_\_gnu\_debug::Safe\_iterator\< Iterator, Sequence \>::Safe\_iterator (const Safe\_iterator\< MutableIterator, typename std::\_\_enable\_if\< Sequence,(std::are\_same\< MutableIterator, typename Sequence::iterator::Base\_iterator \>::M\_type) \>::M\_type \> & x)` [inline]`

**Converting constructor from a mutable iterator to a constant iterator.**

**Precondition:**

`x` **is not singular**

**Definition at line 137 of file safe\_iterator.h.**

## Member Function Documentation

### template\<typename Iterator, typename Sequence\> bool \_\_gnu\_debug::Safe\_iterator\< Iterator, Sequence \>::M\_constant () const` [inline, private]`

**Determine if this is a constant iterator.**

**Definition at line 83 of file safe\_iterator.h.**

### template\<typename Iterator, typename Sequence\> Safe\_iterator& \_\_gnu\_debug::Safe\_iterator\< Iterator, Sequence \>::operator= (const Safe\_iterator\< Iterator, Sequence \> & x)` [inline]`

**Copy assignment.**

**Precondition:**

`x` **is not singular**

**Definition at line 157 of file safe\_iterator.h.**

### template\<typename Iterator, typename Sequence\> reference \_\_gnu\_debug::Safe\_iterator\< Iterator, Sequence \>::operator \* () const` [inline]`

**Iterator dereference.**

**Precondition:**

**iterator is dereferenceable**

**Definition at line 173 of file safe\_iterator.h.**

### template\<typename Iterator, typename Sequence\> pointer \_\_gnu\_debug::Safe\_iterator\< Iterator, Sequence \>::operator-\> () const` [inline]`

**Iterator dereference.**

**Precondition:**

**iterator is dereferenceable**

**Todo**

**Make this correct w.r.t. iterators that return proxies**

**Todo**

**Use addressof() instead of & operator**

**Definition at line 189 of file safe\_iterator.h.**

### template\<typename Iterator, typename Sequence\> Safe\_iterator& \_\_gnu\_debug::Safe\_iterator\< Iterator, Sequence \>::operator++ ()` [inline]`

**Iterator preincrement.**

**Precondition:**

**iterator is incrementable**

**Definition at line 203 of file safe\_iterator.h.**

### template\<typename Iterator, typename Sequence\> Safe\_iterator \_\_gnu\_debug::Safe\_iterator\< Iterator, Sequence \>::operator++ (int)` [inline]`

**Iterator postincrement.**

**Precondition:**

**iterator is incrementable**

**Definition at line 217 of file safe\_iterator.h.**

### template\<typename Iterator, typename Sequence\> Safe\_iterator& \_\_gnu\_debug::Safe\_iterator\< Iterator, Sequence \>::operator-- ()` [inline]`

**Iterator predecrement.**

**Precondition:**

**iterator is decrementable**

**Definition at line 233 of file safe\_iterator.h.**

### template\<typename Iterator, typename Sequence\> Safe\_iterator \_\_gnu\_debug::Safe\_iterator\< Iterator, Sequence \>::operator-- (int)` [inline]`

**Iterator postdecrement.**

**Precondition:**

**iterator is decrementable**

**Definition at line 247 of file safe\_iterator.h.**

### template\<typename Iterator, typename Sequence\> Iterator \_\_gnu\_debug::Safe\_iterator\< Iterator, Sequence \>::base () const` [inline]`

**Return the underlying iterator.**

**Definition at line 310 of file safe\_iterator.h.**

**Referenced by \_\_gnu\_debug\_def::vector\< Type, Allocator \>::erase(), \_\_gnu\_debug::basic\_string\< CharT, Traits, Allocator \>::erase(), \_\_gnu\_debug\_def::set\< Key, Compare, Allocator \>::erase(), \_\_gnu\_debug\_def::multiset\< Key, Compare, Allocator \>::erase(), \_\_gnu\_debug\_def::multimap\< Key, Type, Compare, Allocator \>::erase(), \_\_gnu\_debug\_def::map\< Key, Type, Compare, Allocator \>::erase(), \_\_gnu\_debug\_def::list\< Type, Allocator \>::erase(), \_\_gnu\_debug\_def::hash\_set\< Value, HashFcn, EqualKey, Alloc \>::erase(), \_\_gnu\_debug\_def::hash\_multiset\< Value, HashFcn, EqualKey, Alloc \>::erase(), \_\_gnu\_debug\_def::hash\_multimap\< Value, Type, HashFcn, EqualKey, Alloc \>::erase(), \_\_gnu\_debug\_def::hash\_map\< Value, Type, HashFcn, EqualKey, Alloc \>::erase(), \_\_gnu\_debug\_def::deque\< Type, Allocator \>::erase(), \_\_gnu\_debug\_def::vector\< Type, Allocator \>::insert(), \_\_gnu\_debug::basic\_string\< CharT, Traits, Allocator \>::insert(), \_\_gnu\_debug\_def::set\< Key, Compare, Allocator \>::insert(), \_\_gnu\_debug\_def::multiset\< Key, Compare, Allocator \>::insert(), \_\_gnu\_debug\_def::multimap\< Key, Type, Compare, Allocator \>::insert(), \_\_gnu\_debug\_def::map\< Key, Type, Compare, Allocator \>::insert(), \_\_gnu\_debug\_def::list\< Type, Allocator \>::insert(), \_\_gnu\_debug\_def::deque\< Type, Allocator \>::insert(), \_\_gnu\_debug\_def::list\< Type, Allocator \>::merge(), \_\_gnu\_debug\_def::list\< Type, Allocator \>::remove(), \_\_gnu\_debug\_def::list\< Type, Allocator \>::remove\_if(), \_\_gnu\_debug::basic\_string\< CharT, Traits, Allocator \>::replace(), and \_\_gnu\_debug\_def::list\< Type, Allocator \>::splice().**

### template\<typename Iterator, typename Sequence\> \_\_gnu\_debug::Safe\_iterator\< Iterator, Sequence \>::operator Iterator () const` [inline]`

**Conversion to underlying non-debug iterator to allow better interaction with non-debug containers.**

**Definition at line 316 of file safe\_iterator.h.**

### template\<typename Iterator, typename Sequence\> void \_\_gnu\_debug::Safe\_iterator\< Iterator, Sequence \>::M\_attach (const Sequence \* seq)` [inline]`

**Attach iterator to the given sequence.**

**Definition at line 320 of file safe\_iterator.h.**

### template\<typename Iterator, typename Sequence\> void \_\_gnu\_debug::Safe\_iterator\< Iterator, Sequence \>::M\_invalidate ()

**Invalidate the iterator, making it singular.**

**Definition at line 112 of file safe\_iterator.tcc.**

### template\<typename Iterator, typename Sequence\> bool \_\_gnu\_debug::Safe\_iterator\< Iterator, Sequence \>::M\_dereferenceable () const` [inline]`

**Is the iterator dereferenceable?**

**Definition at line 332 of file safe\_iterator.h.**

### template\<typename Iterator, typename Sequence\> bool \_\_gnu\_debug::Safe\_iterator\< Iterator, Sequence \>::M\_incrementable () const` [inline]`

**Is the iterator incrementable?**

**Definition at line 337 of file safe\_iterator.h.**

### template\<typename Iterator, typename Sequence\> template\<typename Iterator1, typename Iterator2\> static pair\<difference\_type, Distance\_precision\> \_\_gnu\_debug::Safe\_iterator\< Iterator, Sequence \>::M\_get\_distance (const Iterator1 & \_\_lhs, const Iterator2 & \_\_rhs)` [inline, static]`

**Determine the distance between two iterators with some known precision.**

**Definition at line 362 of file safe\_iterator.h.**

### template\<typename Iterator, typename Sequence\> bool \_\_gnu\_debug::Safe\_iterator\< Iterator, Sequence \>::M\_is\_begin () const` [inline]`

**Is this iterator equal to the sequence's begin() iterator?**

**Definition at line 387 of file safe\_iterator.h.**

### template\<typename Iterator, typename Sequence\> bool \_\_gnu\_debug::Safe\_iterator\< Iterator, Sequence \>::M\_is\_end () const` [inline]`

**Is this iterator equal to the sequence's end() iterator?**

**Definition at line 391 of file safe\_iterator.h.**

### void \_\_gnu\_debug::Safe\_iterator\_base::M\_attach (Safe\_sequence\_base \* seq, bool constant)` [inherited]`

**Attaches this iterator to the given sequence, detaching it from whatever sequence it was attached to originally. If the new sequence is the NULL pointer, the iterator is left unattached.**

**Definition at line 190 of file debug.cc.**

### void \_\_gnu\_debug::Safe\_iterator\_base::M\_detach ()` [inherited]`

**Detach the iterator for whatever sequence it is attached to, if any.**

**Definition at line 220 of file debug.cc.**

### bool \_\_gnu\_debug::Safe\_iterator\_base::M\_attached\_to (const Safe\_sequence\_base \* seq) const` [inline, inherited]`

**Determines if we are attached to the given sequence.**

**Definition at line 120 of file safe\_base.h.**

### bool \_\_gnu\_debug::Safe\_iterator\_base::M\_singular () const` [inherited]`

**Is this iterator singular?**

**Definition at line 245 of file debug.cc.**

### bool \_\_gnu\_debug::Safe\_iterator\_base::M\_can\_compare (const Safe\_iterator\_base & x) const` [inherited]`

**Can we compare this iterator to the given iterator** `x`**? Returns true if both iterators are nonsingular and reference the same sequence.**

**Definition at line 250 of file debug.cc.**

## Member Data Documentation

### template\<typename Iterator, typename Sequence\> Iterator \_\_gnu\_debug::Safe\_iterator\< Iterator, Sequence \>::M\_current` [private]`

**The underlying iterator.**

**Definition at line 79 of file safe\_iterator.h.**

### Safe\_sequence\_base\* \_\_gnu\_debug::Safe\_iterator\_base::M\_sequence` [inherited]`

**The sequence this iterator references; may be NULL to indicate a singular iterator.**

**Definition at line 55 of file safe\_base.h.**

### unsigned int \_\_gnu\_debug::Safe\_iterator\_base::M\_version` [inherited]`

**The version number of this iterator. The sentinel value 0 is used to indicate an invalidated iterator (i.e., one that is singular because of an operation on the container). This version number must equal the version number in the sequence referenced by M\_sequence for the iterator to be non-singular.**

**Definition at line 64 of file safe\_base.h.**

### Safe\_iterator\_base\* \_\_gnu\_debug::Safe\_iterator\_base::M\_prior` [inherited]`

**Pointer to the previous iterator in the sequence's list of iterators. Only valid when M\_sequence != NULL.**

**Definition at line 68 of file safe\_base.h.**

### Safe\_iterator\_base\* \_\_gnu\_debug::Safe\_iterator\_base::M\_next` [inherited]`

**Pointer to the next iterator in the sequence's list of iterators. Only valid when M\_sequence != NULL.**

**Definition at line 72 of file safe\_base.h.**

## Author

**Generated automatically by Doxygen for libstdc++-v3 Source from the source code.**