jh::avl::tree_map< K, V, Alloc >::iterator Struct Reference

Bidirectional iterator providing in-order traversal. More...

#include <jh/core/ordered_map.h>

Public Types
using	base_type = tree_map
	Owning tree type.
using	node_type = detail::node_t<K, V>
	Canonical node type used internally.
using	iterator_concept = std::bidirectional_iterator_tag
	Iterator concept tag (bidirectional).
using	value_type = detail::base_t<K, V>
	Value type exposed by dereferencing.
using	reference = detail::reference_t<K, V>
	Reference type: const for set, mutable for map.
using	pointer = detail::pointer_t<K, V>
	Pointer type: const for set, mutable for map.
using	difference_type = std::int64_t
	Difference type used for iterator arithmetic.

Public Member Functions
	iterator ()=default
	Default-construct an iterator in a singular state.
	iterator (base_type *t, std::size_t i)
	Construct an iterator referring to a specific node index.
reference	operator* ()
	Dereference the iterator and obtain the referenced value.
pointer	operator-> ()
	Dereference the iterator and obtain a pointer to the value.
reference	operator* () const
	Const-qualified dereference.
pointer	operator-> () const
	Const-qualified pointer dereference.
const node_type::key_type &	key () const
	Obtain the key associated with the current node.
iterator &	operator++ ()
	Advance to the in-order successor.
iterator	operator++ (int)
	Post-increment: return the previous iterator value and advance to the in-order successor.
iterator &	operator-- ()
	Move to the in-order predecessor.
iterator	operator-- (int)
	Post-decrement: return the previous iterator value and move to the in-order predecessor.
bool	operator== (const iterator &other) const
	Compare two iterators for equality.
bool	operator!= (const iterator &other) const
	Compare two iterators for inequality.

Public Attributes
base_type *	tree = nullptr
	Owning tree instance (never nullptr except for default-constructed iterator).
std::size_t	idx = static_cast<std::size_t>(-1)
	Index of the referenced node, or -1 for end().

Detailed Description

template<typename K, typename V, typename Alloc = std::allocator<detail::value_t<K, V>>>
struct jh::avl::tree_map< K, V, Alloc >::iterator

Bidirectional iterator providing in-order traversal.

Iterator validity follows standard associative-container semantics:

• erase(pos) returns an iterator referring to the element that follows the erased one in sorted order. If no such element exists, the returned iterator is end().

• The returned iterator is the only one whose continued use is well-defined. All other iterators obtained before the erase operation must be considered invalid.

• Insertions and erasures may relocate internal nodes to maintain contiguous storage. Therefore no iterator stability guarantees exist except for the iterator returned by erase().

Dereferencing a valid iterator yields the stored element. Increment and decrement perform in-order successor/predecessor traversal with amortized constant cost.

Constructor & Destructor Documentation

iterator() [1/2]

template<typename K, typename V, typename Alloc = std::allocator<detail::value_t<K, V>>>

jh::avl::tree_map< K, V, Alloc >::iterator::iterator ( )

default

Default-construct an iterator in a singular state.

A default-constructed iterator does not refer to any tree and is therefore singular. It must not be compared, incremented, decremented, or dereferenced. The only valid operations on a singular iterator are assignment and destruction.

Note that this state is distinct from end(): an end iterator is associated with a specific container and can be decremented to obtain the last element, whereas a singular iterator cannot participate in any traversal.

iterator() [2/2]

template<typename K, typename V, typename Alloc = std::allocator<detail::value_t<K, V>>>

jh::avl::tree_map< K, V, Alloc >::iterator::iterator ( base_type * t, std::size_t i )

inline

Construct an iterator referring to a specific node index.

Parameters

t	Pointer to the owning tree.
i	Node index, or -1 to represent end().

This constructor is primarily used internally when producing begin(), end(), and traversal results. Users normally do not instantiate iterators directly.

Member Function Documentation

key()

template<typename K, typename V, typename Alloc = std::allocator<detail::value_t<K, V>>>

const node_type::key_type & jh::avl::tree_map< K, V, Alloc >::iterator::key ( ) const

inlinenodiscard

Obtain the key associated with the current node.

Returns

Constant reference to the key of the referenced element.

Provided as a convenience for callers that require direct access to the ordering key. Undefined behavior if the iterator equals end().

operator!=()

template<typename K, typename V, typename Alloc = std::allocator<detail::value_t<K, V>>>

bool jh::avl::tree_map< K, V, Alloc >::iterator::operator!= ( const iterator & other ) const

inline

Compare two iterators for inequality.

Equivalent to !(a == b).

Returns

true if the iterators are not equal.

operator*() [1/2]

template<typename K, typename V, typename Alloc = std::allocator<detail::value_t<K, V>>>

reference jh::avl::tree_map< K, V, Alloc >::iterator::operator* ( )

inline

Dereference the iterator and obtain the referenced value.

Returns

Reference to the value stored at the current position.

Undefined behavior occurs if the iterator does not refer to a valid element (e.g., it equals end()).

operator*() [2/2]

template<typename K, typename V, typename Alloc = std::allocator<detail::value_t<K, V>>>

reference jh::avl::tree_map< K, V, Alloc >::iterator::operator* ( ) const

inline

Const-qualified dereference.

Returns

Const reference to the stored value.

Undefined behavior if the iterator equals end().

operator++() [1/2]

template<typename K, typename V, typename Alloc = std::allocator<detail::value_t<K, V>>>

iterator & jh::avl::tree_map< K, V, Alloc >::iterator::operator++ ( )

inline

Advance to the in-order successor.

Performs an in-order successor step. The behavior follows standard bidirectional-iterator rules:

• If the iterator is end(), incrementing leaves it unchanged.
• Otherwise, the iterator moves to the next element in sorted key order.
• Undefined behavior results if the iterator is in a singular state (e.g., default-constructed).

Returns

Reference to *this.

operator++() [2/2]

template<typename K, typename V, typename Alloc = std::allocator<detail::value_t<K, V>>>

iterator jh::avl::tree_map< K, V, Alloc >::iterator::operator++ ( int )

inline

Post-increment: return the previous iterator value and advance to the in-order successor.

Equivalent to creating a copy, performing ++(*this), and returning the saved copy. Follows the same semantic rules as operator++().

Returns

A copy of the iterator before incrementing.

operator--() [1/2]

template<typename K, typename V, typename Alloc = std::allocator<detail::value_t<K, V>>>

iterator & jh::avl::tree_map< K, V, Alloc >::iterator::operator-- ( )

inline

Move to the in-order predecessor.

Performs an in-order predecessor step. Bidirectional-iterator semantics apply:

• If the iterator is end(), decrementing moves it to the last element (the greatest key), or leaves it unchanged if the container is empty.

• If the iterator refers to the first element (begin()), decrementing moves it to end().

• Otherwise, the iterator moves to the previous element in sorted key order.

• Undefined behavior results if the iterator is singular (e.g., default-constructed).

Returns

Reference to *this.

operator--() [2/2]

template<typename K, typename V, typename Alloc = std::allocator<detail::value_t<K, V>>>

iterator jh::avl::tree_map< K, V, Alloc >::iterator::operator-- ( int )

inline

Post-decrement: return the previous iterator value and move to the in-order predecessor.

Equivalent to creating a copy, performing –(*this), and returning the saved copy. Follows the same semantic rules as operator--().

Returns

A copy of the iterator before decrementing.

operator->() [1/2]

template<typename K, typename V, typename Alloc = std::allocator<detail::value_t<K, V>>>

pointer jh::avl::tree_map< K, V, Alloc >::iterator::operator-> ( )

inline

Dereference the iterator and obtain a pointer to the value.

Returns

Pointer to the referenced element.

Undefined behavior if the iterator equals end().

operator->() [2/2]

template<typename K, typename V, typename Alloc = std::allocator<detail::value_t<K, V>>>

pointer jh::avl::tree_map< K, V, Alloc >::iterator::operator-> ( ) const

inline

Const-qualified pointer dereference.

Returns

Pointer to the constant stored value.

Undefined behavior if the iterator equals end().

operator==()

template<typename K, typename V, typename Alloc = std::allocator<detail::value_t<K, V>>>

bool jh::avl::tree_map< K, V, Alloc >::iterator::operator== ( const iterator & other ) const

inline

Compare two iterators for equality.

Two iterators are equal only if they refer to the same container and the same logical position. Singular iterators compare equal only if both are singular.

Returns

true if both iterators are equal.

---

The documentation for this struct was generated from the following file:

• include/jh/core/ordered_map.h