Debian Codegraph @

src/mpt/io_read/filecursor.hpp

raw
1 /* SPDX-License-Identifier: BSL-1.0 OR BSD-3-Clause */
2
3 #ifndef MPT_IO_READ_FILECURSOR_HPP
4 #define MPT_IO_READ_FILECURSOR_HPP
5
6
7
8 #include "mpt/base/alloc.hpp"
9 #include "mpt/base/macros.hpp"
10 #include "mpt/base/memory.hpp"
11 #include "mpt/base/namespace.hpp"
12 #include "mpt/base/span.hpp"
13 #include "mpt/base/utility.hpp"
14 #include "mpt/out_of_memory/out_of_memory.hpp"
15
16 #include <algorithm>
17 #include <optional>
18 #include <vector>
19
20 #include <cstddef>
21
22
23
24 namespace mpt {
25 inline namespace MPT_INLINE_NS {
26
27
28
29 namespace IO {
30
31
32
33 // change to show warnings for functions which trigger pre-caching the whole file for unseekable streams
34 //#define MPT_FILECURSOR_DEPRECATED [[deprecated]]
35 #define MPT_FILECURSOR_DEPRECATED
36
37
38
39 template <typename Ttraits, typename Tfilenametraits>
40 class FileCursor {
41
42 private:
43 using traits_type = Ttraits;
44 using filename_traits_type = Tfilenametraits;
45
46 public:
47 using pos_type = typename traits_type::pos_type;
48
49 using data_type = typename traits_type::data_type;
50 using ref_data_type = typename traits_type::ref_data_type;
51 using shared_data_type = typename traits_type::shared_data_type;
52 using value_data_type = typename traits_type::value_data_type;
53
54 using filename_type = typename filename_traits_type::filename_type;
55 using shared_filename_type = typename filename_traits_type::shared_filename_type;
56
57 protected:
58 shared_data_type SharedDataContainer() const {
59 return traits_type::get_shared(m_data);
60 }
61 ref_data_type DataContainer() const {
62 return traits_type::get_ref(m_data);
63 }
64
65 static value_data_type DataInitializer() {
66 return traits_type::make_data();
67 }
68 static value_data_type DataInitializer(mpt::const_byte_span data) {
69 return traits_type::make_data(data);
70 }
71
72 static value_data_type CreateChunkImpl(shared_data_type data, pos_type position, pos_type size) {
73 return traits_type::make_chunk(data, position, size);
74 }
75
76 private:
77 data_type m_data;
78
79 pos_type streamPos; // Cursor location in the file
80
81 shared_filename_type m_fileName; // Filename that corresponds to this FileCursor. It is only set if this FileCursor represents the whole contents of fileName. May be nullopt.
82
83 public:
84 // Initialize invalid file reader object.
85 FileCursor()
86 : m_data(DataInitializer())
87 , streamPos(0)
88 , m_fileName(nullptr) {
89 return;
90 }
91
92 // Initialize file reader object with pointer to data and data length.
93 template <typename Tbyte>
94 explicit FileCursor(mpt::span<Tbyte> bytedata, shared_filename_type filename = shared_filename_type{})
95 : m_data(DataInitializer(mpt::byte_cast<mpt::const_byte_span>(bytedata)))
96 , streamPos(0)
97 , m_fileName(std::move(filename)) {
98 return;
99 }
100
101 // Initialize file reader object based on an existing file reader object window.
102 explicit FileCursor(value_data_type other, shared_filename_type filename = shared_filename_type{})
103 : m_data(std::move(other))
104 , streamPos(0)
105 , m_fileName(std::move(filename)) {
106 return;
107 }
108
109 public:
110 std::optional<filename_type> GetOptionalFileName() const {
111 return filename_traits_type::get_optional_filename(m_fileName);
112 }
113
114 // Returns true if the object points to a valid (non-empty) stream.
115 operator bool() const {
116 return IsValid();
117 }
118
119 // Returns true if the object points to a valid (non-empty) stream.
120 bool IsValid() const {
121 return DataContainer().IsValid();
122 }
123
124 // Reset cursor to first byte in file.
125 void Rewind() {
126 streamPos = 0;
127 }
128
129 // Seek to a position in the mapped file.
130 // Returns false if position is invalid.
131 bool Seek(pos_type position) {
132 if (position <= streamPos) {
133 streamPos = position;
134 return true;
135 }
136 if (DataContainer().CanRead(0, position)) {
137 streamPos = position;
138 return true;
139 } else {
140 return false;
141 }
142 }
143
144 // Increases position by skipBytes.
145 // Returns true if skipBytes could be skipped or false if the file end was reached earlier.
146 bool Skip(pos_type skipBytes) {
147 if (CanRead(skipBytes)) {
148 streamPos += skipBytes;
149 return true;
150 } else {
151 streamPos = DataContainer().GetLength();
152 return false;
153 }
154 }
155
156 // Decreases position by skipBytes.
157 // Returns true if skipBytes could be skipped or false if the file start was reached earlier.
158 bool SkipBack(pos_type skipBytes) {
159 if (streamPos >= skipBytes) {
160 streamPos -= skipBytes;
161 return true;
162 } else {
163 streamPos = 0;
164 return false;
165 }
166 }
167
168 // Returns cursor position in the mapped file.
169 pos_type GetPosition() const {
170 return streamPos;
171 }
172
173 // Return true IFF seeking and GetLength() is fast.
174 // In particular, it returns false for unseekable stream where GetLength()
175 // requires pre-caching.
176 bool HasFastGetLength() const {
177 return DataContainer().HasFastGetLength();
178 }
179
180 // Returns size of the mapped file in bytes.
181 MPT_FILECURSOR_DEPRECATED pos_type GetLength() const {
182 // deprecated because in case of an unseekable std::istream, this triggers caching of the whole file
183 return DataContainer().GetLength();
184 }
185
186 // Return byte count between cursor position and end of file, i.e. how many bytes can still be read.
187 MPT_FILECURSOR_DEPRECATED pos_type BytesLeft() const {
188 // deprecated because in case of an unseekable std::istream, this triggers caching of the whole file
189 return DataContainer().GetLength() - streamPos;
190 }
191
192 bool EndOfFile() const {
193 return !CanRead(1);
194 }
195
196 bool NoBytesLeft() const {
197 return !CanRead(1);
198 }
199
200 // Check if "amount" bytes can be read from the current position in the stream.
201 bool CanRead(pos_type amount) const {
202 return DataContainer().CanRead(streamPos, amount);
203 }
204
205 // Check if file size is at least size, without potentially caching the whole file to query the exact file length.
206 bool LengthIsAtLeast(pos_type size) const {
207 return DataContainer().CanRead(0, size);
208 }
209
210 // Check if file size is exactly size, without potentially caching the whole file if it is larger.
211 bool LengthIs(pos_type size) const {
212 return DataContainer().CanRead(0, size) && !DataContainer().CanRead(size, 1);
213 }
214
215 protected:
216 FileCursor CreateChunk(pos_type position, pos_type length) const {
217 pos_type readableLength = DataContainer().GetReadableLength(position, length);
218 if (readableLength == 0) {
219 return FileCursor();
220 }
221 return FileCursor(CreateChunkImpl(SharedDataContainer(), position, readableLength));
222 }
223
224 public:
225 // Create a new FileCursor object for parsing a sub chunk at a given position with a given length.
226 // The file cursor is not modified.
227 FileCursor GetChunkAt(pos_type position, pos_type length) const {
228 return CreateChunk(position, length);
229 }
230
231 // Create a new FileCursor object for parsing a sub chunk at the current position with a given length.
232 // The file cursor is not advanced.
233 FileCursor GetChunk(pos_type length) {
234 return CreateChunk(streamPos, length);
235 }
236 // Create a new FileCursor object for parsing a sub chunk at the current position with a given length.
237 // The file cursor is advanced by "length" bytes.
238 FileCursor ReadChunk(pos_type length) {
239 pos_type position = streamPos;
240 Skip(length);
241 return CreateChunk(position, length);
242 }
243
244 class PinnedView {
245 private:
246 std::size_t size_;
247 const std::byte * pinnedData;
248 std::vector<std::byte> cache;
249
250 private:
251 void Init(const FileCursor & file, std::size_t size) {
252 size_ = 0;
253 pinnedData = nullptr;
254 if (!file.CanRead(size)) {
255 size = static_cast<std::size_t>(file.BytesLeft());
256 }
257 size_ = size;
258 if (file.DataContainer().HasPinnedView()) {
259 pinnedData = file.DataContainer().GetRawData() + file.GetPosition();
260 } else {
261 cache.resize(size_);
262 if (!cache.empty()) {
263 file.GetRaw(mpt::as_span(cache));
264 }
265 }
266 }
267
268 public:
269 PinnedView()
270 : size_(0)
271 , pinnedData(nullptr) {
272 }
273 PinnedView(const FileCursor & file) {
274 MPT_MAYBE_CONSTANT_IF (!mpt::in_range<std::size_t>(file.BytesLeft())) {
275 mpt::throw_out_of_memory();
276 }
277 Init(file, static_cast<std::size_t>(file.BytesLeft()));
278 }
279 PinnedView(const FileCursor & file, std::size_t size) {
280 Init(file, size);
281 }
282 PinnedView(FileCursor & file, bool advance) {
283 MPT_MAYBE_CONSTANT_IF (!mpt::in_range<std::size_t>(file.BytesLeft())) {
284 mpt::throw_out_of_memory();
285 }
286 Init(file, static_cast<std::size_t>(file.BytesLeft()));
287 if (advance) {
288 file.Skip(size_);
289 }
290 }
291 PinnedView(FileCursor & file, std::size_t size, bool advance) {
292 Init(file, size);
293 if (advance) {
294 file.Skip(size_);
295 }
296 }
297
298 public:
299 mpt::const_byte_span GetSpan() const {
300 if (pinnedData) {
301 return mpt::as_span(pinnedData, size_);
302 } else if (!cache.empty()) {
303 return mpt::as_span(cache);
304 } else {
305 return mpt::const_byte_span();
306 }
307 }
308 mpt::const_byte_span span() const {
309 return GetSpan();
310 }
311 void invalidate() {
312 size_ = 0;
313 pinnedData = nullptr;
314 cache = std::vector<std::byte>();
315 }
316 const std::byte * data() const {
317 return span().data();
318 }
319 std::size_t size() const {
320 return size_;
321 }
322 mpt::const_byte_span::pointer begin() const {
323 return span().data();
324 }
325 mpt::const_byte_span::pointer end() const {
326 return span().data() + span().size();
327 }
328 mpt::const_byte_span::const_pointer cbegin() const {
329 return span().data();
330 }
331 mpt::const_byte_span::const_pointer cend() const {
332 return span().data() + span().size();
333 }
334 };
335
336 // Returns a pinned view into the remaining raw data from cursor position.
337 PinnedView GetPinnedView() const {
338 return PinnedView(*this);
339 }
340 // Returns a pinned view into the remeining raw data from cursor position, clamped at size.
341 PinnedView GetPinnedView(std::size_t size) const {
342 return PinnedView(*this, size);
343 }
344
345 // Returns a pinned view into the remeining raw data from cursor position.
346 // File cursor is advaned by the size of the returned pinned view.
347 PinnedView ReadPinnedView() {
348 return PinnedView(*this, true);
349 }
350 // Returns a pinned view into the remeining raw data from cursor position, clamped at size.
351 // File cursor is advaned by the size of the returned pinned view.
352 PinnedView ReadPinnedView(std::size_t size) {
353 return PinnedView(*this, size, true);
354 }
355
356 template <typename Tspan>
357 Tspan GetRawWithOffset(std::size_t offset, Tspan dst) const {
358 return mpt::byte_cast<Tspan>(DataContainer().Read(streamPos + offset, mpt::byte_cast<mpt::byte_span>(dst)));
359 }
360
361 template <typename Tspan>
362 Tspan GetRaw(Tspan dst) const {
363 return mpt::byte_cast<Tspan>(DataContainer().Read(streamPos, mpt::byte_cast<mpt::byte_span>(dst)));
364 }
365
366 template <typename Tspan>
367 Tspan ReadRaw(Tspan dst) {
368 Tspan result = mpt::byte_cast<Tspan>(DataContainer().Read(streamPos, mpt::byte_cast<mpt::byte_span>(dst)));
369 streamPos += result.size();
370 return result;
371 }
372
373 std::vector<std::byte> GetRawDataAsByteVector() const {
374 PinnedView view = GetPinnedView();
375 return mpt::make_vector(view.span());
376 }
377 std::vector<std::byte> ReadRawDataAsByteVector() {
378 PinnedView view = ReadPinnedView();
379 return mpt::make_vector(view.span());
380 }
381 std::vector<std::byte> GetRawDataAsByteVector(std::size_t size) const {
382 PinnedView view = GetPinnedView(size);
383 return mpt::make_vector(view.span());
384 }
385 std::vector<std::byte> ReadRawDataAsByteVector(std::size_t size) {
386 PinnedView view = ReadPinnedView(size);
387 return mpt::make_vector(view.span());
388 }
389 };
390
391
392
393 } // namespace IO
394
395
396
397 } // namespace MPT_INLINE_NS
398 } // namespace mpt
399
400
401
402 #endif // MPT_IO_READ_FILECURSOR_HPP