@nirs4all/formats-wasm 0.2.12 → 0.2.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (88) hide show
  1. package/THIRD_PARTY_NOTICES.md +49 -0
  2. package/nirs4all_formats_wasm_bg.wasm +0 -0
  3. package/package.json +4 -2
  4. package/reader-backports/hdf5-reader/Cargo.toml +119 -0
  5. package/reader-backports/hdf5-reader/LICENSE-APACHE +164 -0
  6. package/reader-backports/hdf5-reader/LICENSE-MIT +21 -0
  7. package/reader-backports/hdf5-reader/PROVENANCE.json +80 -0
  8. package/reader-backports/hdf5-reader/README.md +308 -0
  9. package/reader-backports/hdf5-reader/UPSTREAM-Cargo.toml +44 -0
  10. package/reader-backports/hdf5-reader/UPSTREAM-VCS.json +6 -0
  11. package/reader-backports/hdf5-reader/src/attribute_api.rs +847 -0
  12. package/reader-backports/hdf5-reader/src/btree_v1.rs +726 -0
  13. package/reader-backports/hdf5-reader/src/btree_v2.rs +2068 -0
  14. package/reader-backports/hdf5-reader/src/cache.rs +354 -0
  15. package/reader-backports/hdf5-reader/src/checksum.rs +56 -0
  16. package/reader-backports/hdf5-reader/src/chunk_index.rs +423 -0
  17. package/reader-backports/hdf5-reader/src/dataset.rs +4733 -0
  18. package/reader-backports/hdf5-reader/src/datatype_api.rs +497 -0
  19. package/reader-backports/hdf5-reader/src/error.rs +167 -0
  20. package/reader-backports/hdf5-reader/src/extensible_array.rs +1886 -0
  21. package/reader-backports/hdf5-reader/src/filters/deflate.rs +93 -0
  22. package/reader-backports/hdf5-reader/src/filters/fletcher32.rs +52 -0
  23. package/reader-backports/hdf5-reader/src/filters/lz4.rs +178 -0
  24. package/reader-backports/hdf5-reader/src/filters/mod.rs +326 -0
  25. package/reader-backports/hdf5-reader/src/filters/nbit.rs +586 -0
  26. package/reader-backports/hdf5-reader/src/filters/scaleoffset.rs +827 -0
  27. package/reader-backports/hdf5-reader/src/filters/shuffle.rs +99 -0
  28. package/reader-backports/hdf5-reader/src/fixed_array.rs +763 -0
  29. package/reader-backports/hdf5-reader/src/fractal_heap.rs +2029 -0
  30. package/reader-backports/hdf5-reader/src/global_heap.rs +284 -0
  31. package/reader-backports/hdf5-reader/src/group.rs +795 -0
  32. package/reader-backports/hdf5-reader/src/io.rs +413 -0
  33. package/reader-backports/hdf5-reader/src/lib.rs +916 -0
  34. package/reader-backports/hdf5-reader/src/local_heap.rs +261 -0
  35. package/reader-backports/hdf5-reader/src/messages/attribute.rs +304 -0
  36. package/reader-backports/hdf5-reader/src/messages/attribute_info.rs +96 -0
  37. package/reader-backports/hdf5-reader/src/messages/btree_k.rs +36 -0
  38. package/reader-backports/hdf5-reader/src/messages/continuation.rs +46 -0
  39. package/reader-backports/hdf5-reader/src/messages/dataspace.rs +259 -0
  40. package/reader-backports/hdf5-reader/src/messages/datatype.rs +938 -0
  41. package/reader-backports/hdf5-reader/src/messages/external_files.rs +50 -0
  42. package/reader-backports/hdf5-reader/src/messages/fill_value.rs +233 -0
  43. package/reader-backports/hdf5-reader/src/messages/filter_pipeline.rs +147 -0
  44. package/reader-backports/hdf5-reader/src/messages/group_info.rs +103 -0
  45. package/reader-backports/hdf5-reader/src/messages/layout.rs +476 -0
  46. package/reader-backports/hdf5-reader/src/messages/link.rs +170 -0
  47. package/reader-backports/hdf5-reader/src/messages/link_info.rs +127 -0
  48. package/reader-backports/hdf5-reader/src/messages/mod.rs +374 -0
  49. package/reader-backports/hdf5-reader/src/messages/modification_time.rs +83 -0
  50. package/reader-backports/hdf5-reader/src/messages/shared.rs +164 -0
  51. package/reader-backports/hdf5-reader/src/messages/shared_table.rs +67 -0
  52. package/reader-backports/hdf5-reader/src/messages/symbol_table_msg.rs +51 -0
  53. package/reader-backports/hdf5-reader/src/object_header.rs +1749 -0
  54. package/reader-backports/hdf5-reader/src/reference.rs +90 -0
  55. package/reader-backports/hdf5-reader/src/shared_message_table.rs +425 -0
  56. package/reader-backports/hdf5-reader/src/storage.rs +538 -0
  57. package/reader-backports/hdf5-reader/src/superblock.rs +285 -0
  58. package/reader-backports/hdf5-reader/src/symbol_table.rs +277 -0
  59. package/reader-backports/netcdf-reader/Cargo.toml +141 -0
  60. package/reader-backports/netcdf-reader/LICENSE-APACHE +164 -0
  61. package/reader-backports/netcdf-reader/LICENSE-MIT +21 -0
  62. package/reader-backports/netcdf-reader/PROVENANCE.json +55 -0
  63. package/reader-backports/netcdf-reader/README.md +308 -0
  64. package/reader-backports/netcdf-reader/UPSTREAM-Cargo.toml +48 -0
  65. package/reader-backports/netcdf-reader/UPSTREAM-VCS.json +6 -0
  66. package/reader-backports/netcdf-reader/src/cf/axes.rs +419 -0
  67. package/reader-backports/netcdf-reader/src/cf/bounds.rs +108 -0
  68. package/reader-backports/netcdf-reader/src/cf/crs.rs +269 -0
  69. package/reader-backports/netcdf-reader/src/cf/mod.rs +30 -0
  70. package/reader-backports/netcdf-reader/src/cf/time.rs +1122 -0
  71. package/reader-backports/netcdf-reader/src/classic/data.rs +1465 -0
  72. package/reader-backports/netcdf-reader/src/classic/header.rs +1097 -0
  73. package/reader-backports/netcdf-reader/src/classic/mod.rs +240 -0
  74. package/reader-backports/netcdf-reader/src/classic/storage.rs +211 -0
  75. package/reader-backports/netcdf-reader/src/classic/types.rs +93 -0
  76. package/reader-backports/netcdf-reader/src/classic/variable.rs +1162 -0
  77. package/reader-backports/netcdf-reader/src/error.rs +59 -0
  78. package/reader-backports/netcdf-reader/src/lib.rs +1531 -0
  79. package/reader-backports/netcdf-reader/src/masked.rs +173 -0
  80. package/reader-backports/netcdf-reader/src/nc4/attributes.rs +203 -0
  81. package/reader-backports/netcdf-reader/src/nc4/dimensions.rs +139 -0
  82. package/reader-backports/netcdf-reader/src/nc4/groups.rs +308 -0
  83. package/reader-backports/netcdf-reader/src/nc4/mod.rs +572 -0
  84. package/reader-backports/netcdf-reader/src/nc4/types.rs +309 -0
  85. package/reader-backports/netcdf-reader/src/nc4/variables.rs +420 -0
  86. package/reader-backports/netcdf-reader/src/types.rs +18 -0
  87. package/reader-backports/netcdf-reader/src/unpack.rs +113 -0
  88. package/reader-backports/netcdf-reader/src/user_defined.rs +569 -0
@@ -0,0 +1,4733 @@
1
+ use std::mem::MaybeUninit;
2
+ use std::num::NonZeroUsize;
3
+ use std::sync::{Arc, OnceLock};
4
+
5
+ use lru::LruCache;
6
+ use ndarray::{ArrayD, IxDyn};
7
+ use parking_lot::Mutex;
8
+ #[cfg(feature = "rayon")]
9
+ use rayon::prelude::*;
10
+ use smallvec::SmallVec;
11
+
12
+ use crate::attribute_api::{
13
+ collect_attribute_messages_storage, decode_string, decoded_vlen_strings_storage,
14
+ read_one_vlen_string_storage, resolve_vlen_bytes_storage, Attribute,
15
+ };
16
+ use crate::cache::{ChunkCache, ChunkCacheStats, ChunkKey};
17
+ use crate::chunk_index;
18
+ use crate::datatype_api::H5Type;
19
+ use crate::error::{ByteOrder, Error, Result};
20
+ use crate::filters::{self, FilterRegistry};
21
+ use crate::io::Cursor;
22
+ use crate::local_heap::LocalHeap;
23
+ use crate::messages::attribute::AttributeMessage;
24
+ use crate::messages::dataspace::{DataspaceMessage, DataspaceType};
25
+ use crate::messages::datatype::{Datatype, StringSize, VarLenKind};
26
+ use crate::messages::external_files::ExternalFilesMessage;
27
+ use crate::messages::fill_value::{FillTime, FillValueMessage};
28
+ use crate::messages::filter_pipeline::FilterPipelineMessage;
29
+ use crate::messages::layout::{ChunkIndexing, DataLayout};
30
+ use crate::messages::HdfMessage;
31
+ use crate::object_header::ObjectHeader;
32
+ use crate::storage::DynStorage;
33
+ use crate::FileContext;
34
+
35
+ const HOT_FULL_DATASET_CACHE_MAX_BYTES: usize = 32 * 1024 * 1024;
36
+
37
+ #[derive(Clone, Copy)]
38
+ struct FlatBufferPtr {
39
+ ptr: *mut u8,
40
+ len: usize,
41
+ }
42
+
43
+ #[derive(Clone, Copy)]
44
+ struct ChunkCopyLayout<'a> {
45
+ chunk_offsets: &'a [u64],
46
+ chunk_shape: &'a [u64],
47
+ dataset_shape: &'a [u64],
48
+ dataset_strides: &'a [usize],
49
+ chunk_strides: &'a [usize],
50
+ elem_size: usize,
51
+ }
52
+
53
+ #[derive(Clone, Copy)]
54
+ struct UnitStrideCopyLayout<'a> {
55
+ chunk_offsets: &'a [u64],
56
+ chunk_shape: &'a [u64],
57
+ dataset_shape: &'a [u64],
58
+ resolved: &'a ResolvedSelection,
59
+ chunk_strides: &'a [usize],
60
+ result_strides: &'a [usize],
61
+ elem_size: usize,
62
+ }
63
+
64
+ #[derive(Clone, Copy)]
65
+ struct ContiguousSliceDirectLayout<'a> {
66
+ dataset_strides: &'a [usize],
67
+ result_strides: &'a [usize],
68
+ elem_size: usize,
69
+ result_total_bytes: usize,
70
+ }
71
+
72
+ #[derive(Clone)]
73
+ struct ResolvedExternalRawSlot {
74
+ logical_offset: u64,
75
+ storage: DynStorage,
76
+ file_offset: u64,
77
+ size: u64,
78
+ }
79
+
80
+ pub(crate) struct DatasetParseContext {
81
+ pub(crate) context: Arc<FileContext>,
82
+ }
83
+
84
+ #[derive(Clone, Copy)]
85
+ struct ChunkEntrySelection<'a> {
86
+ shape: &'a [u64],
87
+ ndim: usize,
88
+ elem_size: usize,
89
+ chunk_bounds: Option<(&'a [u64], &'a [u64])>,
90
+ }
91
+
92
+ // SAFETY: `FlatBufferPtr` has no safe dereference operations. Callers of its
93
+ // unsafe methods must keep the allocation alive and coordinate disjoint writes.
94
+ unsafe impl Send for FlatBufferPtr {}
95
+
96
+ // SAFETY: sharing the pointer does not itself access the allocation. Every
97
+ // access remains unsafe and requires callers to guarantee disjoint writes.
98
+ unsafe impl Sync for FlatBufferPtr {}
99
+
100
+ impl FlatBufferPtr {
101
+ #[cfg(feature = "rayon")]
102
+ #[inline(always)]
103
+ unsafe fn copy_chunk(self, chunk_data: &[u8], layout: ChunkCopyLayout<'_>) -> Result<()> {
104
+ // SAFETY: the caller upholds this method's allocation-lifetime and
105
+ // disjoint-write requirements.
106
+ unsafe { copy_chunk_to_flat_with_strides_ptr(chunk_data, self, layout) }
107
+ }
108
+
109
+ #[cfg(feature = "rayon")]
110
+ #[inline(always)]
111
+ unsafe fn copy_selected(
112
+ self,
113
+ chunk_data: &[u8],
114
+ dim_indices: &[Vec<(usize, usize)>],
115
+ chunk_strides: &[usize],
116
+ result_strides: &[usize],
117
+ elem_size: usize,
118
+ ndim: usize,
119
+ ) -> Result<()> {
120
+ // SAFETY: the caller upholds this method's allocation-lifetime and
121
+ // disjoint-write requirements.
122
+ unsafe {
123
+ copy_selected_elements_ptr(
124
+ chunk_data,
125
+ self.ptr,
126
+ self.len,
127
+ dim_indices,
128
+ chunk_strides,
129
+ result_strides,
130
+ elem_size,
131
+ ndim,
132
+ )
133
+ }
134
+ }
135
+
136
+ #[cfg(feature = "rayon")]
137
+ #[inline(always)]
138
+ unsafe fn copy_unit_stride_chunk_overlap(
139
+ self,
140
+ chunk_data: &[u8],
141
+ layout: UnitStrideCopyLayout<'_>,
142
+ ) -> Result<()> {
143
+ // SAFETY: the caller upholds this method's allocation-lifetime and
144
+ // disjoint-write requirements.
145
+ unsafe { copy_unit_stride_chunk_overlap_ptr(chunk_data, self, layout) }
146
+ }
147
+ }
148
+
149
+ /// Hyperslab selection for reading slices of datasets.
150
+ #[derive(Debug, Clone)]
151
+ pub struct SliceInfo {
152
+ pub selections: Vec<SliceInfoElem>,
153
+ }
154
+
155
+ /// A single dimension's selection.
156
+ #[derive(Debug, Clone)]
157
+ pub enum SliceInfoElem {
158
+ /// Select a single index (reduces dimensionality).
159
+ Index(u64),
160
+ /// Select a range with optional step.
161
+ Slice { start: u64, end: u64, step: u64 },
162
+ }
163
+
164
+ #[derive(Clone, Debug)]
165
+ struct ResolvedSelectionDim {
166
+ start: u64,
167
+ end: u64,
168
+ step: u64,
169
+ count: usize,
170
+ }
171
+
172
+ #[derive(Clone, Debug, PartialEq, Eq, Hash)]
173
+ struct ChunkEntryCacheKey {
174
+ index_address: u64,
175
+ first_chunk: SmallVec<[u64; 4]>,
176
+ last_chunk: SmallVec<[u64; 4]>,
177
+ }
178
+
179
+ impl ResolvedSelectionDim {
180
+ fn chunk_index_range(&self, chunk_extent: u64) -> Option<(u64, u64)> {
181
+ if self.count == 0 {
182
+ return None;
183
+ }
184
+
185
+ Some((self.start / chunk_extent, (self.end - 1) / chunk_extent))
186
+ }
187
+ }
188
+
189
+ #[derive(Clone, Debug)]
190
+ struct ResolvedSelection {
191
+ dims: Vec<ResolvedSelectionDim>,
192
+ result_shape: Vec<usize>,
193
+ result_elements: usize,
194
+ }
195
+
196
+ impl ResolvedSelection {
197
+ fn result_dims_with_collapsed(&self) -> Vec<usize> {
198
+ self.dims.iter().map(|dim| dim.count).collect()
199
+ }
200
+
201
+ fn is_unit_stride(&self) -> bool {
202
+ self.dims.iter().all(|dim| dim.step == 1)
203
+ }
204
+ }
205
+
206
+ impl SliceInfo {
207
+ /// Create a selection that reads everything.
208
+ pub fn all(ndim: usize) -> Self {
209
+ SliceInfo {
210
+ selections: vec![
211
+ SliceInfoElem::Slice {
212
+ start: 0,
213
+ end: u64::MAX,
214
+ step: 1,
215
+ };
216
+ ndim
217
+ ],
218
+ }
219
+ }
220
+ }
221
+
222
+ fn checked_usize(value: u64, context: &str) -> Result<usize> {
223
+ usize::try_from(value).map_err(|_| {
224
+ Error::InvalidData(format!(
225
+ "{context} value {value} exceeds platform usize capacity"
226
+ ))
227
+ })
228
+ }
229
+
230
+ fn checked_mul_usize(lhs: usize, rhs: usize, context: &str) -> Result<usize> {
231
+ lhs.checked_mul(rhs)
232
+ .ok_or_else(|| Error::InvalidData(format!("{context} exceeds platform usize capacity")))
233
+ }
234
+
235
+ fn checked_add_usize(lhs: usize, rhs: usize, context: &str) -> Result<usize> {
236
+ lhs.checked_add(rhs)
237
+ .ok_or_else(|| Error::InvalidData(format!("{context} exceeds platform usize capacity")))
238
+ }
239
+
240
+ fn checked_mul_u64(lhs: u64, rhs: u64, context: &str) -> Result<u64> {
241
+ lhs.checked_mul(rhs)
242
+ .ok_or_else(|| Error::InvalidData(format!("{context} exceeds u64 capacity")))
243
+ }
244
+
245
+ fn checked_add_u64(lhs: u64, rhs: u64, context: &str) -> Result<u64> {
246
+ lhs.checked_add(rhs)
247
+ .ok_or_else(|| Error::InvalidData(format!("{context} exceeds u64 capacity")))
248
+ }
249
+
250
+ fn checked_shape_elements_usize(shape: &[u64], context: &str) -> Result<usize> {
251
+ let mut total = 1usize;
252
+ for &dim in shape {
253
+ total = checked_mul_usize(total, checked_usize(dim, context)?, context)?;
254
+ }
255
+ Ok(total)
256
+ }
257
+
258
+ fn full_dataset_chunk_bounds(
259
+ shape: &[u64],
260
+ chunk_shape: &[u64],
261
+ ) -> Result<Option<(Vec<u64>, Vec<u64>)>> {
262
+ validate_chunk_shape(shape, chunk_shape)?;
263
+ if shape.contains(&0) {
264
+ return Ok(None);
265
+ }
266
+
267
+ let first_chunk = vec![0u64; shape.len()];
268
+ let last_chunk = shape
269
+ .iter()
270
+ .zip(chunk_shape.iter())
271
+ .map(|(&dim, &chunk)| dim.div_ceil(chunk) - 1)
272
+ .collect();
273
+ Ok(Some((first_chunk, last_chunk)))
274
+ }
275
+
276
+ fn validate_chunk_shape(shape: &[u64], chunk_shape: &[u64]) -> Result<()> {
277
+ if chunk_shape.len() != shape.len() {
278
+ return Err(Error::InvalidData(format!(
279
+ "chunk rank {} does not match dataset rank {}",
280
+ chunk_shape.len(),
281
+ shape.len()
282
+ )));
283
+ }
284
+ if let Some((dim, _)) = chunk_shape
285
+ .iter()
286
+ .enumerate()
287
+ .find(|(_, chunk)| **chunk == 0)
288
+ {
289
+ return Err(Error::InvalidData(format!(
290
+ "chunk dimension {dim} has zero extent"
291
+ )));
292
+ }
293
+ Ok(())
294
+ }
295
+
296
+ fn validate_decoded_chunk_len(
297
+ entry: &chunk_index::ChunkEntry,
298
+ chunk_shape: &[u64],
299
+ elem_size: usize,
300
+ actual_len: usize,
301
+ ) -> Result<()> {
302
+ let expected_len = decoded_chunk_expected_len(chunk_shape, elem_size)?;
303
+ if actual_len != expected_len {
304
+ return Err(Error::InvalidData(format!(
305
+ "chunk at offsets {:?} decoded to {} bytes, expected {} bytes",
306
+ entry.offsets, actual_len, expected_len
307
+ )));
308
+ }
309
+ Ok(())
310
+ }
311
+
312
+ fn decoded_chunk_expected_len(chunk_shape: &[u64], elem_size: usize) -> Result<usize> {
313
+ let chunk_elements = checked_shape_elements_usize(chunk_shape, "decoded chunk element count")?;
314
+ checked_mul_usize(chunk_elements, elem_size, "decoded chunk byte length")
315
+ }
316
+
317
+ fn validate_chunk_grid_coverage(
318
+ entries: &mut [chunk_index::ChunkEntry],
319
+ shape: &[u64],
320
+ chunk_shape: &[u64],
321
+ first_chunk: &[u64],
322
+ last_chunk: &[u64],
323
+ ) -> Result<bool> {
324
+ validate_chunk_shape(shape, chunk_shape)?;
325
+ if first_chunk.len() != shape.len() || last_chunk.len() != shape.len() {
326
+ return Err(Error::InvalidData(format!(
327
+ "chunk grid bounds rank does not match dataset rank {}",
328
+ shape.len()
329
+ )));
330
+ }
331
+
332
+ if shape.contains(&0) {
333
+ if entries.is_empty() {
334
+ return Ok(true);
335
+ }
336
+ return Err(Error::InvalidData(
337
+ "chunk index contains entries for an empty dataset".into(),
338
+ ));
339
+ }
340
+
341
+ for dim in 0..shape.len() {
342
+ if first_chunk[dim] > last_chunk[dim] {
343
+ return Err(Error::InvalidData(format!(
344
+ "invalid chunk grid bounds for dimension {dim}: {} > {}",
345
+ first_chunk[dim], last_chunk[dim]
346
+ )));
347
+ }
348
+ }
349
+
350
+ entries.sort_by(|a, b| a.offsets.cmp(&b.offsets));
351
+
352
+ for i in 0..entries.len() {
353
+ validate_chunk_entry_offsets(&entries[i], shape, chunk_shape, first_chunk, last_chunk)?;
354
+ if i > 0 && entries[i].offsets == entries[i - 1].offsets {
355
+ return Err(Error::InvalidData(format!(
356
+ "duplicate chunk output offsets {:?} (addresses {:#x} and {:#x})",
357
+ entries[i].offsets,
358
+ entries[i - 1].address,
359
+ entries[i].address
360
+ )));
361
+ }
362
+ }
363
+
364
+ let mut entry_idx = 0usize;
365
+ let mut expected = first_chunk.to_vec();
366
+ loop {
367
+ let expected_offsets: Vec<u64> = expected
368
+ .iter()
369
+ .enumerate()
370
+ .map(|(dim, chunk_index)| chunk_index * chunk_shape[dim])
371
+ .collect();
372
+
373
+ if entry_idx >= entries.len() || entries[entry_idx].offsets != expected_offsets {
374
+ return Ok(false);
375
+ }
376
+ entry_idx += 1;
377
+
378
+ if !advance_chunk_index(&mut expected, first_chunk, last_chunk) {
379
+ break;
380
+ }
381
+ }
382
+
383
+ Ok(entry_idx == entries.len())
384
+ }
385
+
386
+ fn validate_chunk_entry_offsets(
387
+ entry: &chunk_index::ChunkEntry,
388
+ shape: &[u64],
389
+ chunk_shape: &[u64],
390
+ first_chunk: &[u64],
391
+ last_chunk: &[u64],
392
+ ) -> Result<()> {
393
+ if entry.offsets.len() != shape.len() {
394
+ return Err(Error::InvalidData(format!(
395
+ "chunk at address {:#x} has rank {}, expected {}",
396
+ entry.address,
397
+ entry.offsets.len(),
398
+ shape.len()
399
+ )));
400
+ }
401
+
402
+ for dim in 0..shape.len() {
403
+ let offset = entry.offsets[dim];
404
+ if offset >= shape[dim] {
405
+ return Err(Error::InvalidData(format!(
406
+ "chunk at address {:#x} has out-of-bounds offset {} for dimension {} of size {}",
407
+ entry.address, offset, dim, shape[dim]
408
+ )));
409
+ }
410
+ if offset % chunk_shape[dim] != 0 {
411
+ return Err(Error::InvalidData(format!(
412
+ "chunk at address {:#x} has non-grid offset {} for dimension {} with chunk extent {}",
413
+ entry.address, offset, dim, chunk_shape[dim]
414
+ )));
415
+ }
416
+
417
+ let chunk_index = offset / chunk_shape[dim];
418
+ if chunk_index < first_chunk[dim] || chunk_index > last_chunk[dim] {
419
+ return Err(Error::InvalidData(format!(
420
+ "chunk at address {:#x} has offset {:?} outside requested chunk grid",
421
+ entry.address, entry.offsets
422
+ )));
423
+ }
424
+ }
425
+
426
+ Ok(())
427
+ }
428
+
429
+ fn advance_chunk_index(index: &mut [u64], first_chunk: &[u64], last_chunk: &[u64]) -> bool {
430
+ if index.is_empty() {
431
+ return false;
432
+ }
433
+
434
+ for dim in (0..index.len()).rev() {
435
+ if index[dim] < last_chunk[dim] {
436
+ index[dim] += 1;
437
+ if dim + 1 < index.len() {
438
+ index[(dim + 1)..].copy_from_slice(&first_chunk[(dim + 1)..]);
439
+ }
440
+ return true;
441
+ }
442
+ }
443
+
444
+ false
445
+ }
446
+
447
+ fn row_major_strides(shape: &[u64], context: &str) -> Result<Vec<usize>> {
448
+ let ndim = shape.len();
449
+ if ndim == 0 {
450
+ return Ok(Vec::new());
451
+ }
452
+
453
+ let mut strides = vec![1usize; ndim];
454
+ for i in (0..ndim - 1).rev() {
455
+ let next_extent = checked_usize(shape[i + 1], context)?;
456
+ strides[i] = checked_mul_usize(strides[i + 1], next_extent, context)?;
457
+ }
458
+ Ok(strides)
459
+ }
460
+
461
+ /// Convert an allocation of maybe-uninitialized bytes without copying it.
462
+ ///
463
+ /// # Safety
464
+ ///
465
+ /// Every element of `buffer` must have been initialized.
466
+ unsafe fn assume_init_u8_vec(mut buffer: Vec<MaybeUninit<u8>>) -> Vec<u8> {
467
+ let ptr = buffer.as_mut_ptr() as *mut u8;
468
+ let len = buffer.len();
469
+ let capacity = buffer.capacity();
470
+ std::mem::forget(buffer);
471
+ // SAFETY: guaranteed by the caller; `u8` and `MaybeUninit<u8>` have the
472
+ // same layout, and ownership of the allocation was transferred by forget.
473
+ unsafe { Vec::from_raw_parts(ptr, len, capacity) }
474
+ }
475
+
476
+ /// `len` uninitialised slots, or an error when the allocation cannot be satisfied: a corrupt
477
+ /// dataspace (one dimension of 2.8e14) asked for petabytes and aborted the process instead of
478
+ /// failing the read (ModernViewer MV-110 fuzzing).
479
+ fn try_uninit_vec<T>(len: usize) -> Result<Vec<MaybeUninit<T>>> {
480
+ let mut buffer: Vec<MaybeUninit<T>> = Vec::new();
481
+ buffer.try_reserve_exact(len).map_err(|_| {
482
+ Error::InvalidData(format!(
483
+ "cannot allocate {len} elements of {} bytes for the selection; the dataspace may be corrupt",
484
+ std::mem::size_of::<T>()
485
+ ))
486
+ })?;
487
+ // SAFETY: the capacity is reserved and `MaybeUninit` needs no initialisation.
488
+ unsafe { buffer.set_len(len) };
489
+ Ok(buffer)
490
+ }
491
+
492
+ /// `len` zero bytes, failing like [`try_uninit_vec`] instead of aborting.
493
+ fn try_zeroed_bytes(len: usize) -> Result<Vec<u8>> {
494
+ let mut buffer = Vec::new();
495
+ buffer.try_reserve_exact(len).map_err(|_| {
496
+ Error::InvalidData(format!(
497
+ "cannot allocate {len} bytes for the selection; the dataspace may be corrupt"
498
+ ))
499
+ })?;
500
+ buffer.resize(len, 0);
501
+ Ok(buffer)
502
+ }
503
+
504
+ /// Convert an allocation of maybe-uninitialized values without copying it.
505
+ ///
506
+ /// # Safety
507
+ ///
508
+ /// Every element of `buffer` must have been initialized.
509
+ unsafe fn assume_init_vec<T>(mut buffer: Vec<MaybeUninit<T>>) -> Vec<T> {
510
+ let ptr = buffer.as_mut_ptr() as *mut T;
511
+ let len = buffer.len();
512
+ let capacity = buffer.capacity();
513
+ std::mem::forget(buffer);
514
+ // SAFETY: guaranteed by the caller; `T` and `MaybeUninit<T>` have the
515
+ // same layout, and ownership of the allocation was transferred by forget.
516
+ unsafe { Vec::from_raw_parts(ptr, len, capacity) }
517
+ }
518
+
519
+ fn normalize_selection(selection: &SliceInfo, shape: &[u64]) -> Result<ResolvedSelection> {
520
+ if selection.selections.len() != shape.len() {
521
+ return Err(Error::InvalidData(format!(
522
+ "slice has {} dimensions but dataset has {}",
523
+ selection.selections.len(),
524
+ shape.len()
525
+ )));
526
+ }
527
+
528
+ let mut dims = Vec::with_capacity(shape.len());
529
+ let mut result_shape = Vec::new();
530
+ let mut result_elements = 1usize;
531
+
532
+ for (i, sel) in selection.selections.iter().enumerate() {
533
+ let dim_size = shape[i];
534
+ match sel {
535
+ SliceInfoElem::Index(idx) => {
536
+ if *idx >= dim_size {
537
+ return Err(Error::SliceOutOfBounds {
538
+ dim: i,
539
+ index: *idx,
540
+ size: dim_size,
541
+ });
542
+ }
543
+ dims.push(ResolvedSelectionDim {
544
+ start: *idx,
545
+ end: *idx + 1,
546
+ step: 1,
547
+ count: 1,
548
+ });
549
+ }
550
+ SliceInfoElem::Slice { start, end, step } => {
551
+ if *step == 0 {
552
+ return Err(Error::InvalidData("slice step cannot be 0".into()));
553
+ }
554
+ if *start > dim_size {
555
+ return Err(Error::SliceOutOfBounds {
556
+ dim: i,
557
+ index: *start,
558
+ size: dim_size,
559
+ });
560
+ }
561
+
562
+ let actual_end = if *end == u64::MAX {
563
+ dim_size
564
+ } else {
565
+ (*end).min(dim_size)
566
+ };
567
+ let count_u64 = if *start >= actual_end {
568
+ 0
569
+ } else {
570
+ (actual_end - *start).div_ceil(*step)
571
+ };
572
+ let count = checked_usize(count_u64, "slice element count")?;
573
+
574
+ dims.push(ResolvedSelectionDim {
575
+ start: *start,
576
+ end: actual_end,
577
+ step: *step,
578
+ count,
579
+ });
580
+ result_shape.push(count);
581
+ result_elements =
582
+ checked_mul_usize(result_elements, count, "slice result element count")?;
583
+ }
584
+ }
585
+ }
586
+
587
+ Ok(ResolvedSelection {
588
+ dims,
589
+ result_shape,
590
+ result_elements,
591
+ })
592
+ }
593
+
594
+ fn selection_dim_is_full_unit(dim: &ResolvedSelectionDim, dim_size: u64) -> bool {
595
+ dim.step == 1
596
+ && dim.start == 0
597
+ && dim.end == dim_size
598
+ && u64::try_from(dim.count).ok() == Some(dim_size)
599
+ }
600
+
601
+ fn selection_covers_full_dataset(resolved: &ResolvedSelection, shape: &[u64]) -> bool {
602
+ resolved.result_shape.len() == shape.len()
603
+ && resolved
604
+ .dims
605
+ .iter()
606
+ .zip(shape.iter())
607
+ .all(|(dim, &dim_size)| selection_dim_is_full_unit(dim, dim_size))
608
+ }
609
+
610
+ fn contiguous_slice_tail_start(shape: &[u64], resolved: &ResolvedSelection) -> usize {
611
+ let ndim = shape.len();
612
+ if ndim == 0 {
613
+ return 0;
614
+ }
615
+
616
+ let mut tail_start = if resolved.dims[ndim - 1].step == 1 {
617
+ ndim - 1
618
+ } else {
619
+ ndim
620
+ };
621
+
622
+ while tail_start > 0 {
623
+ let prev = tail_start - 1;
624
+ let later_dims_are_full =
625
+ (tail_start..ndim).all(|d| selection_dim_is_full_unit(&resolved.dims[d], shape[d]));
626
+ if resolved.dims[prev].step == 1 && later_dims_are_full {
627
+ tail_start = prev;
628
+ } else {
629
+ break;
630
+ }
631
+ }
632
+
633
+ tail_start
634
+ }
635
+
636
+ fn contiguous_slice_block_elements(
637
+ resolved: &ResolvedSelection,
638
+ tail_start: usize,
639
+ ) -> Result<usize> {
640
+ let mut elements = 1usize;
641
+ for dim in &resolved.dims[tail_start..] {
642
+ elements = checked_mul_usize(elements, dim.count, "contiguous slice block elements")?;
643
+ }
644
+ Ok(elements)
645
+ }
646
+
647
+ fn result_strides_for_dims(result_dims: &[usize]) -> Result<Vec<usize>> {
648
+ let ndim = result_dims.len();
649
+ let mut result_strides = vec![1usize; ndim];
650
+ for d in (0..ndim.saturating_sub(1)).rev() {
651
+ result_strides[d] =
652
+ checked_mul_usize(result_strides[d + 1], result_dims[d + 1], "result stride")?;
653
+ }
654
+ Ok(result_strides)
655
+ }
656
+
657
+ /// A dataset within an HDF5 file.
658
+ #[derive(Clone)]
659
+ pub struct Dataset {
660
+ pub(crate) context: Arc<FileContext>,
661
+ pub(crate) name: String,
662
+ pub(crate) data_address: u64,
663
+ pub(crate) dataspace: DataspaceMessage,
664
+ pub(crate) datatype: Datatype,
665
+ pub(crate) layout: DataLayout,
666
+ pub(crate) fill_value: Option<FillValueMessage>,
667
+ pub(crate) filters: Option<FilterPipelineMessage>,
668
+ pub(crate) external_files: Option<ExternalFilesMessage>,
669
+ pub(crate) attributes: Vec<AttributeMessage>,
670
+ pub(crate) chunk_cache: Arc<ChunkCache>,
671
+ chunk_entry_cache: Arc<Mutex<LruCache<ChunkEntryCacheKey, Arc<Vec<chunk_index::ChunkEntry>>>>>,
672
+ full_chunk_entries: Arc<OnceLock<Arc<Vec<chunk_index::ChunkEntry>>>>,
673
+ full_dataset_bytes: Arc<OnceLock<Arc<Vec<u8>>>>,
674
+ external_slots: Arc<OnceLock<Arc<Vec<ResolvedExternalRawSlot>>>>,
675
+ pub(crate) filter_registry: Arc<FilterRegistry>,
676
+ }
677
+
678
+ /// One decoded chunk from a chunked dataset.
679
+ pub struct DatasetChunk {
680
+ offsets: Vec<u64>,
681
+ shape: Vec<u64>,
682
+ filter_mask: u32,
683
+ bytes: Arc<Vec<u8>>,
684
+ }
685
+
686
+ impl DatasetChunk {
687
+ /// Dataset coordinates of the first element in this chunk.
688
+ pub fn offsets(&self) -> &[u64] {
689
+ &self.offsets
690
+ }
691
+
692
+ /// Logical chunk shape from the dataset layout.
693
+ pub fn shape(&self) -> &[u64] {
694
+ &self.shape
695
+ }
696
+
697
+ /// HDF5 filter mask recorded for this chunk.
698
+ pub fn filter_mask(&self) -> u32 {
699
+ self.filter_mask
700
+ }
701
+
702
+ /// Decoded logical bytes for this chunk.
703
+ pub fn bytes(&self) -> &[u8] {
704
+ self.bytes.as_ref()
705
+ }
706
+ }
707
+
708
+ /// Iterator over decoded chunks in a chunked dataset.
709
+ pub struct DatasetChunkIterator {
710
+ dataset: Dataset,
711
+ entries: Vec<chunk_index::ChunkEntry>,
712
+ index_address: u64,
713
+ chunk_shape: Vec<u64>,
714
+ elem_size: usize,
715
+ next: usize,
716
+ }
717
+
718
+ impl Iterator for DatasetChunkIterator {
719
+ type Item = Result<DatasetChunk>;
720
+
721
+ fn next(&mut self) -> Option<Self::Item> {
722
+ let entry = self.entries.get(self.next)?;
723
+ self.next += 1;
724
+
725
+ Some(
726
+ self.dataset
727
+ .load_exact_chunk_data(entry, self.index_address, &self.chunk_shape, self.elem_size)
728
+ .map(|bytes| DatasetChunk {
729
+ offsets: entry.offsets.clone(),
730
+ shape: self.chunk_shape.clone(),
731
+ filter_mask: entry.filter_mask,
732
+ bytes,
733
+ }),
734
+ )
735
+ }
736
+ }
737
+
738
+ pub(crate) struct DatasetTemplate {
739
+ name: String,
740
+ data_address: u64,
741
+ dataspace: DataspaceMessage,
742
+ datatype: Datatype,
743
+ layout: DataLayout,
744
+ fill_value: Option<FillValueMessage>,
745
+ filters: Option<FilterPipelineMessage>,
746
+ external_files: Option<ExternalFilesMessage>,
747
+ attributes: Vec<AttributeMessage>,
748
+ chunk_entry_cache: Arc<Mutex<LruCache<ChunkEntryCacheKey, Arc<Vec<chunk_index::ChunkEntry>>>>>,
749
+ full_chunk_entries: Arc<OnceLock<Arc<Vec<chunk_index::ChunkEntry>>>>,
750
+ full_dataset_bytes: Arc<OnceLock<Arc<Vec<u8>>>>,
751
+ external_slots: Arc<OnceLock<Arc<Vec<ResolvedExternalRawSlot>>>>,
752
+ }
753
+
754
+ impl Dataset {
755
+ pub(crate) fn from_template(context: Arc<FileContext>, template: Arc<DatasetTemplate>) -> Self {
756
+ Dataset {
757
+ chunk_cache: context.chunk_cache.clone(),
758
+ filter_registry: context.filter_registry.clone(),
759
+ context,
760
+ name: template.name.clone(),
761
+ data_address: template.data_address,
762
+ dataspace: template.dataspace.clone(),
763
+ datatype: template.datatype.clone(),
764
+ layout: template.layout.clone(),
765
+ fill_value: template.fill_value.clone(),
766
+ filters: template.filters.clone(),
767
+ external_files: template.external_files.clone(),
768
+ attributes: template.attributes.clone(),
769
+ chunk_entry_cache: template.chunk_entry_cache.clone(),
770
+ full_chunk_entries: template.full_chunk_entries.clone(),
771
+ full_dataset_bytes: template.full_dataset_bytes.clone(),
772
+ external_slots: template.external_slots.clone(),
773
+ }
774
+ }
775
+
776
+ pub(crate) fn template(&self) -> Arc<DatasetTemplate> {
777
+ Arc::new(DatasetTemplate {
778
+ name: self.name.clone(),
779
+ data_address: self.data_address,
780
+ dataspace: self.dataspace.clone(),
781
+ datatype: self.datatype.clone(),
782
+ layout: self.layout.clone(),
783
+ fill_value: self.fill_value.clone(),
784
+ filters: self.filters.clone(),
785
+ external_files: self.external_files.clone(),
786
+ attributes: self.attributes.clone(),
787
+ chunk_entry_cache: self.chunk_entry_cache.clone(),
788
+ full_chunk_entries: self.full_chunk_entries.clone(),
789
+ full_dataset_bytes: self.full_dataset_bytes.clone(),
790
+ external_slots: self.external_slots.clone(),
791
+ })
792
+ }
793
+
794
+ pub(crate) fn from_parsed_header(
795
+ context: DatasetParseContext,
796
+ address: u64,
797
+ name: String,
798
+ header: &ObjectHeader,
799
+ ) -> Result<Self> {
800
+ let mut dataspace: Option<DataspaceMessage> = None;
801
+ let mut datatype: Option<Datatype> = None;
802
+ let mut layout: Option<DataLayout> = None;
803
+ let mut fill_value: Option<FillValueMessage> = None;
804
+ let mut filter_pipeline: Option<FilterPipelineMessage> = None;
805
+ let mut external_files: Option<ExternalFilesMessage> = None;
806
+ let attributes = collect_attribute_messages_storage(
807
+ header,
808
+ context.context.storage.as_ref(),
809
+ context.context.superblock.offset_size,
810
+ context.context.superblock.length_size,
811
+ Some(context.context.filter_registry.as_ref()),
812
+ )?;
813
+
814
+ for msg in &header.messages {
815
+ match msg {
816
+ HdfMessage::Dataspace(ds) => dataspace = Some(ds.clone()),
817
+ HdfMessage::Datatype(dt) => datatype = Some(dt.datatype.clone()),
818
+ HdfMessage::DataLayout(dl) => layout = Some(dl.layout.clone()),
819
+ HdfMessage::FillValue(fv) => fill_value = Some(fv.clone()),
820
+ HdfMessage::FilterPipeline(fp) => filter_pipeline = Some(fp.clone()),
821
+ HdfMessage::ExternalFiles(ef) => external_files = Some(ef.clone()),
822
+ _ => {}
823
+ }
824
+ }
825
+
826
+ let dataspace =
827
+ dataspace.ok_or_else(|| Error::InvalidData("dataset missing dataspace".into()))?;
828
+ let dt = datatype.ok_or_else(|| Error::InvalidData("dataset missing datatype".into()))?;
829
+ let layout =
830
+ layout.ok_or_else(|| Error::InvalidData("dataset missing data layout".into()))?;
831
+ let layout = normalize_layout(layout, &dataspace);
832
+ let attr_fill_value = attributes
833
+ .iter()
834
+ .find(|attr| {
835
+ attr.name == "_FillValue" && matches!(attr.dataspace.num_elements(), Ok(1))
836
+ })
837
+ .map(|attr| FillValueMessage {
838
+ defined: !attr.raw_data.is_empty(),
839
+ fill_time: FillTime::IfSet,
840
+ value: Some(attr.raw_data.clone()),
841
+ });
842
+ let fill_value = match fill_value {
843
+ Some(existing) if existing.value.is_some() => Some(existing),
844
+ _ => attr_fill_value,
845
+ };
846
+
847
+ Ok(Dataset {
848
+ context: context.context.clone(),
849
+ name,
850
+ data_address: address,
851
+ dataspace,
852
+ datatype: dt,
853
+ layout,
854
+ fill_value,
855
+ filters: filter_pipeline,
856
+ external_files,
857
+ attributes,
858
+ chunk_cache: context.context.chunk_cache.clone(),
859
+ chunk_entry_cache: Arc::new(Mutex::new(LruCache::new(NonZeroUsize::new(32).unwrap()))),
860
+ full_chunk_entries: Arc::new(OnceLock::new()),
861
+ full_dataset_bytes: Arc::new(OnceLock::new()),
862
+ external_slots: Arc::new(OnceLock::new()),
863
+ filter_registry: context.context.filter_registry.clone(),
864
+ })
865
+ }
866
+
867
+ /// Dataset name.
868
+ pub fn name(&self) -> &str {
869
+ &self.name
870
+ }
871
+
872
+ /// The object header address used to parse this dataset.
873
+ /// Useful as an opaque identifier or for NC4 data_offset.
874
+ pub fn address(&self) -> u64 {
875
+ self.data_address
876
+ }
877
+
878
+ /// Shape of the dataset (dimensions).
879
+ pub fn shape(&self) -> &[u64] {
880
+ &self.dataspace.dims
881
+ }
882
+
883
+ /// Datatype of the dataset.
884
+ pub fn dtype(&self) -> &Datatype {
885
+ &self.datatype
886
+ }
887
+
888
+ /// Number of dimensions.
889
+ pub fn ndim(&self) -> usize {
890
+ self.dataspace.dims.len()
891
+ }
892
+
893
+ fn offset_size(&self) -> u8 {
894
+ self.context.superblock.offset_size
895
+ }
896
+
897
+ fn length_size(&self) -> u8 {
898
+ self.context.superblock.length_size
899
+ }
900
+
901
+ /// Maximum dimension sizes, if defined. `u64::MAX` indicates unlimited.
902
+ pub fn max_dims(&self) -> Option<&[u64]> {
903
+ self.dataspace.max_dims.as_deref()
904
+ }
905
+
906
+ /// Chunk dimensions, if the dataset is chunked.
907
+ pub fn chunks(&self) -> Option<Vec<u32>> {
908
+ match &self.layout {
909
+ DataLayout::Chunked { dims, .. } => Some(dims.clone()),
910
+ _ => None,
911
+ }
912
+ }
913
+
914
+ /// Iterate over decoded chunks for a chunked dataset.
915
+ pub fn iter_chunks(&self) -> Result<DatasetChunkIterator> {
916
+ let DataLayout::Chunked {
917
+ address,
918
+ dims,
919
+ chunk_indexing,
920
+ ..
921
+ } = &self.layout
922
+ else {
923
+ return Err(Error::InvalidData(format!(
924
+ "dataset '{}' is not chunked",
925
+ self.name
926
+ )));
927
+ };
928
+
929
+ if Cursor::is_undefined_offset(*address, self.offset_size()) {
930
+ return Ok(DatasetChunkIterator {
931
+ dataset: self.clone(),
932
+ entries: Vec::new(),
933
+ index_address: *address,
934
+ chunk_shape: dims.iter().map(|&d| d as u64).collect(),
935
+ elem_size: self.raw_element_size()?,
936
+ next: 0,
937
+ });
938
+ }
939
+
940
+ let ndim = self.ndim();
941
+ let shape = &self.dataspace.dims;
942
+ let elem_size = self.raw_element_size()?;
943
+ let chunk_shape: Vec<u64> = dims.iter().map(|&d| d as u64).collect();
944
+ validate_chunk_shape(shape, &chunk_shape)?;
945
+ let entries = self.collect_chunk_entries(
946
+ *address,
947
+ dims,
948
+ chunk_indexing.as_ref(),
949
+ ChunkEntrySelection {
950
+ shape,
951
+ ndim,
952
+ elem_size,
953
+ chunk_bounds: None,
954
+ },
955
+ )?;
956
+
957
+ Ok(DatasetChunkIterator {
958
+ dataset: self.clone(),
959
+ entries,
960
+ index_address: *address,
961
+ chunk_shape,
962
+ elem_size,
963
+ next: 0,
964
+ })
965
+ }
966
+
967
+ /// Return current chunk-cache statistics for this dataset's file.
968
+ pub fn chunk_cache_stats(&self) -> ChunkCacheStats {
969
+ self.chunk_cache.stats()
970
+ }
971
+
972
+ /// Fill value, if defined.
973
+ pub fn fill_value(&self) -> Option<&FillValueMessage> {
974
+ self.fill_value.as_ref()
975
+ }
976
+
977
+ /// Dataset attributes.
978
+ pub fn attributes(&self) -> Vec<Attribute> {
979
+ self.attributes
980
+ .iter()
981
+ .map(|a| attribute_from_message_storage(a, self.context.as_ref()))
982
+ .collect()
983
+ }
984
+
985
+ /// Find an attribute by name.
986
+ pub fn attribute(&self, name: &str) -> Result<Attribute> {
987
+ self.attributes
988
+ .iter()
989
+ .find(|a| a.name == name)
990
+ .map(|a| attribute_from_message_storage(a, self.context.as_ref()))
991
+ .ok_or_else(|| Error::AttributeNotFound(name.to_string()))
992
+ }
993
+
994
+ /// Read a scalar string dataset or single string element.
995
+ ///
996
+ /// Use [`Dataset::read_strings`] when the dataset contains multiple strings.
997
+ pub fn read_string(&self) -> Result<String> {
998
+ let mut strings = self.read_strings()?;
999
+ match strings.len() {
1000
+ 1 => Ok(strings.swap_remove(0)),
1001
+ 0 => Err(Error::InvalidData(format!(
1002
+ "dataset '{}' contains no string elements",
1003
+ self.name
1004
+ ))),
1005
+ count => Err(Error::InvalidData(format!(
1006
+ "dataset '{}' contains {count} string elements; use read_strings()",
1007
+ self.name
1008
+ ))),
1009
+ }
1010
+ }
1011
+
1012
+ /// Read all string elements from a string-typed dataset.
1013
+ pub fn read_strings(&self) -> Result<Vec<String>> {
1014
+ match &self.datatype {
1015
+ Datatype::String {
1016
+ size: StringSize::Fixed(len),
1017
+ encoding,
1018
+ padding,
1019
+ } => {
1020
+ let raw = self.read_raw_bytes()?;
1021
+ let elem_size = *len as usize;
1022
+ let count = checked_usize(self.num_elements()?, "dataset string element count")?;
1023
+ let expected_bytes =
1024
+ checked_mul_usize(count, elem_size, "dataset string byte size")?;
1025
+ if raw.len() < expected_bytes {
1026
+ return Err(Error::InvalidData(format!(
1027
+ "dataset '{}' string data too short: need {} bytes, have {}",
1028
+ self.name,
1029
+ expected_bytes,
1030
+ raw.len()
1031
+ )));
1032
+ }
1033
+
1034
+ let mut strings = Vec::with_capacity(count);
1035
+ for i in 0..count {
1036
+ let start = i * elem_size;
1037
+ let end = start + elem_size;
1038
+ strings.push(decode_string(&raw[start..end], *padding, *encoding)?);
1039
+ }
1040
+ Ok(strings)
1041
+ }
1042
+ Datatype::String {
1043
+ size: StringSize::Variable,
1044
+ encoding,
1045
+ padding,
1046
+ } => {
1047
+ let raw = self.read_raw_bytes()?;
1048
+ let count = checked_usize(self.num_elements()?, "dataset string element count")?;
1049
+ let ref_size = 4 + self.offset_size() as usize + 4;
1050
+ let expected_bytes =
1051
+ checked_mul_usize(count, ref_size, "dataset string reference byte size")?;
1052
+ if raw.len() < expected_bytes {
1053
+ return Err(Error::InvalidData(format!(
1054
+ "dataset '{}' vlen string data too short: need {} bytes, have {}",
1055
+ self.name,
1056
+ expected_bytes,
1057
+ raw.len()
1058
+ )));
1059
+ }
1060
+
1061
+ let mut strings = Vec::with_capacity(count);
1062
+ for i in 0..count {
1063
+ let offset = i * ref_size;
1064
+ strings.push(read_one_vlen_string_storage(
1065
+ &raw,
1066
+ offset,
1067
+ self.context.storage.as_ref(),
1068
+ self.offset_size(),
1069
+ self.length_size(),
1070
+ *padding,
1071
+ *encoding,
1072
+ )?);
1073
+ }
1074
+ Ok(strings)
1075
+ }
1076
+ Datatype::VarLen {
1077
+ base,
1078
+ kind: VarLenKind::String,
1079
+ encoding,
1080
+ padding,
1081
+ } => {
1082
+ if !base.is_vlen_string_base() {
1083
+ return Err(Error::TypeMismatch {
1084
+ expected: "String dataset".into(),
1085
+ actual: format!("{:?}", self.datatype),
1086
+ });
1087
+ }
1088
+
1089
+ let raw = self.read_raw_bytes()?;
1090
+ let count = checked_usize(self.num_elements()?, "dataset string element count")?;
1091
+ let ref_size = 4 + self.offset_size() as usize + 4;
1092
+ let expected_bytes =
1093
+ checked_mul_usize(count, ref_size, "dataset string reference byte size")?;
1094
+ if raw.len() < expected_bytes {
1095
+ return Err(Error::InvalidData(format!(
1096
+ "dataset '{}' vlen byte string data too short: need {} bytes, have {}",
1097
+ self.name,
1098
+ expected_bytes,
1099
+ raw.len()
1100
+ )));
1101
+ }
1102
+
1103
+ let mut strings = Vec::with_capacity(count);
1104
+ for i in 0..count {
1105
+ let offset = i * ref_size;
1106
+ let ref_bytes = &raw[offset..offset + ref_size];
1107
+ let value = resolve_vlen_bytes_storage(
1108
+ ref_bytes,
1109
+ self.context.storage.as_ref(),
1110
+ self.offset_size(),
1111
+ self.length_size(),
1112
+ )
1113
+ .unwrap_or_default();
1114
+ strings.push(decode_string(&value, *padding, *encoding)?);
1115
+ }
1116
+ Ok(strings)
1117
+ }
1118
+ _ => Err(Error::TypeMismatch {
1119
+ expected: "String dataset".into(),
1120
+ actual: format!("{:?}", self.datatype),
1121
+ }),
1122
+ }
1123
+ }
1124
+
1125
+ /// Total number of elements in the dataset.
1126
+ pub fn num_elements(&self) -> Result<u64> {
1127
+ Ok(self.dataspace.num_elements()?)
1128
+ }
1129
+
1130
+ /// Read the entire dataset into an n-dimensional array.
1131
+ pub fn read_array<T: H5Type>(&self) -> Result<ArrayD<T>> {
1132
+ let result = match &self.layout {
1133
+ DataLayout::Compact { data } => self.read_compact::<T>(data),
1134
+ DataLayout::Contiguous { address, size } => self.read_contiguous::<T>(*address, *size),
1135
+ DataLayout::Chunked {
1136
+ address,
1137
+ dims,
1138
+ element_size,
1139
+ chunk_indexing,
1140
+ } => self.read_chunked::<T>(*address, dims, *element_size, chunk_indexing.as_ref()),
1141
+ };
1142
+ result.map_err(|e| e.with_context(&self.name))
1143
+ }
1144
+
1145
+ /// Read the entire dataset into a caller-provided typed buffer.
1146
+ pub fn read_into<T: H5Type>(&self, dst: &mut [T]) -> Result<()> {
1147
+ let result = (|| {
1148
+ let element_count = checked_usize(self.num_elements()?, "dataset element count")?;
1149
+ if dst.len() != element_count {
1150
+ return Err(Error::InvalidData(format!(
1151
+ "destination has {} elements, dataset requires {}",
1152
+ dst.len(),
1153
+ element_count
1154
+ )));
1155
+ }
1156
+
1157
+ let elem_size = self.raw_element_size()?;
1158
+ if T::native_copy_compatible(&self.datatype) && std::mem::size_of::<T>() == elem_size {
1159
+ // SAFETY: `dst` is a live, contiguous mutable slice, and the
1160
+ // checked byte length exactly covers its initialized elements.
1161
+ let dst_bytes = unsafe {
1162
+ std::slice::from_raw_parts_mut(
1163
+ dst.as_mut_ptr() as *mut u8,
1164
+ checked_mul_usize(dst.len(), elem_size, "destination byte length")?,
1165
+ )
1166
+ };
1167
+ return self.read_raw_bytes_into_inner(dst_bytes);
1168
+ }
1169
+
1170
+ let array = self.read_array::<T>()?;
1171
+ let values = array.as_slice_memory_order().ok_or_else(|| {
1172
+ Error::InvalidData("decoded array is not contiguous in memory order".into())
1173
+ })?;
1174
+ dst.clone_from_slice(values);
1175
+ Ok(())
1176
+ })();
1177
+
1178
+ result.map_err(|e| e.with_context(&self.name))
1179
+ }
1180
+
1181
+ /// Read the entire dataset using internal chunk-level parallelism when possible.
1182
+ ///
1183
+ /// Non-chunked datasets fall back to `read_array`.
1184
+ #[cfg(feature = "rayon")]
1185
+ pub fn read_array_parallel<T: H5Type>(&self) -> Result<ArrayD<T>> {
1186
+ match &self.layout {
1187
+ DataLayout::Chunked {
1188
+ address,
1189
+ dims,
1190
+ element_size,
1191
+ chunk_indexing,
1192
+ } => self.read_chunked_parallel::<T>(
1193
+ *address,
1194
+ dims,
1195
+ *element_size,
1196
+ chunk_indexing.as_ref(),
1197
+ ),
1198
+ _ => self.read_array::<T>(),
1199
+ }
1200
+ }
1201
+
1202
+ /// Read the entire dataset using the provided Rayon thread pool.
1203
+ ///
1204
+ /// Non-chunked datasets fall back to `read_array`.
1205
+ #[cfg(feature = "rayon")]
1206
+ pub fn read_array_in_pool<T: H5Type>(&self, pool: &rayon::ThreadPool) -> Result<ArrayD<T>> {
1207
+ match &self.layout {
1208
+ DataLayout::Chunked {
1209
+ address,
1210
+ dims,
1211
+ element_size,
1212
+ chunk_indexing,
1213
+ } => pool.install(|| {
1214
+ self.read_chunked_parallel::<T>(
1215
+ *address,
1216
+ dims,
1217
+ *element_size,
1218
+ chunk_indexing.as_ref(),
1219
+ )
1220
+ }),
1221
+ _ => self.read_array::<T>(),
1222
+ }
1223
+ }
1224
+
1225
+ /// Read a hyperslab of the dataset using chunk-level parallelism when possible.
1226
+ ///
1227
+ /// Chunked datasets decompress overlapping chunks in parallel via Rayon.
1228
+ /// Non-chunked layouts fall back to `read_slice`.
1229
+ #[cfg(feature = "rayon")]
1230
+ pub fn read_slice_parallel<T: H5Type>(&self, selection: &SliceInfo) -> Result<ArrayD<T>> {
1231
+ let resolved = normalize_selection(selection, &self.dataspace.dims)?;
1232
+
1233
+ match &self.layout {
1234
+ DataLayout::Chunked {
1235
+ address,
1236
+ dims,
1237
+ element_size,
1238
+ chunk_indexing,
1239
+ } => self.read_chunked_slice_parallel::<T>(
1240
+ *address,
1241
+ dims,
1242
+ *element_size,
1243
+ chunk_indexing.as_ref(),
1244
+ selection,
1245
+ &resolved,
1246
+ ),
1247
+ _ => self.read_slice::<T>(selection),
1248
+ }
1249
+ }
1250
+
1251
+ /// Read a hyperslab of the dataset.
1252
+ pub fn read_slice<T: H5Type>(&self, selection: &SliceInfo) -> Result<ArrayD<T>> {
1253
+ let resolved = normalize_selection(selection, &self.dataspace.dims)?;
1254
+
1255
+ match &self.layout {
1256
+ DataLayout::Contiguous { address, size } => {
1257
+ self.read_contiguous_slice::<T>(*address, *size, &resolved)
1258
+ }
1259
+ DataLayout::Compact { data } => self.read_compact_slice::<T>(data, selection),
1260
+ DataLayout::Chunked {
1261
+ address,
1262
+ dims,
1263
+ element_size,
1264
+ chunk_indexing,
1265
+ } => self.read_chunked_slice::<T>(
1266
+ *address,
1267
+ dims,
1268
+ *element_size,
1269
+ chunk_indexing.as_ref(),
1270
+ selection,
1271
+ &resolved,
1272
+ ),
1273
+ }
1274
+ }
1275
+
1276
+ fn read_compact<T: H5Type>(&self, data: &[u8]) -> Result<ArrayD<T>> {
1277
+ self.validate_allocated_raw_data_len("compact", data.len())?;
1278
+ self.decode_raw_data::<T>(data)
1279
+ }
1280
+
1281
+ /// Read the dataset as logical element bytes.
1282
+ ///
1283
+ /// The returned bytes are after layout handling, chunk decompression, filter
1284
+ /// decoding, external raw-data resolution, and fill-value materialization.
1285
+ /// Numeric values remain in the dataset datatype's byte order.
1286
+ pub fn read_raw_bytes(&self) -> Result<Vec<u8>> {
1287
+ let result: Result<Vec<u8>> = (|| {
1288
+ let total_bytes = self.raw_byte_len()?;
1289
+ let mut output = try_zeroed_bytes(total_bytes)?;
1290
+ self.read_raw_bytes_into_inner(&mut output)?;
1291
+ Ok(output)
1292
+ })();
1293
+
1294
+ result.map_err(|e| e.with_context(&self.name))
1295
+ }
1296
+
1297
+ /// Number of logical raw bytes in the entire dataset.
1298
+ pub fn raw_byte_len(&self) -> Result<usize> {
1299
+ let elem_size = self.raw_element_size()?;
1300
+ let total_elements = checked_usize(self.num_elements()?, "dataset element count")?;
1301
+ checked_mul_usize(total_elements, elem_size, "dataset size in bytes")
1302
+ }
1303
+
1304
+ /// Read logical raw bytes into a caller-provided buffer.
1305
+ ///
1306
+ /// The destination length must match [`Dataset::raw_byte_len`]. Numeric
1307
+ /// values remain in the dataset datatype's byte order.
1308
+ pub fn read_raw_bytes_into(&self, dst: &mut [u8]) -> Result<()> {
1309
+ let result: Result<()> = (|| {
1310
+ let total_bytes = self.raw_byte_len()?;
1311
+ if dst.len() != total_bytes {
1312
+ return Err(Error::InvalidData(format!(
1313
+ "destination has {} bytes, dataset requires {}",
1314
+ dst.len(),
1315
+ total_bytes
1316
+ )));
1317
+ }
1318
+ self.read_raw_bytes_into_inner(dst)
1319
+ })();
1320
+
1321
+ result.map_err(|e| e.with_context(&self.name))
1322
+ }
1323
+
1324
+ /// Read logical raw bytes converted to native-endian numeric fields.
1325
+ pub fn read_native_bytes(&self) -> Result<Vec<u8>> {
1326
+ let result: Result<Vec<u8>> = (|| {
1327
+ let total_bytes = self.raw_byte_len()?;
1328
+ let mut output = try_zeroed_bytes(total_bytes)?;
1329
+ self.read_raw_bytes_into_inner(&mut output)?;
1330
+ self.convert_to_native_endian(&mut output)?;
1331
+ Ok(output)
1332
+ })();
1333
+
1334
+ result.map_err(|e| e.with_context(&self.name))
1335
+ }
1336
+
1337
+ /// Read logical raw bytes into a buffer and convert numeric fields to native endian.
1338
+ pub fn read_native_bytes_into(&self, dst: &mut [u8]) -> Result<()> {
1339
+ let result: Result<()> = (|| {
1340
+ let total_bytes = self.raw_byte_len()?;
1341
+ if dst.len() != total_bytes {
1342
+ return Err(Error::InvalidData(format!(
1343
+ "destination has {} bytes, dataset requires {}",
1344
+ dst.len(),
1345
+ total_bytes
1346
+ )));
1347
+ }
1348
+ self.read_raw_bytes_into_inner(dst)?;
1349
+ self.convert_to_native_endian(dst)
1350
+ })();
1351
+
1352
+ result.map_err(|e| e.with_context(&self.name))
1353
+ }
1354
+
1355
+ fn read_raw_bytes_into_inner(&self, dst: &mut [u8]) -> Result<()> {
1356
+ match &self.layout {
1357
+ DataLayout::Compact { data } => {
1358
+ self.validate_allocated_raw_data_len("compact", data.len())?;
1359
+ dst.copy_from_slice(data);
1360
+ Ok(())
1361
+ }
1362
+ DataLayout::Contiguous { address, size } => {
1363
+ self.read_contiguous_bytes_into(*address, *size, dst)
1364
+ }
1365
+ DataLayout::Chunked {
1366
+ address,
1367
+ dims,
1368
+ element_size: _,
1369
+ chunk_indexing,
1370
+ } => self.read_chunked_bytes_into(*address, dims, chunk_indexing.as_ref(), dst),
1371
+ }
1372
+ }
1373
+
1374
+ /// Size in bytes of one HDF5 variable-length reference in this file.
1375
+ pub fn vlen_reference_size(&self) -> usize {
1376
+ 4 + self.offset_size() as usize + 4
1377
+ }
1378
+
1379
+ /// Size in bytes of one logical raw element in this file.
1380
+ ///
1381
+ /// Variable-length strings and sequences are stored as global-heap
1382
+ /// references whose width depends on the file offset size.
1383
+ pub fn raw_element_size(&self) -> Result<usize> {
1384
+ raw_element_size_for_datatype(&self.datatype, self.vlen_reference_size())
1385
+ }
1386
+
1387
+ /// Resolve one HDF5 variable-length reference into logical element bytes.
1388
+ ///
1389
+ /// `base_element_size` is the byte width of one value in the vlen sequence.
1390
+ /// The sequence length stored in the reference is interpreted as an element
1391
+ /// count and multiplied by this size.
1392
+ pub fn resolve_vlen_reference_bytes(
1393
+ &self,
1394
+ reference: &[u8],
1395
+ base_element_size: usize,
1396
+ ) -> Result<Vec<u8>> {
1397
+ if reference.len() < self.vlen_reference_size() {
1398
+ return Err(Error::InvalidData(format!(
1399
+ "dataset '{}' vlen reference too short: need {} bytes, have {}",
1400
+ self.name,
1401
+ self.vlen_reference_size(),
1402
+ reference.len()
1403
+ )));
1404
+ }
1405
+
1406
+ let mut cursor = Cursor::new(reference);
1407
+ let seq_len = cursor.read_u32_le()? as usize;
1408
+ let heap_addr = cursor.read_offset(self.offset_size())?;
1409
+ let obj_index = cursor.read_u32_le()? as u16;
1410
+
1411
+ if Cursor::is_undefined_offset(heap_addr, self.offset_size()) || obj_index == 0 {
1412
+ return Ok(Vec::new());
1413
+ }
1414
+
1415
+ let expected_bytes =
1416
+ checked_mul_usize(seq_len, base_element_size, "vlen sequence byte size")?;
1417
+ let collection = crate::global_heap::GlobalHeapCollection::parse_at_storage(
1418
+ self.context.storage.as_ref(),
1419
+ heap_addr,
1420
+ self.offset_size(),
1421
+ self.length_size(),
1422
+ )?;
1423
+ let object = collection.get_object(obj_index).ok_or_else(|| {
1424
+ Error::InvalidData(format!(
1425
+ "dataset '{}' references missing vlen heap object {}",
1426
+ self.name, obj_index
1427
+ ))
1428
+ })?;
1429
+ if object.data.len() < expected_bytes {
1430
+ return Err(Error::InvalidData(format!(
1431
+ "dataset '{}' vlen heap object too short: need {} bytes, have {}",
1432
+ self.name,
1433
+ expected_bytes,
1434
+ object.data.len()
1435
+ )));
1436
+ }
1437
+
1438
+ Ok(object.data[..expected_bytes].to_vec())
1439
+ }
1440
+
1441
+ fn read_contiguous<T: H5Type>(&self, address: u64, size: u64) -> Result<ArrayD<T>> {
1442
+ if self.external_files.is_some() {
1443
+ let elem_size = self.raw_element_size()?;
1444
+ let total_elements = checked_usize(self.num_elements()?, "dataset element count")?;
1445
+ let total_bytes =
1446
+ checked_mul_usize(total_elements, elem_size, "dataset size in bytes")?;
1447
+ let raw = self.read_external_range(0, total_bytes)?;
1448
+ return self.decode_raw_data::<T>(&raw);
1449
+ }
1450
+
1451
+ if Cursor::is_undefined_offset(address, self.offset_size()) || size == 0 {
1452
+ // Dataset with no data written — return fill values
1453
+ return self.make_fill_array::<T>();
1454
+ }
1455
+
1456
+ let sz = checked_usize(size, "contiguous dataset size")?;
1457
+ self.validate_allocated_raw_data_len("contiguous", sz)?;
1458
+ let raw = self.context.read_range(address, sz)?;
1459
+ self.decode_raw_data::<T>(raw.as_ref())
1460
+ }
1461
+
1462
+ fn read_contiguous_bytes_into(&self, address: u64, size: u64, dst: &mut [u8]) -> Result<()> {
1463
+ if self.external_files.is_some() {
1464
+ return self.read_external_range_into(0, dst);
1465
+ }
1466
+
1467
+ if Cursor::is_undefined_offset(address, self.offset_size()) || size == 0 {
1468
+ self.fill_output_buffer(dst);
1469
+ return Ok(());
1470
+ }
1471
+
1472
+ let sz = checked_usize(size, "contiguous dataset size")?;
1473
+ self.validate_allocated_raw_data_len("contiguous", sz)?;
1474
+ if dst.is_empty() {
1475
+ return Ok(());
1476
+ }
1477
+ let raw = self.context.read_range(address, sz)?;
1478
+ dst.copy_from_slice(raw.as_ref());
1479
+ Ok(())
1480
+ }
1481
+
1482
+ fn read_contiguous_logical_range(
1483
+ &self,
1484
+ address: u64,
1485
+ logical_offset: usize,
1486
+ len: usize,
1487
+ ) -> Result<Vec<u8>> {
1488
+ if self.external_files.is_some() {
1489
+ return self.read_external_range(logical_offset, len);
1490
+ }
1491
+
1492
+ let file_offset = checked_add_u64(
1493
+ address,
1494
+ u64::try_from(logical_offset).map_err(|_| {
1495
+ Error::InvalidData("contiguous logical offset exceeds u64 capacity".to_string())
1496
+ })?,
1497
+ "contiguous read file offset",
1498
+ )?;
1499
+ Ok(self.context.read_range(file_offset, len)?.to_vec())
1500
+ }
1501
+
1502
+ fn read_external_range(&self, logical_offset: usize, len: usize) -> Result<Vec<u8>> {
1503
+ let mut output = vec![0u8; len];
1504
+ self.read_external_range_into(logical_offset, &mut output)?;
1505
+ Ok(output)
1506
+ }
1507
+
1508
+ fn read_external_range_into(&self, logical_offset: usize, dst: &mut [u8]) -> Result<()> {
1509
+ self.fill_output_buffer(dst);
1510
+ if dst.is_empty() {
1511
+ return Ok(());
1512
+ }
1513
+
1514
+ let request_start = u64::try_from(logical_offset).map_err(|_| {
1515
+ Error::InvalidData("external dataset offset exceeds u64 capacity".to_string())
1516
+ })?;
1517
+ let request_len = u64::try_from(dst.len()).map_err(|_| {
1518
+ Error::InvalidData("external dataset length exceeds u64 capacity".to_string())
1519
+ })?;
1520
+ let request_end = request_start
1521
+ .checked_add(request_len)
1522
+ .ok_or_else(|| Error::InvalidData("external dataset range overflows".into()))?;
1523
+
1524
+ for slot in self.external_raw_slots()?.iter() {
1525
+ let slot_end = slot.logical_offset.saturating_add(slot.size);
1526
+ let overlap_start = request_start.max(slot.logical_offset);
1527
+ let overlap_end = request_end.min(slot_end);
1528
+ if overlap_start >= overlap_end {
1529
+ continue;
1530
+ }
1531
+
1532
+ let read_offset = slot
1533
+ .file_offset
1534
+ .checked_add(overlap_start - slot.logical_offset)
1535
+ .ok_or_else(|| Error::InvalidData("external file read offset overflows".into()))?;
1536
+ let read_len = checked_usize(overlap_end - overlap_start, "external read length")?;
1537
+ let dst_start = checked_usize(overlap_start - request_start, "external read dst")?;
1538
+ let dst_end = checked_add_usize(dst_start, read_len, "external read dst end")?;
1539
+ let bytes = slot.storage.read_range(read_offset, read_len)?;
1540
+ dst[dst_start..dst_end].copy_from_slice(bytes.as_ref());
1541
+ }
1542
+
1543
+ Ok(())
1544
+ }
1545
+
1546
+ fn external_raw_slots(&self) -> Result<Arc<Vec<ResolvedExternalRawSlot>>> {
1547
+ if let Some(slots) = self.external_slots.get() {
1548
+ return Ok(slots.clone());
1549
+ }
1550
+
1551
+ let slots = Arc::new(self.load_external_raw_slots()?);
1552
+ let _ = self.external_slots.set(slots.clone());
1553
+ Ok(self
1554
+ .external_slots
1555
+ .get()
1556
+ .expect("external slot cache must exist after initialization")
1557
+ .clone())
1558
+ }
1559
+
1560
+ fn load_external_raw_slots(&self) -> Result<Vec<ResolvedExternalRawSlot>> {
1561
+ let Some(external_files) = self.external_files.as_ref() else {
1562
+ return Ok(Vec::new());
1563
+ };
1564
+
1565
+ let heap = LocalHeap::parse_at_storage(
1566
+ self.context.storage.as_ref(),
1567
+ external_files.heap_address,
1568
+ self.offset_size(),
1569
+ self.length_size(),
1570
+ )?;
1571
+
1572
+ let mut logical_offset = 0u64;
1573
+ let mut slots = Vec::with_capacity(external_files.slots.len());
1574
+ for slot in &external_files.slots {
1575
+ let filename =
1576
+ heap.get_string_storage(slot.name_offset, self.context.storage.as_ref())?;
1577
+ let storage = self
1578
+ .context
1579
+ .resolve_external_file(&filename)?
1580
+ .ok_or_else(|| {
1581
+ Error::Other(format!(
1582
+ "external raw data file '{filename}' could not be resolved"
1583
+ ))
1584
+ })?;
1585
+ let size = if Cursor::is_undefined_offset(slot.size, self.length_size()) {
1586
+ u64::MAX.saturating_sub(logical_offset)
1587
+ } else {
1588
+ slot.size
1589
+ };
1590
+
1591
+ slots.push(ResolvedExternalRawSlot {
1592
+ logical_offset,
1593
+ storage,
1594
+ file_offset: slot.offset,
1595
+ size,
1596
+ });
1597
+
1598
+ if Cursor::is_undefined_offset(slot.size, self.length_size()) {
1599
+ break;
1600
+ }
1601
+ logical_offset = logical_offset.checked_add(slot.size).ok_or_else(|| {
1602
+ Error::InvalidData("external raw data logical offset overflows".into())
1603
+ })?;
1604
+ }
1605
+
1606
+ Ok(slots)
1607
+ }
1608
+
1609
+ fn read_chunked<T: H5Type>(
1610
+ &self,
1611
+ index_address: u64,
1612
+ chunk_dims: &[u32],
1613
+ _element_size: u32,
1614
+ chunk_indexing: Option<&ChunkIndexing>,
1615
+ ) -> Result<ArrayD<T>> {
1616
+ if Cursor::is_undefined_offset(index_address, self.offset_size()) {
1617
+ return self.make_fill_array::<T>();
1618
+ }
1619
+
1620
+ let ndim = self.ndim();
1621
+ let shape = &self.dataspace.dims;
1622
+ let elem_size = self.raw_element_size()?;
1623
+ let total_elements = checked_usize(self.num_elements()?, "dataset element count")?;
1624
+ let total_bytes = checked_mul_usize(total_elements, elem_size, "dataset size in bytes")?;
1625
+
1626
+ if total_bytes <= HOT_FULL_DATASET_CACHE_MAX_BYTES {
1627
+ if let Some(cached_bytes) = self.full_dataset_bytes.get() {
1628
+ return self.decode_raw_data::<T>(cached_bytes);
1629
+ }
1630
+ }
1631
+
1632
+ let chunk_shape: Vec<u64> = chunk_dims.iter().map(|&d| d as u64).collect();
1633
+ validate_chunk_shape(shape, &chunk_shape)?;
1634
+ let dataset_strides = row_major_strides(shape, "dataset stride")?;
1635
+ let chunk_strides = row_major_strides(&chunk_shape, "chunk stride")?;
1636
+
1637
+ let mut entries = self.collect_chunk_entries(
1638
+ index_address,
1639
+ chunk_dims,
1640
+ chunk_indexing,
1641
+ ChunkEntrySelection {
1642
+ shape,
1643
+ ndim,
1644
+ elem_size,
1645
+ chunk_bounds: None,
1646
+ },
1647
+ )?;
1648
+
1649
+ let full_chunk_coverage = match full_dataset_chunk_bounds(shape, &chunk_shape)? {
1650
+ Some((first_chunk, last_chunk)) => validate_chunk_grid_coverage(
1651
+ &mut entries,
1652
+ shape,
1653
+ &chunk_shape,
1654
+ &first_chunk,
1655
+ &last_chunk,
1656
+ )?,
1657
+ None if entries.is_empty() => true,
1658
+ None => {
1659
+ return Err(Error::InvalidData(
1660
+ "chunk index contains entries for an empty dataset".into(),
1661
+ ))
1662
+ }
1663
+ };
1664
+ if full_chunk_coverage {
1665
+ if T::native_copy_compatible(&self.datatype) && std::mem::size_of::<T>() == elem_size {
1666
+ let mut result_values: Vec<MaybeUninit<T>> = try_uninit_vec::<T>(total_elements)?;
1667
+ let result_ptr = result_values.as_mut_ptr() as *mut u8;
1668
+ let result_len = checked_mul_usize(
1669
+ result_values.len(),
1670
+ std::mem::size_of::<T>(),
1671
+ "typed dataset size in bytes",
1672
+ )?;
1673
+
1674
+ for entry in &entries {
1675
+ let chunk_data =
1676
+ self.load_exact_chunk_data(entry, index_address, &chunk_shape, elem_size)?;
1677
+ // SAFETY: the validated chunk grid has no duplicate
1678
+ // offsets, the helper checks every range, and the output
1679
+ // allocation remains live for the duration of the copy.
1680
+ unsafe {
1681
+ copy_chunk_to_flat_with_strides_ptr(
1682
+ &chunk_data,
1683
+ FlatBufferPtr {
1684
+ ptr: result_ptr,
1685
+ len: result_len,
1686
+ },
1687
+ ChunkCopyLayout {
1688
+ chunk_offsets: &entry.offsets,
1689
+ chunk_shape: &chunk_shape,
1690
+ dataset_shape: shape,
1691
+ dataset_strides: &dataset_strides,
1692
+ chunk_strides: &chunk_strides,
1693
+ elem_size,
1694
+ },
1695
+ )?;
1696
+ }
1697
+ }
1698
+
1699
+ if total_bytes <= HOT_FULL_DATASET_CACHE_MAX_BYTES {
1700
+ let mut cached_bytes = try_zeroed_bytes(total_bytes)?;
1701
+ // SAFETY: full chunk coverage initialized all
1702
+ // `total_bytes` at `result_ptr`, and both allocations are
1703
+ // live and distinct.
1704
+ unsafe {
1705
+ std::ptr::copy_nonoverlapping(
1706
+ result_ptr,
1707
+ cached_bytes.as_mut_ptr(),
1708
+ total_bytes,
1709
+ );
1710
+ }
1711
+ let _ = self.full_dataset_bytes.set(Arc::new(cached_bytes));
1712
+ }
1713
+
1714
+ let mut result_shape = Vec::with_capacity(shape.len());
1715
+ for &dim in shape {
1716
+ result_shape.push(checked_usize(dim, "dataset dimension")?);
1717
+ }
1718
+ // SAFETY: exact, duplicate-free chunk-grid coverage was
1719
+ // validated above and every chunk was copied successfully.
1720
+ let result_values = unsafe { assume_init_vec(result_values) };
1721
+ return ArrayD::from_shape_vec(IxDyn(&result_shape), result_values)
1722
+ .map_err(|e| Error::InvalidData(format!("array shape error: {e}")));
1723
+ }
1724
+
1725
+ let mut flat_data = try_uninit_vec::<u8>(total_bytes)?;
1726
+ let flat_ptr = flat_data.as_mut_ptr() as *mut u8;
1727
+ let flat_len = flat_data.len();
1728
+
1729
+ for entry in &entries {
1730
+ let chunk_data =
1731
+ self.load_exact_chunk_data(entry, index_address, &chunk_shape, elem_size)?;
1732
+ // SAFETY: the validated chunk grid has no duplicate offsets,
1733
+ // the helper checks every range, and the output allocation
1734
+ // remains live for the duration of the copy.
1735
+ unsafe {
1736
+ copy_chunk_to_flat_with_strides_ptr(
1737
+ &chunk_data,
1738
+ FlatBufferPtr {
1739
+ ptr: flat_ptr,
1740
+ len: flat_len,
1741
+ },
1742
+ ChunkCopyLayout {
1743
+ chunk_offsets: &entry.offsets,
1744
+ chunk_shape: &chunk_shape,
1745
+ dataset_shape: shape,
1746
+ dataset_strides: &dataset_strides,
1747
+ chunk_strides: &chunk_strides,
1748
+ elem_size,
1749
+ },
1750
+ )?;
1751
+ }
1752
+ }
1753
+
1754
+ // SAFETY: exact, duplicate-free chunk-grid coverage was validated
1755
+ // above and every chunk was copied successfully.
1756
+ let flat_data = unsafe { assume_init_u8_vec(flat_data) };
1757
+ if total_bytes <= HOT_FULL_DATASET_CACHE_MAX_BYTES {
1758
+ let _ = self.full_dataset_bytes.set(Arc::new(flat_data.clone()));
1759
+ }
1760
+ return self.decode_raw_data::<T>(&flat_data);
1761
+ }
1762
+
1763
+ let mut flat_data = self.make_output_buffer(total_bytes)?;
1764
+ for entry in &entries {
1765
+ let chunk_data =
1766
+ self.load_exact_chunk_data(entry, index_address, &chunk_shape, elem_size)?;
1767
+ copy_chunk_to_flat_with_strides(
1768
+ &chunk_data,
1769
+ &mut flat_data,
1770
+ ChunkCopyLayout {
1771
+ chunk_offsets: &entry.offsets,
1772
+ chunk_shape: &chunk_shape,
1773
+ dataset_shape: shape,
1774
+ dataset_strides: &dataset_strides,
1775
+ chunk_strides: &chunk_strides,
1776
+ elem_size,
1777
+ },
1778
+ )?;
1779
+ }
1780
+
1781
+ self.decode_raw_data::<T>(&flat_data)
1782
+ }
1783
+
1784
+ fn read_chunked_bytes_into(
1785
+ &self,
1786
+ index_address: u64,
1787
+ chunk_dims: &[u32],
1788
+ chunk_indexing: Option<&ChunkIndexing>,
1789
+ dst: &mut [u8],
1790
+ ) -> Result<()> {
1791
+ if Cursor::is_undefined_offset(index_address, self.offset_size()) {
1792
+ self.fill_output_buffer(dst);
1793
+ return Ok(());
1794
+ }
1795
+
1796
+ let ndim = self.ndim();
1797
+ let shape = &self.dataspace.dims;
1798
+ let elem_size = self.raw_element_size()?;
1799
+
1800
+ if dst.len() <= HOT_FULL_DATASET_CACHE_MAX_BYTES {
1801
+ if let Some(cached_bytes) = self.full_dataset_bytes.get() {
1802
+ if cached_bytes.len() == dst.len() {
1803
+ dst.copy_from_slice(cached_bytes.as_slice());
1804
+ return Ok(());
1805
+ }
1806
+ }
1807
+ }
1808
+
1809
+ let chunk_shape: Vec<u64> = chunk_dims.iter().map(|&d| d as u64).collect();
1810
+ validate_chunk_shape(shape, &chunk_shape)?;
1811
+ let dataset_strides = row_major_strides(shape, "dataset stride")?;
1812
+ let chunk_strides = row_major_strides(&chunk_shape, "chunk stride")?;
1813
+
1814
+ let mut entries = self.collect_chunk_entries(
1815
+ index_address,
1816
+ chunk_dims,
1817
+ chunk_indexing,
1818
+ ChunkEntrySelection {
1819
+ shape,
1820
+ ndim,
1821
+ elem_size,
1822
+ chunk_bounds: None,
1823
+ },
1824
+ )?;
1825
+
1826
+ let full_chunk_coverage = match full_dataset_chunk_bounds(shape, &chunk_shape)? {
1827
+ Some((first_chunk, last_chunk)) => validate_chunk_grid_coverage(
1828
+ &mut entries,
1829
+ shape,
1830
+ &chunk_shape,
1831
+ &first_chunk,
1832
+ &last_chunk,
1833
+ )?,
1834
+ None if entries.is_empty() => true,
1835
+ None => {
1836
+ return Err(Error::InvalidData(
1837
+ "chunk index contains entries for an empty dataset".into(),
1838
+ ))
1839
+ }
1840
+ };
1841
+
1842
+ self.fill_output_buffer(dst);
1843
+ for entry in &entries {
1844
+ let chunk_data =
1845
+ self.load_exact_chunk_data(entry, index_address, &chunk_shape, elem_size)?;
1846
+ copy_chunk_to_flat_with_strides(
1847
+ &chunk_data,
1848
+ dst,
1849
+ ChunkCopyLayout {
1850
+ chunk_offsets: &entry.offsets,
1851
+ chunk_shape: &chunk_shape,
1852
+ dataset_shape: shape,
1853
+ dataset_strides: &dataset_strides,
1854
+ chunk_strides: &chunk_strides,
1855
+ elem_size,
1856
+ },
1857
+ )?;
1858
+ }
1859
+
1860
+ if full_chunk_coverage && dst.len() <= HOT_FULL_DATASET_CACHE_MAX_BYTES {
1861
+ let _ = self.full_dataset_bytes.set(Arc::new(dst.to_vec()));
1862
+ }
1863
+
1864
+ Ok(())
1865
+ }
1866
+
1867
+ #[cfg(feature = "rayon")]
1868
+ fn read_chunked_parallel<T: H5Type>(
1869
+ &self,
1870
+ index_address: u64,
1871
+ chunk_dims: &[u32],
1872
+ _element_size: u32,
1873
+ chunk_indexing: Option<&ChunkIndexing>,
1874
+ ) -> Result<ArrayD<T>> {
1875
+ if Cursor::is_undefined_offset(index_address, self.offset_size()) {
1876
+ return self.make_fill_array::<T>();
1877
+ }
1878
+
1879
+ let ndim = self.ndim();
1880
+ let shape = &self.dataspace.dims;
1881
+ let elem_size = self.raw_element_size()?;
1882
+ let total_elements = checked_usize(self.num_elements()?, "dataset element count")?;
1883
+ let total_bytes = checked_mul_usize(total_elements, elem_size, "dataset size in bytes")?;
1884
+
1885
+ if total_bytes <= HOT_FULL_DATASET_CACHE_MAX_BYTES {
1886
+ if let Some(cached_bytes) = self.full_dataset_bytes.get() {
1887
+ return self.decode_raw_data::<T>(cached_bytes);
1888
+ }
1889
+ }
1890
+
1891
+ let chunk_shape: Vec<u64> = chunk_dims.iter().map(|&d| d as u64).collect();
1892
+ validate_chunk_shape(shape, &chunk_shape)?;
1893
+ let dataset_strides = row_major_strides(shape, "dataset stride")?;
1894
+ let chunk_strides = row_major_strides(&chunk_shape, "chunk stride")?;
1895
+
1896
+ let mut entries = self.collect_chunk_entries(
1897
+ index_address,
1898
+ chunk_dims,
1899
+ chunk_indexing,
1900
+ ChunkEntrySelection {
1901
+ shape,
1902
+ ndim,
1903
+ elem_size,
1904
+ chunk_bounds: None,
1905
+ },
1906
+ )?;
1907
+
1908
+ let full_chunk_coverage = match full_dataset_chunk_bounds(shape, &chunk_shape)? {
1909
+ Some((first_chunk, last_chunk)) => validate_chunk_grid_coverage(
1910
+ &mut entries,
1911
+ shape,
1912
+ &chunk_shape,
1913
+ &first_chunk,
1914
+ &last_chunk,
1915
+ )?,
1916
+ None if entries.is_empty() => true,
1917
+ None => {
1918
+ return Err(Error::InvalidData(
1919
+ "chunk index contains entries for an empty dataset".into(),
1920
+ ))
1921
+ }
1922
+ };
1923
+ if full_chunk_coverage {
1924
+ if T::native_copy_compatible(&self.datatype) && std::mem::size_of::<T>() == elem_size {
1925
+ let mut result_values: Vec<MaybeUninit<T>> = try_uninit_vec::<T>(total_elements)?;
1926
+ let flat = FlatBufferPtr {
1927
+ ptr: result_values.as_mut_ptr() as *mut u8,
1928
+ len: checked_mul_usize(
1929
+ result_values.len(),
1930
+ std::mem::size_of::<T>(),
1931
+ "typed dataset size in bytes",
1932
+ )?,
1933
+ };
1934
+
1935
+ entries
1936
+ .par_iter()
1937
+ .map(|entry| {
1938
+ self.load_exact_chunk_data(entry, index_address, &chunk_shape, elem_size)
1939
+ .and_then(|data| {
1940
+ // SAFETY: validated chunk offsets are unique,
1941
+ // so parallel copies write disjoint ranges;
1942
+ // `result_values` remains live through collect.
1943
+ unsafe {
1944
+ flat.copy_chunk(
1945
+ &data,
1946
+ ChunkCopyLayout {
1947
+ chunk_offsets: &entry.offsets,
1948
+ chunk_shape: &chunk_shape,
1949
+ dataset_shape: shape,
1950
+ dataset_strides: &dataset_strides,
1951
+ chunk_strides: &chunk_strides,
1952
+ elem_size,
1953
+ },
1954
+ )
1955
+ }
1956
+ })
1957
+ })
1958
+ .collect::<std::result::Result<Vec<_>, Error>>()?;
1959
+
1960
+ let mut result_shape = Vec::with_capacity(shape.len());
1961
+ for &dim in shape {
1962
+ result_shape.push(checked_usize(dim, "dataset dimension")?);
1963
+ }
1964
+ if total_bytes <= HOT_FULL_DATASET_CACHE_MAX_BYTES {
1965
+ let mut cached_bytes = try_zeroed_bytes(total_bytes)?;
1966
+ // SAFETY: full chunk coverage initialized all
1967
+ // `total_bytes` at `flat.ptr`, and both allocations are
1968
+ // live and distinct.
1969
+ unsafe {
1970
+ std::ptr::copy_nonoverlapping(
1971
+ flat.ptr,
1972
+ cached_bytes.as_mut_ptr(),
1973
+ total_bytes,
1974
+ );
1975
+ }
1976
+ let _ = self.full_dataset_bytes.set(Arc::new(cached_bytes));
1977
+ }
1978
+ // SAFETY: exact, duplicate-free chunk-grid coverage was
1979
+ // validated above and all parallel copies completed.
1980
+ let result_values = unsafe { assume_init_vec(result_values) };
1981
+ return ArrayD::from_shape_vec(IxDyn(&result_shape), result_values)
1982
+ .map_err(|e| Error::InvalidData(format!("array shape error: {e}")));
1983
+ }
1984
+
1985
+ let mut flat_data = try_uninit_vec::<u8>(total_bytes)?;
1986
+ let flat = FlatBufferPtr {
1987
+ ptr: flat_data.as_mut_ptr() as *mut u8,
1988
+ len: flat_data.len(),
1989
+ };
1990
+
1991
+ entries
1992
+ .par_iter()
1993
+ .map(|entry| {
1994
+ self.load_exact_chunk_data(entry, index_address, &chunk_shape, elem_size)
1995
+ .and_then(|data| {
1996
+ // SAFETY: validated chunk offsets are unique, so
1997
+ // parallel copies write disjoint ranges;
1998
+ // `flat_data` remains live through collect.
1999
+ unsafe {
2000
+ flat.copy_chunk(
2001
+ &data,
2002
+ ChunkCopyLayout {
2003
+ chunk_offsets: &entry.offsets,
2004
+ chunk_shape: &chunk_shape,
2005
+ dataset_shape: shape,
2006
+ dataset_strides: &dataset_strides,
2007
+ chunk_strides: &chunk_strides,
2008
+ elem_size,
2009
+ },
2010
+ )
2011
+ }
2012
+ })
2013
+ })
2014
+ .collect::<std::result::Result<Vec<_>, Error>>()?;
2015
+
2016
+ // SAFETY: exact, duplicate-free chunk-grid coverage was validated
2017
+ // above and all parallel copies completed.
2018
+ let flat_data = unsafe { assume_init_u8_vec(flat_data) };
2019
+ if total_bytes <= HOT_FULL_DATASET_CACHE_MAX_BYTES {
2020
+ let _ = self.full_dataset_bytes.set(Arc::new(flat_data.clone()));
2021
+ }
2022
+ return self.decode_raw_data::<T>(&flat_data);
2023
+ }
2024
+
2025
+ let mut flat_data = self.make_output_buffer(total_bytes)?;
2026
+ let flat = FlatBufferPtr {
2027
+ ptr: flat_data.as_mut_ptr(),
2028
+ len: flat_data.len(),
2029
+ };
2030
+
2031
+ entries
2032
+ .par_iter()
2033
+ .map(|entry| {
2034
+ self.load_exact_chunk_data(entry, index_address, &chunk_shape, elem_size)
2035
+ .and_then(|data| {
2036
+ // SAFETY: validated chunk offsets are unique, so
2037
+ // parallel copies write disjoint ranges; `flat_data`
2038
+ // remains live through collect.
2039
+ unsafe {
2040
+ flat.copy_chunk(
2041
+ &data,
2042
+ ChunkCopyLayout {
2043
+ chunk_offsets: &entry.offsets,
2044
+ chunk_shape: &chunk_shape,
2045
+ dataset_shape: shape,
2046
+ dataset_strides: &dataset_strides,
2047
+ chunk_strides: &chunk_strides,
2048
+ elem_size,
2049
+ },
2050
+ )
2051
+ }
2052
+ })
2053
+ })
2054
+ .collect::<std::result::Result<Vec<_>, Error>>()?;
2055
+
2056
+ self.decode_raw_data::<T>(&flat_data)
2057
+ }
2058
+
2059
+ /// Collect all chunk entries by dispatching on the chunk indexing type.
2060
+ ///
2061
+ /// Shared by `read_chunked` and `read_chunked_slice`.
2062
+ fn collect_chunk_entries(
2063
+ &self,
2064
+ index_address: u64,
2065
+ chunk_dims: &[u32],
2066
+ chunk_indexing: Option<&ChunkIndexing>,
2067
+ selection: ChunkEntrySelection<'_>,
2068
+ ) -> Result<Vec<chunk_index::ChunkEntry>> {
2069
+ if selection.chunk_bounds.is_none() {
2070
+ if let Some(cached) = self.full_chunk_entries.get() {
2071
+ return Ok((**cached).clone());
2072
+ }
2073
+ }
2074
+
2075
+ let cache_key =
2076
+ selection
2077
+ .chunk_bounds
2078
+ .map(|(first_chunk, last_chunk)| ChunkEntryCacheKey {
2079
+ index_address,
2080
+ first_chunk: SmallVec::from_slice(first_chunk),
2081
+ last_chunk: SmallVec::from_slice(last_chunk),
2082
+ });
2083
+
2084
+ if let Some(ref key) = cache_key {
2085
+ let mut cache = self.chunk_entry_cache.lock();
2086
+ if let Some(cached) = cache.get(key) {
2087
+ return Ok((**cached).clone());
2088
+ }
2089
+ }
2090
+
2091
+ let entries = match chunk_indexing {
2092
+ None => {
2093
+ // V1-V3: B-tree v1 chunk indexing
2094
+ self.collect_btree_v1_entries(
2095
+ index_address,
2096
+ selection.ndim,
2097
+ chunk_dims,
2098
+ selection.chunk_bounds,
2099
+ )
2100
+ }
2101
+ Some(ChunkIndexing::SingleChunk {
2102
+ filtered_size,
2103
+ filters,
2104
+ }) => Ok(vec![chunk_index::single_chunk_entry(
2105
+ index_address,
2106
+ *filtered_size,
2107
+ *filters,
2108
+ selection.ndim,
2109
+ )]),
2110
+ Some(ChunkIndexing::BTreeV2) => chunk_index::collect_v2_chunk_entries_storage(
2111
+ self.context.storage.as_ref(),
2112
+ index_address,
2113
+ self.offset_size(),
2114
+ self.length_size(),
2115
+ selection.ndim as u32,
2116
+ chunk_dims,
2117
+ selection.chunk_bounds,
2118
+ ),
2119
+ Some(ChunkIndexing::Implicit) => chunk_index::collect_implicit_chunk_entries(
2120
+ index_address,
2121
+ selection.shape,
2122
+ chunk_dims,
2123
+ selection.elem_size,
2124
+ selection.chunk_bounds,
2125
+ self.context.storage.len(),
2126
+ ),
2127
+ Some(ChunkIndexing::FixedArray { .. }) => {
2128
+ crate::fixed_array::collect_fixed_array_chunk_entries_storage(
2129
+ self.context.storage.as_ref(),
2130
+ index_address,
2131
+ self.offset_size(),
2132
+ self.length_size(),
2133
+ selection.shape,
2134
+ chunk_dims,
2135
+ selection.chunk_bounds,
2136
+ )
2137
+ }
2138
+ Some(ChunkIndexing::ExtensibleArray { .. }) => {
2139
+ crate::extensible_array::collect_extensible_array_chunk_entries_storage(
2140
+ self.context.storage.as_ref(),
2141
+ index_address,
2142
+ self.offset_size(),
2143
+ self.length_size(),
2144
+ selection.shape,
2145
+ chunk_dims,
2146
+ selection.chunk_bounds,
2147
+ )
2148
+ }
2149
+ }?;
2150
+
2151
+ if let Some(key) = cache_key {
2152
+ let mut cache = self.chunk_entry_cache.lock();
2153
+ cache.put(key, Arc::new(entries.clone()));
2154
+ } else {
2155
+ let _ = self.full_chunk_entries.set(Arc::new(entries.clone()));
2156
+ }
2157
+
2158
+ Ok(entries)
2159
+ }
2160
+
2161
+ /// Collect chunk entries from a B-tree v1 index.
2162
+ fn collect_btree_v1_entries(
2163
+ &self,
2164
+ btree_address: u64,
2165
+ ndim: usize,
2166
+ chunk_dims: &[u32],
2167
+ chunk_bounds: Option<(&[u64], &[u64])>,
2168
+ ) -> Result<Vec<chunk_index::ChunkEntry>> {
2169
+ let leaves = crate::btree_v1::collect_btree_v1_leaves_storage(
2170
+ self.context.storage.as_ref(),
2171
+ btree_address,
2172
+ self.offset_size(),
2173
+ self.length_size(),
2174
+ Some(ndim as u32),
2175
+ chunk_dims,
2176
+ chunk_bounds,
2177
+ )?;
2178
+
2179
+ let mut entries = Vec::with_capacity(leaves.len());
2180
+ for (key, chunk_addr) in &leaves {
2181
+ match key {
2182
+ crate::btree_v1::BTreeV1Key::RawData {
2183
+ chunk_size,
2184
+ filter_mask,
2185
+ offsets,
2186
+ } => {
2187
+ entries.push(chunk_index::ChunkEntry {
2188
+ address: *chunk_addr,
2189
+ size: *chunk_size as u64,
2190
+ filter_mask: *filter_mask,
2191
+ offsets: offsets[..ndim].to_vec(),
2192
+ });
2193
+ }
2194
+ _ => {
2195
+ return Err(Error::InvalidData(
2196
+ "expected raw data key in chunk B-tree".into(),
2197
+ ))
2198
+ }
2199
+ }
2200
+ }
2201
+ Ok(entries)
2202
+ }
2203
+
2204
+ fn load_chunk_data(
2205
+ &self,
2206
+ entry: &chunk_index::ChunkEntry,
2207
+ dataset_addr: u64,
2208
+ chunk_shape: &[u64],
2209
+ elem_size: usize,
2210
+ ) -> Result<Arc<Vec<u8>>> {
2211
+ let cache_key = ChunkKey {
2212
+ dataset_addr,
2213
+ chunk_offsets: smallvec::SmallVec::from_slice(&entry.offsets),
2214
+ };
2215
+ let expected_len = decoded_chunk_expected_len(chunk_shape, elem_size)?;
2216
+ let filter_output_limit =
2217
+ checked_add_usize(expected_len, 1, "decoded chunk filter output limit")?;
2218
+
2219
+ self.chunk_cache.get_or_insert_with(cache_key, || {
2220
+ let size = if entry.size > 0 {
2221
+ checked_usize(entry.size, "encoded chunk size")?
2222
+ } else {
2223
+ expected_len
2224
+ };
2225
+ let raw = self.context.read_range(entry.address, size)?;
2226
+
2227
+ if let Some(ref pipeline) = self.filters {
2228
+ filters::apply_pipeline_with_limit(
2229
+ raw.as_ref(),
2230
+ &pipeline.filters,
2231
+ entry.filter_mask,
2232
+ elem_size,
2233
+ Some(&self.filter_registry),
2234
+ Some(filter_output_limit),
2235
+ )
2236
+ } else {
2237
+ Ok(raw.to_vec())
2238
+ }
2239
+ })
2240
+ }
2241
+
2242
+ fn load_exact_chunk_data(
2243
+ &self,
2244
+ entry: &chunk_index::ChunkEntry,
2245
+ dataset_addr: u64,
2246
+ chunk_shape: &[u64],
2247
+ elem_size: usize,
2248
+ ) -> Result<Arc<Vec<u8>>> {
2249
+ let data = self.load_chunk_data(entry, dataset_addr, chunk_shape, elem_size)?;
2250
+ validate_decoded_chunk_len(entry, chunk_shape, elem_size, data.len())?;
2251
+ Ok(data)
2252
+ }
2253
+
2254
+ /// Chunked slice: only read chunks that overlap the selection.
2255
+ ///
2256
+ /// Resolves each `SliceInfoElem` to concrete ranges, computes the chunk
2257
+ /// grid range per dimension, and only decompresses overlapping chunks.
2258
+ fn read_chunked_slice<T: H5Type>(
2259
+ &self,
2260
+ index_address: u64,
2261
+ chunk_dims: &[u32],
2262
+ _element_size: u32,
2263
+ chunk_indexing: Option<&ChunkIndexing>,
2264
+ _selection: &SliceInfo,
2265
+ resolved: &ResolvedSelection,
2266
+ ) -> Result<ArrayD<T>> {
2267
+ if resolved.result_elements == 0 {
2268
+ return self.make_fill_array_from_shape::<T>(0, &resolved.result_shape);
2269
+ }
2270
+
2271
+ if Cursor::is_undefined_offset(index_address, self.offset_size()) {
2272
+ return self
2273
+ .make_fill_array_from_shape::<T>(resolved.result_elements, &resolved.result_shape);
2274
+ }
2275
+
2276
+ let ndim = self.ndim();
2277
+ let shape = &self.dataspace.dims;
2278
+ let elem_size = self.raw_element_size()?;
2279
+
2280
+ if let Some(array) = self.try_read_single_chunk_unit_stride_2d::<T>(
2281
+ index_address,
2282
+ chunk_dims,
2283
+ chunk_indexing,
2284
+ shape,
2285
+ elem_size,
2286
+ resolved,
2287
+ )? {
2288
+ return Ok(array);
2289
+ }
2290
+
2291
+ let chunk_shape: Vec<u64> = chunk_dims.iter().map(|&d| d as u64).collect();
2292
+ validate_chunk_shape(shape, &chunk_shape)?;
2293
+ let mut first_chunk = vec![0u64; ndim];
2294
+ let mut last_chunk = vec![0u64; ndim];
2295
+ for d in 0..ndim {
2296
+ let (first, last) = resolved.dims[d]
2297
+ .chunk_index_range(chunk_shape[d])
2298
+ .expect("zero-sized result handled above");
2299
+ first_chunk[d] = first;
2300
+ last_chunk[d] = last;
2301
+ }
2302
+
2303
+ // Collect all chunk entries.
2304
+ let mut overlapping = self.collect_chunk_entries(
2305
+ index_address,
2306
+ chunk_dims,
2307
+ chunk_indexing,
2308
+ ChunkEntrySelection {
2309
+ shape,
2310
+ ndim,
2311
+ elem_size,
2312
+ chunk_bounds: Some((&first_chunk, &last_chunk)),
2313
+ },
2314
+ )?;
2315
+ let fully_covered_grid = validate_chunk_grid_coverage(
2316
+ &mut overlapping,
2317
+ shape,
2318
+ &chunk_shape,
2319
+ &first_chunk,
2320
+ &last_chunk,
2321
+ )?;
2322
+
2323
+ let result_total_bytes = checked_mul_usize(
2324
+ resolved.result_elements,
2325
+ elem_size,
2326
+ "slice result size in bytes",
2327
+ )?;
2328
+ // Compute result strides (including collapsed dims — they have count=1).
2329
+ let result_dims = resolved.result_dims_with_collapsed();
2330
+ let mut result_strides = vec![1usize; ndim];
2331
+ for d in (0..ndim.saturating_sub(1)).rev() {
2332
+ result_strides[d] =
2333
+ checked_mul_usize(result_strides[d + 1], result_dims[d + 1], "result stride")?;
2334
+ }
2335
+ let mut chunk_strides = vec![1usize; ndim];
2336
+ for d in (0..ndim.saturating_sub(1)).rev() {
2337
+ chunk_strides[d] = checked_mul_usize(
2338
+ chunk_strides[d + 1],
2339
+ chunk_shape[d + 1] as usize,
2340
+ "chunk stride",
2341
+ )?;
2342
+ }
2343
+ let use_unit_stride_fast_path = resolved.is_unit_stride();
2344
+ let fully_covered_unit_stride = use_unit_stride_fast_path && fully_covered_grid;
2345
+
2346
+ if fully_covered_unit_stride {
2347
+ if T::native_copy_compatible(&self.datatype) && std::mem::size_of::<T>() == elem_size {
2348
+ let mut result_values: Vec<MaybeUninit<T>> =
2349
+ try_uninit_vec::<T>(resolved.result_elements)?;
2350
+ let result_ptr = result_values.as_mut_ptr() as *mut u8;
2351
+ let result_len = checked_mul_usize(
2352
+ result_values.len(),
2353
+ std::mem::size_of::<T>(),
2354
+ "typed slice result size in bytes",
2355
+ )?;
2356
+
2357
+ for entry in &overlapping {
2358
+ let chunk_data =
2359
+ self.load_exact_chunk_data(entry, index_address, &chunk_shape, elem_size)?;
2360
+
2361
+ // SAFETY: validated chunk offsets are unique, the overlap
2362
+ // helper checks every range, and the output allocation
2363
+ // remains live for the duration of the copy.
2364
+ unsafe {
2365
+ copy_unit_stride_chunk_overlap_ptr(
2366
+ &chunk_data,
2367
+ FlatBufferPtr {
2368
+ ptr: result_ptr,
2369
+ len: result_len,
2370
+ },
2371
+ UnitStrideCopyLayout {
2372
+ chunk_offsets: &entry.offsets,
2373
+ chunk_shape: &chunk_shape,
2374
+ dataset_shape: shape,
2375
+ resolved,
2376
+ chunk_strides: &chunk_strides,
2377
+ result_strides: &result_strides,
2378
+ elem_size,
2379
+ },
2380
+ )?;
2381
+ }
2382
+ }
2383
+
2384
+ // SAFETY: the fully-covered selection gate proves that the
2385
+ // successful overlap copies initialized every result element.
2386
+ let result_values = unsafe { assume_init_vec(result_values) };
2387
+ return ArrayD::from_shape_vec(IxDyn(&resolved.result_shape), result_values)
2388
+ .map_err(|e| Error::InvalidData(format!("array shape error: {e}")));
2389
+ }
2390
+
2391
+ let mut result_buf = try_uninit_vec::<u8>(result_total_bytes)?;
2392
+ let result_ptr = result_buf.as_mut_ptr() as *mut u8;
2393
+ let result_len = result_buf.len();
2394
+
2395
+ for entry in &overlapping {
2396
+ let chunk_data =
2397
+ self.load_exact_chunk_data(entry, index_address, &chunk_shape, elem_size)?;
2398
+
2399
+ // SAFETY: validated chunk offsets are unique, the overlap
2400
+ // helper checks every range, and the output allocation remains
2401
+ // live for the duration of the copy.
2402
+ unsafe {
2403
+ copy_unit_stride_chunk_overlap_ptr(
2404
+ &chunk_data,
2405
+ FlatBufferPtr {
2406
+ ptr: result_ptr,
2407
+ len: result_len,
2408
+ },
2409
+ UnitStrideCopyLayout {
2410
+ chunk_offsets: &entry.offsets,
2411
+ chunk_shape: &chunk_shape,
2412
+ dataset_shape: shape,
2413
+ resolved,
2414
+ chunk_strides: &chunk_strides,
2415
+ result_strides: &result_strides,
2416
+ elem_size,
2417
+ },
2418
+ )?;
2419
+ }
2420
+ }
2421
+
2422
+ // SAFETY: the fully-covered selection gate proves that the
2423
+ // successful overlap copies initialized every result byte.
2424
+ let result_buf = unsafe { assume_init_u8_vec(result_buf) };
2425
+ return self.decode_buffer_with_shape::<T>(
2426
+ &result_buf,
2427
+ resolved.result_elements,
2428
+ &resolved.result_shape,
2429
+ );
2430
+ }
2431
+
2432
+ let mut result_buf = self.make_output_buffer(result_total_bytes)?;
2433
+
2434
+ // For each overlapping chunk: decompress and copy matching elements.
2435
+ for entry in &overlapping {
2436
+ let chunk_data =
2437
+ self.load_exact_chunk_data(entry, index_address, &chunk_shape, elem_size)?;
2438
+
2439
+ if use_unit_stride_fast_path {
2440
+ copy_unit_stride_chunk_overlap(
2441
+ &chunk_data,
2442
+ &mut result_buf,
2443
+ UnitStrideCopyLayout {
2444
+ chunk_offsets: &entry.offsets,
2445
+ chunk_shape: &chunk_shape,
2446
+ dataset_shape: shape,
2447
+ resolved,
2448
+ chunk_strides: &chunk_strides,
2449
+ result_strides: &result_strides,
2450
+ elem_size,
2451
+ },
2452
+ )?;
2453
+ continue;
2454
+ }
2455
+
2456
+ // For each dimension, compute which elements within this chunk fall
2457
+ // within the selection.
2458
+ let mut dim_indices: Vec<Vec<(usize, usize)>> = Vec::with_capacity(ndim);
2459
+ for d in 0..ndim {
2460
+ let chunk_start = entry.offsets[d];
2461
+ let chunk_end = (chunk_start + chunk_shape[d]).min(shape[d]);
2462
+ let dim = &resolved.dims[d];
2463
+ let sel_start = dim.start;
2464
+ let sel_end = dim.end;
2465
+ let sel_step = dim.step;
2466
+ let mut indices = Vec::new();
2467
+
2468
+ // Find first selected index >= chunk_start
2469
+ let first_sel = if sel_start >= chunk_start {
2470
+ sel_start
2471
+ } else {
2472
+ let steps_to_skip = (chunk_start - sel_start).div_ceil(sel_step);
2473
+ sel_start + steps_to_skip * sel_step
2474
+ };
2475
+
2476
+ let mut sel_idx = first_sel;
2477
+ while sel_idx < sel_end && sel_idx < chunk_end {
2478
+ let chunk_local = checked_usize(sel_idx - chunk_start, "chunk-local index")?;
2479
+ // Compute result-space index for this dimension.
2480
+ let result_dim_idx =
2481
+ checked_usize((sel_idx - dim.start) / sel_step, "result index")?;
2482
+ indices.push((chunk_local, result_dim_idx));
2483
+ sel_idx += sel_step;
2484
+ }
2485
+
2486
+ dim_indices.push(indices);
2487
+ }
2488
+
2489
+ // Iterate over the cartesian product of matching indices.
2490
+ copy_selected_elements(
2491
+ &chunk_data,
2492
+ &mut result_buf,
2493
+ &dim_indices,
2494
+ &chunk_strides,
2495
+ &result_strides,
2496
+ elem_size,
2497
+ ndim,
2498
+ )?;
2499
+ }
2500
+
2501
+ self.decode_buffer_with_shape::<T>(
2502
+ &result_buf,
2503
+ resolved.result_elements,
2504
+ &resolved.result_shape,
2505
+ )
2506
+ }
2507
+
2508
+ fn try_read_single_chunk_unit_stride_2d<T: H5Type>(
2509
+ &self,
2510
+ index_address: u64,
2511
+ chunk_dims: &[u32],
2512
+ chunk_indexing: Option<&ChunkIndexing>,
2513
+ shape: &[u64],
2514
+ elem_size: usize,
2515
+ resolved: &ResolvedSelection,
2516
+ ) -> Result<Option<ArrayD<T>>> {
2517
+ if shape.len() != 2
2518
+ || chunk_dims.len() != 2
2519
+ || resolved.dims.len() != 2
2520
+ || resolved.result_shape.len() != 2
2521
+ || !resolved.is_unit_stride()
2522
+ || std::mem::size_of::<T>() != elem_size
2523
+ || !T::native_copy_compatible(&self.datatype)
2524
+ {
2525
+ return Ok(None);
2526
+ }
2527
+
2528
+ let chunk_shape = [u64::from(chunk_dims[0]), u64::from(chunk_dims[1])];
2529
+ validate_chunk_shape(shape, &chunk_shape)?;
2530
+
2531
+ let row_dim = &resolved.dims[0];
2532
+ let col_dim = &resolved.dims[1];
2533
+ let Some((first_row_chunk, last_row_chunk)) = row_dim.chunk_index_range(chunk_shape[0])
2534
+ else {
2535
+ return Ok(None);
2536
+ };
2537
+ let Some((first_col_chunk, last_col_chunk)) = col_dim.chunk_index_range(chunk_shape[1])
2538
+ else {
2539
+ return Ok(None);
2540
+ };
2541
+ if first_row_chunk != last_row_chunk || first_col_chunk != last_col_chunk {
2542
+ return Ok(None);
2543
+ }
2544
+
2545
+ let first_chunk = [first_row_chunk, first_col_chunk];
2546
+ let last_chunk = first_chunk;
2547
+ let expected_offsets = [
2548
+ checked_mul_u64(first_row_chunk, chunk_shape[0], "single chunk row offset")?,
2549
+ checked_mul_u64(
2550
+ first_col_chunk,
2551
+ chunk_shape[1],
2552
+ "single chunk column offset",
2553
+ )?,
2554
+ ];
2555
+
2556
+ let entries = self.collect_chunk_entries(
2557
+ index_address,
2558
+ chunk_dims,
2559
+ chunk_indexing,
2560
+ ChunkEntrySelection {
2561
+ shape,
2562
+ ndim: 2,
2563
+ elem_size,
2564
+ chunk_bounds: Some((&first_chunk, &last_chunk)),
2565
+ },
2566
+ )?;
2567
+
2568
+ if entries.is_empty() {
2569
+ return self
2570
+ .make_fill_array_from_shape::<T>(resolved.result_elements, &resolved.result_shape)
2571
+ .map(Some);
2572
+ }
2573
+
2574
+ if entries.len() != 1 || entries[0].offsets.as_slice() != expected_offsets.as_slice() {
2575
+ return Ok(None);
2576
+ }
2577
+
2578
+ let entry = &entries[0];
2579
+ let chunk_data =
2580
+ self.load_exact_chunk_data(entry, index_address, &chunk_shape, elem_size)?;
2581
+
2582
+ let row_start = checked_usize(
2583
+ row_dim.start - expected_offsets[0],
2584
+ "single chunk slice row start",
2585
+ )?;
2586
+ let col_start = checked_usize(
2587
+ col_dim.start - expected_offsets[1],
2588
+ "single chunk slice column start",
2589
+ )?;
2590
+ let row_count = row_dim.count;
2591
+ let col_count = col_dim.count;
2592
+ let chunk_cols = checked_usize(chunk_shape[1], "single chunk column extent")?;
2593
+ let row_bytes = checked_mul_usize(col_count, elem_size, "single chunk slice row bytes")?;
2594
+
2595
+ let mut result_values: Vec<MaybeUninit<T>> = try_uninit_vec::<T>(resolved.result_elements)?;
2596
+ let result_ptr = result_values.as_mut_ptr() as *mut u8;
2597
+ let result_len = checked_mul_usize(
2598
+ result_values.len(),
2599
+ std::mem::size_of::<T>(),
2600
+ "typed slice result size in bytes",
2601
+ )?;
2602
+
2603
+ for row in 0..row_count {
2604
+ let chunk_row = checked_add_usize(row_start, row, "single chunk slice source row")?;
2605
+ let src_elem = checked_add_usize(
2606
+ checked_mul_usize(chunk_row, chunk_cols, "single chunk slice source row")?,
2607
+ col_start,
2608
+ "single chunk slice source element",
2609
+ )?;
2610
+ let dst_elem = checked_mul_usize(row, col_count, "single chunk slice destination row")?;
2611
+
2612
+ let src_start =
2613
+ checked_mul_usize(src_elem, elem_size, "single chunk slice source byte offset")?;
2614
+ let dst_start = checked_mul_usize(
2615
+ dst_elem,
2616
+ elem_size,
2617
+ "single chunk slice destination byte offset",
2618
+ )?;
2619
+ let src_end =
2620
+ checked_add_usize(src_start, row_bytes, "single chunk slice source byte end")?;
2621
+ let dst_end = checked_add_usize(
2622
+ dst_start,
2623
+ row_bytes,
2624
+ "single chunk slice destination byte end",
2625
+ )?;
2626
+
2627
+ if src_end > chunk_data.len() || dst_end > result_len {
2628
+ return Err(Error::InvalidData(format!(
2629
+ "single chunk unit-stride slice out of bounds: source range {}..{} of {} bytes, destination range {}..{} of {} bytes",
2630
+ src_start,
2631
+ src_end,
2632
+ chunk_data.len(),
2633
+ dst_start,
2634
+ dst_end,
2635
+ result_len
2636
+ )));
2637
+ }
2638
+
2639
+ // SAFETY: the source and destination ranges were checked above;
2640
+ // their allocations are live and distinct.
2641
+ unsafe {
2642
+ std::ptr::copy_nonoverlapping(
2643
+ chunk_data.as_ptr().add(src_start),
2644
+ result_ptr.add(dst_start),
2645
+ row_bytes,
2646
+ );
2647
+ }
2648
+ }
2649
+
2650
+ // SAFETY: this fast path covers one complete unit-stride selection and
2651
+ // the row loop initialized every checked destination range.
2652
+ let result_values = unsafe { assume_init_vec(result_values) };
2653
+ ArrayD::from_shape_vec(IxDyn(&resolved.result_shape), result_values)
2654
+ .map(Some)
2655
+ .map_err(|e| Error::InvalidData(format!("array shape error: {e}")))
2656
+ }
2657
+
2658
+ /// Parallel variant of `read_chunked_slice`: decompresses overlapping chunks
2659
+ /// in parallel using Rayon, then copies selected elements into the result buffer.
2660
+ ///
2661
+ /// Each chunk writes to a disjoint region of the result buffer (chunks don't
2662
+ /// overlap in output space), so this is safe to parallelize.
2663
+ #[cfg(feature = "rayon")]
2664
+ fn read_chunked_slice_parallel<T: H5Type>(
2665
+ &self,
2666
+ index_address: u64,
2667
+ chunk_dims: &[u32],
2668
+ _element_size: u32,
2669
+ chunk_indexing: Option<&ChunkIndexing>,
2670
+ _selection: &SliceInfo,
2671
+ resolved: &ResolvedSelection,
2672
+ ) -> Result<ArrayD<T>> {
2673
+ if resolved.result_elements == 0 {
2674
+ return self.make_fill_array_from_shape::<T>(0, &resolved.result_shape);
2675
+ }
2676
+
2677
+ if Cursor::is_undefined_offset(index_address, self.offset_size()) {
2678
+ return self
2679
+ .make_fill_array_from_shape::<T>(resolved.result_elements, &resolved.result_shape);
2680
+ }
2681
+
2682
+ let ndim = self.ndim();
2683
+ let shape = &self.dataspace.dims;
2684
+ let elem_size = self.raw_element_size()?;
2685
+ let chunk_shape: Vec<u64> = chunk_dims.iter().map(|&d| d as u64).collect();
2686
+ validate_chunk_shape(shape, &chunk_shape)?;
2687
+ let mut first_chunk = vec![0u64; ndim];
2688
+ let mut last_chunk = vec![0u64; ndim];
2689
+ for d in 0..ndim {
2690
+ let (first, last) = resolved.dims[d]
2691
+ .chunk_index_range(chunk_shape[d])
2692
+ .expect("zero-sized result handled above");
2693
+ first_chunk[d] = first;
2694
+ last_chunk[d] = last;
2695
+ }
2696
+
2697
+ // Collect all chunk entries.
2698
+ let mut overlapping = self.collect_chunk_entries(
2699
+ index_address,
2700
+ chunk_dims,
2701
+ chunk_indexing,
2702
+ ChunkEntrySelection {
2703
+ shape,
2704
+ ndim,
2705
+ elem_size,
2706
+ chunk_bounds: Some((&first_chunk, &last_chunk)),
2707
+ },
2708
+ )?;
2709
+ let fully_covered_grid = validate_chunk_grid_coverage(
2710
+ &mut overlapping,
2711
+ shape,
2712
+ &chunk_shape,
2713
+ &first_chunk,
2714
+ &last_chunk,
2715
+ )?;
2716
+
2717
+ // Allocate result buffer (raw bytes) initialized from fill value.
2718
+ let result_total_bytes = checked_mul_usize(
2719
+ resolved.result_elements,
2720
+ elem_size,
2721
+ "slice result size in bytes",
2722
+ )?;
2723
+ // Compute result strides (including collapsed dims — they have count=1).
2724
+ let result_dims = resolved.result_dims_with_collapsed();
2725
+ let mut result_strides = vec![1usize; ndim];
2726
+ for d in (0..ndim.saturating_sub(1)).rev() {
2727
+ result_strides[d] =
2728
+ checked_mul_usize(result_strides[d + 1], result_dims[d + 1], "result stride")?;
2729
+ }
2730
+ let mut chunk_strides = vec![1usize; ndim];
2731
+ for d in (0..ndim.saturating_sub(1)).rev() {
2732
+ chunk_strides[d] = checked_mul_usize(
2733
+ chunk_strides[d + 1],
2734
+ chunk_shape[d + 1] as usize,
2735
+ "chunk stride",
2736
+ )?;
2737
+ }
2738
+ let use_unit_stride_fast_path = resolved.is_unit_stride();
2739
+ let fully_covered_unit_stride = use_unit_stride_fast_path && fully_covered_grid;
2740
+
2741
+ if fully_covered_unit_stride {
2742
+ if T::native_copy_compatible(&self.datatype) && std::mem::size_of::<T>() == elem_size {
2743
+ let mut result_values: Vec<MaybeUninit<T>> =
2744
+ try_uninit_vec::<T>(resolved.result_elements)?;
2745
+ let flat = FlatBufferPtr {
2746
+ ptr: result_values.as_mut_ptr() as *mut u8,
2747
+ len: checked_mul_usize(
2748
+ result_values.len(),
2749
+ std::mem::size_of::<T>(),
2750
+ "typed slice result size in bytes",
2751
+ )?,
2752
+ };
2753
+
2754
+ overlapping
2755
+ .par_iter()
2756
+ .map(|entry| {
2757
+ let chunk_data = self.load_exact_chunk_data(
2758
+ entry,
2759
+ index_address,
2760
+ &chunk_shape,
2761
+ elem_size,
2762
+ )?;
2763
+
2764
+ // SAFETY: validated chunk offsets are unique, so
2765
+ // parallel overlap copies write disjoint ranges;
2766
+ // `result_values` remains live through collect.
2767
+ unsafe {
2768
+ flat.copy_unit_stride_chunk_overlap(
2769
+ &chunk_data,
2770
+ UnitStrideCopyLayout {
2771
+ chunk_offsets: &entry.offsets,
2772
+ chunk_shape: &chunk_shape,
2773
+ dataset_shape: shape,
2774
+ resolved,
2775
+ chunk_strides: &chunk_strides,
2776
+ result_strides: &result_strides,
2777
+ elem_size,
2778
+ },
2779
+ )?;
2780
+ }
2781
+
2782
+ Ok(())
2783
+ })
2784
+ .collect::<std::result::Result<Vec<_>, Error>>()?;
2785
+
2786
+ // SAFETY: the fully-covered selection gate proves that all
2787
+ // successful parallel copies initialized the result.
2788
+ let result_values = unsafe { assume_init_vec(result_values) };
2789
+ return ArrayD::from_shape_vec(IxDyn(&resolved.result_shape), result_values)
2790
+ .map_err(|e| Error::InvalidData(format!("array shape error: {e}")));
2791
+ }
2792
+
2793
+ let mut result_buf = try_uninit_vec::<u8>(result_total_bytes)?;
2794
+ let flat = FlatBufferPtr {
2795
+ ptr: result_buf.as_mut_ptr() as *mut u8,
2796
+ len: result_buf.len(),
2797
+ };
2798
+
2799
+ overlapping
2800
+ .par_iter()
2801
+ .map(|entry| {
2802
+ let chunk_data =
2803
+ self.load_exact_chunk_data(entry, index_address, &chunk_shape, elem_size)?;
2804
+
2805
+ // SAFETY: validated chunk offsets are unique, so parallel
2806
+ // overlap copies write disjoint ranges; `result_buf`
2807
+ // remains live through collect.
2808
+ unsafe {
2809
+ flat.copy_unit_stride_chunk_overlap(
2810
+ &chunk_data,
2811
+ UnitStrideCopyLayout {
2812
+ chunk_offsets: &entry.offsets,
2813
+ chunk_shape: &chunk_shape,
2814
+ dataset_shape: shape,
2815
+ resolved,
2816
+ chunk_strides: &chunk_strides,
2817
+ result_strides: &result_strides,
2818
+ elem_size,
2819
+ },
2820
+ )?;
2821
+ }
2822
+
2823
+ Ok(())
2824
+ })
2825
+ .collect::<std::result::Result<Vec<_>, Error>>()?;
2826
+
2827
+ // SAFETY: the fully-covered selection gate proves that all
2828
+ // successful parallel copies initialized every result byte.
2829
+ let result_buf = unsafe { assume_init_u8_vec(result_buf) };
2830
+ return self.decode_buffer_with_shape::<T>(
2831
+ &result_buf,
2832
+ resolved.result_elements,
2833
+ &resolved.result_shape,
2834
+ );
2835
+ }
2836
+
2837
+ let mut result_buf = self.make_output_buffer(result_total_bytes)?;
2838
+
2839
+ let flat = FlatBufferPtr {
2840
+ ptr: result_buf.as_mut_ptr(),
2841
+ len: result_buf.len(),
2842
+ };
2843
+
2844
+ overlapping
2845
+ .par_iter()
2846
+ .map(|entry| {
2847
+ let chunk_data =
2848
+ self.load_exact_chunk_data(entry, index_address, &chunk_shape, elem_size)?;
2849
+
2850
+ if use_unit_stride_fast_path {
2851
+ // SAFETY: validated chunk offsets are unique, so parallel
2852
+ // overlap copies write disjoint ranges; `result_buf`
2853
+ // remains live through collect.
2854
+ unsafe {
2855
+ flat.copy_unit_stride_chunk_overlap(
2856
+ &chunk_data,
2857
+ UnitStrideCopyLayout {
2858
+ chunk_offsets: &entry.offsets,
2859
+ chunk_shape: &chunk_shape,
2860
+ dataset_shape: shape,
2861
+ resolved,
2862
+ chunk_strides: &chunk_strides,
2863
+ result_strides: &result_strides,
2864
+ elem_size,
2865
+ },
2866
+ )?;
2867
+ }
2868
+ return Ok(());
2869
+ }
2870
+
2871
+ // For each dimension, compute which elements within this chunk fall
2872
+ // within the selection.
2873
+ let mut dim_indices: Vec<Vec<(usize, usize)>> = Vec::with_capacity(ndim);
2874
+ for d in 0..ndim {
2875
+ let chunk_start = entry.offsets[d];
2876
+ let chunk_end = (chunk_start + chunk_shape[d]).min(shape[d]);
2877
+ let dim = &resolved.dims[d];
2878
+ let sel_start = dim.start;
2879
+ let sel_end = dim.end;
2880
+ let sel_step = dim.step;
2881
+ let mut indices = Vec::new();
2882
+
2883
+ let first_sel = if sel_start >= chunk_start {
2884
+ sel_start
2885
+ } else {
2886
+ let steps_to_skip = (chunk_start - sel_start).div_ceil(sel_step);
2887
+ sel_start + steps_to_skip * sel_step
2888
+ };
2889
+
2890
+ let mut sel_idx = first_sel;
2891
+ while sel_idx < sel_end && sel_idx < chunk_end {
2892
+ let chunk_local =
2893
+ checked_usize(sel_idx - chunk_start, "chunk-local index")?;
2894
+ let result_dim_idx =
2895
+ checked_usize((sel_idx - dim.start) / sel_step, "result index")?;
2896
+ indices.push((chunk_local, result_dim_idx));
2897
+ sel_idx += sel_step;
2898
+ }
2899
+
2900
+ dim_indices.push(indices);
2901
+ }
2902
+
2903
+ // SAFETY: each chunk writes to disjoint output positions because
2904
+ // chunks occupy non-overlapping regions of the dataset grid and
2905
+ // the selection maps each dataset coordinate to a unique result index.
2906
+ unsafe {
2907
+ flat.copy_selected(
2908
+ &chunk_data,
2909
+ &dim_indices,
2910
+ &chunk_strides,
2911
+ &result_strides,
2912
+ elem_size,
2913
+ ndim,
2914
+ )?;
2915
+ }
2916
+
2917
+ Ok(())
2918
+ })
2919
+ .collect::<std::result::Result<Vec<_>, Error>>()?;
2920
+
2921
+ self.decode_buffer_with_shape::<T>(
2922
+ &result_buf,
2923
+ resolved.result_elements,
2924
+ &resolved.result_shape,
2925
+ )
2926
+ }
2927
+
2928
+ fn read_contiguous_slice<T: H5Type>(
2929
+ &self,
2930
+ address: u64,
2931
+ size: u64,
2932
+ resolved: &ResolvedSelection,
2933
+ ) -> Result<ArrayD<T>> {
2934
+ if resolved.result_elements == 0 {
2935
+ return self.make_fill_array_from_shape::<T>(0, &resolved.result_shape);
2936
+ }
2937
+
2938
+ if self.external_files.is_none()
2939
+ && (Cursor::is_undefined_offset(address, self.offset_size()) || size == 0)
2940
+ {
2941
+ return self
2942
+ .make_fill_array_from_shape::<T>(resolved.result_elements, &resolved.result_shape);
2943
+ }
2944
+ if self.external_files.is_none() {
2945
+ self.validate_allocated_raw_data_len(
2946
+ "contiguous",
2947
+ checked_usize(size, "contiguous dataset size")?,
2948
+ )?;
2949
+ }
2950
+
2951
+ let shape = &self.dataspace.dims;
2952
+ if selection_covers_full_dataset(resolved, shape) {
2953
+ return self.read_contiguous::<T>(address, size);
2954
+ }
2955
+
2956
+ let elem_size = self.raw_element_size()?;
2957
+ let result_total_bytes = checked_mul_usize(
2958
+ resolved.result_elements,
2959
+ elem_size,
2960
+ "contiguous slice result size in bytes",
2961
+ )?;
2962
+ let dataset_strides = row_major_strides(shape, "contiguous dataset stride")?;
2963
+ let result_dims = resolved.result_dims_with_collapsed();
2964
+ let result_strides = result_strides_for_dims(&result_dims)?;
2965
+ let result_buf = self.read_contiguous_slice_bytes_direct(
2966
+ address,
2967
+ size,
2968
+ resolved,
2969
+ ContiguousSliceDirectLayout {
2970
+ dataset_strides: &dataset_strides,
2971
+ result_strides: &result_strides,
2972
+ elem_size,
2973
+ result_total_bytes,
2974
+ },
2975
+ )?;
2976
+
2977
+ self.decode_buffer_with_shape::<T>(
2978
+ &result_buf,
2979
+ resolved.result_elements,
2980
+ &resolved.result_shape,
2981
+ )
2982
+ }
2983
+
2984
+ fn read_contiguous_slice_bytes_direct(
2985
+ &self,
2986
+ address: u64,
2987
+ size: u64,
2988
+ resolved: &ResolvedSelection,
2989
+ layout: ContiguousSliceDirectLayout<'_>,
2990
+ ) -> Result<Vec<u8>> {
2991
+ let shape = &self.dataspace.dims;
2992
+ let ndim = shape.len();
2993
+ if resolved.dims.len() != ndim
2994
+ || layout.dataset_strides.len() != ndim
2995
+ || layout.result_strides.len() != ndim
2996
+ {
2997
+ return Err(Error::InvalidData(format!(
2998
+ "contiguous slice layout rank does not match dataset rank {ndim}"
2999
+ )));
3000
+ }
3001
+
3002
+ let storage_len = if self.external_files.is_some() {
3003
+ checked_mul_usize(
3004
+ checked_usize(self.num_elements()?, "dataset element count")?,
3005
+ layout.elem_size,
3006
+ "external dataset size",
3007
+ )?
3008
+ } else {
3009
+ checked_usize(size, "contiguous dataset size")?
3010
+ };
3011
+ let tail_start = contiguous_slice_tail_start(shape, resolved);
3012
+ let block_elements = contiguous_slice_block_elements(resolved, tail_start)?;
3013
+ let block_bytes = checked_mul_usize(
3014
+ block_elements,
3015
+ layout.elem_size,
3016
+ "contiguous slice block size in bytes",
3017
+ )?;
3018
+ let mut result_buf = self.make_output_buffer(layout.result_total_bytes)?;
3019
+
3020
+ let prefix_blocks =
3021
+ resolved.dims[..tail_start]
3022
+ .iter()
3023
+ .try_fold(1usize, |acc, dim| -> Result<usize> {
3024
+ checked_mul_usize(acc, dim.count, "contiguous slice block count")
3025
+ })?;
3026
+ let mut counters = vec![0usize; tail_start];
3027
+
3028
+ for _ in 0..prefix_blocks {
3029
+ let mut source_elem = 0usize;
3030
+ let mut result_elem = 0usize;
3031
+
3032
+ for (d, &counter) in counters.iter().enumerate().take(tail_start) {
3033
+ let ordinal = u64::try_from(counter).map_err(|_| {
3034
+ Error::InvalidData("contiguous slice ordinal exceeds u64".to_string())
3035
+ })?;
3036
+ let coord = checked_add_u64(
3037
+ resolved.dims[d].start,
3038
+ checked_mul_u64(
3039
+ ordinal,
3040
+ resolved.dims[d].step,
3041
+ "contiguous slice coordinate",
3042
+ )?,
3043
+ "contiguous slice coordinate",
3044
+ )?;
3045
+ let coord = checked_usize(coord, "contiguous slice source index")?;
3046
+ let source_term =
3047
+ checked_mul_usize(coord, layout.dataset_strides[d], "contiguous slice source")?;
3048
+ let result_term = checked_mul_usize(
3049
+ counter,
3050
+ layout.result_strides[d],
3051
+ "contiguous slice result",
3052
+ )?;
3053
+ source_elem =
3054
+ checked_add_usize(source_elem, source_term, "contiguous slice source")?;
3055
+ result_elem =
3056
+ checked_add_usize(result_elem, result_term, "contiguous slice result")?;
3057
+ }
3058
+
3059
+ for (d, &dataset_stride) in layout
3060
+ .dataset_strides
3061
+ .iter()
3062
+ .enumerate()
3063
+ .take(ndim)
3064
+ .skip(tail_start)
3065
+ {
3066
+ let coord = checked_usize(resolved.dims[d].start, "contiguous slice source index")?;
3067
+ let source_term =
3068
+ checked_mul_usize(coord, dataset_stride, "contiguous slice source")?;
3069
+ source_elem =
3070
+ checked_add_usize(source_elem, source_term, "contiguous slice source")?;
3071
+ }
3072
+
3073
+ let source_start = checked_mul_usize(
3074
+ source_elem,
3075
+ layout.elem_size,
3076
+ "contiguous slice source byte offset",
3077
+ )?;
3078
+ let source_end = checked_add_usize(
3079
+ source_start,
3080
+ block_bytes,
3081
+ "contiguous slice source byte end",
3082
+ )?;
3083
+ if source_end > storage_len {
3084
+ return Err(Error::InvalidData(format!(
3085
+ "contiguous slice range {}..{} exceeds dataset storage size {}",
3086
+ source_start, source_end, storage_len
3087
+ )));
3088
+ }
3089
+
3090
+ let dst_start = checked_mul_usize(
3091
+ result_elem,
3092
+ layout.elem_size,
3093
+ "contiguous slice destination byte offset",
3094
+ )?;
3095
+ let dst_end = checked_add_usize(
3096
+ dst_start,
3097
+ block_bytes,
3098
+ "contiguous slice destination byte end",
3099
+ )?;
3100
+ if dst_end > result_buf.len() {
3101
+ return Err(Error::InvalidData(format!(
3102
+ "contiguous slice destination range {}..{} exceeds result size {}",
3103
+ dst_start,
3104
+ dst_end,
3105
+ result_buf.len()
3106
+ )));
3107
+ }
3108
+
3109
+ let block = self.read_contiguous_logical_range(address, source_start, block_bytes)?;
3110
+ if block.len() != block_bytes {
3111
+ return Err(Error::InvalidData(format!(
3112
+ "contiguous slice read returned {} bytes, expected {}",
3113
+ block.len(),
3114
+ block_bytes
3115
+ )));
3116
+ }
3117
+ result_buf[dst_start..dst_end].copy_from_slice(&block);
3118
+
3119
+ let mut carry = true;
3120
+ for d in (0..tail_start).rev() {
3121
+ if carry {
3122
+ counters[d] += 1;
3123
+ if counters[d] < resolved.dims[d].count {
3124
+ carry = false;
3125
+ } else {
3126
+ counters[d] = 0;
3127
+ }
3128
+ }
3129
+ }
3130
+ }
3131
+
3132
+ Ok(result_buf)
3133
+ }
3134
+
3135
+ fn read_compact_slice<T: H5Type>(
3136
+ &self,
3137
+ data: &[u8],
3138
+ selection: &SliceInfo,
3139
+ ) -> Result<ArrayD<T>> {
3140
+ let full = self.read_compact::<T>(data)?;
3141
+ slice_array(&full, selection, &self.dataspace.dims)
3142
+ }
3143
+
3144
+ fn decode_buffer_with_shape<T: H5Type>(
3145
+ &self,
3146
+ raw: &[u8],
3147
+ n: usize,
3148
+ shape: &[usize],
3149
+ ) -> Result<ArrayD<T>> {
3150
+ let elem_size = self.raw_element_size()?;
3151
+ let expected_bytes = checked_mul_usize(n, elem_size, "decoded buffer byte length")?;
3152
+ if raw.len() != expected_bytes {
3153
+ return Err(Error::InvalidData(format!(
3154
+ "decoded buffer has {} bytes, expected {} bytes",
3155
+ raw.len(),
3156
+ expected_bytes
3157
+ )));
3158
+ }
3159
+
3160
+ if let Some(elements) = T::decode_vec(raw, &self.datatype, n) {
3161
+ let elements = elements?;
3162
+ return ArrayD::from_shape_vec(IxDyn(shape), elements)
3163
+ .map_err(|e| Error::InvalidData(format!("array shape error: {e}")));
3164
+ }
3165
+
3166
+ let mut elements = Vec::with_capacity(n);
3167
+ for i in 0..n {
3168
+ let start = checked_mul_usize(i, elem_size, "decoded element byte offset")?;
3169
+ let end = checked_mul_usize(i + 1, elem_size, "decoded element end offset")?;
3170
+ elements.push(T::from_bytes(&raw[start..end], &self.datatype)?);
3171
+ }
3172
+
3173
+ ArrayD::from_shape_vec(IxDyn(shape), elements)
3174
+ .map_err(|e| Error::InvalidData(format!("array shape error: {e}")))
3175
+ }
3176
+
3177
+ fn decode_raw_data<T: H5Type>(&self, raw: &[u8]) -> Result<ArrayD<T>> {
3178
+ let n = checked_usize(self.num_elements()?, "dataset element count")?;
3179
+ let mut shape = Vec::with_capacity(self.dataspace.dims.len());
3180
+ for &dim in &self.dataspace.dims {
3181
+ shape.push(checked_usize(dim, "dataset dimension")?);
3182
+ }
3183
+ self.decode_buffer_with_shape::<T>(raw, n, &shape)
3184
+ }
3185
+
3186
+ fn make_fill_array<T: H5Type>(&self) -> Result<ArrayD<T>> {
3187
+ let n = checked_usize(self.num_elements()?, "dataset element count")?;
3188
+ let mut shape = Vec::with_capacity(self.dataspace.dims.len());
3189
+ for &dim in &self.dataspace.dims {
3190
+ shape.push(checked_usize(dim, "dataset dimension")?);
3191
+ }
3192
+ self.make_fill_array_from_shape::<T>(n, &shape)
3193
+ }
3194
+
3195
+ fn make_fill_array_from_shape<T: H5Type>(
3196
+ &self,
3197
+ element_count: usize,
3198
+ shape: &[usize],
3199
+ ) -> Result<ArrayD<T>> {
3200
+ let elem_size = self.raw_element_size()?;
3201
+ let total_bytes = checked_mul_usize(element_count, elem_size, "fill result size in bytes")?;
3202
+ let fill = self.make_output_buffer(total_bytes)?;
3203
+ self.decode_buffer_with_shape::<T>(&fill, element_count, shape)
3204
+ }
3205
+
3206
+ fn make_output_buffer(&self, total_bytes: usize) -> Result<Vec<u8>> {
3207
+ let mut buf = try_zeroed_bytes(total_bytes)?;
3208
+ self.fill_output_buffer(&mut buf);
3209
+ Ok(buf)
3210
+ }
3211
+
3212
+ fn fill_output_buffer(&self, buf: &mut [u8]) {
3213
+ buf.fill(0);
3214
+ if let Some(ref fv) = self.fill_value {
3215
+ if let Some(ref fill_bytes) = fv.value {
3216
+ if !fill_bytes.is_empty() {
3217
+ for chunk in buf.chunks_exact_mut(fill_bytes.len()) {
3218
+ chunk.copy_from_slice(fill_bytes);
3219
+ }
3220
+ }
3221
+ }
3222
+ }
3223
+ }
3224
+
3225
+ fn validate_allocated_raw_data_len(&self, storage_kind: &str, actual_len: usize) -> Result<()> {
3226
+ let expected_len = self.raw_byte_len()?;
3227
+ if actual_len != expected_len {
3228
+ return Err(Error::InvalidData(format!(
3229
+ "{storage_kind} raw data has {actual_len} bytes, expected {expected_len} bytes"
3230
+ )));
3231
+ }
3232
+ Ok(())
3233
+ }
3234
+
3235
+ fn convert_to_native_endian(&self, bytes: &mut [u8]) -> Result<()> {
3236
+ let count = checked_usize(self.num_elements()?, "dataset element count")?;
3237
+ convert_datatype_to_native_endian(&self.datatype, self.vlen_reference_size(), bytes, count)
3238
+ }
3239
+ }
3240
+
3241
+ fn native_byte_order() -> ByteOrder {
3242
+ if cfg!(target_endian = "little") {
3243
+ ByteOrder::LittleEndian
3244
+ } else {
3245
+ ByteOrder::BigEndian
3246
+ }
3247
+ }
3248
+
3249
+ fn convert_datatype_to_native_endian(
3250
+ dtype: &Datatype,
3251
+ vlen_reference_size: usize,
3252
+ bytes: &mut [u8],
3253
+ count: usize,
3254
+ ) -> Result<()> {
3255
+ match dtype {
3256
+ Datatype::FixedPoint {
3257
+ size, byte_order, ..
3258
+ }
3259
+ | Datatype::FloatingPoint { size, byte_order }
3260
+ | Datatype::Bitfield { size, byte_order } => {
3261
+ swap_elements_to_native(bytes, count, *size as usize, *byte_order)
3262
+ }
3263
+ Datatype::Enum { base, .. } => {
3264
+ convert_datatype_to_native_endian(base, vlen_reference_size, bytes, count)
3265
+ }
3266
+ Datatype::Array { base, dims } => {
3267
+ let array_count = dims.iter().try_fold(1usize, |acc, &dim| {
3268
+ checked_mul_usize(
3269
+ acc,
3270
+ checked_usize(dim, "array datatype dimension")?,
3271
+ "array datatype element count",
3272
+ )
3273
+ })?;
3274
+ let total_count =
3275
+ checked_mul_usize(count, array_count, "array datatype total element count")?;
3276
+ convert_datatype_to_native_endian(base, vlen_reference_size, bytes, total_count)
3277
+ }
3278
+ Datatype::Compound { size, fields } => {
3279
+ let record_size = *size as usize;
3280
+ let required = checked_mul_usize(count, record_size, "compound byte length")?;
3281
+ if bytes.len() < required {
3282
+ return Err(Error::InvalidData(format!(
3283
+ "compound native-endian conversion needs {required} bytes, got {}",
3284
+ bytes.len()
3285
+ )));
3286
+ }
3287
+
3288
+ for record in 0..count {
3289
+ let record_start =
3290
+ checked_mul_usize(record, record_size, "compound record byte offset")?;
3291
+ for field in fields {
3292
+ let field_offset = field.byte_offset as usize;
3293
+ let field_size =
3294
+ raw_element_size_for_datatype(&field.datatype, vlen_reference_size)?;
3295
+ let field_start = checked_add_usize(
3296
+ record_start,
3297
+ field_offset,
3298
+ "compound field byte offset",
3299
+ )?;
3300
+ let field_end =
3301
+ checked_add_usize(field_start, field_size, "compound field byte end")?;
3302
+ if field_end > bytes.len() || field_offset + field_size > record_size {
3303
+ return Err(Error::InvalidData(format!(
3304
+ "compound field '{}' range exceeds record size",
3305
+ field.name
3306
+ )));
3307
+ }
3308
+ convert_datatype_to_native_endian(
3309
+ &field.datatype,
3310
+ vlen_reference_size,
3311
+ &mut bytes[field_start..field_end],
3312
+ 1,
3313
+ )?;
3314
+ }
3315
+ }
3316
+ Ok(())
3317
+ }
3318
+ Datatype::String { .. }
3319
+ | Datatype::VarLen { .. }
3320
+ | Datatype::Opaque { .. }
3321
+ | Datatype::Reference { .. } => Ok(()),
3322
+ }
3323
+ }
3324
+
3325
+ fn swap_elements_to_native(
3326
+ bytes: &mut [u8],
3327
+ count: usize,
3328
+ elem_size: usize,
3329
+ byte_order: ByteOrder,
3330
+ ) -> Result<()> {
3331
+ let required = checked_mul_usize(count, elem_size, "native-endian byte length")?;
3332
+ if bytes.len() < required {
3333
+ return Err(Error::InvalidData(format!(
3334
+ "native-endian conversion needs {required} bytes, got {}",
3335
+ bytes.len()
3336
+ )));
3337
+ }
3338
+
3339
+ if elem_size <= 1 || byte_order == native_byte_order() {
3340
+ return Ok(());
3341
+ }
3342
+
3343
+ for chunk in bytes[..required].chunks_exact_mut(elem_size) {
3344
+ chunk.reverse();
3345
+ }
3346
+ Ok(())
3347
+ }
3348
+
3349
+ fn attribute_from_message_storage(message: &AttributeMessage, context: &FileContext) -> Attribute {
3350
+ let decoded_strings = message
3351
+ .dataspace
3352
+ .num_elements()
3353
+ .ok()
3354
+ .and_then(|element_count| {
3355
+ decoded_vlen_strings_storage(
3356
+ &message.datatype,
3357
+ &message.raw_data,
3358
+ context.storage.as_ref(),
3359
+ context.superblock.offset_size,
3360
+ context.superblock.length_size,
3361
+ element_count,
3362
+ )
3363
+ });
3364
+ let raw_data = match &message.datatype {
3365
+ Datatype::VarLen {
3366
+ base,
3367
+ kind: VarLenKind::String,
3368
+ ..
3369
+ } if base.is_vlen_string_base() && matches!(message.dataspace.num_elements(), Ok(1)) => {
3370
+ resolve_vlen_bytes_storage(
3371
+ &message.raw_data,
3372
+ context.storage.as_ref(),
3373
+ context.superblock.offset_size,
3374
+ context.superblock.length_size,
3375
+ )
3376
+ .unwrap_or_else(|| message.raw_data.clone())
3377
+ }
3378
+ _ => message.raw_data.clone(),
3379
+ };
3380
+
3381
+ Attribute {
3382
+ name: message.name.clone(),
3383
+ datatype: message.datatype.clone(),
3384
+ shape: match message.dataspace.dataspace_type {
3385
+ DataspaceType::Scalar => vec![],
3386
+ DataspaceType::Null => vec![0],
3387
+ DataspaceType::Simple => message.dataspace.dims.clone(),
3388
+ },
3389
+ raw_data,
3390
+ decoded_strings,
3391
+ }
3392
+ }
3393
+
3394
+ fn normalize_layout(layout: DataLayout, dataspace: &DataspaceMessage) -> DataLayout {
3395
+ match layout {
3396
+ DataLayout::Chunked {
3397
+ address,
3398
+ mut dims,
3399
+ mut element_size,
3400
+ chunk_indexing,
3401
+ } if dims.len() == dataspace.dims.len() + 1 => {
3402
+ if let Some(legacy_element_size) = dims.pop() {
3403
+ if element_size == 0 {
3404
+ element_size = legacy_element_size;
3405
+ }
3406
+ }
3407
+ DataLayout::Chunked {
3408
+ address,
3409
+ dims,
3410
+ element_size,
3411
+ chunk_indexing,
3412
+ }
3413
+ }
3414
+ other => other,
3415
+ }
3416
+ }
3417
+
3418
+ fn raw_element_size_for_datatype(dtype: &Datatype, vlen_reference_size: usize) -> Result<usize> {
3419
+ match dtype {
3420
+ Datatype::String {
3421
+ size: StringSize::Variable,
3422
+ ..
3423
+ }
3424
+ | Datatype::VarLen { .. } => Ok(vlen_reference_size),
3425
+ Datatype::Array { base, dims } => {
3426
+ let base_size = raw_element_size_for_datatype(base, vlen_reference_size)?;
3427
+ let count = dims.iter().try_fold(1usize, |acc, &dim| {
3428
+ let dim = checked_usize(dim, "array datatype dimension")?;
3429
+ checked_mul_usize(acc, dim, "array datatype element count")
3430
+ })?;
3431
+ checked_mul_usize(base_size, count, "array datatype byte size")
3432
+ }
3433
+ Datatype::Enum { base, .. } => raw_element_size_for_datatype(base, vlen_reference_size),
3434
+ Datatype::FixedPoint { size, .. }
3435
+ | Datatype::FloatingPoint { size, .. }
3436
+ | Datatype::Bitfield { size, .. }
3437
+ | Datatype::Reference { size, .. } => Ok(*size as usize),
3438
+ Datatype::String {
3439
+ size: StringSize::Fixed(len),
3440
+ ..
3441
+ } => Ok(*len as usize),
3442
+ Datatype::Compound { size, .. } | Datatype::Opaque { size, .. } => Ok(*size as usize),
3443
+ }
3444
+ }
3445
+
3446
+ #[cfg(test)]
3447
+ /// Copy a chunk's data into the flat output buffer at the correct position.
3448
+ fn copy_chunk_to_flat(
3449
+ chunk_data: &[u8],
3450
+ flat: &mut [u8],
3451
+ chunk_offsets: &[u64],
3452
+ chunk_shape: &[u64],
3453
+ dataset_shape: &[u64],
3454
+ elem_size: usize,
3455
+ ) -> Result<()> {
3456
+ let dataset_strides = row_major_strides(dataset_shape, "dataset stride")
3457
+ .expect("dataset strides should fit in usize");
3458
+ let chunk_strides =
3459
+ row_major_strides(chunk_shape, "chunk stride").expect("chunk strides should fit in usize");
3460
+ copy_chunk_to_flat_with_strides(
3461
+ chunk_data,
3462
+ flat,
3463
+ ChunkCopyLayout {
3464
+ chunk_offsets,
3465
+ chunk_shape,
3466
+ dataset_shape,
3467
+ dataset_strides: &dataset_strides,
3468
+ chunk_strides: &chunk_strides,
3469
+ elem_size,
3470
+ },
3471
+ )
3472
+ }
3473
+
3474
+ fn copy_chunk_to_flat_with_strides(
3475
+ chunk_data: &[u8],
3476
+ flat: &mut [u8],
3477
+ layout: ChunkCopyLayout<'_>,
3478
+ ) -> Result<()> {
3479
+ // SAFETY: the mutable slice supplies a live, exclusively borrowed output
3480
+ // allocation, and the pointer helper checks every source and destination
3481
+ // range.
3482
+ unsafe {
3483
+ copy_chunk_to_flat_with_strides_ptr(
3484
+ chunk_data,
3485
+ FlatBufferPtr {
3486
+ ptr: flat.as_mut_ptr(),
3487
+ len: flat.len(),
3488
+ },
3489
+ layout,
3490
+ )
3491
+ }
3492
+ }
3493
+
3494
+ #[inline(always)]
3495
+ unsafe fn copy_chunk_to_flat_with_strides_ptr(
3496
+ chunk_data: &[u8],
3497
+ flat: FlatBufferPtr,
3498
+ layout: ChunkCopyLayout<'_>,
3499
+ ) -> Result<()> {
3500
+ let ndim = layout.dataset_shape.len();
3501
+ if layout.chunk_offsets.len() != ndim
3502
+ || layout.chunk_shape.len() != ndim
3503
+ || layout.dataset_strides.len() != ndim
3504
+ || layout.chunk_strides.len() != ndim
3505
+ {
3506
+ return Err(Error::InvalidData(format!(
3507
+ "chunk copy layout rank does not match dataset rank {ndim}"
3508
+ )));
3509
+ }
3510
+
3511
+ if ndim == 0 {
3512
+ if chunk_data.len() < layout.elem_size || flat.len < layout.elem_size {
3513
+ return Err(Error::InvalidData(format!(
3514
+ "scalar chunk copy requires {} bytes, got source {} and destination {}",
3515
+ layout.elem_size,
3516
+ chunk_data.len(),
3517
+ flat.len
3518
+ )));
3519
+ }
3520
+ // SAFETY: both ranges were checked immediately above, and the source
3521
+ // slice and caller-owned output allocation are distinct.
3522
+ unsafe {
3523
+ std::ptr::copy_nonoverlapping(chunk_data.as_ptr(), flat.ptr, layout.elem_size);
3524
+ }
3525
+ return Ok(());
3526
+ }
3527
+
3528
+ // Total elements in this chunk (clamped to dataset boundaries)
3529
+ let mut actual_chunk_shape = Vec::with_capacity(ndim);
3530
+ for i in 0..ndim {
3531
+ if layout.chunk_offsets[i] >= layout.dataset_shape[i] {
3532
+ return Err(Error::InvalidData(format!(
3533
+ "chunk offset {} is outside dimension {} of size {}",
3534
+ layout.chunk_offsets[i], i, layout.dataset_shape[i]
3535
+ )));
3536
+ }
3537
+ let remaining = layout.dataset_shape[i] - layout.chunk_offsets[i];
3538
+ actual_chunk_shape.push(checked_usize(
3539
+ remaining.min(layout.chunk_shape[i]),
3540
+ "actual chunk extent",
3541
+ )?);
3542
+ }
3543
+
3544
+ let row_elems = *actual_chunk_shape.last().unwrap_or(&1);
3545
+ let row_bytes = checked_mul_usize(row_elems, layout.elem_size, "chunk row bytes")?;
3546
+ let mut dataset_origin = 0usize;
3547
+ for (d, offset) in layout.chunk_offsets.iter().enumerate() {
3548
+ let offset = checked_usize(*offset, "chunk offset")?;
3549
+ let term = checked_mul_usize(offset, layout.dataset_strides[d], "chunk origin")?;
3550
+ dataset_origin = checked_add_usize(dataset_origin, term, "chunk origin")?;
3551
+ }
3552
+
3553
+ if ndim == 1 {
3554
+ let dst_start = checked_mul_usize(dataset_origin, layout.elem_size, "chunk dst offset")?;
3555
+ let dst_end = checked_add_usize(dst_start, row_bytes, "chunk dst end")?;
3556
+ if row_bytes > chunk_data.len() || dst_end > flat.len {
3557
+ return Err(Error::InvalidData(format!(
3558
+ "chunk copy out of bounds: source row needs {} bytes from {} bytes, destination range {}..{} exceeds {} bytes",
3559
+ row_bytes,
3560
+ chunk_data.len(),
3561
+ dst_start,
3562
+ dst_end,
3563
+ flat.len
3564
+ )));
3565
+ }
3566
+ // SAFETY: both ranges were checked immediately above, and the source
3567
+ // slice and caller-owned output allocation are distinct.
3568
+ unsafe {
3569
+ std::ptr::copy_nonoverlapping(chunk_data.as_ptr(), flat.ptr.add(dst_start), row_bytes);
3570
+ }
3571
+ return Ok(());
3572
+ }
3573
+
3574
+ let outer_dims = &actual_chunk_shape[..ndim - 1];
3575
+ let total_rows = checked_product_usize(outer_dims, "chunk row count")?;
3576
+ let mut outer_idx = vec![0usize; ndim - 1];
3577
+
3578
+ for _ in 0..total_rows {
3579
+ let mut chunk_row = 0usize;
3580
+ let mut dataset_row = dataset_origin;
3581
+ for (d, outer) in outer_idx.iter().copied().enumerate() {
3582
+ let chunk_term = checked_mul_usize(outer, layout.chunk_strides[d], "chunk row")?;
3583
+ let dataset_term = checked_mul_usize(outer, layout.dataset_strides[d], "dataset row")?;
3584
+ chunk_row = checked_add_usize(chunk_row, chunk_term, "chunk row")?;
3585
+ dataset_row = checked_add_usize(dataset_row, dataset_term, "dataset row")?;
3586
+ }
3587
+
3588
+ let src_start = checked_mul_usize(chunk_row, layout.elem_size, "chunk src offset")?;
3589
+ let dst_start = checked_mul_usize(dataset_row, layout.elem_size, "chunk dst offset")?;
3590
+ let src_end = checked_add_usize(src_start, row_bytes, "chunk src end")?;
3591
+ let dst_end = checked_add_usize(dst_start, row_bytes, "chunk dst end")?;
3592
+ if src_end > chunk_data.len() || dst_end > flat.len {
3593
+ return Err(Error::InvalidData(format!(
3594
+ "chunk copy out of bounds: source range {}..{} of {} bytes, destination range {}..{} of {} bytes",
3595
+ src_start,
3596
+ src_end,
3597
+ chunk_data.len(),
3598
+ dst_start,
3599
+ dst_end,
3600
+ flat.len
3601
+ )));
3602
+ }
3603
+ // SAFETY: both ranges were checked immediately above, and the source
3604
+ // slice and caller-owned output allocation are distinct.
3605
+ unsafe {
3606
+ std::ptr::copy_nonoverlapping(
3607
+ chunk_data.as_ptr().add(src_start),
3608
+ flat.ptr.add(dst_start),
3609
+ row_bytes,
3610
+ );
3611
+ }
3612
+
3613
+ let mut carry = true;
3614
+ for d in (0..outer_idx.len()).rev() {
3615
+ if carry {
3616
+ outer_idx[d] += 1;
3617
+ if outer_idx[d] < outer_dims[d] {
3618
+ carry = false;
3619
+ } else {
3620
+ outer_idx[d] = 0;
3621
+ }
3622
+ }
3623
+ }
3624
+ }
3625
+
3626
+ Ok(())
3627
+ }
3628
+
3629
+ fn checked_product_usize(values: &[usize], context: &str) -> Result<usize> {
3630
+ let mut product = 1usize;
3631
+ for &value in values {
3632
+ product = checked_mul_usize(product, value, context)?;
3633
+ }
3634
+ Ok(product)
3635
+ }
3636
+
3637
+ fn unit_stride_chunk_overlap_plan(
3638
+ chunk_offsets: &[u64],
3639
+ chunk_shape: &[u64],
3640
+ dataset_shape: &[u64],
3641
+ resolved: &ResolvedSelection,
3642
+ ) -> Result<(Vec<usize>, Vec<usize>, Vec<usize>)> {
3643
+ let ndim = dataset_shape.len();
3644
+ let mut overlap_counts = Vec::with_capacity(ndim);
3645
+ let mut chunk_local_start = Vec::with_capacity(ndim);
3646
+ let mut result_start = Vec::with_capacity(ndim);
3647
+
3648
+ for d in 0..ndim {
3649
+ let chunk_start = chunk_offsets[d];
3650
+ let chunk_end = (chunk_start + chunk_shape[d]).min(dataset_shape[d]);
3651
+ let dim = &resolved.dims[d];
3652
+ let overlap_start = chunk_start.max(dim.start);
3653
+ let overlap_end = chunk_end.min(dim.end);
3654
+ if overlap_start >= overlap_end {
3655
+ return Ok((Vec::new(), Vec::new(), Vec::new()));
3656
+ }
3657
+
3658
+ overlap_counts.push(checked_usize(
3659
+ overlap_end - overlap_start,
3660
+ "chunk overlap size",
3661
+ )?);
3662
+ chunk_local_start.push(checked_usize(
3663
+ overlap_start - chunk_start,
3664
+ "chunk overlap start",
3665
+ )?);
3666
+ result_start.push(checked_usize(
3667
+ overlap_start - dim.start,
3668
+ "slice result overlap start",
3669
+ )?);
3670
+ }
3671
+
3672
+ Ok((overlap_counts, chunk_local_start, result_start))
3673
+ }
3674
+
3675
+ #[inline(always)]
3676
+ fn copy_unit_stride_chunk_overlap(
3677
+ chunk_data: &[u8],
3678
+ result_buf: &mut [u8],
3679
+ layout: UnitStrideCopyLayout<'_>,
3680
+ ) -> Result<()> {
3681
+ // SAFETY: the mutable slice supplies a live, exclusively borrowed output
3682
+ // allocation, and the pointer helper checks every source and destination
3683
+ // range.
3684
+ unsafe {
3685
+ copy_unit_stride_chunk_overlap_ptr(
3686
+ chunk_data,
3687
+ FlatBufferPtr {
3688
+ ptr: result_buf.as_mut_ptr(),
3689
+ len: result_buf.len(),
3690
+ },
3691
+ layout,
3692
+ )
3693
+ }
3694
+ }
3695
+
3696
+ /// Copy a unit-step rectangular overlap from a chunk into the result buffer.
3697
+ ///
3698
+ /// This is the hot path for contiguous hyperslab reads over chunked datasets:
3699
+ /// rather than copying one element at a time, it copies contiguous runs along
3700
+ /// the innermost dimension with a single memcpy per output row.
3701
+ ///
3702
+ /// # Safety
3703
+ ///
3704
+ /// The caller must guarantee that `[result_ptr .. result_ptr + result_len)` is
3705
+ /// valid for writes. Concurrent callers must write to disjoint byte ranges.
3706
+ #[inline(always)]
3707
+ unsafe fn copy_unit_stride_chunk_overlap_ptr(
3708
+ chunk_data: &[u8],
3709
+ result: FlatBufferPtr,
3710
+ layout: UnitStrideCopyLayout<'_>,
3711
+ ) -> Result<()> {
3712
+ let ndim = layout.dataset_shape.len();
3713
+ if layout.chunk_offsets.len() != ndim
3714
+ || layout.chunk_shape.len() != ndim
3715
+ || layout.resolved.dims.len() != ndim
3716
+ || layout.chunk_strides.len() != ndim
3717
+ || layout.result_strides.len() != ndim
3718
+ {
3719
+ return Err(Error::InvalidData(format!(
3720
+ "unit-stride copy layout rank does not match dataset rank {ndim}"
3721
+ )));
3722
+ }
3723
+
3724
+ if ndim == 0 {
3725
+ if chunk_data.len() < layout.elem_size || result.len < layout.elem_size {
3726
+ return Err(Error::InvalidData(format!(
3727
+ "scalar slice copy requires {} bytes, got source {} and destination {}",
3728
+ layout.elem_size,
3729
+ chunk_data.len(),
3730
+ result.len
3731
+ )));
3732
+ }
3733
+ // SAFETY: both ranges were checked immediately above, and the source
3734
+ // slice and caller-owned output allocation are distinct.
3735
+ unsafe {
3736
+ std::ptr::copy_nonoverlapping(chunk_data.as_ptr(), result.ptr, layout.elem_size);
3737
+ }
3738
+ return Ok(());
3739
+ }
3740
+
3741
+ let (overlap_counts, chunk_local_start, result_start) = unit_stride_chunk_overlap_plan(
3742
+ layout.chunk_offsets,
3743
+ layout.chunk_shape,
3744
+ layout.dataset_shape,
3745
+ layout.resolved,
3746
+ )?;
3747
+ if overlap_counts.is_empty() {
3748
+ return Ok(());
3749
+ }
3750
+
3751
+ let row_elems = *overlap_counts.last().unwrap_or(&1);
3752
+ let row_bytes = checked_mul_usize(row_elems, layout.elem_size, "unit-stride slice row bytes")?;
3753
+
3754
+ let mut chunk_origin = 0usize;
3755
+ let mut result_origin = 0usize;
3756
+ for d in 0..ndim {
3757
+ let chunk_term = checked_mul_usize(
3758
+ chunk_local_start[d],
3759
+ layout.chunk_strides[d],
3760
+ "chunk overlap origin",
3761
+ )?;
3762
+ let result_term = checked_mul_usize(
3763
+ result_start[d],
3764
+ layout.result_strides[d],
3765
+ "slice result origin",
3766
+ )?;
3767
+ chunk_origin = checked_add_usize(chunk_origin, chunk_term, "chunk overlap origin")?;
3768
+ result_origin = checked_add_usize(result_origin, result_term, "slice result origin")?;
3769
+ }
3770
+
3771
+ if ndim == 1 {
3772
+ let src_start = checked_mul_usize(chunk_origin, layout.elem_size, "slice src offset")?;
3773
+ let dst_start = checked_mul_usize(result_origin, layout.elem_size, "slice dst offset")?;
3774
+ let src_end = checked_add_usize(src_start, row_bytes, "slice src end")?;
3775
+ let dst_end = checked_add_usize(dst_start, row_bytes, "slice dst end")?;
3776
+ if src_end > chunk_data.len() || dst_end > result.len {
3777
+ return Err(Error::InvalidData(format!(
3778
+ "unit-stride slice copy out of bounds: source range {}..{} of {} bytes, destination range {}..{} of {} bytes",
3779
+ src_start,
3780
+ src_end,
3781
+ chunk_data.len(),
3782
+ dst_start,
3783
+ dst_end,
3784
+ result.len
3785
+ )));
3786
+ }
3787
+ // SAFETY: both ranges were checked immediately above, and the source
3788
+ // slice and caller-owned output allocation are distinct.
3789
+ unsafe {
3790
+ std::ptr::copy_nonoverlapping(
3791
+ chunk_data.as_ptr().add(src_start),
3792
+ result.ptr.add(dst_start),
3793
+ row_bytes,
3794
+ );
3795
+ }
3796
+ return Ok(());
3797
+ }
3798
+
3799
+ let outer_counts = &overlap_counts[..ndim - 1];
3800
+ let total_rows = checked_product_usize(outer_counts, "unit-stride slice row count")?;
3801
+ let mut outer_idx = vec![0usize; ndim - 1];
3802
+
3803
+ for _ in 0..total_rows {
3804
+ let mut chunk_row = chunk_origin;
3805
+ let mut result_row = result_origin;
3806
+ for (d, outer) in outer_idx.iter().copied().enumerate() {
3807
+ let chunk_term = checked_mul_usize(outer, layout.chunk_strides[d], "slice chunk row")?;
3808
+ let result_term =
3809
+ checked_mul_usize(outer, layout.result_strides[d], "slice result row")?;
3810
+ chunk_row = checked_add_usize(chunk_row, chunk_term, "slice chunk row")?;
3811
+ result_row = checked_add_usize(result_row, result_term, "slice result row")?;
3812
+ }
3813
+
3814
+ let src_start = checked_mul_usize(chunk_row, layout.elem_size, "slice src offset")?;
3815
+ let dst_start = checked_mul_usize(result_row, layout.elem_size, "slice dst offset")?;
3816
+ let src_end = checked_add_usize(src_start, row_bytes, "slice src end")?;
3817
+ let dst_end = checked_add_usize(dst_start, row_bytes, "slice dst end")?;
3818
+ if src_end > chunk_data.len() || dst_end > result.len {
3819
+ return Err(Error::InvalidData(format!(
3820
+ "unit-stride slice copy out of bounds: source range {}..{} of {} bytes, destination range {}..{} of {} bytes",
3821
+ src_start,
3822
+ src_end,
3823
+ chunk_data.len(),
3824
+ dst_start,
3825
+ dst_end,
3826
+ result.len
3827
+ )));
3828
+ }
3829
+ // SAFETY: both ranges were checked immediately above, and the source
3830
+ // slice and caller-owned output allocation are distinct.
3831
+ unsafe {
3832
+ std::ptr::copy_nonoverlapping(
3833
+ chunk_data.as_ptr().add(src_start),
3834
+ result.ptr.add(dst_start),
3835
+ row_bytes,
3836
+ );
3837
+ }
3838
+
3839
+ let mut carry = true;
3840
+ for d in (0..outer_idx.len()).rev() {
3841
+ if carry {
3842
+ outer_idx[d] += 1;
3843
+ if outer_idx[d] < outer_counts[d] {
3844
+ carry = false;
3845
+ } else {
3846
+ outer_idx[d] = 0;
3847
+ }
3848
+ }
3849
+ }
3850
+ }
3851
+
3852
+ Ok(())
3853
+ }
3854
+
3855
+ #[allow(clippy::too_many_arguments)]
3856
+ /// Copy selected elements from a chunk into the result buffer.
3857
+ ///
3858
+ /// `dim_indices[d]` is a list of `(chunk_local_idx, result_dim_idx)` pairs for dimension `d`.
3859
+ #[inline(always)]
3860
+ fn copy_selected_elements(
3861
+ chunk_data: &[u8],
3862
+ result_buf: &mut [u8],
3863
+ dim_indices: &[Vec<(usize, usize)>],
3864
+ chunk_strides: &[usize],
3865
+ result_strides: &[usize],
3866
+ elem_size: usize,
3867
+ ndim: usize,
3868
+ ) -> Result<()> {
3869
+ if dim_indices.len() != ndim || chunk_strides.len() != ndim || result_strides.len() != ndim {
3870
+ return Err(Error::InvalidData(format!(
3871
+ "selected-element copy layout rank does not match rank {ndim}"
3872
+ )));
3873
+ }
3874
+
3875
+ // Check for empty selection
3876
+ if dim_indices.iter().any(|v| v.is_empty()) {
3877
+ return Ok(());
3878
+ }
3879
+
3880
+ // Recursive cartesian-product iteration, but unrolled iteratively.
3881
+ let counts: Vec<usize> = dim_indices.iter().map(|v| v.len()).collect();
3882
+ let total = checked_product_usize(&counts, "selected-element copy count")?;
3883
+ let mut counters = vec![0usize; ndim];
3884
+
3885
+ for _ in 0..total {
3886
+ let mut chunk_flat = 0;
3887
+ let mut result_flat = 0;
3888
+ for d in 0..ndim {
3889
+ let (cl, ri) = dim_indices[d][counters[d]];
3890
+ let chunk_term = checked_mul_usize(cl, chunk_strides[d], "selected chunk offset")?;
3891
+ let result_term = checked_mul_usize(ri, result_strides[d], "selected result offset")?;
3892
+ chunk_flat = checked_add_usize(chunk_flat, chunk_term, "selected chunk offset")?;
3893
+ result_flat = checked_add_usize(result_flat, result_term, "selected result offset")?;
3894
+ }
3895
+
3896
+ let src_start = checked_mul_usize(chunk_flat, elem_size, "selected source byte offset")?;
3897
+ let dst_start =
3898
+ checked_mul_usize(result_flat, elem_size, "selected destination byte offset")?;
3899
+ let src_end = checked_add_usize(src_start, elem_size, "selected source byte end")?;
3900
+ let dst_end = checked_add_usize(dst_start, elem_size, "selected destination byte end")?;
3901
+
3902
+ if src_end > chunk_data.len() || dst_end > result_buf.len() {
3903
+ return Err(Error::InvalidData(format!(
3904
+ "selected-element copy out of bounds: source range {}..{} of {} bytes, destination range {}..{} of {} bytes",
3905
+ src_start,
3906
+ src_end,
3907
+ chunk_data.len(),
3908
+ dst_start,
3909
+ dst_end,
3910
+ result_buf.len()
3911
+ )));
3912
+ }
3913
+ result_buf[dst_start..dst_end].copy_from_slice(&chunk_data[src_start..src_end]);
3914
+
3915
+ // Increment counters (row-major)
3916
+ let mut carry = true;
3917
+ for d in (0..ndim).rev() {
3918
+ if carry {
3919
+ counters[d] += 1;
3920
+ if counters[d] < dim_indices[d].len() {
3921
+ carry = false;
3922
+ } else {
3923
+ counters[d] = 0;
3924
+ }
3925
+ }
3926
+ }
3927
+ }
3928
+
3929
+ Ok(())
3930
+ }
3931
+
3932
+ /// Copy selected elements from a chunk into a raw output pointer.
3933
+ ///
3934
+ /// This is the pointer-based variant of `copy_selected_elements`, suitable for
3935
+ /// parallel use where multiple threads write to disjoint regions of the same buffer.
3936
+ ///
3937
+ /// # Safety
3938
+ ///
3939
+ /// The caller must guarantee that no two concurrent calls write to the same
3940
+ /// byte range within `[result_ptr .. result_ptr + result_len)`.
3941
+ #[cfg(feature = "rayon")]
3942
+ #[allow(clippy::too_many_arguments)]
3943
+ #[inline(always)]
3944
+ unsafe fn copy_selected_elements_ptr(
3945
+ chunk_data: &[u8],
3946
+ result_ptr: *mut u8,
3947
+ result_len: usize,
3948
+ dim_indices: &[Vec<(usize, usize)>],
3949
+ chunk_strides: &[usize],
3950
+ result_strides: &[usize],
3951
+ elem_size: usize,
3952
+ ndim: usize,
3953
+ ) -> Result<()> {
3954
+ if dim_indices.len() != ndim || chunk_strides.len() != ndim || result_strides.len() != ndim {
3955
+ return Err(Error::InvalidData(format!(
3956
+ "selected-element copy layout rank does not match rank {ndim}"
3957
+ )));
3958
+ }
3959
+
3960
+ if dim_indices.iter().any(|v| v.is_empty()) {
3961
+ return Ok(());
3962
+ }
3963
+
3964
+ let counts: Vec<usize> = dim_indices.iter().map(|v| v.len()).collect();
3965
+ let total = checked_product_usize(&counts, "selected-element copy count")?;
3966
+ let mut counters = vec![0usize; ndim];
3967
+
3968
+ for _ in 0..total {
3969
+ let mut chunk_flat = 0;
3970
+ let mut result_flat = 0;
3971
+ for d in 0..ndim {
3972
+ let (cl, ri) = dim_indices[d][counters[d]];
3973
+ let chunk_term = checked_mul_usize(cl, chunk_strides[d], "selected chunk offset")?;
3974
+ let result_term = checked_mul_usize(ri, result_strides[d], "selected result offset")?;
3975
+ chunk_flat = checked_add_usize(chunk_flat, chunk_term, "selected chunk offset")?;
3976
+ result_flat = checked_add_usize(result_flat, result_term, "selected result offset")?;
3977
+ }
3978
+
3979
+ let src_start = checked_mul_usize(chunk_flat, elem_size, "selected source byte offset")?;
3980
+ let dst_start =
3981
+ checked_mul_usize(result_flat, elem_size, "selected destination byte offset")?;
3982
+ let src_end = checked_add_usize(src_start, elem_size, "selected source byte end")?;
3983
+ let dst_end = checked_add_usize(dst_start, elem_size, "selected destination byte end")?;
3984
+
3985
+ if src_end > chunk_data.len() || dst_end > result_len {
3986
+ return Err(Error::InvalidData(format!(
3987
+ "selected-element copy out of bounds: source range {}..{} of {} bytes, destination range {}..{} of {} bytes",
3988
+ src_start,
3989
+ src_end,
3990
+ chunk_data.len(),
3991
+ dst_start,
3992
+ dst_end,
3993
+ result_len
3994
+ )));
3995
+ }
3996
+ // SAFETY: both ranges were checked immediately above, and the source
3997
+ // slice and caller-owned output allocation are distinct.
3998
+ unsafe {
3999
+ std::ptr::copy_nonoverlapping(
4000
+ chunk_data.as_ptr().add(src_start),
4001
+ result_ptr.add(dst_start),
4002
+ elem_size,
4003
+ );
4004
+ }
4005
+
4006
+ let mut carry = true;
4007
+ for d in (0..ndim).rev() {
4008
+ if carry {
4009
+ counters[d] += 1;
4010
+ if counters[d] < dim_indices[d].len() {
4011
+ carry = false;
4012
+ } else {
4013
+ counters[d] = 0;
4014
+ }
4015
+ }
4016
+ }
4017
+ }
4018
+
4019
+ Ok(())
4020
+ }
4021
+
4022
+ /// Slice an ndarray according to a SliceInfo selection.
4023
+ fn slice_array<T: H5Type + Clone>(
4024
+ array: &ArrayD<T>,
4025
+ selection: &SliceInfo,
4026
+ shape: &[u64],
4027
+ ) -> Result<ArrayD<T>> {
4028
+ // Build result shape
4029
+ let mut result_shape = Vec::new();
4030
+
4031
+ for (i, sel) in selection.selections.iter().enumerate() {
4032
+ let dim_size = shape[i];
4033
+ match sel {
4034
+ SliceInfoElem::Index(idx) => {
4035
+ if *idx >= dim_size {
4036
+ return Err(Error::SliceOutOfBounds {
4037
+ dim: i,
4038
+ index: *idx,
4039
+ size: dim_size,
4040
+ });
4041
+ }
4042
+ // Don't add to result_shape — this dimension is collapsed
4043
+ }
4044
+ SliceInfoElem::Slice { start, end, step } => {
4045
+ let dim_size = checked_usize(dim_size, "slice dimension size")?;
4046
+ let actual_end = if *end == u64::MAX {
4047
+ dim_size
4048
+ } else {
4049
+ checked_usize(*end, "slice end")?.min(dim_size)
4050
+ };
4051
+ let actual_start = checked_usize(*start, "slice start")?;
4052
+ let actual_step = checked_usize(*step, "slice step")?;
4053
+ if actual_step == 0 {
4054
+ return Err(Error::InvalidData("slice step cannot be 0".into()));
4055
+ }
4056
+ if actual_start > dim_size {
4057
+ return Err(Error::SliceOutOfBounds {
4058
+ dim: i,
4059
+ index: *start,
4060
+ size: shape[i],
4061
+ });
4062
+ }
4063
+ let n = (actual_end - actual_start).div_ceil(actual_step);
4064
+ result_shape.push(n);
4065
+ }
4066
+ }
4067
+ }
4068
+
4069
+ // Extract elements manually (ndarray's slicing API is complex with dynamic dims)
4070
+ let ndim = shape.len();
4071
+ let total = checked_product_usize(&result_shape, "slice result element count")?;
4072
+ let mut elements = Vec::with_capacity(total);
4073
+
4074
+ // Generate all indices in the result
4075
+ let mut result_idx = vec![0usize; result_shape.len()];
4076
+
4077
+ for _ in 0..total {
4078
+ // Map result index to source index
4079
+ let mut src_idx = Vec::with_capacity(ndim);
4080
+ let mut ri = 0;
4081
+ for sel in selection.selections.iter() {
4082
+ match sel {
4083
+ SliceInfoElem::Index(idx) => {
4084
+ src_idx.push(checked_usize(*idx, "slice source index")?);
4085
+ }
4086
+ SliceInfoElem::Slice { start, step, .. } => {
4087
+ let start = checked_usize(*start, "slice start")?;
4088
+ let step = checked_usize(*step, "slice step")?;
4089
+ let offset =
4090
+ checked_mul_usize(result_idx[ri], step, "slice source index offset")?;
4091
+ src_idx.push(checked_add_usize(start, offset, "slice source index")?);
4092
+ ri += 1;
4093
+ }
4094
+ }
4095
+ }
4096
+
4097
+ elements.push(array[IxDyn(&src_idx)].clone());
4098
+
4099
+ // Increment result index
4100
+ if !result_shape.is_empty() {
4101
+ let mut carry = true;
4102
+ for d in (0..result_shape.len()).rev() {
4103
+ if carry {
4104
+ result_idx[d] += 1;
4105
+ if result_idx[d] < result_shape[d] {
4106
+ carry = false;
4107
+ } else {
4108
+ result_idx[d] = 0;
4109
+ }
4110
+ }
4111
+ }
4112
+ }
4113
+ }
4114
+
4115
+ ArrayD::from_shape_vec(IxDyn(&result_shape), elements)
4116
+ .map_err(|e| Error::InvalidData(format!("slice shape error: {e}")))
4117
+ }
4118
+
4119
+ #[cfg(test)]
4120
+ mod tests {
4121
+ use super::*;
4122
+ use crate::storage::BytesStorage;
4123
+
4124
+ /// Buffers sized from a corrupt dataspace fail the read instead of aborting.
4125
+ #[test]
4126
+ fn impossible_selection_buffers_are_errors() {
4127
+ assert!(try_uninit_vec::<u64>(usize::MAX / 4).is_err());
4128
+ assert!(try_zeroed_bytes(usize::MAX / 2).is_err());
4129
+ assert_eq!(try_uninit_vec::<u64>(3).unwrap().len(), 3);
4130
+ assert_eq!(try_zeroed_bytes(5).unwrap(), vec![0u8; 5]);
4131
+ }
4132
+ use crate::superblock::Superblock;
4133
+ use std::collections::HashMap;
4134
+
4135
+ fn test_context_with_offset_size(bytes: Vec<u8>, offset_size: u8) -> Arc<FileContext> {
4136
+ let storage: DynStorage = Arc::new(BytesStorage::new(bytes));
4137
+ Arc::new(FileContext {
4138
+ storage,
4139
+ superblock: Superblock {
4140
+ version: 2,
4141
+ offset_size,
4142
+ length_size: 8,
4143
+ group_leaf_node_k: 0,
4144
+ group_internal_node_k: 0,
4145
+ indexed_storage_k: 0,
4146
+ consistency_flags: 0,
4147
+ base_address: 0,
4148
+ free_space_address: u64::MAX,
4149
+ eof_address: 0,
4150
+ driver_info_address: u64::MAX,
4151
+ root_symbol_table_entry: None,
4152
+ root_object_header_address: Some(0),
4153
+ extension_address: None,
4154
+ },
4155
+ chunk_cache: Arc::new(ChunkCache::new(1024, 8)),
4156
+ header_cache: Arc::new(Mutex::new(HashMap::new())),
4157
+ dataset_path_cache: Arc::new(Mutex::new(HashMap::new())),
4158
+ filter_registry: Arc::new(FilterRegistry::default()),
4159
+ external_file_resolver: None,
4160
+ external_link_resolver: None,
4161
+ external_file_cache: Mutex::new(HashMap::new()),
4162
+ sohm_table: OnceLock::new(),
4163
+ full_file_cache: OnceLock::new(),
4164
+ })
4165
+ }
4166
+
4167
+ fn test_context(bytes: Vec<u8>) -> Arc<FileContext> {
4168
+ test_context_with_offset_size(bytes, 8)
4169
+ }
4170
+
4171
+ fn fixed_u16_dataset(layout: DataLayout, storage_bytes: Vec<u8>) -> Dataset {
4172
+ let context = test_context(storage_bytes);
4173
+ Dataset {
4174
+ context: context.clone(),
4175
+ name: "short".to_string(),
4176
+ data_address: 0,
4177
+ dataspace: DataspaceMessage {
4178
+ rank: 1,
4179
+ dims: vec![3],
4180
+ max_dims: None,
4181
+ dataspace_type: DataspaceType::Simple,
4182
+ },
4183
+ datatype: Datatype::FixedPoint {
4184
+ size: 2,
4185
+ signed: false,
4186
+ byte_order: ByteOrder::LittleEndian,
4187
+ },
4188
+ layout,
4189
+ fill_value: None,
4190
+ filters: None,
4191
+ external_files: None,
4192
+ attributes: Vec::new(),
4193
+ chunk_cache: context.chunk_cache.clone(),
4194
+ chunk_entry_cache: Arc::new(Mutex::new(LruCache::new(NonZeroUsize::new(32).unwrap()))),
4195
+ full_chunk_entries: Arc::new(OnceLock::new()),
4196
+ full_dataset_bytes: Arc::new(OnceLock::new()),
4197
+ external_slots: Arc::new(OnceLock::new()),
4198
+ filter_registry: context.filter_registry.clone(),
4199
+ }
4200
+ }
4201
+
4202
+ fn vlen_string_dataset(
4203
+ layout: DataLayout,
4204
+ storage_bytes: Vec<u8>,
4205
+ offset_size: u8,
4206
+ fill_value: Option<FillValueMessage>,
4207
+ ) -> Dataset {
4208
+ let context = test_context_with_offset_size(storage_bytes, offset_size);
4209
+ Dataset {
4210
+ context: context.clone(),
4211
+ name: "vlen".to_string(),
4212
+ data_address: 0,
4213
+ dataspace: DataspaceMessage {
4214
+ rank: 1,
4215
+ dims: vec![2],
4216
+ max_dims: None,
4217
+ dataspace_type: DataspaceType::Simple,
4218
+ },
4219
+ datatype: Datatype::String {
4220
+ size: StringSize::Variable,
4221
+ encoding: crate::messages::datatype::StringEncoding::Ascii,
4222
+ padding: crate::messages::datatype::StringPadding::NullTerminate,
4223
+ },
4224
+ layout,
4225
+ fill_value,
4226
+ filters: None,
4227
+ external_files: None,
4228
+ attributes: Vec::new(),
4229
+ chunk_cache: context.chunk_cache.clone(),
4230
+ chunk_entry_cache: Arc::new(Mutex::new(LruCache::new(NonZeroUsize::new(32).unwrap()))),
4231
+ full_chunk_entries: Arc::new(OnceLock::new()),
4232
+ full_dataset_bytes: Arc::new(OnceLock::new()),
4233
+ external_slots: Arc::new(OnceLock::new()),
4234
+ filter_registry: context.filter_registry.clone(),
4235
+ }
4236
+ }
4237
+
4238
+ #[derive(Clone, Debug, PartialEq, Eq)]
4239
+ struct RawElement(Vec<u8>);
4240
+
4241
+ impl H5Type for RawElement {
4242
+ fn hdf5_type() -> Datatype {
4243
+ Datatype::Opaque {
4244
+ size: 0,
4245
+ tag: "raw".to_string(),
4246
+ }
4247
+ }
4248
+
4249
+ fn from_bytes(bytes: &[u8], _dtype: &Datatype) -> Result<Self> {
4250
+ Ok(Self(bytes.to_vec()))
4251
+ }
4252
+
4253
+ fn element_size(dtype: &Datatype) -> usize {
4254
+ crate::datatype_api::dtype_element_size(dtype).unwrap_or(0)
4255
+ }
4256
+ }
4257
+
4258
+ #[test]
4259
+ fn slice_info_all() {
4260
+ let s = SliceInfo::all(3);
4261
+ assert_eq!(s.selections.len(), 3);
4262
+ }
4263
+
4264
+ #[test]
4265
+ fn raw_element_size_uses_file_vlen_reference_width() {
4266
+ let dtype = Datatype::VarLen {
4267
+ base: Box::new(Datatype::FixedPoint {
4268
+ size: 1,
4269
+ signed: false,
4270
+ byte_order: crate::error::ByteOrder::LittleEndian,
4271
+ }),
4272
+ kind: VarLenKind::Sequence,
4273
+ encoding: crate::messages::datatype::StringEncoding::Ascii,
4274
+ padding: crate::messages::datatype::StringPadding::NullTerminate,
4275
+ };
4276
+
4277
+ assert_eq!(raw_element_size_for_datatype(&dtype, 12).unwrap(), 12);
4278
+ assert_eq!(
4279
+ raw_element_size_for_datatype(
4280
+ &Datatype::Array {
4281
+ base: Box::new(dtype),
4282
+ dims: vec![2, 3],
4283
+ },
4284
+ 12,
4285
+ )
4286
+ .unwrap(),
4287
+ 72
4288
+ );
4289
+ }
4290
+
4291
+ #[test]
4292
+ fn chunked_vlen_slice_uses_file_reference_width() {
4293
+ for (offset_size, ref_size) in [(2u8, 10usize), (4u8, 12usize)] {
4294
+ let chunk_bytes: Vec<u8> = (0..(2 * ref_size)).map(|i| (i + 1) as u8).collect();
4295
+ let dataset = vlen_string_dataset(
4296
+ DataLayout::Chunked {
4297
+ address: 0,
4298
+ dims: vec![2],
4299
+ element_size: 16,
4300
+ chunk_indexing: Some(ChunkIndexing::Implicit),
4301
+ },
4302
+ chunk_bytes.clone(),
4303
+ offset_size,
4304
+ None,
4305
+ );
4306
+
4307
+ let selection = SliceInfo {
4308
+ selections: vec![SliceInfoElem::Slice {
4309
+ start: 0,
4310
+ end: 2,
4311
+ step: 1,
4312
+ }],
4313
+ };
4314
+ let array = dataset.read_slice::<RawElement>(&selection).unwrap();
4315
+ let values: Vec<_> = array.iter().cloned().collect();
4316
+
4317
+ assert_eq!(values[0].0, chunk_bytes[..ref_size]);
4318
+ assert_eq!(values[1].0, chunk_bytes[ref_size..2 * ref_size]);
4319
+ }
4320
+ }
4321
+
4322
+ #[cfg(feature = "rayon")]
4323
+ #[test]
4324
+ fn parallel_chunked_vlen_slice_uses_file_reference_width() {
4325
+ for (offset_size, ref_size) in [(2u8, 10usize), (4u8, 12usize)] {
4326
+ let chunk_bytes: Vec<u8> = (0..(2 * ref_size)).map(|i| (i + 1) as u8).collect();
4327
+ let dataset = vlen_string_dataset(
4328
+ DataLayout::Chunked {
4329
+ address: 0,
4330
+ dims: vec![2],
4331
+ element_size: 16,
4332
+ chunk_indexing: Some(ChunkIndexing::Implicit),
4333
+ },
4334
+ chunk_bytes.clone(),
4335
+ offset_size,
4336
+ None,
4337
+ );
4338
+
4339
+ let selection = SliceInfo {
4340
+ selections: vec![SliceInfoElem::Slice {
4341
+ start: 0,
4342
+ end: 2,
4343
+ step: 1,
4344
+ }],
4345
+ };
4346
+ let array = dataset
4347
+ .read_slice_parallel::<RawElement>(&selection)
4348
+ .unwrap();
4349
+ let values: Vec<_> = array.iter().cloned().collect();
4350
+
4351
+ assert_eq!(values[0].0, chunk_bytes[..ref_size]);
4352
+ assert_eq!(values[1].0, chunk_bytes[ref_size..2 * ref_size]);
4353
+ }
4354
+ }
4355
+
4356
+ #[test]
4357
+ fn undefined_chunked_vlen_slice_fill_uses_file_reference_width() {
4358
+ for (offset_size, ref_size, undefined_address) in
4359
+ [(2u8, 10usize, 0xFFFF), (4u8, 12usize, 0xFFFF_FFFF)]
4360
+ {
4361
+ let fill_bytes = vec![0xA5; ref_size];
4362
+ let dataset = vlen_string_dataset(
4363
+ DataLayout::Chunked {
4364
+ address: undefined_address,
4365
+ dims: vec![2],
4366
+ element_size: 16,
4367
+ chunk_indexing: Some(ChunkIndexing::Implicit),
4368
+ },
4369
+ Vec::new(),
4370
+ offset_size,
4371
+ Some(FillValueMessage {
4372
+ defined: true,
4373
+ fill_time: FillTime::IfSet,
4374
+ value: Some(fill_bytes.clone()),
4375
+ }),
4376
+ );
4377
+
4378
+ let selection = SliceInfo {
4379
+ selections: vec![SliceInfoElem::Slice {
4380
+ start: 0,
4381
+ end: 2,
4382
+ step: 1,
4383
+ }],
4384
+ };
4385
+ let array = dataset.read_slice::<RawElement>(&selection).unwrap();
4386
+ let values: Vec<_> = array.iter().cloned().collect();
4387
+
4388
+ assert_eq!(values[0].0, fill_bytes);
4389
+ assert_eq!(values[1].0, fill_bytes);
4390
+ }
4391
+ }
4392
+
4393
+ #[test]
4394
+ fn array_raw_element_size_rejects_overflow() {
4395
+ let dtype = Datatype::Array {
4396
+ base: Box::new(Datatype::FixedPoint {
4397
+ size: 8,
4398
+ signed: false,
4399
+ byte_order: crate::error::ByteOrder::LittleEndian,
4400
+ }),
4401
+ dims: vec![u64::MAX, 2],
4402
+ };
4403
+
4404
+ let err = raw_element_size_for_datatype(&dtype, 12).unwrap_err();
4405
+ assert!(err.to_string().contains("array datatype"));
4406
+ }
4407
+
4408
+ #[test]
4409
+ fn dataset_num_elements_rejects_overflow() {
4410
+ let mut dataset = fixed_u16_dataset(DataLayout::Compact { data: vec![] }, Vec::new());
4411
+ dataset.dataspace.dims = vec![u64::MAX, 2];
4412
+
4413
+ let err = dataset.num_elements().unwrap_err();
4414
+ assert!(err.to_string().contains("element count"));
4415
+ }
4416
+
4417
+ #[test]
4418
+ fn compact_raw_data_requires_exact_logical_length() {
4419
+ let dataset = fixed_u16_dataset(
4420
+ DataLayout::Compact {
4421
+ data: vec![1, 0, 2, 0, 3],
4422
+ },
4423
+ Vec::new(),
4424
+ );
4425
+
4426
+ let err = dataset.read_array::<u16>().unwrap_err();
4427
+ assert!(
4428
+ matches!(err, Error::Context { .. })
4429
+ && err
4430
+ .to_string()
4431
+ .contains("compact raw data has 5 bytes, expected 6 bytes"),
4432
+ "expected compact raw length error, got: {err}"
4433
+ );
4434
+ }
4435
+
4436
+ #[test]
4437
+ fn contiguous_raw_data_requires_exact_logical_length() {
4438
+ let dataset = fixed_u16_dataset(
4439
+ DataLayout::Contiguous {
4440
+ address: 0,
4441
+ size: 5,
4442
+ },
4443
+ vec![1, 0, 2, 0, 3],
4444
+ );
4445
+
4446
+ let err = dataset.read_raw_bytes().unwrap_err();
4447
+ assert!(
4448
+ matches!(err, Error::Context { .. })
4449
+ && err
4450
+ .to_string()
4451
+ .contains("contiguous raw data has 5 bytes, expected 6 bytes"),
4452
+ "expected contiguous raw length error, got: {err}"
4453
+ );
4454
+ }
4455
+
4456
+ #[test]
4457
+ fn copy_chunk_1d() {
4458
+ let chunk_data = vec![1u8, 2, 3, 4]; // 4 elements of 1 byte each
4459
+ let mut flat = vec![0u8; 8];
4460
+ let chunk_offsets = vec![2u64]; // starts at index 2
4461
+ let chunk_shape = vec![4u64];
4462
+ let dataset_shape = vec![8u64];
4463
+
4464
+ copy_chunk_to_flat(
4465
+ &chunk_data,
4466
+ &mut flat,
4467
+ &chunk_offsets,
4468
+ &chunk_shape,
4469
+ &dataset_shape,
4470
+ 1,
4471
+ )
4472
+ .unwrap();
4473
+ assert_eq!(flat, vec![0, 0, 1, 2, 3, 4, 0, 0]);
4474
+ }
4475
+
4476
+ #[test]
4477
+ fn copy_chunk_2d_rowwise() {
4478
+ let chunk_data = vec![1u8, 2, 3, 4, 5, 6];
4479
+ let mut flat = vec![0u8; 16];
4480
+ let chunk_offsets = vec![1u64, 1u64];
4481
+ let chunk_shape = vec![2u64, 3u64];
4482
+ let dataset_shape = vec![4u64, 4u64];
4483
+
4484
+ copy_chunk_to_flat(
4485
+ &chunk_data,
4486
+ &mut flat,
4487
+ &chunk_offsets,
4488
+ &chunk_shape,
4489
+ &dataset_shape,
4490
+ 1,
4491
+ )
4492
+ .unwrap();
4493
+
4494
+ assert_eq!(flat, vec![0, 0, 0, 0, 0, 1, 2, 3, 0, 4, 5, 6, 0, 0, 0, 0,]);
4495
+ }
4496
+
4497
+ #[test]
4498
+ fn copy_unit_stride_chunk_overlap_2d_partial() {
4499
+ let chunk_data: Vec<u8> = (1..=16).collect();
4500
+ let mut result = vec![0u8; 6];
4501
+ let chunk_offsets = vec![0u64, 0u64];
4502
+ let chunk_shape = vec![4u64, 4u64];
4503
+ let dataset_shape = vec![4u64, 4u64];
4504
+ let resolved = ResolvedSelection {
4505
+ dims: vec![
4506
+ ResolvedSelectionDim {
4507
+ start: 1,
4508
+ end: 3,
4509
+ step: 1,
4510
+ count: 2,
4511
+ },
4512
+ ResolvedSelectionDim {
4513
+ start: 1,
4514
+ end: 4,
4515
+ step: 1,
4516
+ count: 3,
4517
+ },
4518
+ ],
4519
+ result_shape: vec![2, 3],
4520
+ result_elements: 6,
4521
+ };
4522
+ let chunk_strides = vec![4usize, 1usize];
4523
+ let result_strides = vec![3usize, 1usize];
4524
+
4525
+ copy_unit_stride_chunk_overlap(
4526
+ &chunk_data,
4527
+ &mut result,
4528
+ UnitStrideCopyLayout {
4529
+ chunk_offsets: &chunk_offsets,
4530
+ chunk_shape: &chunk_shape,
4531
+ dataset_shape: &dataset_shape,
4532
+ resolved: &resolved,
4533
+ chunk_strides: &chunk_strides,
4534
+ result_strides: &result_strides,
4535
+ elem_size: 1,
4536
+ },
4537
+ )
4538
+ .unwrap();
4539
+
4540
+ assert_eq!(result, vec![6, 7, 8, 10, 11, 12]);
4541
+ }
4542
+
4543
+ fn chunk_entry(offsets: &[u64], address: u64) -> chunk_index::ChunkEntry {
4544
+ chunk_index::ChunkEntry {
4545
+ address,
4546
+ size: 0,
4547
+ filter_mask: 0,
4548
+ offsets: offsets.to_vec(),
4549
+ }
4550
+ }
4551
+
4552
+ #[test]
4553
+ fn chunk_grid_coverage_detects_missing_chunk() {
4554
+ let mut entries = vec![
4555
+ chunk_entry(&[0, 0], 0x1000),
4556
+ chunk_entry(&[0, 2], 0x2000),
4557
+ chunk_entry(&[2, 0], 0x3000),
4558
+ ];
4559
+
4560
+ let complete =
4561
+ validate_chunk_grid_coverage(&mut entries, &[4, 4], &[2, 2], &[0, 0], &[1, 1]).unwrap();
4562
+
4563
+ assert!(!complete);
4564
+ }
4565
+
4566
+ #[test]
4567
+ fn chunk_grid_coverage_rejects_duplicate_offsets() {
4568
+ let mut entries = vec![
4569
+ chunk_entry(&[0, 0], 0x1000),
4570
+ chunk_entry(&[0, 0], 0x2000),
4571
+ chunk_entry(&[0, 2], 0x3000),
4572
+ chunk_entry(&[2, 0], 0x4000),
4573
+ ];
4574
+
4575
+ let err = validate_chunk_grid_coverage(&mut entries, &[4, 4], &[2, 2], &[0, 0], &[1, 1])
4576
+ .unwrap_err();
4577
+
4578
+ assert!(matches!(err, Error::InvalidData(_)));
4579
+ }
4580
+
4581
+ #[test]
4582
+ fn decoded_chunk_len_requires_exact_size() {
4583
+ let entry = chunk_entry(&[0, 0], 0x1000);
4584
+
4585
+ validate_decoded_chunk_len(&entry, &[2, 3], 4, 24).unwrap();
4586
+ let err = validate_decoded_chunk_len(&entry, &[2, 3], 4, 23).unwrap_err();
4587
+
4588
+ assert!(matches!(err, Error::InvalidData(_)));
4589
+ }
4590
+
4591
+ #[test]
4592
+ fn copy_chunk_errors_on_short_row() {
4593
+ let chunk_data = vec![1u8, 2, 3, 4, 5];
4594
+ let mut flat = vec![0u8; 16];
4595
+ let chunk_offsets = vec![1u64, 1u64];
4596
+ let chunk_shape = vec![2u64, 3u64];
4597
+ let dataset_shape = vec![4u64, 4u64];
4598
+
4599
+ let err = copy_chunk_to_flat(
4600
+ &chunk_data,
4601
+ &mut flat,
4602
+ &chunk_offsets,
4603
+ &chunk_shape,
4604
+ &dataset_shape,
4605
+ 1,
4606
+ )
4607
+ .unwrap_err();
4608
+
4609
+ assert!(matches!(err, Error::InvalidData(_)));
4610
+ }
4611
+
4612
+ #[test]
4613
+ fn copy_unit_stride_chunk_overlap_errors_on_short_row() {
4614
+ let chunk_data: Vec<u8> = (1..=7).collect();
4615
+ let mut result = vec![0u8; 6];
4616
+ let chunk_offsets = vec![0u64, 0u64];
4617
+ let chunk_shape = vec![4u64, 4u64];
4618
+ let dataset_shape = vec![4u64, 4u64];
4619
+ let resolved = ResolvedSelection {
4620
+ dims: vec![
4621
+ ResolvedSelectionDim {
4622
+ start: 1,
4623
+ end: 3,
4624
+ step: 1,
4625
+ count: 2,
4626
+ },
4627
+ ResolvedSelectionDim {
4628
+ start: 1,
4629
+ end: 4,
4630
+ step: 1,
4631
+ count: 3,
4632
+ },
4633
+ ],
4634
+ result_shape: vec![2, 3],
4635
+ result_elements: 6,
4636
+ };
4637
+ let chunk_strides = vec![4usize, 1usize];
4638
+ let result_strides = vec![3usize, 1usize];
4639
+
4640
+ let err = copy_unit_stride_chunk_overlap(
4641
+ &chunk_data,
4642
+ &mut result,
4643
+ UnitStrideCopyLayout {
4644
+ chunk_offsets: &chunk_offsets,
4645
+ chunk_shape: &chunk_shape,
4646
+ dataset_shape: &dataset_shape,
4647
+ resolved: &resolved,
4648
+ chunk_strides: &chunk_strides,
4649
+ result_strides: &result_strides,
4650
+ elem_size: 1,
4651
+ },
4652
+ )
4653
+ .unwrap_err();
4654
+
4655
+ assert!(matches!(err, Error::InvalidData(_)));
4656
+ }
4657
+
4658
+ // ------------------------------------------------------------------
4659
+ // validate_chunk_grid_coverage: the gate for the uninitialized-output
4660
+ // fast path. It must return Ok(true) only for an exact, gap-free,
4661
+ // duplicate-free tiling; otherwise the caller falls back to a
4662
+ // zero-initialized buffer, so returning false (not true) on a missing
4663
+ // chunk is what keeps the assume_init path sound.
4664
+ // ------------------------------------------------------------------
4665
+
4666
+ #[test]
4667
+ fn grid_coverage_true_for_exact_tiling() {
4668
+ // 4x6 dataset, 2x3 chunks -> a full 2x2 chunk grid.
4669
+ let shape = [4u64, 6];
4670
+ let chunk_shape = [2u64, 3];
4671
+ let mut entries = vec![
4672
+ chunk_entry(&[0, 0], 0x100),
4673
+ chunk_entry(&[0, 3], 0x200),
4674
+ chunk_entry(&[2, 0], 0x300),
4675
+ chunk_entry(&[2, 3], 0x400),
4676
+ ];
4677
+ let covered =
4678
+ validate_chunk_grid_coverage(&mut entries, &shape, &chunk_shape, &[0, 0], &[1, 1])
4679
+ .unwrap();
4680
+ assert!(covered);
4681
+ }
4682
+
4683
+ #[test]
4684
+ fn grid_coverage_false_when_a_chunk_is_missing() {
4685
+ // Drop the last chunk: coverage is incomplete, so the fast path must
4686
+ // be declined (Ok(false)), never Ok(true).
4687
+ let shape = [4u64, 6];
4688
+ let chunk_shape = [2u64, 3];
4689
+ let mut entries = vec![
4690
+ chunk_entry(&[0, 0], 0x100),
4691
+ chunk_entry(&[0, 3], 0x200),
4692
+ chunk_entry(&[2, 0], 0x300),
4693
+ ];
4694
+ let covered =
4695
+ validate_chunk_grid_coverage(&mut entries, &shape, &chunk_shape, &[0, 0], &[1, 1])
4696
+ .unwrap();
4697
+ assert!(!covered);
4698
+ }
4699
+
4700
+ #[test]
4701
+ fn grid_coverage_rejects_duplicate_chunks() {
4702
+ let shape = [4u64, 6];
4703
+ let chunk_shape = [2u64, 3];
4704
+ let mut entries = vec![
4705
+ chunk_entry(&[0, 0], 0x100),
4706
+ chunk_entry(&[0, 0], 0x999),
4707
+ chunk_entry(&[0, 3], 0x200),
4708
+ chunk_entry(&[2, 0], 0x300),
4709
+ chunk_entry(&[2, 3], 0x400),
4710
+ ];
4711
+ let err =
4712
+ validate_chunk_grid_coverage(&mut entries, &shape, &chunk_shape, &[0, 0], &[1, 1])
4713
+ .unwrap_err();
4714
+ assert!(matches!(err, Error::InvalidData(msg) if msg.contains("duplicate chunk")));
4715
+ }
4716
+
4717
+ #[test]
4718
+ fn grid_coverage_rejects_out_of_grid_offsets() {
4719
+ // An offset not aligned to the chunk grid must be rejected outright.
4720
+ let shape = [4u64, 6];
4721
+ let chunk_shape = [2u64, 3];
4722
+ let mut entries = vec![
4723
+ chunk_entry(&[0, 0], 0x100),
4724
+ chunk_entry(&[1, 3], 0x200), // row offset 1 is not a multiple of 2
4725
+ chunk_entry(&[2, 0], 0x300),
4726
+ chunk_entry(&[2, 3], 0x400),
4727
+ ];
4728
+ let err =
4729
+ validate_chunk_grid_coverage(&mut entries, &shape, &chunk_shape, &[0, 0], &[1, 1])
4730
+ .unwrap_err();
4731
+ assert!(matches!(err, Error::InvalidData(_)));
4732
+ }
4733
+ }