ProxyContainer.h

Go to the documentation of this file.

/*
  Copyright (C) 2002-2026 CERN for the benefit of the ATLAS collaboration
  */
#ifndef UTILS_PROXY_CONTAINER_H
#define UTILS_PROXY_CONTAINER_H
 
#include <cassert>
#include <utility>
 
// Helper classes to construct proxy container objects
// to handle iteration over containers like jagged vectors.
// A use case would be a container which contains containers
// of objects where the elements of the lowest level objects
// of all containers are contained in a single buffer, or
// in a SOA like arrangement, and the sub-containers are realized
// by index ranges. Example, for such a hierarchy:
//    container[module_i][cluster_i][cell_i].cellId()
//    container[module_i][cluster_i][cell_i].cellPosition()
// where the underlying container has the following structure:
//  struct CellData {
//      std::vector<int>   m_cellId;
//      std::vector<float> m_cellPosition;
//      std:vector<std::pair<unsigned int, unsigned int> > m_clusterCellIndexRange;
//      std:vector<std::pair<unsigned int, unsigned int> > m_moduleClusterIndexRange;
//  };
 
namespace Utils {

enum class AccessPolicy {
   ReadOnly,
   ReadWrite
};
 
// test whether a container has a size() member function
template <typename Container>
concept hasSize = requires(Container a) { a.size(); };
 
// test whether the difference can be computed for a certain index type
template <typename IndexType>
concept hasDifference = requires(IndexType a, IndexType b) { a-b; };
 
// test whether a count can be added to a certain index type
template <typename IndexType>
concept hasAddition = requires(IndexType a, std::size_t count) { a+count; };
 
// test whether a proxy is meant to be temporary and provides a method to convert to the actual proxy to be used.
// Such a temporary proxy has to provide the member functions:
// class ElementProxy ... { ..
//       static ActualProxy ElementProxy::create(ContainerType *container, IndexType index);
//       static ActualProxy ElementProxy::create(const ContainerType *container, IndexType index);
// ... };
// For such cases iterators, or the element access operators ([], front, back), would yield the
// type "ActualProxy". The Element Proxy should define at the same time also a method getOriginalElementIndex
// to "compute" the "child" index from the ActualProxy, where the child index is the index that can be
// used to to recover an element proxy from the parent proxy using the access operator[].
// class ElementProxy ... { ..
//       static ActualProxy ElementProxy::create(ContainerType *container, IndexType index);
//       static ActualProxy ElementProxy::create(const ContainerType *container, IndexType index);
//       static IndexType getOriginalElementIndex(const ActualProxy &converted_element_proxy);
// ... };
// auto child_proxy = parent_proxy[index];
// auto index_restore = ParentProxy::computeChildElementIndex(child_proxy);
// assert( index == index_restore )
template <typename T_Proxy, typename T_ContainerPtr, typename T_Index>
concept hasCreateProxy = requires(T_Proxy &&a, T_ContainerPtr ptr, T_Index index) { T_Proxy::create(ptr, index); };
 
template <typename T_Proxy>
concept hasReadWriteProxy = requires( typename T_Proxy::ReadWriteProxy a) { T_Proxy(a);};
 
template <typename T_DestProxy, typename T_SrcProxy>
concept isConvertableToReadOnlyProxy = requires( const T_SrcProxy &a) { T_DestProxy(&(a.container()), a.index());};
 

struct RootNodeIndex {
};
 
// Forward declaration of the actual container proxy class
template <class Container,
          class T_Derived,
          class ElementProxy,
          typename RangeType=RootNodeIndex,
          AccessPolicy accessPolicy=AccessPolicy::ReadOnly>
struct ContainerProxy;

template <class Container,
          typename ElementIndexType,
          AccessPolicy accessPolicy=AccessPolicy::ReadOnly>
struct ContainerProxyBase {
   using element_index_t = ElementIndexType;
 
   // helper class to provide access control to a pointer i.e. read/write or read only.
   template <AccessPolicy ptrAccessPolicy=accessPolicy>
   struct ContainerPtrBase {
      template <AccessPolicy IteratorAccessPolicy>
      friend class iterator_base;
 
      using ContainerPtr = std::conditional_t< ptrAccessPolicy == AccessPolicy::ReadOnly, const Container *, Container *>;
 
      template <class _Container,
                class _T_Derived,
                class _ElementProxy,
                typename _RangeType,
                AccessPolicy _accessPolicy>
      friend struct ContainerProxy;
 
      template <AccessPolicy otherAccessPolicy>
      ContainerPtrBase(ContainerPtrBase<otherAccessPolicy> container) requires (   otherAccessPolicy==ptrAccessPolicy
                                                                                || otherAccessPolicy == AccessPolicy::ReadWrite)
         : m_container(container.m_container) {}
 
      ContainerPtrBase(const Container *container) requires (ptrAccessPolicy == AccessPolicy::ReadOnly)
         : m_container(container) {}
 
      ContainerPtrBase(Container *container)
         : m_container(container) {}
 
      // test whether the pointer is not nullptr
      bool isValid() const { return m_container != nullptr; }
 
      // return a const reference of the container
      // results are "undefined" if isValid has not been checked before
      const Container &container() const                                                      { assert(isValid()); return *m_container; }
      // return a non-const reference of the container if the access policy permits read write access.
      // Results are "undefined" if isValid has not been checked before
      Container &container()             requires(ptrAccessPolicy == AccessPolicy::ReadWrite) { assert(isValid()); return *m_container; }
 
      // return the const pointer of the container.
      // The  result can be a nullptr.
      const Container *cptr() const                                                      {return m_container; }
      // return a non-const pointer if the access policy permits read write access. The result can be a nullptr
      Container *ptr()              requires(ptrAccessPolicy == AccessPolicy::ReadWrite) {return m_container; }
 
      // convenience method to return const or non const pointer depending on
      // an external access policy.
      template <AccessPolicy otherAccessPolicy>
      auto accessPtr() requires(ptrAccessPolicy==AccessPolicy::ReadWrite) {
         if constexpr(otherAccessPolicy == AccessPolicy::ReadWrite) {
            return this->ptr();
         }
         else {
            return this->cptr();
         }
      }
      // convenience method to return const or non const pointer depending on
      // an external access policy, if access is restricted to read only access.
      template <AccessPolicy otherAccessPolicy>
      auto accessPtr() const
         requires(otherAccessPolicy==AccessPolicy::ReadOnly)
      {
         return this->cptr();
      }
 
      // true if the pointer is not nullptr
      operator bool() const { return isValid(); }
 
      // return a const reference of the container
      // Result is "undefined" if container is not valid;
      const Container &operator*() const                                                       { return container(); }
      // return a non const reference of the container if the access policy
      // permits read-write access. Result is "undefined" if container is not valid;
      Container &operator*()              requires(ptrAccessPolicy == AccessPolicy::ReadWrite) { return container(); }
 
      // test whether the two container pointers point to the same container
      template <AccessPolicy otherAccessPolicy>
      bool operator==(const ContainerPtrBase<otherAccessPolicy> &other) const  { return m_container == other.m_container; }
   private:
      ContainerPtr m_container;
   };
 
   using ContainerPtr = ContainerPtrBase<AccessPolicy::ReadWrite>;     // non-const access controlled container pointer
   using ConstContainerPtr = ContainerPtrBase<AccessPolicy::ReadOnly>; // const container pointer
   ContainerPtrBase<accessPolicy> m_container;                         // pointer to the container this proxy refers to
 
   ContainerProxyBase(const Container *container) : m_container(container) {}  // creates a proxy which provides read-only access to its elements
   ContainerProxyBase(Container *container)       : m_container(container) {}  // creates a proxy which provides read-write access to its elements
 
   // @brief Possible base class for an element proxy.
   // This base class is used by the proxy container iterators
   template <AccessPolicy ptrAccessPolicy=accessPolicy>
   struct ElementProxyBase {
      using index_t = ElementIndexType;
 
   protected:
      ContainerPtrBase<ptrAccessPolicy> m_container; // refers to the original container the parent proxy refers to
      index_t m_index;                               // an "index" which indicates the element this proxy refers to
   public:
      ElementProxyBase(const Container *container, const  index_t &index)  // create a read-only element proxy
         : m_container(container), m_index(index)
      {}
      ElementProxyBase(Container *container, const index_t &index)         // create a read-write element proxy
         : m_container(container), m_index(index)
      {}
      ElementProxyBase(const Container *container, index_t &&index)        // create a read only element proxy, and moves the provided "index"
         : m_container(container), m_index(index)
      {}
      ElementProxyBase(Container *container, index_t &&index)              // create a read-write element proxy, and moves the provided "index"
         : m_container(container), m_index(index)
      {}
      ElementProxyBase(const ElementProxyBase<ptrAccessPolicy> &other)     // create a read-write element proxy, and moves the provided "index"
         : m_container(other.m_container), m_index(other.m_index)
      {}
      ElementProxyBase(const ElementProxyBase<AccessPolicy::ReadWrite> &other)   // create a read-write element proxy, and moves the provided "index"
          requires(ptrAccessPolicy == AccessPolicy::ReadOnly)
        : m_container(other.container().cptr()), m_index(other.m_index)
       {}
 
      template <typename T_RWProxy>
      ElementProxyBase(const T_RWProxy &other)   // create a read-write element proxy, and moves the provided "index"
         requires(ptrAccessPolicy == AccessPolicy::ReadOnly && isConvertableToReadOnlyProxy<ElementProxyBase<ptrAccessPolicy>, T_RWProxy> )
      : m_container(&other.container()), m_index(other.index())
      {}

      index_t index() const { return m_index; }

      const Container &container() const                                                    { return m_container.container(); }
      Container &container()             requires(ptrAccessPolicy==AccessPolicy::ReadWrite) { return m_container.container(); }
   };

   const Container &container() const                                                    { return m_container.container(); }
   Container &container()             requires(accessPolicy==AccessPolicy::ReadWrite) { return m_container.container(); }
};

template <class Container,
          class T_Derived,
          class ElementProxy,
          typename IndexType,
          AccessPolicy accessPolicy>
struct ContainerProxy : ContainerProxyBase<Container, typename ElementProxy::index_t, accessPolicy> {
   using value_type = ElementProxy;
   using index_t = IndexType;
   using element_index_t = typename ElementProxy::index_t;
   index_t m_index;
 
   // the base class
   using BASE = ContainerProxyBase<Container, typename ElementProxy::index_t, accessPolicy>;

   ContainerProxy(Container *container)
      requires ( std::is_same_v<index_t,RootNodeIndex> && hasSize<Container> )
   : BASE(container), m_index() {}

   ContainerProxy(const Container *container)
      requires ( std::is_same_v<index_t,RootNodeIndex> && hasSize<Container> )
      : BASE(container), m_index() {}

   ContainerProxy(Container *container, const index_t &index) : BASE(container), m_index(index) {}
   ContainerProxy(const Container *container, const index_t &index) : BASE(container), m_index(index) {}

   template <typename T_RWProxy>
   ContainerProxy(const T_RWProxy &other)
      requires(accessPolicy == AccessPolicy::ReadOnly
               && isConvertableToReadOnlyProxy<ContainerProxy<Container, T_Derived, ElementProxy, IndexType, accessPolicy>, T_RWProxy> )
   : BASE(&other.container()), m_index(other.index())
   {}

   static auto createElementProxy(const Container *ptr, element_index_t &&element_index) {
      if constexpr(hasCreateProxy<ElementProxy, decltype(ptr), element_index_t> ) {
         return ElementProxy::create(ptr, std::move(element_index));
      }
      else {
         return ElementProxy(ptr, std::move(element_index));
      }
   }

   static auto createElementProxy(Container *ptr, element_index_t &&element_index) requires (accessPolicy == AccessPolicy::ReadWrite) {
      if constexpr(hasCreateProxy<ElementProxy, decltype(ptr), element_index_t> ) {
         return ElementProxy::create(ptr, std::move(element_index));
      }
      else {
         return ElementProxy(ptr, element_index);
      }
   }
 
   // base class of proxy objects referring to elements of this container proxy
   template <AccessPolicy elementAccessPolicy>
   using ElementProxyBase = typename  BASE::template ElementProxyBase<elementAccessPolicy>;

   template <AccessPolicy iteratorAccessPolicy>
   struct iterator_base : ElementProxyBase<iteratorAccessPolicy> {
      using ElementProxyBase<iteratorAccessPolicy>::ElementProxyBase;
 
      // Go to the next element of this container proxy.
      iterator_base &operator++() {
         this->m_index = T_Derived::nextElementIndex(this->m_container.cptr(), std::move(this->m_index));
         return *this;
      }
 
      // Create a proxy object to access the element this iterator refers to.
      auto operator*()
      {
         return createElementProxy(this->m_container.template accessPtr<iteratorAccessPolicy>(),
                                   typename ElementProxyBase<iteratorAccessPolicy>::index_t(this->m_index));
      }
 
      // Test whether two iterators of this proxy container refer to the same element.
      // The result is undefined if the iterators refer to different containers.
      template<AccessPolicy otherIteratorAccessPolicy>
      bool operator==(const iterator_base<otherIteratorAccessPolicy> &other) const {
         assert ( this->m_container == other.m_container);
         return this->m_index == other.m_index;
      }
   };
 
   // the iterator class to iterator over elements of this proxy container with read write element access
   using iterator = iterator_base<AccessPolicy::ReadWrite>;
   // the iterator class to iterator over elements of this proxy container with read only element access
   using const_iterator = iterator_base<AccessPolicy::ReadOnly>;

   const index_t &index() const { return m_index; }

   element_index_t computeChildElementIndex(const ElementProxy &element_proxy) const
      requires (   !hasCreateProxy<ElementProxy, const Container *, element_index_t>
                && !hasCreateProxy<ElementProxy, Container *, element_index_t>)
   {
      return element_proxy.index() - T_Derived::beginIndex(this->m_container.cptr(), m_index);
   }

   template <typename T_ElementProxy>
   element_index_t computeChildElementIndex(const T_ElementProxy &element_proxy) const
      requires (   hasCreateProxy<ElementProxy, const Container *, element_index_t>
                || hasCreateProxy<ElementProxy, Container *, element_index_t>)
   {
      return ElementProxy::getOriginalElementIndex(element_proxy.index())  - T_Derived::beginIndex(this->m_container.cptr(), m_index);
   }

   iterator begin() requires ( accessPolicy == AccessPolicy::ReadWrite ) {
      return iterator(this->m_container.ptr(), T_Derived::beginIndex(this->m_container.cptr(), m_index) );
   }

   iterator end() requires ( accessPolicy == AccessPolicy::ReadWrite ) {
      return iterator(this->m_container.ptr(), T_Derived::endIndex(this->m_container.cptr(), m_index) );
   }

   const_iterator begin() const {
      return const_iterator(this->m_container.cptr(), T_Derived::beginIndex(this->m_container.cptr(), m_index) );
   }

   const_iterator end() const {
      return const_iterator(this->m_container.cptr(), T_Derived::endIndex(this->m_container.cptr(), m_index) );
   }

   auto operator[](std::size_t element_count) const
   { assert( element_count < size() );
     return createElementProxy(this->m_container.cptr(), T_Derived::elementIndexAt(this->m_container.cptr(), this->m_index,element_count)); }

   auto operator[](std::size_t element_count) requires (accessPolicy == AccessPolicy::ReadWrite)
   { assert( element_count < size() );
     return createElementProxy(this->m_container.ptr(), T_Derived::elementIndexAt(this->m_container.cptr(), this->m_index,element_count));}

   auto front() const
   { assert( !empty() );
     return createElementProxy(this->m_container.cptr(), T_Derived::beginIndex(this->m_container.cptr(), this->m_index));}

   auto front() requires (accessPolicy == AccessPolicy::ReadWrite)
   { assert( !empty() );
     return createElementProxy(this->m_container.ptr(), T_Derived::beginIndex(this->m_container.cptr(), this->m_index));}

   auto back() const
   { assert(this->size() > 0);
     std::size_t element_count = this->size()-1;
     return createElementProxy(this->m_container.cptr(), T_Derived::elementIndexAt(this->m_container.cptr(), this->m_index,element_count));
   }

   auto back() requires (accessPolicy == AccessPolicy::ReadWrite)
   { assert(this->size() > 0);
     //coverity[INTEGER_OVERFLOW]
     std::size_t element_count = this->size()-1;
     return createElementProxy(this->m_container.ptr(), T_Derived::elementIndexAt(this->m_container.ptr(), this->m_index,element_count));
   }

   static element_index_t beginIndex([[maybe_unused]] const Container *container, [[maybe_unused]] const index_t &this_index)
      requires (std::is_same_v<index_t,RootNodeIndex> && std::is_convertible_v<std::size_t, element_index_t> && hasSize<Container> )
   {
      return static_cast<element_index_t>(0u);
   }

   static element_index_t endIndex([[maybe_unused]] const Container *container, [[maybe_unused]] const index_t &this_index)
      requires (std::is_same_v<index_t,RootNodeIndex> && std::is_convertible_v<std::size_t, element_index_t> && hasSize<Container>)
   {
      assert( !container || container->size() < std::numeric_limits<element_index_t>::max());
      return (container ? static_cast<element_index_t>(container->size()) : 0u);
   }
   // @brief Default implementation to get the next index following the element identified by the given element index.
   // In most cases the next element is computed by the prefix increment operator
   static element_index_t nextElementIndex([[maybe_unused]] const Container *container, element_index_t &&element_index)
   {
      assert( container );
      return ++element_index;
   }

   static element_index_t elementIndexAt(const Container *container, const index_t &this_index, std::size_t element_counter)
      requires (hasAddition<element_index_t> )
   {  return T_Derived::beginIndex(container,this_index) + element_counter; }
 

   std::size_t size() const
      requires (hasDifference<element_index_t>)
   {
      return (this->m_container.cptr()
              ? T_Derived::endIndex(this->m_container.cptr(), m_index)-T_Derived::beginIndex(this->m_container.cptr(), m_index)
              : 0u);
   }

   std::size_t empty() const
   {
      return (this->m_container.cptr()
              ? T_Derived::endIndex(this->m_container.cptr(), m_index)==T_Derived::beginIndex(this->m_container.cptr(), m_index)
              : true);
   }
 
};
}
#endif