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>
#include <type_traits>
 
// 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 {
   Const,
   Mutable
};
 
template <bool isConst>
struct AccessPolicyHelper;
 
template<>
struct AccessPolicyHelper<true> {
   static constexpr AccessPolicy accessPolicy = AccessPolicy::Const;
};
 
template<>
struct AccessPolicyHelper<false> {
   static constexpr AccessPolicy accessPolicy = AccessPolicy::Mutable;
};
 
template <typename Container,  AccessPolicy accessPolicy>
struct ContainerAccessHelper {
   using ContainerNonConst = std::remove_cvref_t<Container>;
   using ContainerPtr = std::conditional<accessPolicy==AccessPolicy::Const , const ContainerNonConst *, ContainerNonConst *>::type;
   using ContainerType = std::conditional<accessPolicy==AccessPolicy::Const , const ContainerNonConst, ContainerNonConst>::type;
};
 
// 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>
struct ContainerProxy;
 
 
// @brief Possible base class for an element proxy.
// This base class is used by the proxy container iterators
template <class Container,
          typename ElementIndexType>
struct ElementProxyBase {
   static constexpr bool isConst = std::is_const_v<Container>;
   using index_t = ElementIndexType;
   using ContainerNonConst = std::remove_cvref_t<Container>;
   using ContainerPtr = std::conditional<isConst , const ContainerNonConst *, ContainerNonConst *>::type;
 
public:
   ElementProxyBase(const ContainerNonConst *container, const  index_t &index)  // create a read-only element proxy
      requires(isConst)
      : m_container(container), m_index(index)
   {}
   ElementProxyBase(ContainerNonConst *container, const index_t &index)         // create a read-write element proxy
      : m_container(container), m_index(index)
   {}
   ElementProxyBase(const ContainerNonConst *container, index_t &&index)        // create a read only element proxy, and moves the provided "index"
      requires(isConst)
      : m_container(container), m_index(index)
   {}
   ElementProxyBase(ContainerNonConst *container, index_t &&index)              // create a read-write element proxy, and moves the provided "index"
      : m_container(container), m_index(index)
   {}
   template <class OtherContainer>
   ElementProxyBase(const ElementProxyBase<OtherContainer, ElementIndexType> &other)// create a read-write element proxy, and moves the provided "index"
      requires(std::is_same_v<ContainerNonConst, typename OtherContainer::ContainerNonConst>
               && (!OtherContainer::isConst || isConst) )
      : m_container(other.m_container), m_index(other.m_index)
   {}

   index_t index() const { return m_index; }

   const ContainerNonConst &container() const
   { assert( m_container != nullptr); return *m_container; }

   ContainerNonConst &container()             requires(!isConst)
   { assert( m_container != nullptr); return *m_container; }
protected:
   const ContainerNonConst *cptr() const {
      return &container();
   }
   ContainerPtr 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
};

template <class Container,
          typename ElementIndexType>
struct ContainerProxyBase {
   static constexpr bool isConst = std::is_const_v<Container>;
   using element_index_t = ElementIndexType;
   using ContainerNonConst = std::remove_cvref_t<Container>;
   using ContainerPtr = std::conditional<isConst , const ContainerNonConst *, ContainerNonConst *>::type;
 
   template <class OtherContainer>
   ContainerProxyBase(const ContainerProxyBase<OtherContainer,ElementIndexType> &a)
      requires(std::is_same_v<ContainerNonConst, typename OtherContainer::ContainerNonConst> || !OtherContainer::isConst)
   : m_container(a.m_container) {}
   ContainerProxyBase(const ContainerNonConst *container) requires(isConst)
     : m_container(container) {}  // creates a proxy which provides read-only access to its elements
   ContainerProxyBase(ContainerNonConst *container)
     : m_container(container) {}  // creates a proxy which provides read-write access to its elements

   const ContainerNonConst &container() const
   { assert(m_container != nullptr); return *m_container; }

   ContainerNonConst &container()             requires(!isConst)
   { assert( m_container != nullptr); return *m_container; }
 
protected:
   const ContainerNonConst *cptr() const {
      return m_container;
   }
   ContainerNonConst *ptr() requires(!isConst) {
      return m_container;
   }
 
   ContainerPtr m_container;                         // pointer to the container this proxy refers to
};

template <class Container,
          class T_Derived,
          class ElementProxy>
struct ProxyIteratorBase : ElementProxyBase<Container, typename ElementProxy::index_t> {
   using element_index_t = typename ElementProxy::index_t;
   using BASE=ElementProxyBase<Container, element_index_t>;
   using BASE::BASE;
 
   // Go to the next element of this container proxy.
   ProxyIteratorBase &operator++() {
      this->m_index = T_Derived::nextElementIndex(this->cptr(), std::move(this->m_index));
      return *this;
   }
   ProxyIteratorBase &operator+=(std::size_t offset) requires(hasAddition<element_index_t>) {
      this->m_index = this->m_index + offset;
      return *this;
   }
 
   // Create a proxy object to access the element this iterator refers to.
   auto operator*()
   {
      return this->createElementProxy(this->m_container,
                                      typename BASE::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<class OtherContainer>
   bool operator==(const ProxyIteratorBase<OtherContainer, T_Derived, ElementProxy> &other) const
      requires(std::is_same_v<typename BASE::ContainerNonConst,
                              typename ProxyIteratorBase<OtherContainer, T_Derived, ElementProxy>::ContainerNonConst>)
   {
      assert ( this->m_container == other.m_container);
      return this->m_index == other.m_index;
   }

   static auto createElementProxy(const BASE::ContainerNonConst *ptr, element_index_t &&element_index)
      requires(hasCreateProxy<ElementProxy, decltype(ptr), element_index_t> )
   {
      return ElementProxy::create(ptr,std::move(element_index));
   }

   static auto createElementProxy(const BASE::ContainerNonConst *ptr, element_index_t &&element_index)
      requires(ElementProxy::isConst && !hasCreateProxy<ElementProxy, decltype(ptr), element_index_t> )
   {
      return ElementProxy(ptr,std::move(element_index));
   }

   static auto createElementProxy(BASE::ContainerNonConst *ptr, element_index_t &&element_index)
      requires (!BASE::isConst) {
      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));
      }
   }
 
};
 
// extension of the ProxyIteratorBase to make it usable in std::ranges::subrange
template <class Container,
          class T_Derived,
          class ElementProxy>
struct ProxyIterator : ProxyIteratorBase<Container,T_Derived, ElementProxy> {
public:
   using BASE=ProxyIteratorBase<Container,T_Derived, ElementProxy>;
   using BASE::BASE;
 
   // default constructor needed to use these iterators in a std::range::subrange
   ProxyIterator() : BASE(nullptr,typename BASE::element_index_t{}) {}
 
   ProxyIterator &operator++() {
      (void) BASE::operator++();
      return *this;
   }
   ProxyIterator &operator+=(std::size_t offset) requires(hasAddition<typename BASE::element_index_t>) {
      (void) BASE::operator+=(offset);
      return *this;
   }
 
   // also define post-fix iterator to allow these iterators to be used to create a std::ranges::subrange
   ProxyIterator operator++(int) {
      ProxyIterator clone(*this);
      this->m_index = T_Derived::nextElementIndex(this->cptr(), std::move(this->m_index));
      return clone;
   }
 
   template<class OtherContainer>
   bool operator!=(const ProxyIteratorBase<OtherContainer, T_Derived, ElementProxy> &other) const
      requires(std::is_same_v<typename BASE::ContainerNonConst, typename ProxyIteratorBase<OtherContainer, T_Derived, ElementProxy>::ContainerNonConst>)
   {
      return !(this->operator==(other));
   }
 
   // the type resulting from dereferencing the iterator
   using value_type = decltype( std::declval<BASE>().operator *());
private:
   // helper class to define the type representing the differences of two iterators
   // e.g. used to compute the size of std::ranges::subrange
   template <typename T>
   struct diff_type_helper {
      // for integral types assume that a 64 bit signed integer is a good choice
      static std::int64_t diff(const T &a, const T &b)
         requires(std::is_integral_v<T>)
      {return a-b;}
 
      // if a difference operation is defined for the index then use the return type
      static auto  diff(const T &a, const T &b)
         requires(!std::is_integral_v<T> && hasDifference<T>)
      {return a-b;}
 
      // otherwise use a type which is not a valid difference type what concerns std::ranges::subrange
      static void  diff([[maybe_unused]] const T &a, [[maybe_unused]] const T &b)
         requires(!std::is_integral_v<T> && !hasDifference<T>)
      { }
   };
public:
   using difference_type = decltype( diff_type_helper<typename BASE::element_index_t>::diff(std::declval<typename BASE::element_index_t>(),
                                                                                            std::declval<typename BASE::element_index_t>()) );
};
 

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

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

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

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

   template <typename T_RWProxy>
   ContainerProxy(const T_RWProxy &other)
      requires(BASE::isConst
               && isConvertableToReadOnlyProxy<ContainerProxy<Container, T_Derived, ElementProxy, IndexType>, T_RWProxy> )
   : BASE(&other.container()), m_index(other.index())
   {}
 
 
 
 
   // the iterator class to iterator over elements of this proxy container with read write element access
   using iterator = ProxyIterator<ContainerNonConst,T_Derived, ElementProxy>;
   // the iterator class to iterator over elements of this proxy container with read only element access
   using const_iterator = ProxyIterator<const ContainerNonConst,T_Derived, ElementProxy>;

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

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

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

   iterator begin() requires ( !BASE::isConst ) {
      return iterator(this->ptr(), T_Derived::beginIndex(this->cptr(), m_index) );
   }

   iterator end() requires ( !BASE::isConst ) {
      return iterator(this->ptr(), T_Derived::endIndex(this->cptr(), m_index) );
   }

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

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

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

   auto operator[](std::size_t element_count) requires (!BASE::isConst)
   { assert( element_count < size() );
      return iterator::createElementProxy(this->ptr(), T_Derived::elementIndexAt(this->cptr(), this->m_index,element_count));}

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

   auto front() requires (!BASE::isConst)
   { assert( !empty() );
     return iterator::createElementProxy(this->ptr(), T_Derived::beginIndex(this->cptr(), this->m_index));}

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

   auto back() requires (!BASE::isConst)
   { assert(this->size() > 0);
     //coverity[INTEGER_OVERFLOW]
     std::size_t element_count = this->size()-1;
     return iterator::createElementProxy(this->ptr(), T_Derived::elementIndexAt(this->ptr(), this->m_index,element_count));
   }

   static element_index_t beginIndex([[maybe_unused]] const ContainerNonConst *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<ContainerNonConst> )
   {
      return static_cast<element_index_t>(0u);
   }

   static element_index_t endIndex([[maybe_unused]] const ContainerNonConst *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 ContainerNonConst *container, element_index_t &&element_index)
   {
      assert( container );
      return ++element_index;
   }

   static element_index_t elementIndexAt(const ContainerNonConst *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->cptr()
              ? T_Derived::endIndex(this->cptr(), m_index)-T_Derived::beginIndex(this->cptr(), m_index)
              : 0u);
   }

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