hdf5-pure 0.3.0

Pure-Rust HDF5 writer library (WASM-compatible, no C dependencies)
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
141

//! MATLAB class strings used in the `MATLAB_class` attribute.
//!
//! These correspond to MATLAB's built-in numeric, character, logical, struct,
//! and cell classes. Other MATLAB classes (`string`, `function_handle`,
//! user-defined `classdef` objects, …) exist but are not emitted by the
//! serializer in this release.

use super::error::MatError;

/// A recognized `MATLAB_class` value.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum MatClass {
    /// IEEE 754 64-bit float.
    Double,
    /// IEEE 754 32-bit float.
    Single,
    /// Signed 8-bit integer.
    Int8,
    /// Signed 16-bit integer.
    Int16,
    /// Signed 32-bit integer.
    Int32,
    /// Signed 64-bit integer.
    Int64,
    /// Unsigned 8-bit integer.
    UInt8,
    /// Unsigned 16-bit integer.
    UInt16,
    /// Unsigned 32-bit integer.
    UInt32,
    /// Unsigned 64-bit integer.
    UInt64,
    /// UTF-16 character array.
    Char,
    /// Boolean / logical (stored as `uint8`).
    Logical,
    /// Struct (HDF5 group with `MATLAB_fields`).
    Struct,
    /// Heterogeneous cell array. Stored as object references resolved against
    /// a hidden `#refs#` group (one entry per cell slot).
    Cell,
}

impl MatClass {
    /// The exact string stored in the `MATLAB_class` attribute.
    pub fn as_str(self) -> &'static str {
        match self {
            MatClass::Double => "double",
            MatClass::Single => "single",
            MatClass::Int8 => "int8",
            MatClass::Int16 => "int16",
            MatClass::Int32 => "int32",
            MatClass::Int64 => "int64",
            MatClass::UInt8 => "uint8",
            MatClass::UInt16 => "uint16",
            MatClass::UInt32 => "uint32",
            MatClass::UInt64 => "uint64",
            MatClass::Char => "char",
            MatClass::Logical => "logical",
            MatClass::Struct => "struct",
            MatClass::Cell => "cell",
        }
    }

    /// Parse a `MATLAB_class` attribute value.
    pub fn parse(s: &str) -> Result<Self, MatError> {
        let trimmed = trim_null_padding(s);
        Ok(match trimmed {
            "double" => MatClass::Double,
            "single" => MatClass::Single,
            "int8" => MatClass::Int8,
            "int16" => MatClass::Int16,
            "int32" => MatClass::Int32,
            "int64" => MatClass::Int64,
            "uint8" => MatClass::UInt8,
            "uint16" => MatClass::UInt16,
            "uint32" => MatClass::UInt32,
            "uint64" => MatClass::UInt64,
            "char" => MatClass::Char,
            "logical" => MatClass::Logical,
            "struct" => MatClass::Struct,
            "cell" => MatClass::Cell,
            other => return Err(MatError::UnknownClass(other.to_string())),
        })
    }

    /// The size in bytes of a single element of this numeric class.
    /// Returns `None` for non-numeric classes (Char, Struct, Cell).
    pub fn elem_size(self) -> Option<usize> {
        Some(match self {
            MatClass::Double => 8,
            MatClass::Single => 4,
            MatClass::Int8 | MatClass::UInt8 | MatClass::Logical => 1,
            MatClass::Int16 | MatClass::UInt16 | MatClass::Char => 2,
            MatClass::Int32 | MatClass::UInt32 => 4,
            MatClass::Int64 | MatClass::UInt64 => 8,
            MatClass::Struct | MatClass::Cell => return None,
        })
    }
}

fn trim_null_padding(s: &str) -> &str {
    s.trim_end_matches('\0').trim_end()
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn roundtrip_class_strings() {
        for c in [
            MatClass::Double,
            MatClass::Single,
            MatClass::Int8,
            MatClass::Int16,
            MatClass::Int32,
            MatClass::Int64,
            MatClass::UInt8,
            MatClass::UInt16,
            MatClass::UInt32,
            MatClass::UInt64,
            MatClass::Char,
            MatClass::Logical,
            MatClass::Struct,
            MatClass::Cell,
        ] {
            assert_eq!(MatClass::parse(c.as_str()).unwrap(), c);
        }
    }

    #[test]
    fn parse_tolerates_null_padding() {
        assert_eq!(MatClass::parse("double\0\0\0").unwrap(), MatClass::Double);
    }

    #[test]
    fn unknown_class_is_error() {
        assert!(matches!(MatClass::parse("datetime"), Err(MatError::UnknownClass(_))));
    }
}