|
| 1 | +/// \file ROOT/RNTupleAttrReading.hxx |
| 2 | +/// \ingroup NTuple |
| 3 | +/// \author Giacomo Parolini <giacomo.parolini@cern.ch> |
| 4 | +/// \date 2026-04-01 |
| 5 | +/// \warning This is part of the ROOT 7 prototype! It will change without notice. It might trigger earthquakes. Feedback |
| 6 | +/// is welcome! |
| 7 | + |
| 8 | +#ifndef ROOT7_RNTuple_Attr_Reading |
| 9 | +#define ROOT7_RNTuple_Attr_Reading |
| 10 | + |
| 11 | +#include <memory> |
| 12 | +#include <vector> |
| 13 | + |
| 14 | +#include <ROOT/RNTupleFillContext.hxx> |
| 15 | +#include <ROOT/RNTupleAttrUtils.hxx> |
| 16 | + |
| 17 | +namespace ROOT { |
| 18 | + |
| 19 | +class REntry; |
| 20 | +class RNTupleDescriptor; |
| 21 | +class RNTupleModel; |
| 22 | + |
| 23 | +namespace Experimental { |
| 24 | + |
| 25 | +// clang-format off |
| 26 | +/** |
| 27 | +\class ROOT::Experimental::RNTupleAttrRange |
| 28 | +\ingroup NTuple |
| 29 | +\brief A range of main entries referred to by an attribute entry |
| 30 | +
|
| 31 | +Each attribute entry contains a set of values referring to 0 or more contiguous entries in the main RNTuple. |
| 32 | +This class represents that contiguous range of entries. |
| 33 | +*/ |
| 34 | +// clang-format on |
| 35 | +class RNTupleAttrRange final { |
| 36 | + ROOT::NTupleSize_t fStart = 0; |
| 37 | + ROOT::NTupleSize_t fLength = 0; |
| 38 | + |
| 39 | + RNTupleAttrRange(ROOT::NTupleSize_t start, ROOT::NTupleSize_t length) : fStart(start), fLength(length) {} |
| 40 | + |
| 41 | +public: |
| 42 | + static RNTupleAttrRange FromStartLength(ROOT::NTupleSize_t start, ROOT::NTupleSize_t length) |
| 43 | + { |
| 44 | + return RNTupleAttrRange{start, length}; |
| 45 | + } |
| 46 | + |
| 47 | + /// Creates an AttributeRange from [start, end), where `end` is one past the last valid entry of the range |
| 48 | + /// (`FromStartEnd(0, 10)` will create a range whose last valid index is 9). |
| 49 | + static RNTupleAttrRange FromStartEnd(ROOT::NTupleSize_t start, ROOT::NTupleSize_t end) |
| 50 | + { |
| 51 | + R__ASSERT(end >= start); |
| 52 | + return RNTupleAttrRange{start, end - start}; |
| 53 | + } |
| 54 | + |
| 55 | + RNTupleAttrRange() = default; |
| 56 | + |
| 57 | + /// Returns the first valid entry index in the range. Returns nullopt if the range has zero length. |
| 58 | + std::optional<ROOT::NTupleSize_t> GetFirst() const { return fLength ? std::make_optional(fStart) : std::nullopt; } |
| 59 | + /// Returns the beginning of the range. Note that this is *not* a valid index in the range if the range has zero |
| 60 | + /// length. |
| 61 | + ROOT::NTupleSize_t GetStart() const { return fStart; } |
| 62 | + /// Returns the last valid entry index in the range. Returns nullopt if the range has zero length. |
| 63 | + std::optional<ROOT::NTupleSize_t> GetLast() const |
| 64 | + { |
| 65 | + return fLength ? std::make_optional(fStart + fLength - 1) : std::nullopt; |
| 66 | + } |
| 67 | + /// Returns one past the last valid index of the range, equal to `GetStart() + GetLength()`. |
| 68 | + ROOT::NTupleSize_t GetEnd() const { return fStart + fLength; } |
| 69 | + ROOT::NTupleSize_t GetLength() const { return fLength; } |
| 70 | + |
| 71 | + /// Returns the pair { firstEntryIdx, lastEntryIdx } (inclusive). Returns nullopt if the range has zero length. |
| 72 | + std::optional<std::pair<ROOT::NTupleSize_t, ROOT::NTupleSize_t>> GetFirstLast() const |
| 73 | + { |
| 74 | + return fLength ? std::make_optional(std::make_pair(fStart, fStart + fLength - 1)) : std::nullopt; |
| 75 | + } |
| 76 | + /// Returns the pair { start, length }. |
| 77 | + std::pair<ROOT::NTupleSize_t, ROOT::NTupleSize_t> GetStartLength() const { return {GetStart(), GetLength()}; } |
| 78 | +}; |
| 79 | + |
| 80 | +class RNTupleAttrEntryIterable; |
| 81 | + |
| 82 | +// clang-format off |
| 83 | +/** |
| 84 | +\class ROOT::Experimental::RNTupleAttrSetReader |
| 85 | +\ingroup NTuple |
| 86 | +\brief Class used to read a RNTupleAttrSet in the context of a RNTupleReader |
| 87 | +
|
| 88 | +An RNTupleAttrSetReader is created via RNTupleReader::OpenAttributeSet. Once created, it may outlive its parent Reader. |
| 89 | +Reading Attributes works similarly to reading regular RNTuple entries: you can either create entries or just use the |
| 90 | +AttrSetReader Model's default entry and load data into it via LoadEntry. |
| 91 | +
|
| 92 | +~~ {.cpp} |
| 93 | +// Reading Attributes via RNTupleAttrSetReader |
| 94 | +// ------------------------------------------- |
| 95 | +
|
| 96 | +// Assuming `reader` is a RNTupleReader: |
| 97 | +auto attrSet = reader->OpenAttributeSet("MyAttrSet"); |
| 98 | +
|
| 99 | +// Just like how you would read a regular RNTuple, first get the pointer to the fields you want to read: |
| 100 | +auto &attrEntry = attrSet->GetModel().GetDefaultEntry(); |
| 101 | +auto pAttr = attrEntry->GetPtr<std::string>("myAttr"); |
| 102 | +
|
| 103 | +// Then select which attributes you want to read. E.g. read all attributes linked to the entry at index 10: |
| 104 | +for (auto idx : attrSet->GetAttributes(10)) { |
| 105 | + attrSet->LoadEntry(idx); |
| 106 | + cout << "entry " << idx << " has attribute " << *pAttr << "\n"; |
| 107 | +} |
| 108 | +~~ |
| 109 | +*/ |
| 110 | +// clang-format on |
| 111 | +class RNTupleAttrSetReader final { |
| 112 | + friend class ROOT::RNTupleReader; |
| 113 | + |
| 114 | + /// List containing pairs { entryRange, entryIndex }, used to quickly find out which entries in the Attribute |
| 115 | + /// RNTuple contain entries that overlap a given range. The list is sorted by range start, i.e. |
| 116 | + /// entryRange.first.Start(). |
| 117 | + std::vector<std::pair<RNTupleAttrRange, NTupleSize_t>> fEntryRanges; |
| 118 | + /// The internal Reader used to read the AttributeSet RNTuple |
| 119 | + std::unique_ptr<RNTupleReader> fReader; |
| 120 | + /// The reconstructed user model |
| 121 | + std::unique_ptr<ROOT::RNTupleModel> fUserModel; |
| 122 | + |
| 123 | + explicit RNTupleAttrSetReader(std::unique_ptr<RNTupleReader> reader); |
| 124 | + |
| 125 | +public: |
| 126 | + RNTupleAttrSetReader(const RNTupleAttrSetReader &) = delete; |
| 127 | + RNTupleAttrSetReader &operator=(const RNTupleAttrSetReader &) = delete; |
| 128 | + RNTupleAttrSetReader(RNTupleAttrSetReader &&) = default; |
| 129 | + RNTupleAttrSetReader &operator=(RNTupleAttrSetReader &&) = default; |
| 130 | + ~RNTupleAttrSetReader() = default; |
| 131 | + |
| 132 | + /// Returns the read-only descriptor of this attribute set |
| 133 | + const ROOT::RNTupleDescriptor &GetDescriptor() const; |
| 134 | + /// Returns the read-only model of this attribute set |
| 135 | + const ROOT::RNTupleModel &GetModel() const { return *fUserModel; } |
| 136 | + |
| 137 | + /// Creates an entry suitable for use with LoadEntry. |
| 138 | + /// This is a convenience method equivalent to GetModel().CreateEntry(). |
| 139 | + std::unique_ptr<REntry> CreateEntry(); |
| 140 | + |
| 141 | + /// Loads the attribute entry at position `index` into the default entry. |
| 142 | + /// Returns the range of main RNTuple entries that the loaded set of attributes refers to. |
| 143 | + RNTupleAttrRange LoadEntry(NTupleSize_t index); |
| 144 | + /// Loads the attribute entry at position `index` into the given entry. |
| 145 | + /// Returns the range of main RNTuple entries that the loaded set of attributes refers to. |
| 146 | + RNTupleAttrRange LoadEntry(NTupleSize_t index, REntry &entry); |
| 147 | + |
| 148 | + /// Returns the number of all attribute entries in this attribute set. |
| 149 | + std::size_t GetNEntries() const { return fEntryRanges.size(); } |
| 150 | +}; |
| 151 | + |
| 152 | +} // namespace Experimental |
| 153 | +} // namespace ROOT |
| 154 | + |
| 155 | +#endif |
0 commit comments