`intrusive_list_iterator` Class Template

A class template for the intrusive list iterator. More...

Declaration

template <class T, class N, N T::* MP, class U = T>
class micro_os_plus::utils::intrusive_list_iterator<T, N, MP, U> { ... }

Included Headers

#include "micro-os-plus/utils/lists.h"

Public Member Typedefs Index

template <class T, class N, N T::* MP, class U = T>
using	difference_type = ptrdiff_t
	Type of pointer difference. More...

template <class T, class N, N T::* MP, class U = T>
using	iterator_category = std::bidirectional_iterator_tag
	Category of iterator. More...

template <class T, class N, N T::* MP, class U = T>
using	iterator_pointer = N *
	Type of reference to the iterator internal pointer. More...

template <class T, class N, N T::* MP, class U = T>
using	pointer = value_type *
	Type of pointer to object pointed to by the iterator. More...

template <class T, class N, N T::* MP, class U = T>
using	reference = value_type &
	Type of reference to object pointed to by the iterator. More...

template <class T, class N, N T::* MP, class U = T>
using	value_type = U
	Type of value pointed to by the iterator. More...

Public Constructors Index

template <class T, class N, N T::* MP, class U = T>
constexpr	intrusive_list_iterator () noexcept
	Default constructor. Constructs an iterator pointing to nullptr. More...

template <class T, class N, N T::* MP, class U = T>
constexpr	intrusive_list_iterator (iterator_pointer const node) noexcept
	Construct an iterator from a node pointer. More...

template <class T, class N, N T::* MP, class U = T>
constexpr	intrusive_list_iterator (reference element) noexcept
	Construct an iterator from a reference to an element. More...

Public Operators Index

template <class T, class N, N T::* MP, class U = T>
reference	operator* () const noexcept
	Dereference operator. More...

template <class T, class N, N T::* MP, class U = T>
constexpr intrusive_list_iterator &	operator++ () noexcept
	Pre-increment operator. More...

template <class T, class N, N T::* MP, class U = T>
constexpr intrusive_list_iterator	operator++ (int) noexcept
	Post-increment operator. More...

template <class T, class N, N T::* MP, class U = T>
constexpr intrusive_list_iterator &	operator-- () noexcept
	Pre-decrement operator. More...

template <class T, class N, N T::* MP, class U = T>
constexpr intrusive_list_iterator	operator-- (int) noexcept
	Post-decrement operator. More...

template <class T, class N, N T::* MP, class U = T>
pointer	operator-> () const noexcept
	Pointer access operator. More...

template <class T, class N, N T::* MP, class U = T>
constexpr bool	operator== (const intrusive_list_iterator &other) const noexcept
	Equality comparison operator. More...

Public Member Functions Index

template <class T, class N, N T::* MP, class U = T>
constexpr iterator_pointer	get_iterator_pointer (void) const noexcept
	Retrieve the iterator pointer for the current node. More...

template <class T, class N, N T::* MP, class U = T>
pointer	get_pointer (void) const noexcept
	Get the object pointer from the intrusive node. More...

Protected Member Attributes Index

template <class T, class N, N T::* MP, class U = T>
iterator_pointer	node_
	Pointer to intrusive node. More...

Description

A class template for the intrusive list iterator.

Template Parameters

T	Type of object that includes the intrusive node.
N	Type of intrusive node. Must have the public members previous & next.
MP	Name of the intrusive node member in object T.
U	Type stored in the list, derived from T.

This class provides an interface similar to std::list::iterator, except that it keeps track of the offset where the intrusive list element is located in the parent object. It supports bidirectional iteration and access to the underlying object and node.

Definition at line 70 of file intrusive-list.h.

Public Member Typedefs

difference_type

template <class T, class N, N T::* MP, class U = T>

using micro_os_plus::utils::intrusive_list_iterator< T, N, MP, U >::difference_type = ptrdiff_t

Type of pointer difference.

Definition at line 96 of file intrusive-list.h.

96 using difference_type = ptrdiff_t;

iterator_category

template <class T, class N, N T::* MP, class U = T>

using micro_os_plus::utils::intrusive_list_iterator< T, N, MP, U >::iterator_category = std::bidirectional_iterator_tag

Category of iterator.

Definition at line 101 of file intrusive-list.h.

101 using iterator_category = std::bidirectional_iterator_tag;

iterator_pointer

template <class T, class N, N T::* MP, class U = T>

using micro_os_plus::utils::intrusive_list_iterator< T, N, MP, U >::iterator_pointer = N*

Type of reference to the iterator internal pointer.

Definition at line 91 of file intrusive-list.h.

91 using iterator_pointer = N*;

pointer

template <class T, class N, N T::* MP, class U = T>

using micro_os_plus::utils::intrusive_list_iterator< T, N, MP, U >::pointer = value_type*

Type of pointer to object pointed to by the iterator.

Definition at line 81 of file intrusive-list.h.

81 using pointer = value_type*;

reference

template <class T, class N, N T::* MP, class U = T>

using micro_os_plus::utils::intrusive_list_iterator< T, N, MP, U >::reference = value_type&

Type of reference to object pointed to by the iterator.

Definition at line 86 of file intrusive-list.h.

86 using reference = value_type&;

value_type

template <class T, class N, N T::* MP, class U = T>

using micro_os_plus::utils::intrusive_list_iterator< T, N, MP, U >::value_type = U

Type of value pointed to by the iterator.

Definition at line 76 of file intrusive-list.h.

76 using value_type = U;

Public Constructors

intrusive_list_iterator()

template <class T, class N, N T::* MP, class U = T>

micro_os_plus::utils::intrusive_list_iterator< T, N, MP, U >::intrusive_list_iterator ()

constexpr noexcept

Default constructor. Constructs an iterator pointing to nullptr.

The default constructor for intrusive_list_iterator initialises the iterator to a null state, meaning it does not point to any node in the list. This is typically used to create an "end" iterator or to initialise an iterator variable before assigning it to a valid node.

info

The internal node pointer is value-initialised (set to nullptr), ensuring that the iterator is safe to use in comparisons and will not dereference an invalid address.

Declaration at line 109 of file intrusive-list.h, definition at line 68 of file intrusive-list-inlines.h.

68 U>::intrusive_list_iterator () noexcept

69 : node_{}

70 {

71 }

References micro_os_plus::utils::intrusive_list_iterator< T, N, MP, U >::intrusive_list_iterator and micro_os_plus::utils::intrusive_list_iterator< T, N, MP, U >::node_.

Referenced by micro_os_plus::utils::intrusive_list_iterator< T, N, MP, U >::intrusive_list_iterator and micro_os_plus::utils::intrusive_list_iterator< T, N, MP, U >::operator==.

intrusive_list_iterator()

template <class T, class N, N T::* MP, class U = T>

micro_os_plus::utils::intrusive_list_iterator< T, N, MP, U >::intrusive_list_iterator (iterator_pointer const node)

explicit constexpr noexcept

Construct an iterator from a node pointer.

Parameters

node	Pointer to the node to which the iterator should point.

This constructor creates an intrusive_list_iterator that points to the specified node. The internal node pointer is set to the provided node address, allowing the iterator to traverse the list starting from that node. This is typically used to initialise an iterator to a specific position within the list, such as the beginning or end.

Declaration at line 116 of file intrusive-list.h, definition at line 82 of file intrusive-list-inlines.h.

82 constexpr intrusive_list_iterator<T, N, MP, U>::intrusive_list_iterator (

83 N* const node) noexcept

84 : node_{ node }

85 {

86 }

Reference micro_os_plus::utils::intrusive_list_iterator< T, N, MP, U >::node_.

intrusive_list_iterator()

template <class T, class N, N T::* MP, class U = T>

micro_os_plus::utils::intrusive_list_iterator< T, N, MP, U >::intrusive_list_iterator (reference element)

explicit constexpr noexcept

Construct an iterator from a reference to an element.

Parameters

element

Reference to the element to which the iterator should point.

info

This constructor is only available when U is derived from (or is the same type as) T, as required by std::derived_from<U, T>.

This constructor creates an intrusive_list_iterator that points to the specified element. The internal node pointer is set to the address of the intrusive node member within the given element, allowing the iterator to traverse the list starting from that element. This is typically used to initialise an iterator to a specific object in the list.

Declaration at line 129 of file intrusive-list.h, definition at line 97 of file intrusive-list-inlines.h.

97 constexpr intrusive_list_iterator<T, N, MP, U>::intrusive_list_iterator (

98 reference element) noexcept

99 requires std::derived_from<U, T>

100 : node_{ &(element.*MP) }

101 {

102 }

Reference micro_os_plus::utils::intrusive_list_iterator< T, N, MP, U >::node_.

Public Operators

operator--()

template <class T, class N, N T::* MP, class U = T>

intrusive_list_iterator< T, N, MP, U > & micro_os_plus::utils::intrusive_list_iterator< T, N, MP, U >::operator-- ()

constexpr noexcept

Pre-decrement operator.

Returns: Reference to the decremented iterator.

The pre-decrement operator (operator--) moves the intrusive list iterator to the previous node in the list. It updates the internal node pointer to point to the node returned by the current node's previous() method. This enables backward traversal of the list, following the linked structure in reverse.

Declaration at line 173 of file intrusive-list.h, definition at line 180 of file intrusive-list-inlines.h.

180 intrusive_list_iterator<T, N, MP, U>::operator--() noexcept

181 {

182 node_ = static_cast<iterator_pointer> (node_->previous ());

183 return *this;

184 }

Reference micro_os_plus::utils::intrusive_list_iterator< T, N, MP, U >::node_.

operator--()

template <class T, class N, N T::* MP, class U = T>

intrusive_list_iterator< T, N, MP, U > micro_os_plus::utils::intrusive_list_iterator< T, N, MP, U >::operator-- (int)

constexpr noexcept

Post-decrement operator.

Returns: Iterator before decrement.

The post-decrement operator (operator--(int)) moves the intrusive list iterator to the previous node in the list, but returns a copy of the iterator as it was before the decrement. This enables iteration logic that requires access to the current element before moving backward, following the standard C++ iterator semantics for post-decrement.

Declaration at line 181 of file intrusive-list.h, definition at line 196 of file intrusive-list-inlines.h.

196 intrusive_list_iterator<T, N, MP, U>::operator--(int) noexcept

197 {

198 const auto tmp = *this;

199 node_ = static_cast<iterator_pointer> (node_->previous ());

200 return tmp;

201 }

Reference micro_os_plus::utils::intrusive_list_iterator< T, N, MP, U >::node_.

operator->()

template <class T, class N, N T::* MP, class U = T>

intrusive_list_iterator< T, N, MP, U >::pointer micro_os_plus::utils::intrusive_list_iterator< T, N, MP, U >::operator-> ()

inline nodiscard noexcept

Pointer access operator.

Returns: Pointer to the value pointed to by the iterator.

The pointer access operator (operator->) allows the intrusive list iterator to provide direct access to the value pointed to by the iterator, mimicking the behavior of a raw pointer. Internally, it calls get_pointer(), which computes and returns a pointer to the underlying value or object associated with the current node in the list.

Declaration at line 141 of file intrusive-list.h, definition at line 114 of file intrusive-list-inlines.h.

114 intrusive_list_iterator<T, N, MP, U>::operator->() const noexcept

115 {

116 return get_pointer ();

117 }

Reference micro_os_plus::utils::intrusive_list_iterator< T, N, MP, U >::get_pointer.

operator*()

template <class T, class N, N T::* MP, class U = T>

intrusive_list_iterator< T, N, MP, U >::reference micro_os_plus::utils::intrusive_list_iterator< T, N, MP, U >::operator* ()

inline nodiscard noexcept

Dereference operator.

Returns: Reference to the value pointed to by the iterator.

The dereference operator (operator*) provides access to the value or object pointed to by the iterator. Internally, it calls get_pointer() to obtain a pointer to the underlying value or object associated with the current node in the list, and then dereferences it to return a reference.

This allows the iterator to be used in a manner similar to standard C++ iterators, enabling direct access to the list element for reading or modification.

Declaration at line 149 of file intrusive-list.h, definition at line 132 of file intrusive-list-inlines.h.

132 intrusive_list_iterator<T, N, MP, U>::operator*() const noexcept

133 {

134 return *get_pointer ();

135 }

Reference micro_os_plus::utils::intrusive_list_iterator< T, N, MP, U >::get_pointer.

operator++()

template <class T, class N, N T::* MP, class U = T>

intrusive_list_iterator< T, N, MP, U > & micro_os_plus::utils::intrusive_list_iterator< T, N, MP, U >::operator++ ()

constexpr noexcept

Pre-increment operator.

Returns: Reference to the incremented iterator.

The pre-increment operator (operator++) advances the intrusive list iterator to the next node in the list. It updates the internal node pointer to point to the node returned by the current node's next() method. This enables forward traversal of the list, following the linked structure.

Declaration at line 157 of file intrusive-list.h, definition at line 147 of file intrusive-list-inlines.h.

147 intrusive_list_iterator<T, N, MP, U>::operator++() noexcept

148 {

149 node_ = static_cast<iterator_pointer> (node_->next ());

150 return *this;

151 }

Reference micro_os_plus::utils::intrusive_list_iterator< T, N, MP, U >::node_.

operator++()

template <class T, class N, N T::* MP, class U = T>

intrusive_list_iterator< T, N, MP, U > micro_os_plus::utils::intrusive_list_iterator< T, N, MP, U >::operator++ (int)

constexpr noexcept

Post-increment operator.

Returns: Iterator before increment.

The post-increment operator (operator++(int)) advances the intrusive list iterator to the next node in the list, but returns a copy of the iterator as it was before the increment. This allows iteration logic that requires access to the current element before moving to the next one, following the standard C++ iterator semantics for post-increment.

Declaration at line 165 of file intrusive-list.h, definition at line 163 of file intrusive-list-inlines.h.

163 intrusive_list_iterator<T, N, MP, U>::operator++(int) noexcept

164 {

165 const auto tmp = *this;

166 node_ = static_cast<iterator_pointer> (node_->next ());

167 return tmp;

168 }

Reference micro_os_plus::utils::intrusive_list_iterator< T, N, MP, U >::node_.

operator==()

template <class T, class N, N T::* MP, class U = T>

bool micro_os_plus::utils::intrusive_list_iterator< T, N, MP, U >::operator== (const intrusive_list_iterator & other)

nodiscard constexpr noexcept

Equality comparison operator.

Parameters

other

Iterator to compare with.

Returns: true if both iterators point to the same node, false otherwise.

info

The inequality operator (!=) is synthesised automatically by the compiler from this operator (C++20).

The equality comparison operator (operator==) checks whether two intrusive list iterators point to the same node in the list by comparing their internal node pointers. This enables standard iterator comparisons, such as detecting the end of a range or verifying if two iterators refer to the same position within the list.

Declaration at line 195 of file intrusive-list.h, definition at line 213 of file intrusive-list-inlines.h.

213 intrusive_list_iterator<T, N, MP, U>::operator==(

214 const intrusive_list_iterator& other) const noexcept

215 {

216 return node_ == other.node_;

217 }

References micro_os_plus::utils::intrusive_list_iterator< T, N, MP, U >::intrusive_list_iterator and micro_os_plus::utils::intrusive_list_iterator< T, N, MP, U >::node_.

Public Member Functions

get_iterator_pointer()

template <class T, class N, N T::* MP, class U = T>

intrusive_list_iterator< T, N, MP, U >::iterator_pointer micro_os_plus::utils::intrusive_list_iterator< T, N, MP, U >::get_iterator_pointer (void)

nodiscard constexpr noexcept

Retrieve the iterator pointer for the current node.

Parameters: None.

Returns: The iterator pointer corresponding to the current node.

Returns a pointer to the internal iterator node associated with the current object. This is typically used for advanced list operations or when direct access to the underlying node is required.

Declaration at line 215 of file intrusive-list.h, definition at line 258 of file intrusive-list-inlines.h.

258 intrusive_list_iterator<T, N, MP, U>::get_iterator_pointer () const noexcept

259 {

260 return node_;

261 }

Reference micro_os_plus::utils::intrusive_list_iterator< T, N, MP, U >::node_.

get_pointer()

template <class T, class N, N T::* MP, class U = T>

intrusive_list_iterator< T, N, MP, U >::pointer micro_os_plus::utils::intrusive_list_iterator< T, N, MP, U >::get_pointer (void)

inline nodiscard noexcept

Get the object pointer from the intrusive node.

Parameters: None.

Returns: Pointer to the parent object.

Computes and returns a pointer to the parent object that contains the intrusive node currently referenced by the iterator. This is achieved by calculating the offset of the intrusive node member within the parent object type and subtracting it from the node's address. This technique allows the iterator to provide access to the full object from just the node pointer, enabling intrusive list traversal and manipulation.

Declaration at line 205 of file intrusive-list.h, definition at line 230 of file intrusive-list-inlines.h.

230 intrusive_list_iterator<T, N, MP, U>::get_pointer (void) const noexcept

231 {

232 // static_assert(std::is_convertible<U, T>::value == true, "U must be

233 // implicitly convertible to T!");

234

235 // Compute the byte offset of the intrusive node member within T.

236 // Note: dereferencing a null pointer is formally undefined behaviour

237 // under the C++ standard. In practice, no known compiler miscompiles

238 // this idiom on any supported target; `offsetof` cannot be used here

239 // because `MP` is a template parameter (a pointer-to-member), not a

240 // literal member name.

241 const auto offset = reinterpret_cast<difference_type> (

242 &(static_cast<T*> (nullptr)->*MP));

243

244 // Compute the address of the object which includes the

245 // intrusive node, by adjusting down the node address.

246 return reinterpret_cast<pointer> (reinterpret_cast<difference_type> (node_)

247 - offset);

248 }

Reference micro_os_plus::utils::intrusive_list_iterator< T, N, MP, U >::node_.

Referenced by micro_os_plus::utils::intrusive_list_iterator< T, N, MP, U >::operator* and micro_os_plus::utils::intrusive_list_iterator< T, N, MP, U >::operator->.

Protected Member Attributes

node_

template <class T, class N, N T::* MP, class U = T>

iterator_pointer micro_os_plus::utils::intrusive_list_iterator< T, N, MP, U >::node_

protected

Pointer to intrusive node.

Stores the address of the current intrusive node in the list.

Definition at line 224 of file intrusive-list.h.

224 iterator_pointer node_;

The documentation for this class was generated from the following files:

Generated via doxygen2docusaurus 2.2.2 by Doxygen 1.17.0.

Declaration​

Included Headers​

Public Member Typedefs Index​

Public Constructors Index​

Public Operators Index​

Public Member Functions Index​

Protected Member Attributes Index​

Description​

Public Member Typedefs​

difference_type​

iterator_category​

iterator_pointer​

pointer​

reference​

value_type​

Public Constructors​

intrusive_list_iterator()​

intrusive_list_iterator()​

intrusive_list_iterator()​

Public Operators​

operator--()​

operator--()​

operator->()​

operator*()​

operator++()​

operator++()​

operator==()​

Public Member Functions​

get_iterator_pointer()​

get_pointer()​

Protected Member Attributes​

node_​

Declaration

Included Headers

Public Member Typedefs Index

Public Constructors Index

Public Operators Index

Public Member Functions Index

Protected Member Attributes Index

Description

Public Member Typedefs

difference_type

iterator_category

iterator_pointer

pointer

reference

value_type

Public Constructors

intrusive_list_iterator()

intrusive_list_iterator()

intrusive_list_iterator()

Public Operators

operator--()

operator--()

operator->()

operator*()

operator++()

operator++()

operator==()

Public Member Functions

get_iterator_pointer()

get_pointer()

Protected Member Attributes

node_