iox::cxx::list

C++11 compatible bi-directional list implementation. More...

#include <iceoryx_hoofs/cxx/list.hpp>

Public Types

	Name
using IteratorBase< false >	iterator
using IteratorBase< true >	const_iterator
using T	value_type
using decltype(Capacity)	size_type

Public Functions

	Name
	list() constructor for an empty list (of T-types elements)
	~list() destructs the list and also calls the destructor of all contained elements
	list(const list & rhs) copy constructor list including elements
	list(list && rhs) move constructor list including elements
list &	operator=(const list & rhs) copy assignment, each element is copied (added) to the constructed list any existing elements in 'this'/lhs are removed (same behaviour as std::list : Assigns new contents to the container, replacing its current contents, and modifying its size accordingly.)
list &	operator=(list && rhs) move assignment, list is cleared and initialized, elements are moved from source list any existing elements in 'this'/lhs are removed (same behaviour as std::list : Assigns new contents to the container, replacing its current contents, and modifying its size accordingly.)
iterator	begin() default list operation to retrieve an interator to first list element
const_iterator	begin() const default list operation to retrieve an const_iterator to first list element
const_iterator	cbegin() const default list operation to retrieve an const_iterator to first list element
iterator	end() default list operation to retrieve an interator to end of list (behind last valid element) Terminated when content is attemted to read (operator*, operator->)
const_iterator	end() const default list operation to retrieve an const_iterator to end of list (behind last valid element) Terminated when content is attemted to read (operator*, operator->)
const_iterator	cend() const default list operation to retrieve an const_iterator to end of list (behind last valid element) Terminated when content is attemted to read (operator*, operator->)
bool	empty() const list meta information on filling
bool	full() const list meta information on filling
size_type	size() const list meta information on filling
size_type	capacity() const list meta information, maximum number of elements the list can contain
size_type	max_size() const list meta information, maximum number of elements the list can contain
T &	front() Returns a reference to the first element in the container. calling front() on an empty list will terminate() the processing.
const T &	front() const Returns a reference to the first element in the container. calling front() on an empty list will terminate() the processing.
T &	back() Returns a reference to the last element in the container. calling back() on an empty list will terminate() the processing.
const T &	back() const Returns a reference to the last element in the container. calling back() on an empty list will terminate() the processing.
bool	push_front(const T & data) add element to the beginning of the list
bool	push_front(T && data) add element to the beginning of the list via move
bool	push_back(const T & data) add element to the end of the list
bool	push_back(T && data) add element to the end of the list via move
bool	pop_front() remove the first element from the begining of the list element destructor will be invoked
bool	pop_back() remove the last element from the end of the list element destructor will be invoked
void	clear() remove all elements from the list, list will be empty element destructors will be invoked
iterator	erase(const_iterator iter) remove next element from linked iterator position element destructors will be invoked recursive calls to erase_after only delete each 2nd element
size_type	remove(const T & data) remove all elements which matches the given comparing element (compare by value) requires a the template type T to have operator== defined.
template <typename UnaryPredicate > size_type	remove_if(UnaryPredicate pred) remove all elements which matches the provided comparison function requires a the template type T to have a operator== defined.
template <typename... ConstructorArgs> T &	emplace_front(ConstructorArgs &&... args) construct element inplace at begining of list
template <typename... ConstructorArgs> T &	emplace_back(ConstructorArgs &&... args) construct element inplace at end of list
template <typename... ConstructorArgs> iterator	emplace(const_iterator iter, ConstructorArgs &&... args) construct element inplace at iterator position
iterator	insert(const_iterator citer, const T & data) insert element before iterator position
iterator	insert(const_iterator citer, T && data) add element before the pointed-to element via move

Detailed Description

template <typename T ,
uint64_t Capacity>
class iox::cxx::list;

C++11 compatible bi-directional list implementation.

Adjustments in the API were done to not use exceptions and serve the requirement of a data structure movable over shared memory. attempt to add elements to a full list will be ignored. Capacity must at least be 1, (unintended) negative initialization is rejected with compile assertion limitation: concurrency concerns have to be handled by client side.

overview of cxx::forward_list deviations to std::forward_list(C++11)

• list declaration with mandatory max list size argument
• member functions don't throw exception but will trigger different failure handling
• push_front/~_back returns a bool (instead of void) informing on successful insertion (true)
• pop_front/~_back returns a bool (instead of void) informing on successful removal (true), otherwise empty (false)
• emplace_front/~_back returns a reference to the inserted element (instead of void), this is C++17-conform
• remove / remove_if returns a the number of removed elements (instead of void), this is C++20-conform

(yet) missing implementations

• allocator, difference_type / range operations
• assign, resize, swap, merge, splice_after, reverse, rbegin/crbegin, rend/crend, unique, sort
• list operator==, operator!=, operator<, operator<=, operator>, operator>= Ttype user data to be managed within list

Capacitynumber of maximum list elements a client can push to the list. minimum value is '1'

Public Types Documentation

using iterator

using iox::cxx::list< T, Capacity >::iterator =  IteratorBase<false>;

using const_iterator

using iox::cxx::list< T, Capacity >::const_iterator =  IteratorBase<true>;

using value_type

using iox::cxx::list< T, Capacity >::value_type =  T;

using size_type

using iox::cxx::list< T, Capacity >::size_type =  decltype(Capacity);

Public Functions Documentation

function list

list()

constructor for an empty list (of T-types elements)

function ~list

~list()

destructs the list and also calls the destructor of all contained elements

function list

list(
    const list & rhs
)

copy constructor list including elements

Parameters:

• rhs is the list to copy from (same capacity)

function list

list(
    list && rhs
)

move constructor list including elements

Parameters:

• rhs is the list to move-construct elements from (same capacity)

function operator=

list & operator=(
    const list & rhs
)

copy assignment, each element is copied (added) to the constructed list any existing elements in 'this'/lhs are removed (same behaviour as std::list : Assigns new contents to the container, replacing its current contents, and modifying its size accordingly.)

Parameters:

• rhs is the list to copy from (same capacity)

Return: reference to created list

function operator=

list & operator=(
    list && rhs
)

move assignment, list is cleared and initialized, elements are moved from source list any existing elements in 'this'/lhs are removed (same behaviour as std::list : Assigns new contents to the container, replacing its current contents, and modifying its size accordingly.)

Parameters:

• rhs is the list to move from ('source', same capacity)

Return: reference to created list

function begin

iterator begin()

default list operation to retrieve an interator to first list element

Return: iterator to first list element, returns iterator to end() when list is empty

function begin

const_iterator begin() const

default list operation to retrieve an const_iterator to first list element

Return: iterator to first list element, returns iterator to end() when list is empty

function cbegin

const_iterator cbegin() const

default list operation to retrieve an const_iterator to first list element

Return: iterator to first list element, returns iterator to end() when list is empty

function end

iterator end()

default list operation to retrieve an interator to end of list (behind last valid element) Terminated when content is attemted to read (operator*, operator->)

Return: iterator to end element, does not contain data.

function end

const_iterator end() const

default list operation to retrieve an const_iterator to end of list (behind last valid element) Terminated when content is attemted to read (operator*, operator->)

Return: iterator to end element, does not contain data.

function cend

const_iterator cend() const

default list operation to retrieve an const_iterator to end of list (behind last valid element) Terminated when content is attemted to read (operator*, operator->)

Return: iterator to end element, does not contain data.

function empty

bool empty() const

list meta information on filling

Return: no elements in list (true), otherwise (false)

function full

bool full() const

list meta information on filling

Return: whether list is full (filled with 'capacity' / 'max_size' elements) (true), otherwise (false)

function size

size_type size() const

list meta information on filling

Return: current number of elements in list @min returns min 0 @max returns max capacity

function capacity

size_type capacity() const

list meta information, maximum number of elements the list can contain

Return: list has been initialized with the following number of elements.

function max_size

size_type max_size() const

list meta information, maximum number of elements the list can contain

Return: list has been initialized with the following number of elements, same as capacity()

function front

T & front()

Returns a reference to the first element in the container. calling front() on an empty list will terminate() the processing.

Return: reference to the first element

function front

const T & front() const

Returns a reference to the first element in the container. calling front() on an empty list will terminate() the processing.

Return: const reference to the first element

function back

T & back()

Returns a reference to the last element in the container. calling back() on an empty list will terminate() the processing.

Return: reference to the last element

function back

const T & back() const

Returns a reference to the last element in the container. calling back() on an empty list will terminate() the processing.

Return: const reference to the last element

function push_front

bool push_front(
    const T & data
)

add element to the beginning of the list

Parameters:

• data reference to data element

Return: successful insertion (true), otherwise no element could be added to list (e.g. full -> false)

function push_front

bool push_front(
    T && data
)

add element to the beginning of the list via move

Parameters:

• data universal reference perfectly forwarded to client class

Return: successful insertion (true), otherwise no element could be added to list (e.g. full -> false)

function push_back

bool push_back(
    const T & data
)

add element to the end of the list

Parameters:

• data reference to data element

Return: successful insertion (true), otherwise no element could be added to list (e.g. full -> false)

function push_back

bool push_back(
    T && data
)

add element to the end of the list via move

Parameters:

• data universal reference perfectly forwarded to client class

Return: successful insertion (true), otherwise no element could be added to list (e.g. full -> false)

function pop_front

bool pop_front()

remove the first element from the begining of the list element destructor will be invoked

Return: successful removal (true), otherwise no element could be taken from list (e.g. empty -> false)

function pop_back

bool pop_back()

remove the last element from the end of the list element destructor will be invoked

Return: successful removal (true), otherwise no element could be taken from list (e.g. empty -> false)

function clear

void clear()

remove all elements from the list, list will be empty element destructors will be invoked

function erase

iterator erase(
    const_iterator iter
)

remove next element from linked iterator position element destructors will be invoked recursive calls to erase_after only delete each 2nd element

Parameters:

• iter iterator linking the to-be-removed element

Return: an (non-const_) iterator to the element after the removed element, returns end() element when reached end of list

function remove

size_type remove(
    const T & data
)

remove all elements which matches the given comparing element (compare by value) requires a the template type T to have operator== defined.

Parameters:

• data value to compare to

Return: the number of elements removed, return is C++20-conform

function remove_if

template <typename UnaryPredicate >
size_type remove_if(
    UnaryPredicate pred
)

remove all elements which matches the provided comparison function requires a the template type T to have a operator== defined.

Parameters:

• pred unary predicate which returns true if the element should be removed

Return: the number of elements removed, return is C++20-conform

function emplace_front

template <typename... ConstructorArgs>
T & emplace_front(
    ConstructorArgs &&... args
)

construct element inplace at begining of list

Parameters:

• args T-typed construction parameters (initializer list)

Return: referene to generated element, return is C++17-conform

function emplace_back

template <typename... ConstructorArgs>
T & emplace_back(
    ConstructorArgs &&... args
)

construct element inplace at end of list

Parameters:

• args T-typed construction parameters (initializer list)

Return: referene to generated element, return is C++17-conform

function emplace

template <typename... ConstructorArgs>
iterator emplace(
    const_iterator iter,
    ConstructorArgs &&... args
)

construct element inplace at iterator position

Parameters:

• args T-typed construction parameters (initializer list)
• iter position in list to (construct)insert after

Return: iterator to the newly added element

function insert

iterator insert(
    const_iterator citer,
    const T & data
)

insert element before iterator position

Parameters:

• citer iterator with the position to insert after
• data reference to element to add

Return: iterator to the newly added element

function insert

iterator insert(
    const_iterator citer,
    T && data
)

add element before the pointed-to element via move

Parameters:

• citer iterator with the position to insert after
• data universal reference perfectly forwarded to client class

Return: iterator to the newly added element

---

Updated on 2 April 2022 at 16:37:47 CEST