Make collection iterators forward_iterator* and beyond

[m-fila]

BEGINRELEASENOTES

• Collection iterators fulfill forward_iterator, bidirectional_iterator and random_access_iteratorconcepts. The collections can be used with more categories of range algorithms - up to random_access_range, for example std::adjacent_find, std::lower_bound, std::fold_right, and more views like std::ranges::views::reverse.
• LinkCollection and its iterators fulfill concepts up to random_access_range and random_access_iterator.
• Add reverse iterator methods to Collections, LinkCollection and UserDataCollection.

ENDRELEASENOTES

Here is a proposal how to make collection iterators fulfill std::forward_iterator which also opens the way for std::bidirectional_iterator and std::random_access_iterator by making a single exception

The collection iterators fulfill all the forward_iterator requirements except one semantic requirement:

Pointers and references obtained from a forward iterator into a range remain valid while the range exists.

The problem here is the operator-> that returns a pointer to data type object that is a member of the iterator (collections store data layer objects and data type are created on-the-fly so there is no data type object with lifetime livinf inside collection to which pointer we could return). Due to this the validity of obtained pointer is as long as the iterator is valid - to fulfill the requirement it should be as long the collection is valid.

In reality it's quite hard to abuse as things obtained through -> (iterator->energy()) are safe since they go through the data layer that lives in the collection. The problem seems to be only getting the pointer directly with pattern like this:

auto* ptr = iterator.operator->();

which is rather rare in normal usage. A pattern like this auto particle = *(iterator.operator->()); again is okay since the pointer is used immediately

Of course the final question is whether it's used somewhere in an implementation of the std algorithms. On top of that it should be used in a certain way like creating a temporary copy of iterator, taking pointer, disposing of the copy, using iterator

In the past there were some precedence event in the standard library that iterators were assigned some category except something (that was for Legacy iterators):

• std::regex_iterator

  std::regex_iterator is a read-only iterator that accesses the individual matches of a regular expression within the underlying character sequence. It meets the requirements of a LegacyForwardIterator, except that for dereferenceable values a and b with a == b, *a and *b will not be bound to the same object.

• std::filesystem::path::iterator

  a constant LegacyInputIterator with a value_type of path that meets all requirements of LegacyBidirectionalIterator except that for two equal dereferenceable iterators a and b of type const_iterator, there is no requirement that *a and *b refer to the same object.
  It is unspecified whether const_iterator is actually a LegacyBidirectionalIterator

TL;DR Iterators gain support up to std::random_access_iterator except that technically they don't meet a requirement for pointers obtained with auto* ptr = it.operator->(); pattern to outlive the iterator

[m-fila]

Ah used <=> to define comparison operators. I think I'll leave it with that since the move to C++20 is upcoming anyway

[tmadlener]

Does this already include the LinkCollections? (see #725 ;))

[m-fila]

Does this already include the LinkCollections? (see #725 ;))

Now, yes 😎