h5rio 0.3.0

A simple HDF5 IO library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140

use std::rc::Rc;

use hdf5_metno as hdf5;

use ndarray::arr0;

use crate::ArrayHdf5Writer;

/// Append-only writer for one-dimensional HDF5 table datasets.
///
/// Each call to [`write`](Self::write) appends one row of type `T`. The row
/// type must implement `hdf5::H5Type`; for plain record structs, use the
/// [`h5type`](crate::h5type) attribute macro.
///
/// The dataset shape is `(n_rows,)`, where the leading dimension grows as rows
/// are appended.
pub struct TableHdf5Writer<T: hdf5::H5Type>(ArrayHdf5Writer<T>);

impl<T: hdf5::H5Type> TableHdf5Writer<T> {
    /// Create a new appendable table dataset.
    ///
    /// `chunk_size` is the number of rows buffered before writing to disk.
    /// The value must be greater than zero.
    pub fn new(file: Rc<hdf5::File>, dataset: &str, chunk_size: usize) -> hdf5::Result<Self> {
        ArrayHdf5Writer::new(file, dataset, chunk_size, vec![]).map(Self)
    }

    /// Write any buffered rows to disk.
    ///
    /// Writers also attempt to flush when dropped, but explicit flushing is
    /// preferred because it reports failures directly.
    pub fn flush(&self) -> hdf5::Result<()> {
        self.0.flush()
    }

    /// Append one row to the table.
    ///
    /// The row may be buffered in memory until `chunk_size` rows are available
    /// or [`flush`](Self::flush) is called.
    pub fn write(&self, value: T) -> hdf5::Result<()> {
        self.0.write(arr0(value))
    }
}


#[cfg(test)]
mod tests {
    use super::*;
    use hdf5_metno as hdf5;
    use pretty_assertions::assert_eq;
    use crate::read_table;
    use crate::utils::tempfile;

    // This is meant to be done with #[h5type], but here we keep things as
    // independent as possible
    #[derive(hdf5::H5Type, Clone, PartialEq, Debug)]
    #[repr(C)]
    pub struct Dummy {
        a: i64,
        b: f32,
    }

    type DummyWriter = TableHdf5Writer::<Dummy>;

    #[test]
    fn new_valid() {
        let (_dir, filename) = tempfile("new_valid");
        let file             = hdf5::File::create(filename).unwrap();
        let writer           = DummyWriter::new(Rc::new(file), "/here", 123);
        assert!(writer.is_ok());
    }

    #[test]
    fn new_invalid_dataset_name() {
        let (_dir, filename) = tempfile("new_invalid_dataset_name");
        let file             = hdf5::File::create(filename).unwrap();
        let writer           = DummyWriter::new(Rc::new(file), "/", 123);
        assert!(writer.is_err());
    }

    #[test]
    fn new_invalid_chunksize() {
        let (_dir, filename) = tempfile("new_invalid_chunksize");
        let file             = hdf5::File::create(filename).unwrap();
        let writer           = DummyWriter::new(Rc::new(file), "/here", 0);
        assert!(writer.is_err());
    }

    #[test]
    fn round_trip_single() {
        let (_dir, filename) = tempfile("round_trip_single");
        let file             = hdf5::File::create(filename.clone()).unwrap();
        let writer           = DummyWriter::new(Rc::new(file), "/here", 1).unwrap();

        let data = Dummy{a: 42, b: 3.14};
        writer.write(data.clone()).unwrap();

        let read = read_table::<Dummy>(&filename, "/here").unwrap();

        assert_eq!(read.len(), 1);
        assert_eq!(read[0], data);
    }

    #[test]
    fn round_trip_double() {
        let (_dir, filename) = tempfile("round_trip_double");
        let file             = hdf5::File::create(filename.clone()).unwrap();
        let writer           = DummyWriter::new(Rc::new(file), "/here", 1).unwrap();

        let data0 = Dummy{a: 42, b: 3.14};
        let data1 = Dummy{a: 99, b: 2.72};
        writer.write(data0.clone()).unwrap();
        writer.write(data1.clone()).unwrap();

        let read = read_table::<Dummy>(&filename, "/here").unwrap();

        assert_eq!(read.len(), 2);
        assert_eq!(read[0], data0);
        assert_eq!(read[1], data1);
    }

    #[test]
    fn flush_on_drop() {
        // Write less entries than chunk size and verify that it is still written
        let (_dir, filename) = tempfile("flush_on_drop");
        let file             = hdf5::File::create(filename.clone()).unwrap();
        let writer           = DummyWriter::new(Rc::new(file), "/here", 5).unwrap();

        let data = Dummy{a: 42, b: 3.14};
        writer.write(data.clone()).unwrap(); // not actually written because of cache

        let read = read_table::<Dummy>(&filename, "/here").unwrap();
        assert_eq!(read.len(), 0);

        drop(writer);
        let read = read_table::<Dummy>(&filename, "/here").unwrap();
        assert_eq!(read.len(), 1);
    }

}