Ensure iterators satisfy input_iterator concept for views and ranges

CMakeLists.txt

@@ -36,7 +36,7 @@ endif()
 # ``-DCMAKE_CXX_STANDARD=<standard>`` when invoking CMake
 set(CMAKE_CXX_STANDARD 17 CACHE STRING "")
 
-if(NOT CMAKE_CXX_STANDARD MATCHES "17|20")
+if(NOT CMAKE_CXX_STANDARD MATCHES "17|20|23")
   message(FATAL_ERROR "Unsupported C++ standard: ${CMAKE_CXX_STANDARD}")
 endif()
 

doc/examples.md

@@ -65,22 +65,54 @@ If asking for an entry outside bounds, a std::out_of_range exception is thrown.
 
 
 ### Looping through Collections
-Looping through collections is supported in two ways. Via iterators:
+Looping through collections is supported in several ways.
+
+Via iterators:
 
 ```cpp
     for(auto i = hits.begin(), end = hits.end(); i != end; ++i) {
       std::cout << i->energy() << std::endl;
     }
 ```
 
-and via direct object access:
+Via direct object access:
 
 ```cpp
     for(int i = 0, end = hits.size(), i != end, ++i){
       std::cout << hit[i].energy() << std::endl;
     }
 ```
 
+Via ranged for loops:
+
+```cpp
+    for(auto hit: hits) {
+      std::cout << hit.energy() << std::endl;
+    }
+```
+
+Via `std::for_each`:
+
+```cpp
+    std::for_each(hits.begin(), hits.end(), [](const auto& hit) {
+      std::cout << hit.energy() << std::endl;
+    });
+```
+
+Via C++20 ranges and views:
+
+```cpp
+    auto is_electron = [](const auto& p){ return p.PDG() == 11; };
+    for (auto hit: hits | std::views::filter(is_electron)) {
+      std::cout << hit.energy() << std::endl;
+    }
+```
+
+Note, however, that writing to collections from iterators is not expected to work:
+```cpp
+    std::fill(hits.begin(), hits.end(), Hit()); // bad! iterator lvalues do not modify collection!
+```
+
 ### Support for Notebook-Pattern
 
 The `notebook pattern` uses the assumption that it is better to create a small

python/templates/Collection.cc.jinja2

@@ -1,6 +1,6 @@
 {% import "macros/utils.jinja2" as utils %}
 {% import "macros/collections.jinja2" as macros %}
-{% from "macros/iterator.jinja2" import iterator_definitions %}
+{% from "macros/iterator.jinja2" import iterator_definitions, reverse_iterator_definitions %}
 // AUTOMATICALLY GENERATED FILE - DO NOT EDIT
 
 #include "{{ incfolder }}{{ class.bare_type }}Collection.h"
@@ -152,6 +152,10 @@ podio::CollectionBuffers {{ collection_type }}::getBuffers() {
 
 {{ iterator_definitions(class, prefix='Mutable' ) }}
 
+{{ reverse_iterator_definitions(class) }}
+
+{{ reverse_iterator_definitions(class, prefix='Mutable' ) }}
+
 {{ macros.ostream_operator(class, Members, OneToOneRelations, OneToManyRelations, VectorMembers, use_get_syntax, ostream_collection_settings) }}
 
 {{ utils.namespace_close(class.namespace) }}

python/templates/Collection.h.jinja2

@@ -1,6 +1,7 @@
 {% import "macros/utils.jinja2" as utils %}
 {% import "macros/collections.jinja2" as macros %}
 {% from "macros/iterator.jinja2" import iterator_declaration %}
+{% from "macros/iterator.jinja2" import reverse_iterator_declaration %}
 // AUTOMATICALLY GENERATED FILE - DO NOT EDIT
 
 #ifndef {{ package_name.upper() }}_{{ class.bare_type }}Collection_H
@@ -26,13 +27,18 @@
 #include <ostream>
 #include <mutex>
 #include <memory>
+#if __has_include(<ranges>)
+#  include <ranges>
+#endif
 
 {{ utils.namespace_open(class.namespace) }}
 
 
 {{ iterator_declaration(class) }}
+{{ reverse_iterator_declaration(class) }}
 
 {{ iterator_declaration(class, prefix='Mutable') }}
+{{ reverse_iterator_declaration(class, prefix='Mutable') }}
 
 /**
 A Collection is identified by an ID.
@@ -41,8 +47,19 @@ class {{ class.bare_type }}Collection : public podio::CollectionBase {
 public:
   using const_iterator = {{ class.bare_type }}CollectionIterator;
   using iterator = {{ class.bare_type }}MutableCollectionIterator;
+  using const_reverse_iterator = {{ class.bare_type }}CollectionReverseIterator;
+  using reverse_iterator = {{ class.bare_type }}MutableCollectionReverseIterator;
 
   {{ class.bare_type }}Collection();
+  #if __cpp_lib_ranges
+  {{ class.bare_type }}Collection(std::ranges::input_range auto&& range)
+  requires(std::convertible_to<std::ranges::range_value_t<decltype(range)>, {{ class.bare_type }}>)
+  : m_isValid(false), m_isPrepared(false), m_isSubsetColl(false), m_collectionID(0), m_storage() {
+    for (auto&& item : range) {
+      push_back(item);
+    }
+  };
+  #endif
   // This is a move-only type
   {{ class.bare_type }}Collection(const {{ class.bare_type}}Collection& ) = delete;
   {{ class.bare_type }}Collection& operator=(const {{ class.bare_type}}Collection& ) = delete;
@@ -120,18 +137,42 @@ public:
   }
 
   // support for the iterator protocol
-  iterator begin() {
+  iterator begin() noexcept {
     return iterator(0, &m_storage.entries);
   }
-  const_iterator begin() const {
+  const_iterator cbegin() const noexcept {
     return const_iterator(0, &m_storage.entries);
   }
-  iterator end() {
+  const_iterator begin() const noexcept {
+    return const_iterator(0, &m_storage.entries);
+  }
+  reverse_iterator rbegin() noexcept {
+    return reverse_iterator(m_storage.entries.size() - 1, &m_storage.entries);
+  }
+  const_reverse_iterator crbegin() const noexcept {
+    return const_reverse_iterator(m_storage.entries.size() - 1, &m_storage.entries);
+  }
+  const_reverse_iterator rbegin() const noexcept {
+    return const_reverse_iterator(m_storage.entries.size() - 1, &m_storage.entries);
+  }
+  iterator end() noexcept {
     return iterator(m_storage.entries.size(), &m_storage.entries);
   }
-  const_iterator end() const {
+  const_iterator cend() const noexcept {
+    return const_iterator(m_storage.entries.size(), &m_storage.entries);
+  }
+  const_iterator end() const noexcept {
     return const_iterator(m_storage.entries.size(), &m_storage.entries);
   }
+  reverse_iterator rend() noexcept {
+    return reverse_iterator(-1, &m_storage.entries);
+  }
+  const_reverse_iterator crend() const noexcept {
+    return const_reverse_iterator(-1, &m_storage.entries);
+  }
+  const_reverse_iterator rend() const noexcept {
+    return const_reverse_iterator(-1, &m_storage.entries);
+  }
 
 {% for member in Members %}
   template<size_t arraysize>

python/templates/MutableObject.h.jinja2

@@ -24,6 +24,7 @@ class Mutable{{ class.bare_type }} {
 
   friend class {{ class.bare_type }}Collection;
   friend class {{ class.bare_type }}MutableCollectionIterator;
+  friend class {{ class.bare_type }}MutableCollectionReverseIterator;
   friend class {{ class.bare_type }};
 
 public:

python/templates/Object.h.jinja2

@@ -24,6 +24,7 @@ class {{ class.bare_type }} {
   friend class Mutable{{ class.bare_type }};
   friend class {{ class.bare_type }}Collection;
   friend class {{ class.bare_type }}CollectionIterator;
+  friend class {{ class.bare_type }}CollectionReverseIterator;
 
 public:
 {{ macros.constructors_destructors(class.bare_type, Members) }}

python/templates/macros/iterator.jinja2

@@ -2,18 +2,41 @@
 {% with iterator_type = class.bare_type + prefix + 'CollectionIterator' %}
 class {{ iterator_type }} {
 public:
-  {{ iterator_type }}(size_t index, const {{ class.bare_type }}ObjPointerContainer* collection) : m_index(index), m_object(nullptr), m_collection(collection) {}
+  using difference_type = std::ptrdiff_t;
+  using value_type = {{ prefix }}{{ class.bare_type }};
+  using pointer = {{ prefix }}{{ class.bare_type }}*;
+  using reference = {{ prefix }}{{ class.bare_type }}&;
+  using iterator_category = std::input_iterator_tag;
 
-  {{ iterator_type }}(const {{ iterator_type }}&) = delete;
-  {{ iterator_type }}& operator=(const {{ iterator_type }}&) = delete;
+  {{ iterator_type }}()
+    : m_index(0), m_object(nullptr), m_collection(nullptr) {};
+  {{ iterator_type }}(size_t index, const {{ class.bare_type }}ObjPointerContainer* collection)
+    : m_index(index), m_object(nullptr), m_collection(collection) {};
+
+  {{ iterator_type }}(const {{ iterator_type }}&) = default;
+  {{ iterator_type }}& operator=(const {{ iterator_type }}&) = default;
 
   bool operator!=(const {{ iterator_type}}& x) const {
     return m_index != x.m_index; // TODO: may not be complete
   }
+  bool operator==(const {{ iterator_type}}& x) const {
+    return !operator!=(x);
+  }
 
-  {{ prefix }}{{ class.bare_type }} operator*();
+  {{ prefix }}{{ class.bare_type }} operator*() const;
   {{ prefix }}{{ class.bare_type }}* operator->();
   {{ iterator_type }}& operator++();
+  {{ iterator_type }} operator++(int) {
+    {{ iterator_type }} temp = *this;
+    ++*this;
+    return temp;
+  };
+  {{ iterator_type }}& operator--();
+  {{ iterator_type }} operator--(int) {
+    {{ iterator_type }} temp = *this;
+    --*this;
+    return temp;
+  };
 
 private:
   size_t m_index;
@@ -23,12 +46,58 @@ private:
 {% endwith %}
 {% endmacro %}
 
+{% macro reverse_iterator_declaration(class, prefix='') %}
+{% with iterator_type = class.bare_type + prefix + 'CollectionReverseIterator' %}
+class {{ iterator_type }} {
+public:
+  using difference_type = std::ptrdiff_t;
+  using value_type = {{prefix}}{{ class.bare_type }};
+  using pointer = {{prefix}}{{ class.bare_type }}*;
+  using reference = {{prefix}}{{ class.bare_type }}&;
+  using iterator_category = std::input_iterator_tag;
+
+  {{ iterator_type }}()
+    : m_index(0), m_object(nullptr), m_collection(nullptr) {};
+  {{ iterator_type }}(size_t index, const {{ class.bare_type }}ObjPointerContainer* collection)
+    : m_index(index), m_object(nullptr), m_collection(collection) {};
+
+  {{ iterator_type }}(const {{ iterator_type }}&) = default;
+  {{ iterator_type }}& operator=(const {{ iterator_type }}&) = default;
+
+  bool operator!=(const {{ iterator_type }}& x) const {
+    return m_index != x.m_index; // TODO: may not be complete
+  }
+  bool operator==(const {{ iterator_type }}& x) const {
+    return !operator!=(x);
+  }
+
+  {{ prefix }}{{ class.bare_type }} operator*() const;
+  {{ prefix }}{{ class.bare_type }}* operator->();
+  {{ iterator_type }}& operator++();
+  {{ iterator_type }} operator++(int) {
+    {{ iterator_type }} temp = *this;
+    ++*this;
+    return temp;
+  };
+  {{ iterator_type }}& operator--();
+  {{ iterator_type }} operator--(int) {
+    {{ iterator_type }} temp = *this;
+    --*this;
+    return temp;
+  };
+
+private:
+  size_t m_index;
+  {{ prefix }}{{ class.bare_type }} m_object;
+  const {{ class.bare_type }}ObjPointerContainer* m_collection;
+};
+{% endwith %}
+{% endmacro %}
 
 {% macro iterator_definitions(class, prefix='') %}
 {% with iterator_type = class.bare_type + prefix + 'CollectionIterator' %}
-{{ prefix }}{{ class.bare_type }} {{ iterator_type }}::operator*() {
-  m_object.m_obj = (*m_collection)[m_index];
-  return m_object;
+{{ prefix }}{{ class.bare_type }} {{ iterator_type }}::operator*() const {
+  return {(*m_collection)[m_index]};
 }
 
 {{ prefix }}{{ class.bare_type }}* {{ iterator_type }}::operator->() {
@@ -41,5 +110,32 @@ private:
   return *this;
 }
 
+{{ iterator_type }}& {{ iterator_type }}::operator--() {
+  --m_index;
+  return *this;
+}
+{% endwith %}
+{% endmacro %}
+
+{% macro reverse_iterator_definitions(class, prefix='') %}
+{% with iterator_type = class.bare_type + prefix + 'CollectionReverseIterator' %}
+{{ prefix }}{{ class.bare_type }} {{ iterator_type }}::operator*() const {
+  return {(*m_collection)[m_index]};
+}
+
+{{ prefix }}{{ class.bare_type }}* {{ iterator_type }}::operator->() {
+  m_object.m_obj = (*m_collection)[m_index];
+  return &m_object;
+}
+
+{{ iterator_type }}& {{ iterator_type }}::operator++() {
+  --m_index;
+  return *this;
+}
+
+{{ iterator_type }}& {{ iterator_type }}::operator--() {
+  ++m_index;
+  return *this;
+}
 {% endwith %}
 {% endmacro %}