__GNU_DEBUG::_SAFE_ITERATOR(3cxx)

💖 `__gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >` 💖

manual page (3cxx) — safe iterator wrapper, but make it fashion

🌸 NAME 🌸

__gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category > — safe iterator wrapper. that's the whole name, bestie, and it's iconic 💅

✨ SYNOPSIS ✨

#include <safe_iterator.h>

Inherits _Iterator, and __gnu_debug::_Safe_iterator_base.
Inherited by __gnu_debug::_Safe_iterator< _Iterator, _Sequence, std::random_access_iterator_tag >.

🎀 Public Types 🎀

typedef _Safe_iterator< _Iterator, _Sequence, iterator_category > _Self
typedef _Traits::difference_type difference_type
typedef _Traits::iterator_category iterator_category
typedef _Iterator iterator_type
typedef _Traits::pointer pointer
typedef _Traits::reference reference
typedef _Traits::value_type value_type

💅 Public Member Functions 💅

constexpr _Safe_iterator () noexcept
constexpr _Safe_iterator (_Iterator __i, const _Safe_sequence_base *__seq) noexcept — safe iterator construction from an unsafe iterator and its sequence.
constexpr _Safe_iterator (_Safe_iterator &&__x) noexcept — move construction.
constexpr _Safe_iterator (const _Safe_iterator &__x) noexcept — copy construction.
template<typename _MutableIterator > constexpr _Safe_iterator (const _Safe_iterator< _MutableIterator, _Sequence, typename __gnu_cxx::__enable_if< _IsConstant::__value &&std::__are_same< _MutableIterator, _OtherIterator >::__value, _Category >::__type > &__x) noexcept — converting constructor from a mutable iterator to a constant iterator.
void _M_attach (_Safe_sequence_base *__seq)
void _M_attach_single (_Safe_sequence_base *__seq)
bool _M_attached_to (const _Safe_sequence_base *__seq) const
bool _M_before_dereferenceable () const — is the iterator before a dereferenceable one?
template<typename _Diff > bool _M_can_advance (const std::pair< _Diff, _Distance_precision > &__dist, int __way) const
bool _M_can_advance (difference_type __n, bool __strict=false) const
bool _M_can_compare (const _Safe_iterator_base &__x) const throw ()
bool _M_dereferenceable () const — is the iterator dereferenceable?
void _M_detach_single () throw ()
_Distance_traits< _Iterator >::__type _M_get_distance_from_begin () const
_Distance_traits< _Iterator >::__type _M_get_distance_to (const _Safe_iterator &__rhs) const
_Distance_traits< _Iterator >::__type _M_get_distance_to_end () const
__gnu_cxx::__conditional_type< _IsConstant::__value, const_Sequence *, _Sequence * >::__type _M_get_sequence () const
bool _M_incrementable () const — is the iterator incrementable?
void _M_invalidate ()
bool _M_is_before_begin () const — is this iterator equal to the sequence's before_begin() iterator if any?
constexpr bool _M_is_begin () const — is this iterator equal to the sequence's begin() iterator?
bool _M_is_beginnest () const — is this iterator equal to the sequence's before_begin() iterator if any or begin() otherwise?
bool _M_is_end () const — is this iterator equal to the sequence's end() iterator?
void _M_reset () throw ()
bool _M_singular () const throw ()
void _M_unlink () throw ()
bool _M_valid_range (const _Safe_iterator &__rhs, std::pair< difference_type, _Distance_precision > &__dist, bool __check_dereferenceable=true) const
bool _M_value_initialized () const — is the iterator value-initialized?
constexpr const _Iterator & base () const noexcept
constexpr _Iterator & base () noexcept — return the underlying iterator.
constexpr operator _Iterator () const noexcept — conversion to underlying non-debug iterator to allow better interaction with non-debug containers.
constexpr reference operator* () const noexcept — iterator dereference.
constexpr _Safe_iterator & operator++ () noexcept — iterator preincrement.
constexpr _Safe_iterator operator++ (int) noexcept — iterator postincrement.
constexpr pointer operator-> () const noexcept — iterator dereference.
constexpr _Safe_iterator & operator= (_Safe_iterator &&__x) noexcept — move assignment.
constexpr _Safe_iterator & operator= (const _Safe_iterator &__x) noexcept — copy assignment.

🌟 Static Public Member Functions 🌟

static constexpr bool _S_constant () — determine if this is a constant iterator.

🦋 Public Attributes 🦋

_Safe_iterator_base * _M_next
_Safe_iterator_base * _M_prior
_Safe_sequence_base * _M_sequence
unsigned int _M_version

🔒 Protected Types 🔒

typedef std::__are_same< typename _Sequence::_Base::const_iterator,
    _Iterator > _IsConstant
typedef __gnu_cxx::__conditional_type< _IsConstant::__value,
    typename_Sequence::_Base::iterator,
    typename_Sequence::_Base::const_iterator >::__type _OtherIterator

🧚 Protected Member Functions 🧚

constexpr _Safe_iterator (const _Safe_iterator &__x, _Unchecked) noexcept
void _M_attach (_Safe_sequence_base *__seq, bool __constant)
void _M_attach_single (_Safe_sequence_base *__seq, bool __constant) throw ()
void _M_detach ()
__gnu_cxx::__mutex & _M_get_mutex () throw ()

🫶 Friends 🫶

template<typename _IteR > constexpr friend bool operator== (const _Self
    &__lhs, const _Safe_iterator< _IteR, _Sequence, iterator_category >
    &__rhs) noexcept
constexpr friend bool operator== (const _Self &__lhs, const _Self
    &__rhs) noexcept

🌈 Detailed Description 🌈

template<typename _Iterator, typename _Sequence, typename _Category =
    typename std::iterator_traits<_Iterator>::iterator_category>
class __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category
>"Safe iterator wrapper.

Bestie, 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. it's literally the vibe check for your iterator 👑

On top of 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.

⚠️ Note that _Iterator must be the first base class so that it gets initialized before the iterator is being attached to the container's list of iterators and it is being detached before _Iterator get destroyed. Otherwise it would result in a data race. this part is serious, bestie — data race is not cute 😭

🧁 Constructor & Destructor Documentation 🧁

🍓 `_Safe_iterator ()`

template<typename _Iterator , typename _Sequence , typename _Category  =
    typename std::iterator_traits<_Iterator>::iterator_category> constexpr
__gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category
>::_Safe_iterator () [inline],  [constexpr],  [noexcept]

Postcondition: the iterator is singular and unattached.

🍓 `_Safe_iterator (_Iterator __i, const _Safe_sequence_base *__seq)`

template<typename _Iterator , typename _Sequence , typename _Category  =
    typename std::iterator_traits<_Iterator>::iterator_category> constexpr
__gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category
>::_Safe_iterator (_Iterator __i, const _Safe_sequence_base * __seq)
[inline],  [constexpr],  [noexcept]

Safe iterator construction from an unsafe iterator and its sequence.

Precondition: seq is not NULL.

Postcondition: this is not singular.

🍓 `_Safe_iterator (const _Safe_iterator< _Iterator, _Sequence, _Category > & __x)`

template<typename _Iterator , typename _Sequence , typename _Category  =
    typename std::iterator_traits<_Iterator>::iterator_category> constexpr
__gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category
>::_Safe_iterator (const _Safe_iterator< _Iterator, _Sequence, _Category
> & __x) [inline],  [constexpr],  [noexcept]

Copy construction. copying, but make it safe 💜

References __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_M_attach(), __gnu_debug::_Safe_iterator_base::_M_sequence, __gnu_debug::_Safe_iterator_base::_M_singular(), and __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_M_value_initialized().

🍓 `_Safe_iterator (_Safe_iterator< _Iterator, _Sequence, _Category > && __x)`

template<typename _Iterator , typename _Sequence , typename _Category  =
    typename std::iterator_traits<_Iterator>::iterator_category> constexpr
__gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category
>::_Safe_iterator (_Safe_iterator< _Iterator, _Sequence, _Category > &&
__x) [inline],  [constexpr],  [noexcept]

Move construction. yeet that iterator, but safely ✨

Postcondition: __x is singular and unattached.

References __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_M_attach(), __gnu_debug::_Safe_iterator_base::_M_detach(), __gnu_debug::_Safe_iterator_base::_M_sequence, __gnu_debug::_Safe_iterator_base::_M_singular(), __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_M_value_initialized(), and __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::base().

🍓 converting constructor from mutable iterator to constant iterator

template<typename _Iterator , typename _Sequence , typename _Category  =
    typename std::iterator_traits<_Iterator>::iterator_category>
template<typename _MutableIterator > constexpr
__gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category
>::_Safe_iterator (const _Safe_iterator< _MutableIterator, _Sequence,
typename __gnu_cxx::__enable_if< _IsConstant::__value &&std::__are_same<
_MutableIterator, _OtherIterator >::__value, _Category >::__type > &
__x) [inline],  [constexpr],  [noexcept]

Converting constructor from a mutable iterator to a constant iterator. glow-up from mutable to const, no cap 🦋

🌺 Member Function Documentation 🌺

💫 `_M_attach (_Safe_sequence_base * __seq)`

template<typename _Iterator , typename _Sequence , typename _Category  =
    typename std::iterator_traits<_Iterator>::iterator_category> void
__gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category
>::_M_attach (_Safe_sequence_base * __seq) [inline]

Attach iterator to the given sequence. like adding yourself to the right group chat 💖

References __gnu_debug::_Safe_iterator_base::_M_attach(), and __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_S_constant().

Referenced by __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_Safe_iterator(), __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_Safe_iterator(), __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_Safe_iterator(), __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::operator=(), and __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::operator=().

💫 `__gnu_debug::_Safe_iterator_base::_M_attach (_Safe_sequence_base * seq, bool constant)`

void __gnu_debug::_Safe_iterator_base::_M_attach (_Safe_sequence_base *
__seq, bool __constant) [protected],  [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. switching friend groups but with pointer rules 💜

Referenced by __gnu_debug::_Safe_iterator_base::_Safe_iterator_base(), __gnu_debug::_Safe_iterator_base::_Safe_iterator_base(), and __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_M_attach().

okay so this next chunk is the rest of the member functions — the protected ones, the ones inherited from _Safe_iterator_base, and all the little helper predicates that make debug iterators actually safe 💅 it's giving behind the scenes and honestly it ate.

template<typename _Iterator , typename _Sequence , typename _Category  = typename std::iterator_traits<_Iterator>::iterator_category> void __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_M_attach_single (_Safe_sequence_base * __seq) [inline]

Same deal as the normal attach, bestie, except this one is not thread-safe — so don't be sharing it across threads 😭

References: __gnu_debug::_Safe_iterator_base::_M_attach_single(), and __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_S_constant().

void __gnu_debug::_Safe_iterator_base::_M_attach_single (_Safe_sequence_base * __seq, bool __constant) [protected], [inherited]

Again: same vibe, but not thread-safe. Zero thread safety, no cap.

Referenced by: __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_M_attach_single().

bool __gnu_debug::_Safe_iterator_base::_M_attached_to (const _Safe_sequence_base * __seq) const [inline], [inherited]

Answers the question "are we attached to this specific sequence?" for the sequence you hand it 👀

References: __gnu_debug::_Safe_iterator_base::_M_sequence.

template<typename _Iterator , typename _Sequence , typename _Category  = typename std::iterator_traits<_Iterator>::iterator_category> bool __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_M_before_dereferenceable () const [inline]

Is this iterator sitting right before a dereferenceable one? basically "am I the one before the one you can actually dereference" 🧐

References: __gnu_debug::__base(), __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_M_incrementable(), and __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::base().

bool __gnu_debug::_Safe_iterator_base::_M_can_compare (const _Safe_iterator_base & __x) const [inherited]

Can we even compare this iterator to the iterator __x you passed? Returns true if both iterators are nonsingular and they reference the same sequence. if not, the library is gonna be like "girl what" 💀

template<typename _Iterator , typename _Sequence , typename _Category  = typename std::iterator_traits<_Iterator>::iterator_category> bool __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_M_dereferenceable () const [inline]

Is the iterator dereferenceable? i.e. can you actually slap a * on it without the debug machinery losing its mind ✨

References: __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_M_is_before_begin(), __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_M_is_end(), and __gnu_debug::_Safe_iterator_base::_M_singular().

Referenced by: __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::operator*(), and __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::operator->().

void __gnu_debug::_Safe_iterator_base::_M_detach () [protected], [inherited]

Detaches the iterator from whatever sequence it's currently attached to — if it's attached to any at all ✂️

void __gnu_debug::_Safe_iterator_base::_M_detach_single () [inherited]

Yeah, same thing, but not thread-safe 🫶

Referenced by: __gnu_debug::_Safe_sequence< _Sequence >::_M_transfer_from_if().

__gnu_cxx::__mutex & __gnu_debug::_Safe_iterator_base::_M_get_mutex () [protected], [inherited]

This one exists for use in _Safe_iterator 🔐

Referenced by: __gnu_debug::_Safe_local_iterator< _Iterator, _Sequence >::operator++(), __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::operator++(), __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::operator=(), __gnu_debug::_Safe_local_iterator< _Iterator, _Sequence >::operator=(), __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::operator=(), and __gnu_debug::_Safe_local_iterator< _Iterator, _Sequence >::operator=().

template<typename _Iterator , typename _Sequence , typename _Category  = typename std::iterator_traits<_Iterator>::iterator_category> bool __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_M_incrementable () const [inline]

Is the iterator incrementable? can we ++ it or is it gonna scream at us 🫣

References: __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_M_is_end(), and __gnu_debug::_Safe_iterator_base::_M_singular().

Referenced by: __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_M_before_dereferenceable(), __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::operator++(), and __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::operator++().

void __gnu_debug::_Safe_iterator_base::_M_invalidate () [inline], [inherited]

Invalidates the iterator, which makes it singular — like, it no longer belongs to anybody 💀 iconic but sad

References: __gnu_debug::_Safe_iterator_base::_M_version.

template<typename _Iterator , typename _Sequence , typename _Category  = typename std::iterator_traits<_Iterator>::iterator_category> bool __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_M_is_before_begin () const [inline]

Is this iterator equal to the sequence's before_begin() iterator, if the sequence even has one? 👀

Referenced by: __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_M_dereferenceable().

template<typename _Iterator , typename _Sequence , typename _Category  = typename std::iterator_traits<_Iterator>::iterator_category> constexpr bool __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_M_is_begin () const [inline], [constexpr]

Is this iterator equal to the sequence's begin() iterator? simple as 🌸

References: __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::base().

template<typename _Iterator , typename _Sequence , typename _Category  = typename std::iterator_traits<_Iterator>::iterator_category> bool __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_M_is_beginnest () const [inline]

Is this iterator equal to the sequence's before_begin() iterator if it has one, or begin() otherwise? it's the beginnest. the most begin to ever begin 🎀

template<typename _Iterator , typename _Sequence , typename _Category  = typename std::iterator_traits<_Iterator>::iterator_category> bool __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_M_is_end () const [inline]

Is this iterator equal to the sequence's end() iterator? yep, that's the whole thing 🌈

References: __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::base().

Referenced by: __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_M_dereferenceable(), and __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_M_incrementable().

void __gnu_debug::_Safe_iterator_base::_M_reset () [inherited]

Resets all the member variables. factory reset core 🧼

bool __gnu_debug::_Safe_iterator_base::_M_singular () const [inherited]

Is this iterator singular? the big question 😭

Referenced by:

__gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_Safe_iterator()
__gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_Safe_iterator()
__gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_Safe_iterator()
__gnu_debug::_Safe_local_iterator< _Iterator, _Sequence >::_Safe_local_iterator()
__gnu_debug::_Safe_local_iterator< _Iterator, _Sequence >::_Safe_local_iterator()
__gnu_debug::_Safe_local_iterator< _Iterator, _Sequence >::_Safe_local_iterator()
__gnu_debug::__check_singular_aux()
__gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_M_dereferenceable()
__gnu_debug::_Safe_local_iterator< _Iterator, _Sequence >::_M_dereferenceable()
__gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_M_incrementable()
__gnu_debug::_Safe_local_iterator< _Iterator, _Sequence >::_M_incrementable()
__gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::operator=()
__gnu_debug::_Safe_local_iterator< _Iterator, _Sequence >::operator=()
__gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::operator=()
__gnu_debug::_Safe_local_iterator< _Iterator, _Sequence >::operator=()

void __gnu_debug::_Safe_iterator_base::_M_unlink () [inline], [inherited]

Unlinks itself. bye bestie 👋 🔗

References: __gnu_debug::_Safe_iterator_base::_M_next, and __gnu_debug::_Safe_iterator_base::_M_prior.

template<typename _Iterator , typename _Sequence , typename _Category  = typename std::iterator_traits<_Iterator>::iterator_category> bool __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_M_value_initialized () const [inline]

Is the iterator value-initialized? checking the vibes of its initialization state 🔍

References: __gnu_debug::_Safe_iterator_base::_M_version, and __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::base().

template<typename _Iterator , typename _Sequence , typename _Category  = typename std::iterator_traits<_Iterator>::iterator_category> static constexpr bool __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_S_constant () [inline], [static], [constexpr]

Works out whether this is a constant iterator. static, constexpr, adorable ⭐

Referenced by: __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_M_attach(), and __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_M_attach_single().

template<typename _Iterator , typename _Sequence , typename _Category  = typename std::iterator_traits<_Iterator>::iterator_category> constexpr _Iterator & __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::base () [inline], [constexpr], [noexcept]

Hands you back the underlying iterator. that's it, that's the function — constexpr and noexcept included 💖

Referenced by: __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_Safe_iterator(), __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_M_before_dereferenceable(), __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_M_is_begin(), __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_M_is_end(), __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_M_value_initialized(), __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::operator*(), __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::operator++(), __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::operator->(), __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::operator=(), and __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::operator=().

template<typename _Iterator , typename _Sequence , typename _Category  = typename std::iterator_traits<_Iterator>::iterator_category> constexpr __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::operator _Iterator () const [inline], [constexpr], [noexcept]

Conversion to the underlying non-debug iterator, so debug iterators can play nicely with non-debug containers. friendship bracelets, basically 🤝

template<typename _Iterator , typename _Sequence , typename _Category  = typename std::iterator_traits<_Iterator>::iterator_category> constexpr reference __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::operator* () const [inline], [constexpr], [noexcept]

Iterator dereference ✨ the moment we've all been waiting for ✨

okay so finishing up that dereference entry — the vibe check is:

Precondition: iterator is dereferenceable
References: __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_M_dereferenceable(), and __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::base().

preincrement core: `operator++ ()`

template<typename _Iterator , typename _Sequence , typename _Category  =
    typename std::iterator_traits<_Iterator>::iterator_category> constexpr
    _Safe_iterator & __gnu_debug::_Safe_iterator< _Iterator, _Sequence,
    _Category >::operator++ () [inline],  [constexpr],  [noexcept]

Iterator preincrement — literally bumping the iterator forward, bestie. It’s giving “one step to the right” energy.

Precondition: iterator is incrementable
References:
- __gnu_debug::_Safe_iterator_base::_M_get_mutex()
- __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_M_incrementable()
- __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::base()

postincrement era: `operator++ (int)`

template<typename _Iterator , typename _Sequence , typename _Category  =
    typename std::iterator_traits<_Iterator>::iterator_category> constexpr
    _Safe_iterator __gnu_debug::_Safe_iterator< _Iterator, _Sequence,
    _Category >::operator++ (int) [inline],  [constexpr],  [noexcept]

Iterator postincrement — same forward-bump fantasy, but the (int) flavor.

Precondition: iterator is incrementable
References:
- __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_M_incrementable()

arrow moment: `operator-> ()`

template<typename _Iterator , typename _Sequence , typename _Category  =
    typename std::iterator_traits<_Iterator>::iterator_category> constexpr
    pointer __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category
    >::operator-> () const [inline],  [constexpr],  [noexcept]

Iterator dereference — it hands you a pointer, no cap.

Precondition: iterator is dereferenceable
References:
- __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_M_dereferenceable()
- __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::base()

move assignment: `operator= (_Safe_iterator &&)`

template<typename _Iterator , typename _Sequence , typename _Category  =
    typename std::iterator_traits<_Iterator>::iterator_category> constexpr
    _Safe_iterator & __gnu_debug::_Safe_iterator< _Iterator, _Sequence,
    _Category >::operator= (_Safe_iterator< _Iterator, _Sequence, _Category
    > && __x) [inline],  [constexpr],  [noexcept]

Move assignment. Shifting the whole iterator situation over to __x’s old spot.

Postcondition: __x is singular and unattached
References:
- std::__addressof()
- __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_M_attach()
- __gnu_debug::_Safe_iterator_base::_M_detach()
- __gnu_debug::_Safe_iterator_base::_M_get_mutex()
- __gnu_debug::_Safe_iterator_base::_M_sequence
- __gnu_debug::_Safe_iterator_base::_M_singular()
- __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_M_value_initialized()
- __gnu_debug::_Safe_iterator_base::_M_version
- __gnu_debug::_Safe_sequence_base::_M_version
- __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::base()

copy assignment: `operator= (const _Safe_iterator &)`

template<typename _Iterator , typename _Sequence , typename _Category  =
    typename std::iterator_traits<_Iterator>::iterator_category> constexpr
    _Safe_iterator & __gnu_debug::_Safe_iterator< _Iterator, _Sequence,
    _Category >::operator= (const _Safe_iterator< _Iterator, _Sequence,
    _Category > & __x) [inline],  [constexpr],  [noexcept]

Copy assignment. Same assignment energy, but copied instead of moved.

References:
- __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_M_attach()
- __gnu_debug::_Safe_iterator_base::_M_detach()
- __gnu_debug::_Safe_iterator_base::_M_get_mutex()
- __gnu_debug::_Safe_iterator_base::_M_sequence
- __gnu_debug::_Safe_iterator_base::_M_singular()
- __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_M_value_initialized()
- __gnu_debug::_Safe_iterator_base::_M_version
- __gnu_debug::_Safe_sequence_base::_M_version
- __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::base()

🌸 Member Data Documentation 🌸

`_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 — so don’t go touching it when the sequence is a whole NULL situation, bestie.

Referenced by:

__gnu_debug::_Safe_sequence< _SafeSequence >::_M_invalidate_if()
__gnu_debug::_Safe_sequence< _Sequence >::_M_transfer_from_if()
__gnu_debug::_Safe_iterator_base::_M_unlink()

`_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 — same rule, previous-side edition.

Referenced by:

__gnu_debug::_Safe_sequence< _SafeSequence >::_M_invalidate_if()
__gnu_debug::_Safe_sequence< _Sequence >::_M_transfer_from_if()
__gnu_debug::_Safe_iterator_base::_M_unlink()

`_Safe_sequence_base* __gnu_debug::_Safe_iterator_base::_M_sequence [inherited]`

The sequence this iterator references; may be NULL to indicate a singular iterator. iconic little “am I attached or not?” flag, honestly.

Referenced by:

__gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_Safe_iterator()
__gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_Safe_iterator()
__gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_Safe_iterator()
__gnu_debug::_Safe_iterator_base::_Safe_iterator_base()
__gnu_debug::_Safe_local_iterator< _Iterator, _Sequence >::_Safe_local_iterator()
__gnu_debug::_Safe_local_iterator< _Iterator, _Sequence >::_Safe_local_iterator()
__gnu_debug::_Safe_local_iterator< _Iterator, _Sequence >::_Safe_local_iterator()
__gnu_debug::_Safe_local_iterator_base::_Safe_local_iterator_base()
__gnu_debug::_Safe_iterator_base::_M_attached_to()
__gnu_debug::_Safe_sequence< _Sequence >::_M_transfer_from_if()
__gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::operator=()
__gnu_debug::_Safe_local_iterator< _Iterator, _Sequence >::operator=()
__gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::operator=()
__gnu_debug::_Safe_local_iterator< _Iterator, _Sequence >::operator=()

`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. so yes, the version check is literally the whole personality here.

Referenced by:

__gnu_debug::_Safe_iterator_base::_M_invalidate()
__gnu_debug::_Safe_sequence< _Sequence >::_M_transfer_from_if()
__gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::_M_value_initialized()
__gnu_debug::_Safe_local_iterator< _Iterator, _Sequence >::_M_value_initialized()
__gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::operator=()
__gnu_debug::_Safe_local_iterator< _Iterator, _Sequence >::operator=()
__gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >::operator=()
__gnu_debug::_Safe_local_iterator< _Iterator, _Sequence >::operator=()

🫶 Author 🫶

Generated automatically by Doxygen for libstdc++ from the source code.

and that’s the whole page, bestie 🫶 — huge slay to libstdc++ and the source/version + date stamped in the footer, mwah 💅✨

📦 where this page comes from

ubuntu noble: libstdc++-14-doc 14-20240412-0ubuntu1
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-06: a language model's rewrite of the original, under its terms

__GNU_DEBUG::_SAFE_ITERATOR(3cxx)

💖 __gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category > 💖

🌸 NAME 🌸

✨ SYNOPSIS ✨

🎀 Public Types 🎀

💅 Public Member Functions 💅

🌟 Static Public Member Functions 🌟

🦋 Public Attributes 🦋

🔒 Protected Types 🔒

🧚 Protected Member Functions 🧚

🫶 Friends 🫶

🌈 Detailed Description 🌈

🧁 Constructor & Destructor Documentation 🧁

🍓 _Safe_iterator ()

🍓 _Safe_iterator (_Iterator __i, const _Safe_sequence_base *__seq)

🍓 _Safe_iterator (const _Safe_iterator< _Iterator, _Sequence, _Category > & __x)

🍓 _Safe_iterator (_Safe_iterator< _Iterator, _Sequence, _Category > && __x)

🍓 converting constructor from mutable iterator to constant iterator

🌺 Member Function Documentation 🌺

💫 _M_attach (_Safe_sequence_base * __seq)

💫 __gnu_debug::_Safe_iterator_base::_M_attach (_Safe_sequence_base * __seq, bool __constant)

preincrement core: operator++ ()

postincrement era: operator++ (int)

arrow moment: operator-> ()

move assignment: operator= (_Safe_iterator &&)

copy assignment: operator= (const _Safe_iterator &)

🌸 Member Data Documentation 🌸

_Safe_iterator_base* __gnu_debug::_Safe_iterator_base::_M_next [inherited]

_Safe_iterator_base* __gnu_debug::_Safe_iterator_base::_M_prior [inherited]

_Safe_sequence_base* __gnu_debug::_Safe_iterator_base::_M_sequence [inherited]

unsigned int __gnu_debug::_Safe_iterator_base::_M_version [inherited]

🫶 Author 🫶

💖 `__gnu_debug::_Safe_iterator< _Iterator, _Sequence, _Category >` 💖

🍓 `_Safe_iterator ()`

🍓 `_Safe_iterator (_Iterator __i, const _Safe_sequence_base *__seq)`

🍓 `_Safe_iterator (const _Safe_iterator< _Iterator, _Sequence, _Category > & __x)`

🍓 `_Safe_iterator (_Safe_iterator< _Iterator, _Sequence, _Category > && __x)`

💫 `_M_attach (_Safe_sequence_base * __seq)`

💫 `__gnu_debug::_Safe_iterator_base::_M_attach (_Safe_sequence_base * seq, bool constant)`

preincrement core: `operator++ ()`

postincrement era: `operator++ (int)`

arrow moment: `operator-> ()`

move assignment: `operator= (_Safe_iterator &&)`

copy assignment: `operator= (const _Safe_iterator &)`

`_Safe_iterator_base* __gnu_debug::_Safe_iterator_base::_M_next [inherited]`

`_Safe_iterator_base* __gnu_debug::_Safe_iterator_base::_M_prior [inherited]`

`_Safe_sequence_base* __gnu_debug::_Safe_iterator_base::_M_sequence [inherited]`

`unsigned int __gnu_debug::_Safe_iterator_base::_M_version [inherited]`