Merge pull request #163 from kornelski/public-api

Public API cleanups

Author: kornelski

src/encoder.rs

@@ -7,39 +7,33 @@ use std::borrow::Cow;
 
 use weezl::{BitOrder, encode::Encoder as LzwEncoder};
 
-use crate::traits::{WriteBytesExt};
+use crate::traits::WriteBytesExt;
 use crate::common::{AnyExtension, Block, DisposalMethod, Extension, Frame};
 
+/// The image has incorrect properties, making it impossible to encode as a gif.
 #[derive(Debug)]
-enum FormatErrorKind {
+#[non_exhaustive]
+pub enum EncodingFormatError {
     /// The image has too many colors.
     TooManyColors,
     /// The image has no color palette which is required.
     MissingColorPalette,
-}
-
-/// The image has incorrect properties, making it impossible to encode as a gif.
-#[derive(Debug)]
-pub struct EncodingFormatError {
-    kind: FormatErrorKind
+    /// LZW data is not valid for GIF. This may happen when wrong buffer is given to `write_lzw_pre_encoded_frame`
+    InvalidMinCodeSize,
 }
 
 impl error::Error for EncodingFormatError {}
 impl fmt::Display for EncodingFormatError {
+    #[cold]
     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
-        match self.kind {
-            FormatErrorKind::TooManyColors => write!(fmt, "the image has too many colors"),
-            FormatErrorKind::MissingColorPalette => write!(fmt, "the GIF format requires a color palette but none was given")
+        match self {
+            Self::TooManyColors => write!(fmt, "the image has too many colors"),
+            Self::MissingColorPalette => write!(fmt, "the GIF format requires a color palette but none was given"),
+            Self::InvalidMinCodeSize => write!(fmt, "LZW data is invalid"),
         }
     }
 }
 
-impl From<FormatErrorKind> for EncodingFormatError {
-    fn from(kind: FormatErrorKind) -> Self {
-        EncodingFormatError { kind }
-    }
-}
-
 #[derive(Debug)]
 /// Encoding error.
 pub enum EncodingError {
@@ -50,6 +44,7 @@ pub enum EncodingError {
 }
 
 impl fmt::Display for EncodingError {
+    #[cold]
     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
         match self {
             EncodingError::Io(err) => err.fmt(fmt),
@@ -59,6 +54,7 @@ impl fmt::Display for EncodingError {
 }
 
 impl error::Error for EncodingError {
+    #[cold]
     fn source(&self) -> Option<&(dyn error::Error + 'static)> {
         match self {
             EncodingError::Io(err) => Some(err),
@@ -68,24 +64,19 @@ impl error::Error for EncodingError {
 }
 
 impl From<io::Error> for EncodingError {
+    #[cold]
     fn from(err: io::Error) -> Self {
         EncodingError::Io(err)
     }
 }
 
 impl From<EncodingFormatError> for EncodingError {
+    #[cold]
     fn from(err: EncodingFormatError) -> Self {
         EncodingError::Format(err)
     }
 }
 
-impl From<FormatErrorKind> for EncodingError {
-    fn from(kind: FormatErrorKind) -> Self {
-        EncodingError::Format(kind.into())
-    }
-}
-
-
 /// Number of repetitions
 #[derive(Copy, Clone, Debug)]
 pub enum Repeat {
@@ -159,7 +150,7 @@ impl<W: Write> Encoder<W> {
         flags |= 0b1000_0000;
         let num_colors = palette.len() / 3;
         if num_colors > 256 {
-            return Err(EncodingError::from(FormatErrorKind::TooManyColors));
+            return Err(EncodingError::from(EncodingFormatError::TooManyColors));
         }
         // Size of global color table.
         flags |= flag_size(num_colors);
@@ -201,14 +192,14 @@ impl<W: Write> Encoder<W> {
                 flags |= 0b1000_0000;
                 let num_colors = palette.len() / 3;
                 if num_colors > 256 {
-                    return Err(EncodingError::from(FormatErrorKind::TooManyColors));
+                    return Err(EncodingError::from(EncodingFormatError::TooManyColors));
                 }
                 flags |= flag_size(num_colors);
                 writer.write_le(flags)?;
                 self.write_color_table(palette)
             },
             None => if !self.global_palette {
-                Err(EncodingError::from(FormatErrorKind::MissingColorPalette))
+                Err(EncodingError::from(EncodingFormatError::MissingColorPalette))
             } else {
                 writer.write_le(flags).map_err(Into::into)
             }
@@ -246,7 +237,7 @@ impl<W: Write> Encoder<W> {
         let writer = self.w.as_mut().unwrap();
         let num_colors = table.len() / 3;
         if num_colors > 256 {
-            return Err(EncodingError::from(FormatErrorKind::TooManyColors));
+            return Err(EncodingError::from(EncodingFormatError::TooManyColors));
         }
         let size = flag_size(num_colors);
         writer.write_all(&table[..num_colors * 3])?;
@@ -318,7 +309,7 @@ impl<W: Write> Encoder<W> {
         // empty data is allowed
         if let Some(&min_code_size) = frame.buffer.get(0) {
             if min_code_size > 11 || min_code_size < 2 {
-                return Err(EncodingError::from(io::Error::new(io::ErrorKind::InvalidInput, "invalid code size")));
+                return Err(EncodingError::Format(EncodingFormatError::InvalidMinCodeSize));
             }
         }
 
@@ -429,5 +420,5 @@ fn flag_size(size: usize) -> u8 {
 
 #[test]
 fn error_cast() {
-    let _ : Box<dyn error::Error> = EncodingError::from(FormatErrorKind::MissingColorPalette).into();
+    let _ : Box<dyn error::Error> = EncodingError::from(EncodingFormatError::MissingColorPalette).into();
 }

src/reader/decoder.rs

@@ -33,21 +33,6 @@ impl error::Error for DecodingFormatError {
     }
 }
 
-impl DecodingFormatError {
-    // Cold hints the optimizer that the error paths are less likely.
-    //
-    // This function isn't inlined to reduce code size
-    // when it's often used with a string literal.
-    #[cold]
-    fn new(
-        err: impl Into<Box<dyn error::Error + Send + Sync>>,
-    ) -> Self {
-        DecodingFormatError {
-            underlying: err.into(),
-        }
-    }
-}
-
 #[derive(Debug)]
 /// Decoding error.
 pub enum DecodingError {
@@ -58,11 +43,11 @@ pub enum DecodingError {
 }
 
 impl DecodingError {
-    #[inline]
-    pub(crate) fn format(
-        err: impl Into<Box<dyn error::Error + Send + Sync>>,
-    ) -> Self {
-        DecodingError::Format(DecodingFormatError::new(err))
+    #[cold]
+    pub(crate) fn format(err: &'static str) -> Self {
+        DecodingError::Format(DecodingFormatError {
+            underlying: err.into(),
+        })
     }
 }
 
@@ -93,6 +78,13 @@ impl From<io::Error> for DecodingError {
     }
 }
 
+impl From<io::ErrorKind> for DecodingError {
+    #[cold]
+    fn from(err: io::ErrorKind) -> Self {
+        DecodingError::Io(io::Error::from(err))
+    }
+}
+
 impl From<DecodingFormatError> for DecodingError {
     #[inline]
     fn from(err: DecodingFormatError) -> Self {
@@ -118,6 +110,7 @@ pub enum FrameDataType {
 
 /// Indicates whether a certain object has been decoded
 #[derive(Debug)]
+#[non_exhaustive]
 pub enum Decoded<'a> {
     /// Decoded nothing.
     Nothing,
@@ -257,11 +250,11 @@ impl LzwReader {
             Ok(LzwStatus::Done | LzwStatus::Ok) => {},
             Ok(LzwStatus::NoProgress) => {
                 if self.check_for_end_code {
-                    return Err(io::Error::new(io::ErrorKind::InvalidData, "No end code in lzw stream"));
+                    return Err(io::Error::new(io::ErrorKind::InvalidData, "no end code in lzw stream"));
                 }
             },
-            Err(LzwError::InvalidCode) => {
-                return Err(io::Error::new(io::ErrorKind::InvalidData, "invalid code in LZW stream").into());
+            Err(err @ LzwError::InvalidCode) => {
+                return Err(io::Error::new(io::ErrorKind::InvalidData, err).into());
             }
         }
         Ok((decoded.consumed_in, decoded.consumed_out))
@@ -272,7 +265,6 @@ impl LzwReader {
 pub struct StreamingDecoder {
     state: State,
     lzw_reader: LzwReader,
-    skip_extensions: bool,
     skip_frame_decoding: bool,
     check_frame_consistency: bool,
     allow_unknown_blocks: bool,
@@ -289,7 +281,6 @@ pub struct StreamingDecoder {
 
 /// One version number of the GIF standard.
 #[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
-#[non_exhaustive]
 pub enum Version {
     /// Version 87a, from May 1987.
     V87a,
@@ -324,7 +315,6 @@ impl StreamingDecoder {
         StreamingDecoder {
             state: Magic(0, [0; 6]),
             lzw_reader: LzwReader::new(options.check_for_end_code),
-            skip_extensions: true,
             skip_frame_decoding: options.skip_frame_decoding,
             check_frame_consistency: options.check_frame_consistency,
             allow_unknown_blocks: options.allow_unknown_blocks,
@@ -435,15 +425,6 @@ impl StreamingDecoder {
         self.version
     }
 
-    /// Configure whether extensions are saved or skipped.
-    #[deprecated = "Does not work as intended. In fact, doesn't do anything. This may disappear soon."]
-    pub fn set_extensions(&mut self, extensions: Extensions) {
-        self.skip_extensions = match extensions {
-            Extensions::Skip => true,
-            Extensions::Save => false,
-        }
-    }
-
     fn next_state(&mut self, buf: &[u8], write_into: &mut OutputBuffer<'_>) -> Result<(usize, Decoded<'_>), DecodingError> {
         macro_rules! goto (
             ($n:expr, $state:expr) => ({
@@ -464,7 +445,7 @@ impl StreamingDecoder {
             })
         );
 
-        let b = *buf.get(0).ok_or_else(|| DecodingError::format("empty buf"))?;
+        let b = *buf.get(0).ok_or_else(|| io::ErrorKind::UnexpectedEof)?;
 
         match self.state {
             Magic(i, mut version) => if i < 6 {
@@ -474,7 +455,7 @@ impl StreamingDecoder {
                 self.version = match &version[3..] {
                     b"87a" => Version::V87a,
                     b"89a" => Version::V89a,
-                    _ => return Err(DecodingError::format("unsupported GIF version"))
+                    _ => return Err(DecodingError::format("malformed GIF header"))
                 };
                 goto!(U16Byte1(U16Value::ScreenWidth, b))
             } else {
@@ -533,7 +514,7 @@ impl StreamingDecoder {
                         let global_table = global_flags & 0x80 != 0;
                         let table_size = if global_table {
                             let table_size = PLTE_CHANNELS * (1 << ((global_flags & 0b111) + 1) as usize);
-                            self.global_color_table.try_reserve_exact(table_size).map_err(|_| io::Error::from(io::ErrorKind::OutOfMemory))?;
+                            self.global_color_table.try_reserve_exact(table_size).map_err(|_| io::ErrorKind::OutOfMemory)?;
                             table_size
                         } else {
                             0usize
@@ -587,7 +568,7 @@ impl StreamingDecoder {
                         if local_table {
                             let entries = PLTE_CHANNELS * (1 << (table_size + 1));
                             let mut pal = Vec::new();
-                            pal.try_reserve_exact(entries).map_err(|_| io::Error::from(io::ErrorKind::OutOfMemory))?;
+                            pal.try_reserve_exact(entries).map_err(|_| io::ErrorKind::OutOfMemory)?;
                             frame.palette = Some(pal);
                             goto!(LocalPalette(entries))
                         } else {
@@ -664,9 +645,7 @@ impl StreamingDecoder {
                         }
                     }
                 } else {
-                    Err(DecodingError::format(
-                        "unknown extention block encountered"
-                    ))
+                    Err(DecodingError::format("unknown block type encountered"))
                 }
             }
             SkipBlock(left) => {
@@ -717,7 +696,7 @@ impl StreamingDecoder {
                             (len, len)
                         },
                         OutputBuffer::Vec(vec) => {
-                            vec.try_reserve(n).map_err(|_| io::Error::from(io::ErrorKind::OutOfMemory))?;
+                            vec.try_reserve(n).map_err(|_| io::ErrorKind::OutOfMemory)?;
                             vec.extend_from_slice(&buf[..n]);
                             (n, n)
                         },
@@ -787,5 +766,5 @@ impl StreamingDecoder {
 
 #[test]
 fn error_cast() {
-    let _ : Box<dyn error::Error> = DecodingError::Format(DecodingFormatError::new("testing")).into();
+    let _ : Box<dyn error::Error> = DecodingError::format("testing").into();
 }

src/reader/mod.rs

@@ -194,9 +194,7 @@ impl<R: Read> ReadDecoder<R> {
             let (consumed, result) = {
                 let buf = self.reader.fill_buf()?;
                 if buf.is_empty() {
-                    return Err(DecodingError::format(
-                        "unexpected EOF"
-                    ))
+                    return Err(io::ErrorKind::UnexpectedEof.into());
                 }
 
                 // Dead code checks the lifetimes that the later mem::transmute can't.
@@ -328,9 +326,7 @@ impl<R> Decoder<R> where R: Read {
             let (width, height) = (frame.width, frame.height);
             let pixel_bytes = self.memory_limit
                 .buffer_size(self.color_output, width, height)
-                .ok_or_else(|| {
-                    DecodingError::format("image is too large to decode")
-                })?;
+                .ok_or_else(|| io::Error::new(io::ErrorKind::OutOfMemory, "image is too large"))?;
 
             debug_assert_eq!(
                 pixel_bytes, self.buffer_size(),
@@ -412,7 +408,7 @@ impl<R> Decoder<R> where R: Read {
                 ColorOutput::RGBA => {
                     let buffer_size = buf.len() / N_CHANNELS;
                     if buffer_size == 0 {
-                        return Err(DecodingError::Io(io::Error::new(io::ErrorKind::InvalidInput, "odd-sized buffer")));
+                        return Err(DecodingError::format("odd-sized buffer"));
                     }
                     if self.buffer.len() < buffer_size {
                         self.buffer.resize(buffer_size, 0);