Skip to content

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:11:42 CET