hdf5-rust

HDF5的Rust版本。

hdf5 crate（以前称为 hdf5-rs）提供了对HDF5库API的线程安全Rust绑定和高层包装。一些功能包括

• 通过可重入互斥锁保证非线程安全的libhdf5构建的线程安全性。
• 大多数HDF5类型的本地表示，包括变长字符串和数组。
• 推导宏，用于自动将用户struct和enum映射到HDF5类型。
• 通过 ndarray 提供多维数组读取/写入接口。

还提供了直接的底层绑定，并在 hdf5-sys crate中提供。

需要1.8.4或更高版本的HDF5库。

示例

#[cfg(feature = "blosc")]
use hdf5::filters::blosc_set_nthreads;
use hdf5::{File, H5Type, Result};
use ndarray::{arr2, s};

#[derive(H5Type, Clone, PartialEq, Debug)] // register with HDF5
#[repr(u8)]
pub enum Color {
    R = 1,
    G = 2,
    B = 3,
}

#[derive(H5Type, Clone, PartialEq, Debug)] // register with HDF5
#[repr(C)]
pub struct Pixel {
    xy: (i64, i64),
    color: Color,
}

impl Pixel {
    pub fn new(x: i64, y: i64, color: Color) -> Self {
        Self { xy: (x, y), color }
    }
}

fn write_hdf5() -> Result<()> {
    use Color::*;
    let file = File::create("pixels.h5")?; // open for writing
    let group = file.create_group("dir")?; // create a group
    #[cfg(feature = "blosc")]
    blosc_set_nthreads(2); // set number of blosc threads
    let builder = group.new_dataset_builder();
    #[cfg(feature = "blosc")]
    let builder = builder.blosc_zstd(9, true); // zstd + shuffle
    let ds = builder
        .with_data(&arr2(&[
            // write a 2-D array of data
            [Pixel::new(1, 2, R), Pixel::new(2, 3, B)],
            [Pixel::new(3, 4, G), Pixel::new(4, 5, R)],
            [Pixel::new(5, 6, B), Pixel::new(6, 7, G)],
        ]))
        // finalize and write the dataset
        .create("pixels")?;
    // create an attr with fixed shape but don't write the data
    let attr = ds.new_attr::<Color>().shape([3]).create("colors")?;
    // write the attr data
    attr.write(&[R, G, B])?;
    Ok(())
}

fn read_hdf5() -> Result<()> {
    use Color::*;
    let file = File::open("pixels.h5")?; // open for reading
    let ds = file.dataset("dir/pixels")?; // open the dataset
    assert_eq!(
        // read a slice of the 2-D dataset and verify it
        ds.read_slice::<Pixel, _, _>(s![1.., ..])?,
        arr2(&[
            [Pixel::new(3, 4, G), Pixel::new(4, 5, R)],
            [Pixel::new(5, 6, B), Pixel::new(6, 7, G)],
        ])
    );
    let attr = ds.attr("colors")?; // open the attribute
    assert_eq!(attr.read_1d::<Color>()?.as_slice().unwrap(), &[R, G, B]);
    Ok(())
}

fn main() -> Result<()> {
    write_hdf5()?;
    read_hdf5()?;
    Ok(())
}

兼容性

平台

hdf5 crate已知可以在以下平台上运行：Linux、macOS、Windows（在Ubuntu 16.04、18.04和20.04、Windows Server 2019（MSVC和GNU工具链）以及macOS Catalina上测试过）。

Rust

hdf5 crate对所有三个官方发布渠道进行了持续测试，并需要一个相当新的Rust编译器（例如版本1.51或更高版本）。

HDF5

所需HDF5版本为1.8.4或更高。用户代码不需要通过启用线程安全选项来构建库，以便使代码线程安全。

支持并测试了各种HDF5安装选项：通过包管理器如homebrew和apt；Windows上的系统级安装；来自官方渠道和conda-forge的conda安装。在Linux和macOS上，支持并测试了OpenMPI和MPICH并行构建。

还可以从源代码构建HDF5 C库，并通过启用 hdf5-sys/static 功能将库静态链接（需要CMake）。