`double_list` Class Template

A class template for a doubly linked list of nodes. More...

Declaration

template <class T, class L = double_list_links> class micro_os_plus::utils::double_list<T, L> { ... }

Included Headers

Public Member Typedefs Index

template <class T, class L = double_list_links>
using	is_statically_allocated = typename links_type::is_statically_allocated
	Type indicating if the links node is statically allocated. More...

template <class T, class L = double_list_links>
using	iterator = double_list_iterator< value_type >
	Type of iterator over the values. More...

template <class T, class L = double_list_links>
using	iterator_pointer = value_type *
	Type of reference to the iterator internal pointer. More...

template <class T, class L = double_list_links>
using	links_type = L
	Type of the links node object where the pointers to the list head and tail are stored. More...

template <class T, class L = double_list_links>
using	pointer = value_type *
	Type of pointer to object pointed to by the iterator. More...

template <class T, class L = double_list_links>
using	reference = value_type &
	Type of reference to object pointed to by the iterator. More...

template <class T, class L = double_list_links>
using	value_type = T
	Type of value pointed to by the iterator. More...

Public Constructors Index

template <class T, class L = double_list_links>
double_list ()
	Construct a doubly linked list. More...

template <class T, class L = double_list_links>
double_list (const double_list &)=delete
	Deleted copy constructor. More...

template <class T, class L = double_list_links>
double_list (double_list &&)=delete
	Deleted move constructor. More...

Public Destructor Index

template <class T, class L = double_list_links>
constexpr	~double_list ()
	Destruct the list. More...

Public Operators Index

template <class T, class L = double_list_links>
double_list &	operator= (const double_list &)=delete
	Deleted copy assignment operator. More...

template <class T, class L = double_list_links>
double_list &	operator= (double_list &&)=delete
	Deleted move assignment operator. More...

Public Member Functions Index

template <class T, class L = double_list_links>
iterator	begin () const
	Iterator begin. More...

template <class T, class L = double_list_links>
void	clear (void)
	Clear the list. More...

template <class T, class L = double_list_links>
bool	empty (void) const
	Check if the list is empty. More...

template <class T, class L = double_list_links>
iterator	end () const
	Iterator end. More...

template <class T, class L = double_list_links>
constexpr pointer	head (void) const
	Get the list head. More...

template <class T, class L = double_list_links>
void	initialize_once (void)
	Initialize the list only at first run. More...

template <class T, class L = double_list_links>
void	link_head (reference node)
	Add a node to the head of the list. More...

template <class T, class L = double_list_links>
void	link_tail (reference node)
	Add a node to the tail of the list. More...

template <class T, class L = double_list_links>
constexpr const links_type *	links_pointer (void) const
	Get the address of the node storing the list links. More...

template <class T, class L = double_list_links>
constexpr pointer	tail (void) const
	Get the list tail. More...

template <class T, class L = double_list_links>
bool	uninitialized (void) const
	Check if the list is uninitialised (only statically allocated lists can be uninitialised). More...

Protected Member Attributes Index

template <class T, class L = double_list_links>
links_type	links_
	The list top node used to point to head and tail nodes. More...

Description

A class template for a doubly linked list of nodes.

Template Parameters

T	Type of the elements linked into the list, derived from class double_list_links_base.
L	Type of the links node (either double_list_links or static_double_list_links).

This class implements a generic doubly linked list, maintaining a pair of head and tail pointers to allow efficient iteration and manipulation of nodes. The list elements (of type T) must be derived from double_list_links_base (typically from double_list_links) and extended with the required payload, which may be the actual content or a pointer to it.

The class uses composition for the links node, rather than inheritance, to avoid inheriting unwanted methods. Iterators return pointers to the list elements, enabling traversal of the list in a manner similar to standard containers.

info

Only forward iterators are provided by default, but reverse iterators can be added if required.

Definition at line 679 of file lists.h.

Public Member Typedefs

is_statically_allocated

template <class T, class L = double_list_links>

using micro_os_plus::utils::double_list< T, L >::is_statically_allocated = typename links_type::is_statically_allocated

Type indicating if the links node is statically allocated.

Definition at line 721 of file lists.h.

721 using is_statically_allocated =

iterator

template <class T, class L = double_list_links>

using micro_os_plus::utils::double_list< T, L >::iterator = double_list_iterator<value_type>

Type of iterator over the values.

Definition at line 711 of file lists.h.

711 using iterator = double_list_iterator<value_type>;

iterator_pointer

template <class T, class L = double_list_links>

using micro_os_plus::utils::double_list< T, L >::iterator_pointer = value_type*

Type of reference to the iterator internal pointer.

Definition at line 716 of file lists.h.

716 using iterator_pointer = value_type*;

links_type

template <class T, class L = double_list_links>

using micro_os_plus::utils::double_list< T, L >::links_type = L

Type of the links node object where the pointers to the list head and tail are stored.

Definition at line 691 of file lists.h.

691 using links_type = L;

pointer

template <class T, class L = double_list_links>

using micro_os_plus::utils::double_list< T, L >::pointer = value_type*

Type of pointer to object pointed to by the iterator.

Definition at line 701 of file lists.h.

701 using pointer = value_type*;

reference

template <class T, class L = double_list_links>

using micro_os_plus::utils::double_list< T, L >::reference = value_type&

Type of reference to object pointed to by the iterator.

Definition at line 706 of file lists.h.

706 using reference = value_type&;

value_type

template <class T, class L = double_list_links>

using micro_os_plus::utils::double_list< T, L >::value_type = T

Type of value pointed to by the iterator.

Definition at line 696 of file lists.h.

696 using value_type = T;

Public Constructors

double_list()

template <class T, class L = double_list_links>

micro_os_plus::utils::double_list< T, L >::double_list ()

Construct a doubly linked list.

For non-statically allocated lists, the initial list status is empty after construction, meaning the list is ready for use and contains no nodes.

For statically allocated lists, the list remains uninitialised after construction, with its internal pointers set to nullptr. Such lists require explicit initialisation (typically via initialize_once()) before use.

This constructor does not clear or modify the internal pointers for statically allocated lists, relying on zero-initialisation by the runtime. For dynamically allocated lists, it calls clear() to ensure the list is in a valid empty state.

The rule of five: The copy constructor, move constructor, copy assignment operator, and move assignment operator are explicitly deleted to prevent accidental copying or moving of intrusive_list objects. This ensures the integrity of the list structure, as duplicating or moving lists could result in invalid or inconsistent links within the list.

Declaration at line 727 of file lists.h, definition at line 486 of file lists-inlines.h.

486 double_list<T, L>::double_list ()

487 {

488#if defined(MICRO_OS_PLUS_TRACE_UTILS_LISTS_CONSTRUCT)

489 trace::printf ("%s() @%p \n", __func__, this);

490#endif

491

492 if constexpr (is_statically_allocated::value)

493 {

494 // By all means, do not add any code to clear the pointers, since

495 // the links node was statically initialised.

496 }

497 else

498 {

499 clear ();

500 }

501 }

Reference micro_os_plus::utils::double_list< T, L >::clear.

Referenced by micro_os_plus::utils::double_list< T, L >::double_list, micro_os_plus::utils::double_list< T, L >::double_list, micro_os_plus::utils::double_list< T, L >::operator= and micro_os_plus::utils::double_list< T, L >::operator=.

double_list()

template <class T, class L = double_list_links>

micro_os_plus::utils::double_list< T, L >::double_list (const double_list &)

delete

Deleted copy constructor.

Copying of double_list instances is explicitly disallowed to prevent accidental duplication, which could compromise the integrity of the list structure.

Definition at line 737 of file lists.h.

Reference micro_os_plus::utils::double_list< T, L >::double_list.

double_list()

template <class T, class L = double_list_links>

micro_os_plus::utils::double_list< T, L >::double_list (double_list &&)

delete

Deleted move constructor.

Moving of double_list instances is explicitly disallowed to avoid invalid or inconsistent links within the list that could result from moving lists.

Definition at line 747 of file lists.h.

Reference micro_os_plus::utils::double_list< T, L >::double_list.

Public Destructor

~double_list()

template <class T, class L = double_list_links>

micro_os_plus::utils::double_list< T, L >::~double_list ()

constexpr

Destruct the list.

Normally at this point there must be no nodes in the list. However, for statically allocated lists, this might not be always true due to their lifetime and initialization patterns.

info

In debug mode, the destructor emits a warning if the list is not empty when destroyed, helping to catch potential resource leaks or logic errors in list management.

Declaration at line 775 of file lists.h, definition at line 516 of file lists-inlines.h.

516 constexpr double_list<T, L>::~double_list ()

517 {

518#if defined(MICRO_OS_PLUS_TRACE_UTILS_LISTS_CONSTRUCT)

519 trace::printf ("%s() @%p \n", __func__, this);

520#endif

521

522 // Perhaps enable it for non statically allocated lists.

523 // assert (empty ());

524#if defined(MICRO_OS_PLUS_TRACE_UTILS_LISTS)

525 if (!empty ())

526 {

527 trace::printf ("%s() @%p list not empty\n", __func__, this);

528 }

529#endif

530 }

Reference micro_os_plus::utils::double_list< T, L >::empty.

Public Operators

operator=()

template <class T, class L = double_list_links>

double_list & micro_os_plus::utils::double_list< T, L >::operator= (const double_list &)

delete

Deleted copy assignment operator.

Copy assignment is explicitly disallowed to prevent accidental overwriting of list objects, which could lead to corruption of the list structure.

Definition at line 758 of file lists.h.

Reference micro_os_plus::utils::double_list< T, L >::double_list.

operator=()

template <class T, class L = double_list_links>

double_list & micro_os_plus::utils::double_list< T, L >::operator= (double_list &&)

delete

Deleted move assignment operator.

Move assignment is explicitly disallowed to avoid invalid or inconsistent links within the list that could result from moving lists.

Definition at line 769 of file lists.h.

Reference micro_os_plus::utils::double_list< T, L >::double_list.

Public Member Functions

begin()

template <class T, class L = double_list_links>

double_list< T, L >::iterator micro_os_plus::utils::double_list< T, L >::begin ()

Iterator begin.

Returns: An iterator to the first element.

Returns an iterator to the first element in the list. For statically allocated lists, asserts that the list is already initialised. The iterator will point to the node after the internal links node (the head). If the list is empty, the iterator will compare equal to end().

Declaration at line 871 of file lists.h, definition at line 691 of file lists-inlines.h.

691 double_list<T, L>::begin () const

692 {

693 if constexpr (is_statically_allocated::value)

694 {

695 assert (!links_.uninitialized ());

696 }

697

698 return iterator{ static_cast<iterator_pointer> (links_.next ()) };

699 }

Reference micro_os_plus::utils::double_list< T, L >::links_.

clear()

template <class T, class L = double_list_links>

void micro_os_plus::utils::double_list< T, L >::clear (void)

Clear the list.

Parameters: None.

Returns: Nothing.

The clear() method initialises the mandatory internal links node so that both its previous_ and next_ pointers refer to itself. This marks the list as empty and ensures it is in a safe, known state, ready for new insertions. This operation is typically used to reset the list, removing all elements and breaking any existing links.

Declaration at line 821 of file lists.h, definition at line 601 of file lists-inlines.h.

601 double_list<T, L>::clear (void)

602 {

603#if defined(MICRO_OS_PLUS_TRACE_UTILS_LISTS)

604 trace::printf ("%s() @%p\n", __func__, this);

605#endif

606 links_.initialize ();

607 }

Reference micro_os_plus::utils::double_list< T, L >::links_.

Referenced by micro_os_plus::utils::double_list< T, L >::double_list.

empty()

template <class T, class L = double_list_links>

bool micro_os_plus::utils::double_list< T, L >::empty (void)

Check if the list is empty.

Parameters: None.

Return Values

true	The list has no nodes.
false	The list has at least one node.

Checks whether the list contains any nodes. The list is considered empty if the internal links node is not linked to any other nodes. This method provides a fast way to determine if the list has elements or is currently empty.

Declaration at line 810 of file lists.h, definition at line 585 of file lists-inlines.h.

585 double_list<T, L>::empty (void) const

586 {

587 // If the links node is not linked, the list is empty.

588 return !links_.linked ();

589 }

Reference micro_os_plus::utils::double_list< T, L >::links_.

Referenced by micro_os_plus::utils::double_list< T, L >::~double_list and micro_os_plus::utils::intrusive_list< T, N, MP, L, U >::empty.

end()

template <class T, class L = double_list_links>

double_list< T, L >::iterator micro_os_plus::utils::double_list< T, L >::end ()

Iterator end.

Returns: An iterator positioned after the last element.

Returns an iterator to the position after the last element in the list (the end iterator). This iterator points to the internal links node, which acts as a sentinel. It is used as the past-the-end marker in iteration and comparison operations. The end iterator does not reference any valid list element.

Declaration at line 879 of file lists.h, definition at line 711 of file lists-inlines.h.

711 double_list<T, L>::end () const

712 {

713 // The assert would probably be redundant, since it was

714 // already tested in `begin()`.

715

716 return iterator{ reinterpret_cast<iterator_pointer> (

717 const_cast<links_type*> (&links_)) };

718 }

Reference micro_os_plus::utils::double_list< T, L >::links_.

head()

template <class T, class L = double_list_links>

double_list< T, L >::pointer micro_os_plus::utils::double_list< T, L >::head (void)

constexpr

Get the list head.

Parameters: None.

Returns: Pointer to the head node.

Returns a pointer to the first node in the list. If the list is empty, this will point to the internal links node itself, which can be used to detect the end of the list during iteration. The returned pointer should be checked against end() or the sentinel node to determine if the list contains any elements.

Declaration at line 831 of file lists.h, definition at line 619 of file lists-inlines.h.

619 double_list<T, L>::head (void) const

620 {

621 return reinterpret_cast<pointer> (links_.next ());

622 }

Reference micro_os_plus::utils::double_list< T, L >::links_.

Referenced by micro_os_plus::utils::double_list< T, L >::link_head and micro_os_plus::utils::intrusive_list< T, N, MP, L, U >::link_head.

initialize_once()

template <class T, class L = double_list_links>

void micro_os_plus::utils::double_list< T, L >::initialize_once (void)

Initialize the list only at first run.

Parameters: None.

Returns: Nothing.

If the statically allocated list is still in the initial uninitialised state (with both pointers null), this method initialises the list to the empty state, with both pointers pointing to itself. For non-statically initialised lists, this method has no effect.

info

Must be manually called for statically allocated lists before inserting elements or performing any other operations.

Declaration at line 799 of file lists.h, definition at line 568 of file lists-inlines.h.

568 double_list<T, L>::initialize_once (void)

569 {

570 if constexpr (is_statically_allocated::value)

571 {

572 links_.initialize_once ();

573 }

574 }

Reference micro_os_plus::utils::double_list< T, L >::links_.

Referenced by micro_os_plus::utils::intrusive_list< T, N, MP, L, U >::initialize_once.

link_head()

template <class T, class L = double_list_links>

void micro_os_plus::utils::double_list< T, L >::link_head (reference node)

Add a node to the head of the list.

Parameters

[in] node

Reference to the node to add.

Returns: Nothing.

Adds a new node to the beginning (head) of the list. For statically allocated lists, asserts that the list is already initialised. The new node is linked before the current head node, updating the list structure accordingly. This operation does not check for duplicate nodes or whether the node is already linked elsewhere.

Declaration at line 861 of file lists.h, definition at line 670 of file lists-inlines.h.

670 double_list<T, L>::link_head (reference node)

671 {

672 if constexpr (is_statically_allocated::value)

673 {

674 assert (!links_.uninitialized ());

675 }

676

677 // Add the new node at the head of the list.

678 head ()->link_previous (&node);

679 }

References micro_os_plus::utils::double_list< T, L >::head and micro_os_plus::utils::double_list< T, L >::links_.

link_tail()

template <class T, class L = double_list_links>

void micro_os_plus::utils::double_list< T, L >::link_tail (reference node)

Add a node to the tail of the list.

Parameters

[in] node

Reference to the node to add.

Returns: Nothing.

Adds a new node to the end (tail) of the list. For statically allocated lists, asserts that the list is already initialised. The new node is linked after the current tail node, updating the list structure accordingly. This operation does not check for duplicate nodes or whether the node is already linked elsewhere.

Declaration at line 851 of file lists.h, definition at line 649 of file lists-inlines.h.

649 double_list<T, L>::link_tail (reference node)

650 {

651 if constexpr (is_statically_allocated::value)

652 {

653 assert (!links_.uninitialized ());

654 }

655

656 // Add new node at the end of the list.

657 tail ()->link_next (&node);

658 }

References micro_os_plus::utils::double_list< T, L >::links_ and micro_os_plus::utils::double_list< T, L >::tail.

links_pointer()

template <class T, class L = double_list_links>

const links_type * micro_os_plus::utils::double_list< T, L >::links_pointer (void)

inline constexpr

Get the address of the node storing the list links.

Parameters: None.

Returns: A pointer to the list head object.

Definition at line 891 of file lists.h.

891 links_pointer (void) const

892 {

893 return &links_;

894 }

Reference micro_os_plus::utils::double_list< T, L >::links_.

Referenced by micro_os_plus::utils::intrusive_list< T, N, MP, L, U >::end.

tail()

template <class T, class L = double_list_links>

double_list< T, L >::pointer micro_os_plus::utils::double_list< T, L >::tail (void)

constexpr

Get the list tail.

Parameters: None.

Returns: Pointer to the tail node.

Returns a pointer to the last node in the list. If the list is empty, this will point to the internal links node itself, which can be used to detect the end of the list during reverse iteration. The returned pointer should be checked against the sentinel node to determine if the list contains any elements.

Declaration at line 841 of file lists.h, definition at line 634 of file lists-inlines.h.

634 double_list<T, L>::tail (void) const

635 {

636 return reinterpret_cast<pointer> (links_.previous ());

637 }

Reference micro_os_plus::utils::double_list< T, L >::links_.

Referenced by micro_os_plus::utils::double_list< T, L >::link_tail and micro_os_plus::utils::intrusive_list< T, N, MP, L, U >::link_tail.

uninitialized()

template <class T, class L = double_list_links>

bool micro_os_plus::utils::double_list< T, L >::uninitialized (void)

Check if the list is uninitialised (only statically allocated lists can be uninitialised).

Parameters: None.

Return Values

true	The list was not initialised.
false	The list was initialised.

An uninitialized node is a node with any of the pointers set to nullptr. Only statically allocated nodes in the initial state are considered uninitialized. For dynamically allocated lists, this method always returns false since their nodes are explicitly initialized during construction.

Declaration at line 788 of file lists.h, definition at line 542 of file lists-inlines.h.

542 double_list<T, L>::uninitialized (void) const

543 {

544 if constexpr (is_statically_allocated::value)

545 {

546 return links_.uninitialized ();

547 }

548 else

549 {

550 return false;

551 }

552 }

Reference micro_os_plus::utils::double_list< T, L >::links_.

Protected Member Attributes

links_

template <class T, class L = double_list_links>

links_type micro_os_plus::utils::double_list< T, L >::links_

protected

The list top node used to point to head and tail nodes.

This member stores the internal links node for the list. The next pointer of this node points to the head of the list, and the previous pointer points to the tail. For an empty list, both pointers refer to the node itself, simplifying list management and boundary checks.

Definition at line 909 of file lists.h.

909 links_type links_;

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

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.14.0.

Declaration​

Included Headers​

Public Member Typedefs Index​

Public Constructors Index​

Public Destructor Index​

Public Operators Index​

Public Member Functions Index​

Protected Member Attributes Index​

Description​

Public Member Typedefs​

is_statically_allocated​

iterator​

iterator_pointer​

links_type​

pointer​

reference​

value_type​

Public Constructors​

double_list()​

double_list()​

double_list()​

Public Destructor​

~double_list()​

Public Operators​

operator=()​

operator=()​

Public Member Functions​

begin()​

clear()​

empty()​

end()​

head()​

initialize_once()​

link_head()​

link_tail()​

links_pointer()​

tail()​

uninitialized()​

Protected Member Attributes​

links_​

Declaration

Included Headers

Public Member Typedefs Index

Public Constructors Index

Public Destructor Index

Public Operators Index

Public Member Functions Index

Protected Member Attributes Index

Description

Public Member Typedefs

is_statically_allocated

iterator

iterator_pointer

links_type

pointer

reference

value_type

Public Constructors

double_list()

double_list()

double_list()

Public Destructor

~double_list()

Public Operators

operator=()

operator=()

Public Member Functions

begin()

clear()

empty()

end()

head()

initialize_once()

link_head()

link_tail()

links_pointer()

tail()

uninitialized()

Protected Member Attributes

links_