Merge pull request #178 from aldanor/feature/update-example

Author: aldanor

.github/workflows/ci.yml

@@ -134,6 +134,9 @@ jobs:
       - name: Build and test with filters
         run: cargo test --workspace -v --features hdf5-sys/static,hdf5-sys/zlib,lzf,blosc --exclude hdf5-derive
         if: matrix.rust != 'stable-gnu'
+      - name: Run example
+        run: cargo r --example simple --features hdf5-sys/static,hdf5-sys/zlib,lzf,blosc
+        if: matrix.rust != 'stable-gnu'
 
   apt:
     name: apt

CHANGELOG.md

@@ -93,6 +93,7 @@
 - Globals no longer creates a `lazy_static` per global.
 - Unsafe `ObjectClass::cast()` has been renamed to `ObjectClass::cast_unchecked()`.
 - Bump `winreg` (Windows only) to 0.10, `pretty_assertions` (dev) to 1.0.
+- Updated the example in the readme to showcase the new features.
 
 ### Fixed
 

Cargo.toml

@@ -27,6 +27,7 @@ lazy_static = "1.4"
 libc = "0.2"
 parking_lot = "0.11"
 ndarray = "0.15"
+paste = "1.0"
 mpi-sys = { version = "0.1", optional = true }
 errno = { version = "0.2", optional = true }
 hdf5-sys = { path = "hdf5-sys", version = "0.7.1" }  # !V

README.md

@@ -7,6 +7,7 @@ HDF5 for Rust.
 [![Documentation](https://docs.rs/hdf5/badge.svg)](https://docs.rs/hdf5)
 [![Changelog](https://img.shields.io/github/v/release/aldanor/hdf5-rust)](https://github.com/aldanor/hdf5-rust/blob/master/CHANGELOG.md)
 ![hdf5: rustc 1.51+](https://img.shields.io/badge/hdf5-rustc_1.51+-lightblue.svg)
+[![Total Lines](https://tokei.rs/b1/github/aldanor/hdf5-rust)](https://github.com/aldanor/hdf5-rust)
 [![Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
@@ -25,53 +26,77 @@ Requires HDF5 library of version 1.8.4 or later.
 ## Example
 
 ```rust
-#[derive(hdf5::H5Type, Clone, PartialEq, Debug)]
+#[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 {
-    RED = 1,
-    GREEN = 2,
-    BLUE = 3,
+    R = 1,
+    G = 2,
+    B = 3,
 }
 
-#[derive(hdf5::H5Type, Clone, PartialEq, Debug)]
+#[derive(H5Type, Clone, PartialEq, Debug)] // register with HDF5
 #[repr(C)]
 pub struct Pixel {
     xy: (i64, i64),
     color: Color,
 }
 
-fn main() -> hdf5::Result<()> {
-    use self::Color::*;
-    use ndarray::{arr1, arr2};
-
-    {
-        // write
-        let file = hdf5::File::create("pixels.h5")?;
-        let colors = file.new_dataset::<Color>().shape(2).create("colors")?;
-        colors.write(&[RED, BLUE])?;
-        let group = file.create_group("dir")?;
-        let pixels = group.new_dataset::<Pixel>().shape((2, 2)).create("pixels")?;
-        pixels.write(&arr2(&[
-            [Pixel { xy: (1, 2), color: RED }, Pixel { xy: (3, 4), color: BLUE }],
-            [Pixel { xy: (5, 6), color: GREEN }, Pixel { xy: (7, 8), color: RED }],
-        ]))?;
-    }
-    {
-        // read
-        let file = hdf5::File::open("pixels.h5")?;
-        let colors = file.dataset("colors")?;
-        assert_eq!(colors.read_1d::<Color>()?, arr1(&[RED, BLUE]));
-        let pixels = file.dataset("dir/pixels")?;
-        assert_eq!(
-            pixels.read_raw::<Pixel>()?,
-            vec![
-                Pixel { xy: (1, 2), color: RED },
-                Pixel { xy: (3, 4), color: BLUE },
-                Pixel { xy: (5, 6), color: GREEN },
-                Pixel { xy: (7, 8), color: RED },
-            ]
-        );
+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(())
 }
 ```

examples/simple.rs

@@ -1,49 +1,73 @@
-#[derive(hdf5::H5Type, Clone, PartialEq, Debug)]
+#[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 {
-    RED = 1,
-    GREEN = 2,
-    BLUE = 3,
+    R = 1,
+    G = 2,
+    B = 3,
 }
 
-#[derive(hdf5::H5Type, Clone, PartialEq, Debug)]
+#[derive(H5Type, Clone, PartialEq, Debug)] // register with HDF5
 #[repr(C)]
 pub struct Pixel {
     xy: (i64, i64),
     color: Color,
 }
 
-fn main() -> hdf5::Result<()> {
-    use self::Color::*;
-    use ndarray::{arr1, arr2};
-
-    {
-        // write
-        let file = hdf5::File::create("pixels.h5")?;
-        let colors = file.new_dataset::<Color>().shape(2).create("colors")?;
-        colors.write(&[RED, BLUE])?;
-        let group = file.create_group("dir")?;
-        let pixels = group.new_dataset::<Pixel>().shape((2, 2)).create("pixels")?;
-        pixels.write(&arr2(&[
-            [Pixel { xy: (1, 2), color: RED }, Pixel { xy: (3, 4), color: BLUE }],
-            [Pixel { xy: (5, 6), color: GREEN }, Pixel { xy: (7, 8), color: RED }],
-        ]))?;
-    }
-    {
-        // read
-        let file = hdf5::File::open("pixels.h5")?;
-        let colors = file.dataset("colors")?;
-        assert_eq!(colors.read_1d::<Color>()?, arr1(&[RED, BLUE]));
-        let pixels = file.dataset("dir/pixels")?;
-        assert_eq!(
-            pixels.read_raw::<Pixel>()?,
-            vec![
-                Pixel { xy: (1, 2), color: RED },
-                Pixel { xy: (3, 4), color: BLUE },
-                Pixel { xy: (5, 6), color: GREEN },
-                Pixel { xy: (7, 8), color: RED },
-            ]
-        );
+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(())
 }