gum::ListIterator< Val > Class Template Reference

Unsafe but fast iterators for Lists. More...

#include <agrum/base/core/list.h>

Inheritance diagram for gum::ListIterator< Val >:

Collaboration diagram for gum::ListIterator< Val >:

Public Types
using	iterator_category = std::bidirectional_iterator_tag
	Types for STL compliance.
using	value_type = Val
	Types for STL compliance.
using	reference = Val&
	Types for STL compliance.
using	const_reference = const Val&
	Types for STL compliance.
using	pointer = Val*
	Types for STL compliance.
using	const_pointer = const Val*
	Types for STL compliance.
using	difference_type = std::ptrdiff_t
	Types for STL compliance.

Public Member Functions
Constructors / Destructors
	ListIterator () noexcept
	Default constructor.
	ListIterator (const List< Val > &theList) noexcept
	Constructor for a begin.
	ListIterator (const ListIterator< Val > &src) noexcept
	Copy constructor.
	ListIterator (ListIterator< Val > &&src) noexcept
	Move constructor.
	ListIterator (const List< Val > &theList, Size ind_elt)
	Constructor for an iterator pointing to the ind_eltth element of a List.
	~ListIterator () noexcept
	Class destructor.
Operators
ListIterator< Val > &	operator= (const ListIterator< Val > &src) noexcept
	Copy operator.
ListIterator< Val > &	operator= (ListIterator< Val > &&src) noexcept
	move operator
ListIterator< Val > &	operator++ () noexcept
	Makes the iterator point to the next element in the List.
ListIterator< Val > &	operator+= (difference_type i) noexcept
	Makes the iterator point to i elements further in the List.
ListIterator< Val > &	operator-- () noexcept
	Makes the iterator point to the preceding element in the List.
ListIterator< Val > &	operator-= (difference_type i) noexcept
	Makes the iterator point to i elements befor in the List.
ListIterator< Val >	operator+ (difference_type i) noexcept
	Returns a new iterator pointing to i further elements in the gum::List.
ListIterator< Val >	operator- (difference_type i) noexcept
	Returns a new iterator pointing to i preceding elements in the gum::List.
bool	operator== (const ListIterator< Val > &src) const noexcept
	Checks whether two iterators point toward the same elements.
bool	operator!= (const ListIterator< Val > &src) const noexcept
	Checks whether two iterators point toward different elements.
const Val &	operator* () const
	Gives access to the content of the iterator.
Val &	operator* ()
	Gives access to the iterator's content.
const Val *	operator-> () const
	Dereferences the value pointed to by the iterator.
Val *	operator-> ()
	Dereferences the value pointed to by the iterator.
Accessors / Modifiers
void	clear () noexcept
	Makes the iterator point toward nothing.
void	setToEnd () noexcept
	Positions the iterator to the end of the list.
bool	isEnd () const noexcept
	Returns a bool indicating whether the iterator points to the end of the list.
Operators
bool	operator!= (const ListConstIterator< Val > &src) const noexcept
	Checks whether two iterators point toward different elements.
bool	operator== (const ListConstIterator< Val > &src) const noexcept
	Checks whether two iterators point toward the same elements.

Private Member Functions
ListBucket< Val > *	_getBucket_ () const noexcept
	Returns the bucket the iterator is pointing to.

Private Attributes
ListBucket< Val > *	_bucket_ {nullptr}
	The bucket in the chained list pointed to by the iterator.

Detailed Description

template<typename Val>
class gum::ListIterator< Val >

Unsafe but fast iterators for Lists.

Class ListIterator implements iterators for List. However, developers may consider using List<x>::iterator instead of ListIterator<x>.

These iterators are fast but they are unaware of changes within the List. Therefore, if they point to an element that is being deleted from memory by the list, their accessing this element will most probably produce a segmentation fault. Similarly, incrementing or decrementing such an iterator pointing to a deleted element will most certainly produce a mess. So, ListIterator should be used only if you are sure that they will never point to an element that has been removed from the list (a typical use is to iterate over a const List). Whenever you are not sure that this property holds, use ListIteratorSafe<x> or List<x>::iterator_safe. Those iterators are a little bit slower but guarantee that no segmentation fault will ever occur.

Usage example:

// create a list of strings
List<string> list;
list.pushBack ("toto"); list.pushBack ("titi");
 
// parse all the elements of a list
for ( List<string>::iterator iter = list.begin ();
      iter != list.end (); ++iter )
  cerr << *iter << endl;
for ( List<string>::iterator iter = list.begin ();
      iter != list.end (); iter += 2 ) // step = 2
  cerr << *iter << endl;
for ( List<string>::iterator iter = list.begin ();
      iter != list.end (); iter = iter + 2 ) // step = 2
  cerr << *iter << endl;
for ( List<string>::iterator iter = list.rbegin ();
      iter != list.rend (); --iter )
  cerr << *iter << endl;
 
// use member size() of the strings
for ( List<string>::iterator iter = list.begin ();
      iter != list.end (); ++iter)
  cerr << iter->size() << endl;

Template Parameters

Val	The gum::List values type.

Definition at line 1737 of file list.h.

Member Typedef Documentation

const_pointer

template<typename Val>

using gum::ListIterator< Val >::const_pointer = const Val*

Types for STL compliance.

Definition at line 1746 of file list.h.

const_reference

template<typename Val>

using gum::ListIterator< Val >::const_reference = const Val&

Types for STL compliance.

Definition at line 1744 of file list.h.

difference_type

template<typename Val>

using gum::ListIterator< Val >::difference_type = std::ptrdiff_t

Types for STL compliance.

Definition at line 1747 of file list.h.

iterator_category

template<typename Val>

using gum::ListIterator< Val >::iterator_category = std::bidirectional_iterator_tag

Types for STL compliance.

Definition at line 1741 of file list.h.

pointer

template<typename Val>

using gum::ListIterator< Val >::pointer = Val*

Types for STL compliance.

Definition at line 1745 of file list.h.

reference

template<typename Val>

using gum::ListIterator< Val >::reference = Val&

Types for STL compliance.

Definition at line 1743 of file list.h.

value_type

template<typename Val>

using gum::ListIterator< Val >::value_type = Val

Types for STL compliance.

Definition at line 1742 of file list.h.

Constructor & Destructor Documentation

ListIterator() [1/5]

template<typename Val>

INLINE gum::ListIterator< Val >::ListIterator ( )

explicitnoexcept

Default constructor.

Returns an iterator pointing toward nothing.

Definition at line 365 of file list_tpl.h.

                                                    : ListConstIterator< Val >() {
    GUM_CONSTRUCTOR(ListIterator);
  }

References gum::ListConstIterator< Val >::ListConstIterator(), and ListIterator().

Referenced by ListIterator(), ListIterator(), ListIterator(), ListIterator(), ListIterator(), ~ListIterator(), operator!=(), operator++(), operator-(), operator--(), operator=(), operator=(), and operator==().

Here is the call graph for this function:

Here is the caller graph for this function:

ListIterator() [2/5]

template<typename Val>

INLINE gum::ListIterator< Val >::ListIterator ( const List< Val > & theList )

noexcept

Constructor for a begin.

Parameters

theList

The list to iterate over.

Definition at line 371 of file list_tpl.h.

                                                                              :
      ListConstIterator< Val >(theList) {
    GUM_CONSTRUCTOR(ListIterator);
  }

References gum::ListConstIterator< Val >::ListConstIterator(), ListIterator(), and gum::ListConstIterator< Val >::List< Val >.

Here is the call graph for this function:

ListIterator() [3/5]

template<typename Val>

INLINE gum::ListIterator< Val >::ListIterator ( const ListIterator< Val > & src )

noexcept

Copy constructor.

Parameters

src	The gum::ListIterator to copy.

Definition at line 378 of file list_tpl.h.

                                                                                  :
      ListConstIterator< Val >(src) {
    GUM_CONS_CPY(ListIterator);
  }

References gum::ListConstIterator< Val >::ListConstIterator(), and ListIterator().

Here is the call graph for this function:

ListIterator() [4/5]

template<typename Val>

INLINE gum::ListIterator< Val >::ListIterator ( ListIterator< Val > && src )

noexcept

Move constructor.

Parameters

src	The gum::ListIterator to move.

Definition at line 385 of file list_tpl.h.

                                                                             :
      ListConstIterator< Val >(std::move(src)) {
    GUM_CONS_MOV(ListIterator);
  }

References gum::ListConstIterator< Val >::ListConstIterator(), and ListIterator().

Here is the call graph for this function:

ListIterator() [5/5]

template<typename Val>

INLINE gum::ListIterator< Val >::ListIterator	(	const List< Val > &	theList,
		Size	ind_elt )

Constructor for an iterator pointing to the ind_eltth element of a List.

Parameters

theList	The gum::List to iterate over.
ind_elt	The position to point to.

Exceptions

UndefinedIteratorValue

Raised if the element does not exist in the list.

Definition at line 393 of file list_tpl.h.

                                                                                   :
      ListConstIterator< Val >(theList, ind_elt) {
    GUM_CONSTRUCTOR(ListIterator);
  }

References gum::ListConstIterator< Val >::ListConstIterator(), ListIterator(), and gum::ListConstIterator< Val >::List< Val >.

Here is the call graph for this function:

~ListIterator()

template<typename Val>

INLINE gum::ListIterator< Val >::~ListIterator ( )

noexcept

Class destructor.

Definition at line 417 of file list_tpl.h.

                                                     {
    GUM_DESTRUCTOR(ListIterator);
  }

References ListIterator().

Here is the call graph for this function:

Member Function Documentation

_getBucket_()

template<typename Val>

INLINE ListBucket< Val > * gum::ListConstIterator< Val >::_getBucket_ ( ) const

privatenoexceptinherited

Returns the bucket the iterator is pointing to.

Definition at line 237 of file list_tpl.h.

                                                                                 {
    return _bucket_;
  }

References _bucket_.

Referenced by gum::List< Val >::_insert_().

Here is the caller graph for this function:

clear()

template<typename Val>

INLINE void gum::ListConstIterator< Val >::clear ( )

noexceptinherited

Makes the iterator point toward nothing.

A method for detaching the iterator from the List it is attached to. After being detached, the iterator does not point to any element, i.e., trying to access its content will raise an exception.

Definition at line 243 of file list_tpl.h.

                                                       {
    _bucket_ = nullptr;
  }

References _bucket_.

isEnd()

template<typename Val>

INLINE bool gum::ListConstIterator< Val >::isEnd ( ) const

noexceptinherited

Returns a bool indicating whether the iterator points to the end of the list.

Returns

Returns a bool indicating whether the iterator points to the end of the list.

Definition at line 256 of file list_tpl.h.

                                                             {
    return (_bucket_ == nullptr);
  }

References _bucket_.

operator!=() [1/2]

template<typename Val>

INLINE bool gum::ListConstIterator< Val >::operator!= ( const ListConstIterator< Val > & src ) const

noexceptinherited

Checks whether two iterators point toward different elements.

Warning

the end and rend iterators are always equal, whatever the list they belong to, i.e., list1.end() == list2.rend().

Parameters

src	The gum::ListConstIterator to test for inequality.

Returns

Returns true if src and this are equal.

Definition at line 321 of file list_tpl.h.

                                                                                           {
    return (_bucket_ != src._bucket_);
  }

References ListConstIterator(), and _bucket_.

Here is the call graph for this function:

operator!=() [2/2]

template<typename Val>

INLINE bool gum::ListIterator< Val >::operator!= ( const ListIterator< Val > & src ) const

noexcept

Checks whether two iterators point toward different elements.

Warning

the end and rend iterators are always equal, whatever the list they belong to, i.e., list1.end() == list2.rend().

Parameters

src	The gum::ListIterator to test for inequality.

Returns

Returns true if src and this are equal.

Definition at line 429 of file list_tpl.h.

                                                                                         {
    return !operator==(src);
  }

References ListIterator(), and gum::operator==().

Here is the call graph for this function:

operator*() [1/2]

template<typename Val>

INLINE Val & gum::ListIterator< Val >::operator*

(

)

Gives access to the iterator's content.

Returns

Returns the iterator content.

Exceptions

UndefinedIteratorValue

Raised if the iterator is pointing toward nothing.

Definition at line 491 of file list_tpl.h.

                                             {
    return const_cast< Val& >(ListConstIterator< Val >::operator*());
  }

References gum::ListConstIterator< Val >::operator*().

Here is the call graph for this function:

operator*() [2/2]

template<typename Val>

INLINE const Val & gum::ListIterator< Val >::operator*

(

)

const

Gives access to the content of the iterator.

Exceptions

UndefinedIteratorValue

Raised if the iterator points to nothing.

Returns

Returns the content of the iterator.

Definition at line 497 of file list_tpl.h.

                                                         {
    return ListConstIterator< Val >::operator*();
  }

References gum::ListConstIterator< Val >::operator*().

Here is the call graph for this function:

operator+()

template<typename Val>

INLINE ListIterator< Val > gum::ListIterator< Val >::operator+ ( difference_type i )

noexcept

Returns a new iterator pointing to i further elements in the gum::List.

Parameters

i	The number of steps to move the iterator.

Returns

Returns a new gum::ListIterator.

Definition at line 466 of file list_tpl.h.

                                                                                              {
    return ListIterator< Val >(*this) += i;
  }

operator++()

template<typename Val>

INLINE ListIterator< Val > & gum::ListIterator< Val >::operator++ ( )

noexcept

Makes the iterator point to the next element in the List.

for (iter = list.begin(); iter != list.end(); ++iter) { }

The above loop is guaranteed to parse the whole List as long as no element is added to or deleted from the List while being in the loop. Deleting elements during the loop is guaranteed to never produce a segmentation fault. Runs in constant time.

Returns

Returns this gum::ListIterator.

Definition at line 435 of file list_tpl.h.

                                                                       {
    ListConstIterator< Val >::operator++();
    return *this;
  }

References ListIterator(), and gum::ListConstIterator< Val >::operator++().

Here is the call graph for this function:

operator+=()

template<typename Val>

INLINE ListIterator< Val > & gum::ListIterator< Val >::operator+= ( difference_type i )

noexcept

Makes the iterator point to i elements further in the List.

Parameters

i	The number of steps to move the iterator.

Returns

Returns this gum::ListIterator.

Definition at line 443 of file list_tpl.h.

                                                                                             {
    ListConstIterator< Val >::operator+=(i);
    return *this;
  }

References gum::ListConstIterator< Val >::operator+=().

Here is the call graph for this function:

operator-()

template<typename Val>

INLINE ListIterator< Val > gum::ListIterator< Val >::operator- ( difference_type i )

noexcept

Returns a new iterator pointing to i preceding elements in the gum::List.

Parameters

i	The number of steps to move the iterator.

Returns

Returns a new gum::ListIterator.

Definition at line 473 of file list_tpl.h.

                                                                                              {
    return ListIterator< Val >(*this) -= i;
  }

References ListIterator().

Here is the call graph for this function:

operator--()

template<typename Val>

INLINE ListIterator< Val > & gum::ListIterator< Val >::operator-- ( )

noexcept

Makes the iterator point to the preceding element in the List.

for (iter = list.rbegin(); iter != list.rend(); --iter) { }

The above loop is guaranteed to parse the whole List as long as no element is added to or deleted from the List while being in the loop. Runs in constant time.

Returns

Returns this gum::ListIterator.

Definition at line 450 of file list_tpl.h.

                                                                       {
    ListConstIterator< Val >::operator--();
    return *this;
  }

References ListIterator(), and gum::ListConstIterator< Val >::operator--().

Here is the call graph for this function:

operator-=()

template<typename Val>

INLINE ListIterator< Val > & gum::ListIterator< Val >::operator-= ( difference_type i )

noexcept

Makes the iterator point to i elements befor in the List.

Parameters

i	The number of steps to move the iterator.

Returns

Returns this gum::ListIterator.

Definition at line 458 of file list_tpl.h.

                                                                                             {
    ListConstIterator< Val >::operator-=(i);
    return *this;
  }

References gum::ListConstIterator< Val >::operator-=().

Here is the call graph for this function:

operator->() [1/2]

template<typename Val>

INLINE Val * gum::ListIterator< Val >::operator->

(

)

Dereferences the value pointed to by the iterator.

Returns

Returns the iterator content.

Exceptions

UndefinedIteratorValue

Raised if the iterator is pointing toward nothing.

Definition at line 479 of file list_tpl.h.

                                              {
    return const_cast< Val* >(ListConstIterator< Val >::operator->());
  }

References gum::ListConstIterator< Val >::operator->().

Here is the call graph for this function:

operator->() [2/2]

template<typename Val>

INLINE const Val * gum::ListIterator< Val >::operator->

(

)

const

Dereferences the value pointed to by the iterator.

Exceptions

UndefinedIteratorValue

Raised if the iterator points to nothing.

Returns

Returns the value pointed to by the iterator.

Definition at line 485 of file list_tpl.h.

                                                          {
    return ListConstIterator< Val >::operator->();
  }

References gum::ListConstIterator< Val >::operator->().

Here is the call graph for this function:

operator=() [1/2]

template<typename Val>

INLINE ListIterator< Val > & gum::ListIterator< Val >::operator= ( const ListIterator< Val > & src )

noexcept

Copy operator.

The current iterator now points to the same element as iterator src.

Parameters

src	The gum::ListIterator to copy.

Returns

Returns this gum::ListIterator.

Definition at line 401 of file list_tpl.h.

                                                                             {
    GUM_OP_CPY(ListIterator);
    ListConstIterator< Val >::operator=(src);
    return *this;
  }

References ListIterator(), and gum::ListConstIterator< Val >::operator=().

Here is the call graph for this function:

operator=() [2/2]

template<typename Val>

INLINE ListIterator< Val > & gum::ListIterator< Val >::operator= ( ListIterator< Val > && src )

noexcept

move operator

Move operator.

The current iterator now points to the same element as iterator src.

Parameters

src	The gum::ListIterator to move.

Returns

Returns this gum::ListIterator.

Definition at line 409 of file list_tpl.h.

                                                                                             {
    GUM_OP_MOV(ListIterator);
    ListConstIterator< Val >::operator=(std::move(src));
    return *this;
  }

References ListIterator(), and gum::ListConstIterator< Val >::operator=().

Here is the call graph for this function:

operator==() [1/2]

template<typename Val>

INLINE bool gum::ListConstIterator< Val >::operator== ( const ListConstIterator< Val > & src ) const

noexceptinherited

Checks whether two iterators point toward the same elements.

Warning

the end and rend iterators are always equal, whatever the list they belong to, i.e., list1.end() == list2.rend().

Parameters

src	The gum::ListConstIterator to test for equality.

Returns

Returns true if src and this are equal.

Definition at line 328 of file list_tpl.h.

                                                                                           {
    return (_bucket_ == src._bucket_);
  }

References ListConstIterator(), and _bucket_.

Referenced by gum::ListIterator< Val >::operator==().

Here is the call graph for this function:

Here is the caller graph for this function:

operator==() [2/2]

template<typename Val>

INLINE bool gum::ListIterator< Val >::operator== ( const ListIterator< Val > & src ) const

noexcept

Checks whether two iterators point toward the same elements.

Warning

the end and rend iterators are always equal, whatever the list they belong to, i.e., list1.end() == list2.rend().

Parameters

src	The gum::ListIterator to test for equality.

Returns

Returns true if src and this are equal.

Definition at line 423 of file list_tpl.h.

                                                                                         {
    return ListConstIterator< Val >::operator==(src);
  }

References ListIterator(), and gum::ListConstIterator< Val >::operator==().

Here is the call graph for this function:

setToEnd()

template<typename Val>

INLINE void gum::ListConstIterator< Val >::setToEnd ( )

noexceptinherited

Positions the iterator to the end of the list.

Definition at line 249 of file list_tpl.h.

                                                          {
    _bucket_ = nullptr;
  }

References _bucket_.

Member Data Documentation

_bucket_

template<typename Val>

ListBucket< Val >* gum::ListConstIterator< Val >::_bucket_ {nullptr}

privateinherited

The bucket in the chained list pointed to by the iterator.

Definition at line 1672 of file list.h.

{nullptr};

Referenced by ListConstIterator(), ListConstIterator(), ListConstIterator(), ListConstIterator(), _getBucket_(), clear(), isEnd(), operator!=(), operator*(), operator++(), operator+=(), operator--(), operator-=(), operator->(), operator==(), and setToEnd().

---

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

• agrum/base/core/list.h
• agrum/base/core/list_tpl.h