rust_hdf5/
lib.rs

1//! Pure Rust HDF5 library with full read/write support.
2//!
3//! This crate provides a high-level API for creating and reading HDF5 files
4//! without any C dependencies. It supports contiguous and chunked datasets,
5//! deflate compression (with optional shuffle), SWMR streaming, and hyperslab
6//! (slice) I/O.
7//!
8//! # Quick start
9//!
10//! ## Writing a dataset
11//!
12//! ```no_run
13//! use rust_hdf5::H5File;
14//!
15//! let file = H5File::create("output.h5").unwrap();
16//! let ds = file.new_dataset::<f64>()
17//!     .shape(&[100, 200])
18//!     .create("matrix")
19//!     .unwrap();
20//! let data: Vec<f64> = (0..20_000).map(|i| i as f64).collect();
21//! ds.write_raw(&data).unwrap();
22//! file.close().unwrap();
23//! ```
24//!
25//! ## Reading a dataset
26//!
27//! ```no_run
28//! use rust_hdf5::H5File;
29//!
30//! let file = H5File::open("output.h5").unwrap();
31//! let ds = file.dataset("matrix").unwrap();
32//! let data = ds.read_raw::<f64>().unwrap();
33//! assert_eq!(data.len(), 20_000);
34//! ```
35//!
36//! ## Chunked + compressed streaming
37//!
38//! ```no_run
39//! use rust_hdf5::H5File;
40//!
41//! let file = H5File::create("stream.h5").unwrap();
42//! let ds = file.new_dataset::<f32>()
43//!     .shape(&[0usize, 64])
44//!     .chunk(&[1, 64])
45//!     .max_shape(&[None, Some(64)])
46//!     .deflate(6)
47//!     .create("sensor")
48//!     .unwrap();
49//!
50//! for frame in 0..1000u64 {
51//!     let vals: Vec<f32> = (0..64).map(|i| (frame * 64 + i) as f32).collect();
52//!     let raw: Vec<u8> = vals.iter().flat_map(|v| v.to_le_bytes()).collect();
53//!     ds.write_chunk(frame as usize, &raw).unwrap();
54//! }
55//! ds.extend(&[1000, 64]).unwrap();
56//! file.close().unwrap();
57//! ```
58//!
59//! ## Hyperslab (slice) I/O
60//!
61//! ```no_run
62//! use rust_hdf5::H5File;
63//!
64//! // Write a sub-region
65//! let file = H5File::create("slice.h5").unwrap();
66//! let ds = file.new_dataset::<i32>()
67//!     .shape(&[10usize, 10])
68//!     .create("grid")
69//!     .unwrap();
70//! ds.write_raw(&[0i32; 100]).unwrap();
71//! ds.write_slice(&[2, 3], &[3, 4], &[1i32, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]).unwrap();
72//! file.close().unwrap();
73//!
74//! // Read a sub-region
75//! let file = H5File::open("slice.h5").unwrap();
76//! let ds = file.dataset("grid").unwrap();
77//! let region = ds.read_slice::<i32>(&[2, 3], &[3, 4]).unwrap();
78//! assert_eq!(region.len(), 12);
79//! ```
80
81// The crate reads and writes numeric values by transmuting host-native
82// bytes (`H5Type` raw read/write paths) while always declaring a
83// little-endian datatype on disk. That is correct only on a little-endian
84// host; fail the build loudly on big-endian rather than corrupt data.
85#[cfg(target_endian = "big")]
86compile_error!("rust-hdf5 currently supports little-endian hosts only");
87
88pub mod format;
89pub(crate) mod io;
90
91/// Private rayon thread pool (half the cores by default) for all internal
92/// parallelism; only present under the `parallel` feature.
93#[cfg(feature = "parallel")]
94pub(crate) mod parallel;
95
96/// The run-time SIMD level the filter kernels dispatch on; only present
97/// under the `simd` feature.
98#[cfg(feature = "simd")]
99pub(crate) mod simd;
100
101pub mod attribute;
102pub mod dataset;
103pub mod error;
104pub mod file;
105pub mod group;
106/// Zero-copy views of a dataset's stored bytes. Requires the `mmap` feature.
107#[cfg(feature = "mmap")]
108pub mod mapped;
109pub mod named_datatype;
110pub mod swmr;
111pub mod types;
112
113pub use attribute::{AttrShape, H5Attribute};
114pub use dataset::{
115    AllocTime, ChunkIndex, DatasetAccess, FillTime, FillValue, H5Dataset, ReadNumeric,
116    StorageLayout, VirtualView,
117};
118pub use error::{Hdf5Error, Result};
119pub use file::{H5File, H5FileOptions};
120pub use format::creation_order::CreationOrder;
121pub use format::messages::datatype::{ByteOrder, DatatypeMessage};
122pub use format::messages::filter::{Filter, FilterPipeline};
123pub use format::messages::superblock_ext::{
124    BtreeKMessage, DriverInfoMessage, FileSpaceInfoMessage, FileSpaceStrategy,
125    SharedMessageTableMessage,
126};
127pub use format::messages::virtual_mapping::VirtualMapping;
128pub use format::reference::Reference;
129pub use format::selection::{
130    Hyperslab, HyperslabBlock, PointSelection, RegularHyperslab, Selection,
131};
132pub use format::storage_kind::{AttributeStorage, LinkStorage};
133pub use format::LibverBound;
134pub use group::H5Group;
135pub use io::locking::{FileLocking, LockMode};
136pub use io::reader::ExternalFileSegment;
137pub use io::reader::LinkClass;
138pub use io::reader::SuperblockExtension;
139pub use io::writer::{MAX_COMPACT_DATA, MIN_USERBLOCK};
140#[cfg(feature = "mmap")]
141pub use mapped::{MappedView, ViewRefusal};
142pub use named_datatype::H5NamedDatatype;
143pub use types::{Complex32, Complex64, CompoundType, H5Type, HBool, VarLenUnicode};
rust_hdf5/lib.rs

rust_hdf5/
lib.rs
