jaulib v1.3.6
Jau Support Library (C++, Java, ..)
Loading...
Searching...
No Matches
jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container > Class Template Reference

Implementation of a Copy-On-Write (CoW) read-onlu iterator over immutable value_type storage. More...

#include <cow_iterator.hpp>

Inheritance diagram for jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >:
Collaboration diagram for jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >:

Public Types

typedef CoW_container cow_container_t
 
typedef storage_t::difference_type difference_type
 
typedef sub_traits_t::iterator_category iterator_category
 
typedef storage_t::const_iterator iterator_type
 Actual const iterator type of the contained native iterator, probably a simple pointer.
 
typedef sub_traits_t::pointer pointer
 
typedef sub_traits_t::reference reference
 
typedef storage_t::size_type size_type
 
typedef Storage_ref_type storage_ref_t
 
typedef Storage_type storage_t
 
typedef sub_traits_t::value_type value_type
 

Public Member Functions

constexpr cow_ro_iterator () noexcept
 
constexpr cow_ro_iterator (const cow_ro_iterator &o) noexcept
 
constexpr cow_ro_iterator (cow_ro_iterator &&o) noexcept
 
constexpr iterator_type base () const noexcept
 Returns a copy of the underlying storage const_iterator.
 
constexpr bool capacity_reached () const noexcept
 Returns true if storage capacity has been reached and the next push_back() will grow the storage and invalidates all iterators and references.
 
constexpr cow_ro_iterator cbegin () const noexcept
 Returns a new const_iterator pointing to the first element, aka begin.
 
constexpr cow_ro_iterator cend () const noexcept
 Returns a new const_iterator pointing to the element following the last element, aka end.
 
constexpr int compare (const cow_ro_iterator &rhs) const noexcept
 Returns signum or three-way comparison value.
 
constexpr int compare (const cow_rw_iterator< storage_t, storage_ref_t, cow_container_t > &rhs) const noexcept
 
constexpr difference_type dist_begin () const noexcept
 Returns the distance to_begin() using zero as first index.
 
constexpr difference_type dist_end () const noexcept
 Returns the distance to_end() using zero as first index.
 
constexpr difference_type distance (const cow_rw_iterator< storage_t, storage_ref_t, cow_container_t > &rhs) const noexcept
 
constexpr bool empty () const noexcept
 Returns true if storage is empty().
 
std::string get_info () const noexcept
 
constexpr bool is_begin () const noexcept
 Returns true, if this iterator points to cbegin().
 
constexpr bool is_end () const noexcept
 Returns true, if this iterator points to cend().
 
constexpr const reference operator* () const noexcept
 
constexpr cow_ro_iterator operator+ (difference_type rhs) const noexcept
 Binary 'iterator + element_count'; Try to avoid: Low performance due to returning copy-ctor.
 
constexpr cow_ro_iteratoroperator++ () noexcept
 Pre-increment; Well performing, return *this.
 
constexpr cow_ro_iterator operator++ (int) noexcept
 Post-increment; Try to avoid: Low performance due to returning copy-ctor.
 
constexpr cow_ro_iteratoroperator+= (difference_type i) noexcept
 Addition-assignment of 'element_count'; Well performing, return *this.
 
constexpr difference_type operator- (const cow_ro_iterator &rhs) const noexcept
 Binary 'iterator - iterator -> element_count'; Well performing, return element_count of type difference_type.
 
constexpr cow_ro_iterator operator- (difference_type rhs) const noexcept
 Binary 'iterator - element_count'; Try to avoid: Low performance due to returning copy-ctor.
 
constexpr cow_ro_iteratoroperator-- () noexcept
 Pre-decrement; Well performing, return *this.
 
constexpr cow_ro_iterator operator-- (int) noexcept
 Post-decrement; Try to avoid: Low performance due to returning copy-ctor.
 
constexpr cow_ro_iteratoroperator-= (difference_type i) noexcept
 Subtraction-assignment of 'element_count'; Well performing, return *this.
 
constexpr const pointer operator-> () const noexcept
 
std::strong_ordering operator<=> (const cow_ro_iterator &rhs) const noexcept
 Three way std::strong_ordering comparison operator, C++20.
 
constexpr cow_ro_iteratoroperator= (const cow_ro_iterator &o) noexcept
 
constexpr cow_ro_iteratoroperator= (cow_ro_iterator &&o) noexcept
 
constexpr bool operator== (const cow_ro_iterator &rhs) const noexcept
 Two way comparison operator, != is implicit, C++20.
 
constexpr const reference operator[] (difference_type i) const noexcept
 Subscript of 'element_index', returning immutable Value_type reference.
 
constexpr size_type size () const noexcept
 Return the size of the underlying value_type store.
 
constexpr storage_tstorage () const noexcept
 Returns this instances' underlying shared storage by reference.
 
void swap (cow_ro_iterator &o) noexcept
 
constexpr cow_ro_iteratorto_begin () noexcept
 This iterator is set to the first element, cbegin().
 
constexpr cow_ro_iteratorto_end () noexcept
 This iterator is set to the last element, cend().
 
std::string toString () const noexcept
 

Friends

template<typename, typename, typename, bool, bool>
class cow_darray
 
template<typename, typename>
class cow_vector
 

Detailed Description

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
class jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >

Implementation of a Copy-On-Write (CoW) read-onlu iterator over immutable value_type storage.


Instance holds a shared storage snapshot of the parents' CoW storage until destruction.

Implementation complies with Type Traits iterator_category 'random_access_iterator_tag'

Implementation simply wraps the native iterator of type 'iterator_type' and manages the CoW related resource lifecycle.

This iterator is the preferred choice if no mutations are made to the elements state itself, or all changes can be discarded after the iterator's destruction.
This avoids the costly mutex lock and storage copy of jau::cow_rw_iterator.
Also see jau::for_each_fidelity to iterate through in this good faith fashion.

To allow data-race free operations on this iterator's data snapshot from a potentially mutated CoW, only one begin iterator should be retrieved from CoW and all further operations shall use jau::cow_ro_iterator::size(), jau::cow_ro_iterator::begin() and jau::cow_ro_iterator::end().

See also
jau::cow_ro_iterator::size()
jau::cow_ro_iterator::begin()
jau::cow_ro_iterator::end()
jau::for_each_fidelity
jau::cow_darray

Definition at line 642 of file cow_iterator.hpp.

Member Typedef Documentation

◆ storage_t

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
typedef Storage_type jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::storage_t

Definition at line 648 of file cow_iterator.hpp.

◆ storage_ref_t

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
typedef Storage_ref_type jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::storage_ref_t

Definition at line 649 of file cow_iterator.hpp.

◆ cow_container_t

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
typedef CoW_container jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::cow_container_t

Definition at line 650 of file cow_iterator.hpp.

◆ iterator_type

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
typedef storage_t::const_iterator jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::iterator_type

Actual const iterator type of the contained native iterator, probably a simple pointer.

Definition at line 653 of file cow_iterator.hpp.

◆ iterator_category

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
typedef sub_traits_t::iterator_category jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::iterator_category

Definition at line 665 of file cow_iterator.hpp.

◆ size_type

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
typedef storage_t::size_type jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::size_type

Definition at line 667 of file cow_iterator.hpp.

◆ difference_type

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
typedef storage_t::difference_type jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::difference_type

Definition at line 668 of file cow_iterator.hpp.

◆ value_type

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
typedef sub_traits_t::value_type jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::value_type

Definition at line 672 of file cow_iterator.hpp.

◆ reference

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
typedef sub_traits_t::reference jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::reference

Definition at line 673 of file cow_iterator.hpp.

◆ pointer

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
typedef sub_traits_t::pointer jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::pointer

Definition at line 674 of file cow_iterator.hpp.

Constructor & Destructor Documentation

◆ cow_ro_iterator() [1/3]

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::cow_ro_iterator ( )
inlineconstexprnoexcept

Definition at line 682 of file cow_iterator.hpp.

Here is the caller graph for this function:

◆ cow_ro_iterator() [2/3]

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::cow_ro_iterator ( const cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container > & o)
inlineconstexprnoexcept

Definition at line 686 of file cow_iterator.hpp.

◆ cow_ro_iterator() [3/3]

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::cow_ro_iterator ( cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container > && o)
inlineconstexprnoexcept

Definition at line 699 of file cow_iterator.hpp.

Member Function Documentation

◆ operator=() [1/2]

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
cow_ro_iterator & jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::operator= ( const cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container > & o)
inlineconstexprnoexcept

Definition at line 690 of file cow_iterator.hpp.

◆ operator=() [2/2]

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
cow_ro_iterator & jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::operator= ( cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container > && o)
inlineconstexprnoexcept

Definition at line 705 of file cow_iterator.hpp.

◆ swap()

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
void jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::swap ( cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container > & o)
inlinenoexcept

Definition at line 715 of file cow_iterator.hpp.

◆ cbegin()

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
cow_ro_iterator jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::cbegin ( ) const
inlineconstexprnoexcept

Returns a new const_iterator pointing to the first element, aka begin.

This is an addition API entry, allowing data-race free operations on this iterator's data snapshot from a potentially mutated CoW.

See also
size()
end()

Definition at line 729 of file cow_iterator.hpp.

Here is the caller graph for this function:

◆ cend()

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
cow_ro_iterator jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::cend ( ) const
inlineconstexprnoexcept

Returns a new const_iterator pointing to the element following the last element, aka end.


This is an addition API entry, allowing data-race free operations on this iterator's data snapshot from a potentially mutated CoW.

See also
size()
begin()

Definition at line 741 of file cow_iterator.hpp.

Here is the caller graph for this function:

◆ empty()

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
bool jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::empty ( ) const
inlineconstexprnoexcept

Returns true if storage is empty().

Definition at line 747 of file cow_iterator.hpp.

◆ capacity_reached()

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
bool jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::capacity_reached ( ) const
inlineconstexprnoexcept

Returns true if storage capacity has been reached and the next push_back() will grow the storage and invalidates all iterators and references.

Definition at line 753 of file cow_iterator.hpp.

◆ size()

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
size_type jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::size ( ) const
inlineconstexprnoexcept

Return the size of the underlying value_type store.

This is an addition API entry, allowing data-race free arithmetic on this iterator's data snapshot from a potentially mutated CoW.

See also
begin()
end()

Definition at line 764 of file cow_iterator.hpp.

◆ storage()

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
storage_t & jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::storage ( ) const
inlineconstexprnoexcept

Returns this instances' underlying shared storage by reference.

Definition at line 769 of file cow_iterator.hpp.

◆ dist_end()

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
difference_type jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::dist_end ( ) const
inlineconstexprnoexcept

Returns the distance to_end() using zero as first index.

A.k.a the remaining elements iterable.

Definition at line 776 of file cow_iterator.hpp.

◆ is_end()

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
bool jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::is_end ( ) const
inlineconstexprnoexcept

Returns true, if this iterator points to cend().

Definition at line 781 of file cow_iterator.hpp.

◆ to_end()

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
cow_ro_iterator & jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::to_end ( )
inlineconstexprnoexcept

This iterator is set to the last element, cend().

Returns *this;

Definition at line 786 of file cow_iterator.hpp.

◆ dist_begin()

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
difference_type jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::dist_begin ( ) const
inlineconstexprnoexcept

Returns the distance to_begin() using zero as first index.

A.k.a the index from start.

Definition at line 792 of file cow_iterator.hpp.

◆ is_begin()

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
bool jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::is_begin ( ) const
inlineconstexprnoexcept

Returns true, if this iterator points to cbegin().

Definition at line 797 of file cow_iterator.hpp.

◆ to_begin()

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
cow_ro_iterator & jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::to_begin ( )
inlineconstexprnoexcept

This iterator is set to the first element, cbegin().

Returns *this;

Definition at line 802 of file cow_iterator.hpp.

◆ base()

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
iterator_type jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::base ( ) const
inlineconstexprnoexcept

Returns a copy of the underlying storage const_iterator.

This is an addition API entry, inspired by the STL std::normal_iterator.

Definition at line 811 of file cow_iterator.hpp.

◆ compare() [1/2]

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
int jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::compare ( const cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container > & rhs) const
inlineconstexprnoexcept

Returns signum or three-way comparison value.

   0 if equal (both, store and iteratore),
  -1 if this->iterator_ < rhs_iter and
   1 if this->iterator_ > rhs_iter (otherwise)
Parameters
rhs_storeright-hand side store
rhs_iterright-hand side iterator

Definition at line 825 of file cow_iterator.hpp.

◆ compare() [2/2]

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
int jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::compare ( const cow_rw_iterator< storage_t, storage_ref_t, cow_container_t > & rhs) const
inlineconstexprnoexcept

Definition at line 830 of file cow_iterator.hpp.

◆ operator==()

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
bool jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::operator== ( const cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container > & rhs) const
inlineconstexprnoexcept

Two way comparison operator, != is implicit, C++20.

Definition at line 836 of file cow_iterator.hpp.

◆ operator<=>()

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
std::strong_ordering jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::operator<=> ( const cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container > & rhs) const
inlinenoexcept

Three way std::strong_ordering comparison operator, C++20.

Definition at line 840 of file cow_iterator.hpp.

◆ operator*()

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
const reference jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::operator* ( ) const
inlineconstexprnoexcept

Definition at line 847 of file cow_iterator.hpp.

◆ operator->()

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
const pointer jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::operator-> ( ) const
inlineconstexprnoexcept

Definition at line 851 of file cow_iterator.hpp.

◆ operator++() [1/2]

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
cow_ro_iterator & jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::operator++ ( )
inlineconstexprnoexcept

Pre-increment; Well performing, return *this.

Definition at line 856 of file cow_iterator.hpp.

◆ operator++() [2/2]

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
cow_ro_iterator jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::operator++ ( int )
inlineconstexprnoexcept

Post-increment; Try to avoid: Low performance due to returning copy-ctor.

Definition at line 862 of file cow_iterator.hpp.

◆ operator--() [1/2]

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
cow_ro_iterator & jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::operator-- ( )
inlineconstexprnoexcept

Pre-decrement; Well performing, return *this.

Definition at line 868 of file cow_iterator.hpp.

◆ operator--() [2/2]

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
cow_ro_iterator jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::operator-- ( int )
inlineconstexprnoexcept

Post-decrement; Try to avoid: Low performance due to returning copy-ctor.

Definition at line 874 of file cow_iterator.hpp.

◆ operator[]()

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
const reference jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::operator[] ( difference_type i) const
inlineconstexprnoexcept

Subscript of 'element_index', returning immutable Value_type reference.

Definition at line 880 of file cow_iterator.hpp.

◆ operator+=()

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
cow_ro_iterator & jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::operator+= ( difference_type i)
inlineconstexprnoexcept

Addition-assignment of 'element_count'; Well performing, return *this.

Definition at line 884 of file cow_iterator.hpp.

◆ operator+()

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
cow_ro_iterator jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::operator+ ( difference_type rhs) const
inlineconstexprnoexcept

Binary 'iterator + element_count'; Try to avoid: Low performance due to returning copy-ctor.

Definition at line 888 of file cow_iterator.hpp.

◆ operator-=()

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
cow_ro_iterator & jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::operator-= ( difference_type i)
inlineconstexprnoexcept

Subtraction-assignment of 'element_count'; Well performing, return *this.

Definition at line 892 of file cow_iterator.hpp.

◆ operator-() [1/2]

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
cow_ro_iterator jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::operator- ( difference_type rhs) const
inlineconstexprnoexcept

Binary 'iterator - element_count'; Try to avoid: Low performance due to returning copy-ctor.

Definition at line 896 of file cow_iterator.hpp.

◆ operator-() [2/2]

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
difference_type jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::operator- ( const cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container > & rhs) const
inlineconstexprnoexcept

Binary 'iterator - iterator -> element_count'; Well performing, return element_count of type difference_type.

Definition at line 902 of file cow_iterator.hpp.

◆ distance()

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
difference_type jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::distance ( const cow_rw_iterator< storage_t, storage_ref_t, cow_container_t > & rhs) const
inlineconstexprnoexcept

Definition at line 905 of file cow_iterator.hpp.

◆ toString()

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
std::string jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::toString ( ) const
inlinenoexcept

Definition at line 908 of file cow_iterator.hpp.

Here is the caller graph for this function:

◆ get_info()

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
std::string jau::cow_ro_iterator< Storage_type, Storage_ref_type, CoW_container >::get_info ( ) const
inlinenoexcept

Definition at line 916 of file cow_iterator.hpp.

Friends And Related Symbol Documentation

◆ cow_darray

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
template<typename, typename, typename, bool, bool>
friend class cow_darray
friend

Definition at line 644 of file cow_iterator.hpp.

◆ cow_vector

template<typename Storage_type, typename Storage_ref_type, typename CoW_container>
template<typename, typename>
friend class cow_vector
friend

Definition at line 645 of file cow_iterator.hpp.


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