rc_zip/
encoding.rs

1//! Character encodings used in ZIP files.
2//!
3//! ZIP entry paths may be encoded in a variety of character encodings:
4//! historically, CP-437 was used, but many modern zip files use UTF-8 with an
5//! optional UTF-8 flag.
6//!
7//! Others use the system's local character encoding, and we have no choice but
8//! to make an educated guess thanks to the chardet-ng crate.
9
10use std::fmt;
11
12/// Encodings supported by this crate
13#[derive(Clone, Copy, PartialEq, Eq, Debug)]
14pub enum Encoding {
15    /// [UTF-8](https://en.wikipedia.org/wiki/UTF-8), opt-in for ZIP files.
16    Utf8,
17
18    /// [Codepage 437](https://en.wikipedia.org/wiki/Code_page_437), also known as
19    /// OEM-US, PC-8, or DOS Latin US.
20    ///
21    /// This is the fallback if UTF-8 is not specified and no other encoding
22    /// is auto-detected. It was the original encoding of the zip format.
23    Cp437,
24
25    /// [Shift JIS](https://en.wikipedia.org/wiki/Shift_JIS), also known as SJIS.
26    ///
27    /// Still in use by some Japanese users as of 2019.
28    ShiftJis,
29}
30
31impl fmt::Display for Encoding {
32    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
33        use Encoding as T;
34        match self {
35            T::Utf8 => write!(f, "utf-8"),
36            T::Cp437 => write!(f, "cp-437"),
37            T::ShiftJis => write!(f, "shift-jis"),
38        }
39    }
40}
41
42/// Errors encountered while converting text to UTF-8.
43#[derive(Debug, thiserror::Error)]
44pub enum DecodingError {
45    /// Text claimed to be UTF-8, but wasn't (as far as we can tell).
46    #[error("invalid utf-8: {0}")]
47    Utf8Error(std::str::Utf8Error),
48
49    /// Text is too large to be converted.
50    ///
51    /// In practice, this happens if the text's length is larger than
52    /// [usize::MAX], which seems unlikely.
53    #[error("text too large to be converted")]
54    StringTooLarge,
55
56    /// Text is not valid in the given encoding.
57    #[error("encoding error: {0}")]
58    EncodingError(&'static str),
59}
60
61impl From<std::str::Utf8Error> for DecodingError {
62    fn from(e: std::str::Utf8Error) -> Self {
63        DecodingError::Utf8Error(e)
64    }
65}
66
67impl Encoding {
68    pub(crate) fn decode(&self, i: &[u8]) -> Result<String, DecodingError> {
69        match self {
70            Encoding::Utf8 => {
71                let s = std::str::from_utf8(i)?;
72                Ok(s.to_string())
73            }
74            Encoding::Cp437 => Ok(oem_cp::decode_string_complete_table(
75                i,
76                &oem_cp::code_table::DECODING_TABLE_CP437,
77            )),
78            Encoding::ShiftJis => self.decode_as(i, encoding_rs::SHIFT_JIS),
79        }
80    }
81
82    fn decode_as(
83        &self,
84        i: &[u8],
85        encoding: &'static encoding_rs::Encoding,
86    ) -> Result<String, DecodingError> {
87        let mut decoder = encoding.new_decoder();
88        let len = decoder
89            .max_utf8_buffer_length(i.len())
90            .ok_or(DecodingError::StringTooLarge)?;
91        let mut v = vec![0u8; len];
92        let last = true;
93        let (_decoder_result, _decoder_read, decoder_written, had_errors) =
94            decoder.decode_to_utf8(i, &mut v, last);
95        if had_errors {
96            return Err(DecodingError::EncodingError(encoding.name()));
97        }
98        v.resize(decoder_written, 0u8);
99        Ok(unsafe { String::from_utf8_unchecked(v) })
100    }
101}
102
103// detect_utf8 reports whether s is a valid UTF-8 string, and whether the string
104// must be considered UTF-8 encoding (i.e., not compatible with CP-437, ASCII,
105// or any other common encoding).
106pub(crate) fn detect_utf8(input: &[u8]) -> (bool, bool) {
107    match std::str::from_utf8(input) {
108        Err(_) => {
109            // not valid utf-8
110            (false, false)
111        }
112        Ok(s) => {
113            let mut require = false;
114
115            // Officially, ZIP uses CP-437, but many readers use the system's
116            // local character encoding. Most encoding are compatible with a large
117            // subset of CP-437, which itself is ASCII-like.
118            //
119            // Forbid 0x7e and 0x5c since EUC-KR and Shift-JIS replace those
120            // characters with localized currency and overline characters.
121            for c in s.chars() {
122                if c < 0x20 as char || c > 0x7d as char || c == 0x5c as char {
123                    require = true
124                }
125            }
126            (true, require)
127        }
128    }
129}
rc_zip/encoding.rs

rc_zip/
encoding.rs
