iox::cxx::forward_list

C++11 compatible uni-directional forward list implementation. More...

#include <iceoryx_hoofs/cxx/forward_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
	forward_list() constructor for an empty list (of T-types elements)
	~forward_list() destructs the list and also calls the destructor of all contained elements
	forward_list(const forward_list & rhs) copy constructor list including elements
	forward_list(forward_list && rhs) move constructor list including elements
forward_list &	operator=(const forward_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.)
forward_list &	operator=(forward_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	before_begin() retrieve an interator before first element only allowed for usage in erase_after, insert_after, emplace_after Terminated when content is attemted to read (operator*, operator->)
const_iterator	before_begin() const retrieve a const_iterator before first element only allowed for usage in erase_after, insert_after, emplace_after
const_iterator	cbefore_begin() const const_iterator an interator before first element only allowed for usage in erase_after, insert_after, emplace_after
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.
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	pop_front() remove the first element from the begining 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_after(const_iterator beforeToBeErasedIter) 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> iterator	emplace_after(const_iterator afterToBeEmplacedIter, ConstructorArgs &&... args) construct element inplace after the pointed-to element
iterator	insert_after(const_iterator citer, const T & data) insert element after iterator position
iterator	insert_after(const_iterator citer, T && data) add element after the pointed-to element via move

Detailed Description

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

C++11 compatible uni-directional forward 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 returns a bool (instead of void) informing on successful insertion (true)
• pop_front returns a bool (instead of void) informing on successful removal (true), otherwise empty (false)
• emplace_front 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 based operations
• assign, resize, swap, merge, splice_after, reverse, 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::forward_list< T, Capacity >::iterator =  IteratorBase<false>;

using const_iterator

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

using value_type

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

using size_type

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

Public Functions Documentation

function forward_list

forward_list()

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

function ~forward_list

~forward_list()

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

function forward_list

forward_list(
    const forward_list & rhs
)

copy constructor list including elements

Parameters:

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

function forward_list

forward_list(
    forward_list && rhs
)

move constructor list including elements

Parameters:

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

function operator=

forward_list & operator=(
    const forward_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=

forward_list & operator=(
    forward_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 before_begin

iterator before_begin()

retrieve an interator before first element only allowed for usage in erase_after, insert_after, emplace_after Terminated when content is attemted to read (operator*, operator->)

Return: iterator to fictional element before first data element

function before_begin

const_iterator before_begin() const

retrieve a const_iterator before first element only allowed for usage in erase_after, insert_after, emplace_after

Return: iterator to fictional element before first data element

function cbefore_begin

const_iterator cbefore_begin() const

const_iterator an interator before first element only allowed for usage in erase_after, insert_after, emplace_after

Return: iterator to fictional element before first data element

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 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 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 clear

void clear()

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

function erase_after

iterator erase_after(
    const_iterator beforeToBeErasedIter
)

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

Parameters:

• beforeToBeErasedIter iterator linking the element before 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_after

template <typename... ConstructorArgs>
iterator emplace_after(
    const_iterator afterToBeEmplacedIter,
    ConstructorArgs &&... args
)

construct element inplace after the pointed-to element

Parameters:

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

Return: iterator to the newly added element

function insert_after

iterator insert_after(
    const_iterator citer,
    const T & data
)

insert element after 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_after

iterator insert_after(
    const_iterator citer,
    T && data
)

add element after 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 18 December 2023 at 13:02:34 CET