Enum MatError 

#[non_exhaustive]
pub enum MatError {
    Hdf5(Error),
    Format(FormatError),
    Io(Error),
    RootMustBeStruct,
    UnsupportedType(&'static str),
    MixedSequenceElementTypes,
    ShapeMismatch {
        expected: String,
        actual: String,
    },
    MissingField(String),
    UnknownClass(String),
    UnsupportedMatlabClass(String),
    Utf16Decode(String),
    BlockSizeMismatch {
        block: usize,
        expected: usize,
        actual: usize,
    },
    CompressionUnsupportedForBlocks,
    CompressionNeedsNewerFormat,
    Custom(String),
    Source(Box<dyn Error + Send + Sync + 'static>),
}

Errors that can occur when (de)serializing .mat v7.3 files.

Marked #[non_exhaustive]: reading MATLAB’s MCOS opaque classes is an ongoing effort (datetime, categorical, table, containers.Map, dictionary, …), and each newly decoded — or newly refused — class can introduce a more specific error variant. Keeping the enum open lets those additions land without a breaking change, so downstream matches must include a wildcard arm.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Hdf5(Error)

Underlying HDF5 I/O or format error.

Format(FormatError)

Underlying HDF5 format parse error.

Io(Error)

I/O error when reading or writing a file path.

RootMustBeStruct

Top-level must be a struct with named fields (each field becomes a MATLAB variable).

UnsupportedType(&'static str)

The requested Rust type has no MATLAB v7.3 encoding in this crate.

MixedSequenceElementTypes

A sequence contained elements of different primitive types.

ShapeMismatch

A dataset’s on-disk shape didn’t match the Rust type.

Fields

expected: String

The Rust side’s expectation.

actual: String

What the file contained.

MissingField(String)

A required struct field was missing from the file.

UnknownClass(String)

A MATLAB_class attribute value wasn’t recognized.

UnsupportedMatlabClass(String)

A recognized but not-yet-supported MATLAB class was encountered on read — an MCOS opaque class (datetime, categorical, table, containers.Map, dictionary, an enumeration, a user classdef, …) whose decoder is not yet implemented. Refused by name rather than misread; the modern string class is supported.

Utf16Decode(String)

UTF-16 decoding of a char dataset failed.

BlockSizeMismatch

A DataProducer wrote the wrong number of bytes for a block. Refused rather than written: a block of the wrong size displaces every address after it, and the result would be a file that fails to open for reasons that no longer point back here.

Fields

block: usize

Block index the producer was asked for.

expected: usize

Bytes it had to write, as Blocking::block_len reports.

actual: usize

Bytes it actually wrote.

CompressionUnsupportedForBlocks

A producer-backed dataset was asked for on a builder configured for compression. The layout needs each block’s exact on-disk size before it writes anything, and a compressed block’s size is not knowable without compressing it — which would buffer the data the path exists to avoid.

CompressionNeedsNewerFormat

Options::compression was set alongside an Options::libver too old to carry it.

Compression needs chunked storage, and the chunk indices this crate writes arrived in HDF5 1.10 — while the MAT default is the 1.8 format, because MATLAB used HDF5 1.8.12 before R2021b. Refused rather than resolved either way: dropping the compression loses what the caller asked for, and raising the format produces a .mat file MATLAB cannot load. Set libver to LibVer::V110 to compress and accept the newer format.

Custom(String)

A generic serde-originated error (from Error::custom).

Source(Box<dyn Error + Send + Sync + 'static>)

An error from the calling crate, carried whole.

The builder’s nesting closures (MatBuilder::struct_, MatBuilder::cell, CellWriter::push_with and their siblings) and DataProducer::block_bytes return Result<(), MatError>, so a crate that emits .mat files as one of several formats has to put its own error type through that boundary. Custom keeps only the Display text; this keeps the error, so the caller’s caller can still downcast_ref it back out of source:

let mut mb = MatBuilder::new(Options::default());
let err = mb
    .struct_("payload", |s| {
        let value = encode().map_err(MatError::from_source)?;
        s.write_scalar_u32("value", value)?;
        Ok(())
    })
    .err()
    .expect("the closure failed");

let original = err.source().unwrap().downcast_ref::<EncodeError>().unwrap();
assert_eq!(original.0, "no MAT encoding");

'static is what source hands back. Send + Sync is what the crate already needs of a MatError: a failed producer’s error waits in an Arc<Mutex<_>> for the finalizer to swap it back in, and that is what keeps MatBuilder itself Send + Sync.

Display prints the inner error, which a formatter that walks the whole source chain will therefore print twice. That matches std::io::Error’s behaviour for the same case.

Implementations

impl MatError

pub fn from_source<E>(source: E) -> Self

where E: Into<Box<dyn Error + Send + Sync + 'static>>,

Carry an error from the calling crate whole, as MatError::Source.

Shaped after std::io::Error::other: it takes a concrete error type or an already-boxed one. Reach for it at a builder closure’s edge, where .map_err(MatError::from_source) reads as a one-word conversion.

The bound also admits a String, which the conversion accepts and nothing can recover: downcast_ref needs a type that implements Error, and String does not. A bare message belongs in MatError::Custom.

Trait Implementations

impl Debug for MatError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for MatError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for MatError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl Error for MatError

Available on crate feature serde only.

fn custom<T: Display>(msg: T) -> Self

Used when a Serialize implementation encounters any error while serializing a type.

impl Error for MatError

Available on crate feature serde only.

fn custom<T: Display>(msg: T) -> Self

Raised when there is general error when deserializing a type.

fn invalid_type(unexp: Unexpected<'_>, exp: &dyn Expected) -> Self

Raised when a Deserialize receives a type different from what it was expecting.

fn invalid_value(unexp: Unexpected<'_>, exp: &dyn Expected) -> Self

Raised when a Deserialize receives a value of the right type but that is wrong for some other reason.

fn invalid_length(len: usize, exp: &dyn Expected) -> Self

Raised when deserializing a sequence or map and the input data contains too many or too few elements.

fn unknown_variant(variant: &str, expected: &'static [&'static str]) -> Self

Raised when a Deserialize enum type received a variant with an unrecognized name.

fn unknown_field(field: &str, expected: &'static [&'static str]) -> Self

Raised when a Deserialize struct type received a field with an unrecognized name.

fn missing_field(field: &'static str) -> Self

Raised when a Deserialize struct type expected to receive a required field with a particular name but that field was not present in the input.

fn duplicate_field(field: &'static str) -> Self

Raised when a Deserialize struct type received more than one of the same field.

impl From<Error> for MatError

fn from(e: Hdf5Error) -> Self

Converts to this type from the input type.

impl From<Error> for MatError

fn from(e: Error) -> Self

Converts to this type from the input type.

impl From<FormatError> for MatError

fn from(e: FormatError) -> Self

Converts to this type from the input type.