mzstd 0.2.1

Zstandard (RFC 8878) compression and decompression in safe Rust; single-threaded encoding is byte-identical to zstd 1.5.7
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

//! The failure of a writer's finalisation, with the writer handed back.

use std::io::Error;

/// A finalisation that failed, with the adapter that can retry it.
///
/// `finish` consumes the adapter, which would strand the stream if a
/// recoverable sink failure destroyed it. Instead the adapter comes back
/// here: retry with its `try_finish` or `finish`, or drop it to abandon the
/// stream.
///
/// # Examples
///
/// ```
/// # #[cfg(feature = "compression")]
/// # {
/// use mzstd::Compressor;
/// use std::io::{ErrorKind, Write};
///
/// /// A sink that refuses the first write and accepts everything after.
/// struct Stubborn { written: Vec<u8>, refused: bool }
///
/// impl Write for Stubborn {
///     fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
///         if !self.refused {
///             self.refused = true;
///             return Err(std::io::Error::new(ErrorKind::WouldBlock, "not yet"));
///         }
///         self.written.extend_from_slice(buf);
///         Ok(buf.len())
///     }
///     fn flush(&mut self) -> std::io::Result<()> { Ok(()) }
/// }
///
/// let mut encoder = Compressor::new(Default::default())?;
/// let mut sink = encoder.writer(Stubborn { written: Vec::new(), refused: false }, Default::default());
/// sink.write_all(b"payload payload")?;
/// let sink = match sink.finish() {
///     Ok(_) => unreachable!("the sink refuses its first write"),
///     Err(failure) => {
///         assert_eq!(failure.error().kind(), ErrorKind::WouldBlock);
///         failure.into_inner()
///     }
/// };
/// let inner = sink.finish().map_err(mzstd::io::FinishError::into_error)?;
/// assert!(!inner.written.is_empty());
/// # }
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
pub struct FinishError<T> {
    error: Error,
    writer: T,
}

impl<T> FinishError<T> {
    /// Preserves an adapter after a failed finalisation.
    pub(crate) const fn from_parts(error: Error, writer: T) -> Self {
        Self { error, writer }
    }

    /// The failure that stopped the stream from being terminated.
    #[must_use]
    pub const fn error(&self) -> &Error {
        &self.error
    }

    /// Takes the failure, dropping the adapter and abandoning the stream.
    #[must_use]
    pub fn into_error(self) -> Error {
        self.error
    }

    /// Takes the adapter back, so the finalisation can be retried.
    #[must_use]
    pub fn into_inner(self) -> T {
        self.writer
    }

    /// Splits the failure from the adapter.
    #[must_use]
    pub fn into_parts(self) -> (Error, T) {
        (self.error, self.writer)
    }
}

impl<T> std::fmt::Debug for FinishError<T> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("FinishError")
            .field("error", &self.error)
            .finish_non_exhaustive()
    }
}

impl<T> std::fmt::Display for FinishError<T> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "the stream could not be finished: {}", self.error)
    }
}

impl<T> std::error::Error for FinishError<T> {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        Some(&self.error)
    }
}

impl<T> From<FinishError<T>> for Error {
    fn from(value: FinishError<T>) -> Self {
        value.error
    }
}