Acts/EventData/SpacePointColumnProxy.hpp

0001 // This file is part of the ACTS project.
0002 //
0003 // Copyright (C) 2016 CERN for the benefit of the ACTS project
0004 //
0005 // This Source Code Form is subject to the terms of the Mozilla Public
0006 // License, v. 2.0. If a copy of the MPL was not distributed with this
0007 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
0008
0009 #pragma once
0010
0011 #include "Acts/EventData/Types.hpp"
0012 #include "Acts/Utilities/TypeTraits.hpp"
0013 #include "Acts/Utilities/detail/ContainerSubset.hpp"
0014
0015 #include <cassert>
0016 #include <span>
0017 #include <vector>
0018
0019 namespace Acts {
0020
0021 class SpacePointContainer;
0022
0023 /// Additional column of data that can be added to the space point container.
0024 /// The column is indexed by the space point index.
0025 template <typename T, bool read_only>
0026 class SpacePointColumnProxy {
0027  public:
0028   /// Flag indicating whether this space point column proxy is read-only
0029   constexpr static bool ReadOnly = read_only;
0030   /// Type alias for space point index type
0031   using Index = SpacePointIndex;
0032   /// Type alias for space point index range type
0033   using IndexRange = SpacePointIndexRange;
0034   /// Type alias for space point index subset type
0035   using IndexSubset = SpacePointIndexSubset;
0036   /// Type alias for column value type
0037   using Value = T;
0038   /// Type alias for container type (const if read-only)
0039   using Container = const_if_t<ReadOnly, SpacePointContainer>;
0040   /// Type alias for column container type (const if read-only)
0041   using Column = const_if_t<ReadOnly, std::vector<Value>>;
0042
0043   /// Constructs a space point column proxy for the given container and column.
0044   /// @param container The container holding the space point.
0045   /// @param column The column of data to access.
0046   SpacePointColumnProxy(Container &container, Column &column)
0047       : m_container{&container}, m_column(&column) {}
0048
0049   /// Copy construct a space point column proxy.
0050   /// @param other The space point column proxy to copy.
0051   SpacePointColumnProxy(const SpacePointColumnProxy &other) noexcept = default;
0052
0053   /// Copy construct a mutable space point column proxy.
0054   /// @param other The mutable space point column proxy to copy.
0055   explicit SpacePointColumnProxy(
0056       const SpacePointColumnProxy<T, false> &other) noexcept
0057     requires ReadOnly
0058       : m_container(&other.container()), m_column(&other.column()) {}
0059
0060   /// Returns the number of entries in the space point column.
0061   /// @return The size of the space point column.
0062   std::uint32_t size() const noexcept { return column().size(); }
0063
0064   /// Returns a const proxy of the space point column.
0065   /// @return A const proxy of the space point column.
0066   SpacePointColumnProxy<T, true> asConst() const noexcept
0067     requires(!ReadOnly)
0068   {
0069     return {*m_container, *m_column};
0070   }
0071
0072   /// Gets the container holding the space point.
0073   /// @return A reference to the container holding the space point.
0074   SpacePointContainer &container() noexcept
0075     requires(!ReadOnly)
0076   {
0077     return *m_container;
0078   }
0079   /// Gets the container holding the space point.
0080   /// @return A const reference to the container holding the space point.
0081   const SpacePointContainer &container() const noexcept { return *m_container; }
0082
0083   /// Returns a const reference to the column container.
0084   /// @return A const reference to the column container.
0085   const std::vector<Value> &column() const noexcept { return *m_column; }
0086
0087   /// Returns a mutable span to the column data.
0088   /// @return A mutable span to the column data.
0089   std::span<Value> data() noexcept
0090     requires(!ReadOnly)
0091   {
0092     return std::span<Value>(column().data(), column().size());
0093   }
0094   /// Returns a const span to the column data.
0095   /// @return A const span to the column data.
0096   std::span<const Value> data() const noexcept {
0097     return std::span<const Value>(column().data(), column().size());
0098   }
0099
0100   /// Returns a mutable reference to the column entry at the given index.
0101   /// If the index is out of range, an exception is thrown.
0102   /// @param index The index of the space point to access.
0103   /// @return A mutable reference to the column entry at the given index.
0104   /// @throws std::out_of_range if the index is out of range.
0105   Value &at(Index index)
0106     requires(!ReadOnly)
0107   {
0108     if (index >= column().size()) {
0109       throw std::out_of_range("Index out of range in SpacePointContainer: " +
0110                               std::to_string(index) +
0111                               " >= " + std::to_string(size()));
0112     }
0113     return data()[index];
0114   }
0115   /// Returns a const reference to the column entry at the given index.
0116   /// If the index is out of range, an exception is thrown.
0117   /// @param index The index of the space point to access.
0118   /// @return A const reference to the column entry at the given index.
0119   /// @throws std::out_of_range if the index is out of range.
0120   const Value &at(Index index) const {
0121     if (index >= column().size()) {
0122       throw std::out_of_range("Index out of range in SpacePointContainer: " +
0123                               std::to_string(index) +
0124                               " >= " + std::to_string(size()));
0125     }
0126     return data()[index];
0127   }
0128
0129   /// Returns a mutable reference to the column entry at the given index.
0130   /// @param index The index of the space point to access.
0131   /// @return A mutable reference to the column entry at the given index.
0132   Value &operator[](Index index) noexcept
0133     requires(!ReadOnly)
0134   {
0135     assert(index < column().size() && "Index out of bounds");
0136     return data()[index];
0137   }
0138   /// Returns a const reference to the column entry at the given index.
0139   /// @param index The index of the space point to access.
0140   /// @return A const reference to the column entry at the given index.
0141   const Value &operator[](Index index) const noexcept {
0142     assert(index < column().size() && "Index out of bounds");
0143     return data()[index];
0144   }
0145
0146   /// Subset view over selected column entries.
0147   class Subset
0148       : public detail::ContainerSubset<Subset, Subset, Column, Value,
0149                                        std::span<const Index>, ReadOnly> {
0150    public:
0151     /// Base class type
0152     using Base = detail::ContainerSubset<Subset, Subset, Column, Value,
0153                                          std::span<const Index>, ReadOnly>;
0154
0155     using Base::Base;
0156   };
0157
0158   /// Creates a subset view of this space point column based on provided
0159   /// indices.
0160   ///
0161   /// This method creates a subset proxy that provides access to only the space
0162   /// points at the indices specified in the IndexSubset. The subset maintains a
0163   /// reference to the original column data without copying, enabling efficient
0164   /// access to selected space points for filtering, clustering, or other
0165   /// operations.
0166   ///
0167   /// @param subset The index subset specifying which space points to include
0168   /// @return A subset proxy providing access to the selected space points
0169   ///
0170   /// @note The returned subset shares data with the original column
0171   /// @note The subset remains valid only as long as the original column exists
0172   /// @note This operation does not copy data, providing efficient subset access
0173   Subset subset(const IndexSubset &subset) const noexcept {
0174     return Subset(*m_column, subset);
0175   }
0176
0177  private:
0178   Container *m_container{};
0179   Column *m_column{};
0180
0181   std::vector<Value> &column() noexcept
0182     requires(!ReadOnly)
0183   {
0184     return *m_column;
0185   }
0186
0187   friend class SpacePointContainer;
0188 };
0189
0190 /// Const proxy to a space point column for read-only access
0191 template <typename T>
0192 using ConstSpacePointColumnProxy = SpacePointColumnProxy<T, true>;
0193 /// Mutable proxy to a space point column allowing modification
0194 template <typename T>
0195 using MutableSpacePointColumnProxy = SpacePointColumnProxy<T, false>;
0196
0197 }  // namespace Acts