 |
utils-lists 4.0.2
The µOS++ Intrusive Lists
|
|
utils-lists 4.0.2
The µOS++ Intrusive Lists
|
A class template for a doubly linked list of nodes. More...
#include <micro-os-plus/utils/lists.h>
Public Types | |
| using | is_statically_allocated |
| Type indicating if the links node is statically allocated. | |
| using | iterator = double_list_iterator<value_type> |
| Type of iterator over the values. | |
| using | iterator_pointer = value_type* |
| Type of reference to the iterator internal pointer. | |
| using | links_type = L |
| Type of the links node object where the pointers to the list head and tail are stored. | |
| using | pointer = value_type* |
| Type of pointer to object pointed to by the iterator. | |
| using | reference = value_type& |
| Type of reference to object pointed to by the iterator. | |
| using | value_type = T |
| Type of value pointed to by the iterator. | |
Public Member Functions | |
| double_list () | |
| Construct a doubly linked list. | |
| double_list (const double_list &)=delete | |
| Deleted copy constructor. | |
| double_list (double_list &&)=delete | |
| Deleted move constructor. | |
| constexpr | ~double_list () |
| Destruct the list. | |
| iterator | begin () const |
| Iterator begin. | |
| void | clear (void) |
| Clear the list. | |
| bool | empty (void) const |
| Check if the list is empty. | |
| iterator | end () const |
| Iterator end. | |
| constexpr pointer | head (void) const |
| Get the list head. | |
| void | initialize_once (void) |
| Initialize the list only at first run. | |
| void | link_head (reference node) |
| Add a node to the head of the list. | |
| void | link_tail (reference node) |
| Add a node to the tail of the list. | |
| constexpr const links_type * | links_pointer (void) const |
| Get the address of the node storing the list links. | |
| double_list & | operator= (const double_list &)=delete |
| Deleted copy assignment operator. | |
| double_list & | operator= (double_list &&)=delete |
| Deleted move assignment operator. | |
| constexpr pointer | tail (void) const |
| Get the list tail. | |
| bool | uninitialized (void) const |
| Check if the list is uninitialised (only statically allocated lists can be uninitialised). | |
Protected Attributes | |
| links_type | links_ |
| The list top node used to point to head and tail nodes. | |
A class template for a doubly linked list of nodes.
| 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.
| using micro_os_plus::utils::double_list< T, L >::is_statically_allocated |
| using micro_os_plus::utils::double_list< T, L >::iterator = double_list_iterator<value_type> |
| using micro_os_plus::utils::double_list< T, L >::iterator_pointer = value_type* |
| using micro_os_plus::utils::double_list< T, L >::links_type = L |
| using micro_os_plus::utils::double_list< T, L >::pointer = value_type* |
| using micro_os_plus::utils::double_list< T, L >::reference = value_type& |
| using micro_os_plus::utils::double_list< T, L >::value_type = T |
| 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.
Definition at line 486 of file lists-inlines.h.
|
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.
|
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.
|
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.
Definition at line 516 of file lists-inlines.h.
| double_list< T, L >::iterator micro_os_plus::utils::double_list< T, L >::begin | ( | ) | const |
Iterator begin.
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().
Definition at line 691 of file lists-inlines.h.
| void micro_os_plus::utils::double_list< T, L >::clear | ( | void | ) |
Clear the list.
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.
Definition at line 601 of file lists-inlines.h.
| bool micro_os_plus::utils::double_list< T, L >::empty | ( | void | ) | const |
Check if the list is empty.
| 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.
Definition at line 585 of file lists-inlines.h.
| double_list< T, L >::iterator micro_os_plus::utils::double_list< T, L >::end | ( | ) | const |
Iterator end.
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.
Definition at line 711 of file lists-inlines.h.
|
constexpr |
Get the list head.
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.
Definition at line 619 of file lists-inlines.h.
| void micro_os_plus::utils::double_list< T, L >::initialize_once | ( | void | ) |
Initialize the list only at first run.
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.
Definition at line 568 of file lists-inlines.h.
| void micro_os_plus::utils::double_list< T, L >::link_head | ( | reference | node | ) |
Add a node to the head of the list.
| [in] | node | Reference to the node to add. |
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.
Definition at line 670 of file lists-inlines.h.
| void micro_os_plus::utils::double_list< T, L >::link_tail | ( | reference | node | ) |
Add a node to the tail of the list.
| [in] | node | Reference to the node to add. |
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.
Definition at line 649 of file lists-inlines.h.
|
inlineconstexpr |
|
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.
|
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.
|
constexpr |
Get the list tail.
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.
Definition at line 634 of file lists-inlines.h.
| bool micro_os_plus::utils::double_list< T, L >::uninitialized | ( | void | ) | const |
Check if the list is uninitialised (only statically allocated lists can be uninitialised).
| 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.
Definition at line 542 of file lists-inlines.h.
|
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.
1.13.2