/* * Copyright (c) 2023. * * This software is free software; * * You can redistribute it or modify it under terms of the MIT, Apache License or Zlib license */ //! Traits for reading and writing images in zune //! //! //! This exposes the traits and implementations for readers //! and writers in the zune family of decoders and encoders. use crate::bytestream::reader::{ZByteIoError, ZSeekFrom}; /// The de-facto Input trait implemented for readers. /// /// This provides the basic functions needed to quick and sometimes /// heap free I/O for the zune image decoders with easy support for extending it /// to multiple implementations. /// /// # Considerations /// /// If you have an in memory buffer, prefer [`ZCursor`](crate::bytestream::ZCursor) over [`Cursor`](std::io::Cursor). /// We implement this trait for two types, `ZCursor`, and any thing that implements `BufRead`+`Seek`, `Cursor` falls in the latter /// and since Rust doesn't have specialization for traits, we can only implement it once. This means functions like /// [`read_byte_no_error`](crate::bytestream::ZByteReaderTrait::read_byte_no_error) are slower than they should be for `Cursor`. /// pub trait ZByteReaderTrait { /// Read a single byte from the decoder and return /// `0` if we can't read the byte, e.g because of EOF /// /// The implementation should try to be as fast as possible as this is called /// from some hot loops where it may become the bottleneck fn read_byte_no_error(&mut self) -> u8; /// Read exact bytes required to fill `buf` or return an error if that isn't possible /// /// ## Arguments /// - `buf`: Buffer to fill with bytes from the underlying reader /// ## Errors /// In case of an error, the implementation should not increment the internal position fn read_exact_bytes(&mut self, buf: &mut [u8]) -> Result<(), ZByteIoError>; /// Read exact bytes required to fill `buf` or return an error if that isn't possible /// /// This is the same as [`read_exact_bytes`](Self::read_exact_bytes) but implemented as a separate /// method to allow some implementations to optimize it to cost fewer instructions /// /// ## Arguments /// - `buf`: Buffer to fill with bytes from the underlying reader /// ## Errors /// In case of an error, the implementation should not increment the internal position fn read_const_bytes(&mut self, buf: &mut [u8; N]) -> Result<(), ZByteIoError>; /// Read exact bytes required to fill `buf` or ignore buf entirely if you can't fill it /// due to an error like the inability to fill the buffer completely /// ## Arguments /// - `buf`: Buffer to fill with bytes from the underlying reader /// ## Errors /// In case of an error, the implementation should not increment the internal position fn read_const_bytes_no_error(&mut self, buf: &mut [u8; N]); /// Read bytes into `buf` returning how many bytes you have read or an error if one occurred /// /// This doesn't guarantee that buf will be filled with bytes for such a guarantee see /// [`read_exact_bytes`](Self::read_exact_bytes) /// /// ## Arguments /// - `buf`: The buffer to fill with bytes /// /// ## Returns /// - `Ok(usize)` - Actual bytes read into the buffer /// - `Err()` - The error encountered when reading bytes for which we couldn't recover fn read_bytes(&mut self, buf: &mut [u8]) -> Result; /// Reads data into provided buffer but does not advance read position. /// /// fn peek_bytes(&mut self, buf: &mut [u8]) -> Result; fn peek_exact_bytes(&mut self, buf: &mut [u8]) -> Result<(), ZByteIoError>; /// Seek into a new position from the buffer /// /// This is similar to the [seek](std::io::Seek::seek) function in the [Seek](std::io::Seek) trait /// but implemented to work for no-std environments fn z_seek(&mut self, from: ZSeekFrom) -> Result; /// Report whether we are at the end of a stream. /// /// ## Warning /// This may cause an additional syscall e.g when we are reading from a file, we must query the file /// multiple times to check if we really are at the end of the file and the user didn't sneakily /// add more contents to it hence use it with care /// /// ## Returns /// - `Ok(bool)` - The answer to whether or not we are at end of file /// - `Err()` - The error that occurred when we queried the underlying reader if we were at EOF fn is_eof(&mut self) -> Result; /// Return the current position of the inner cursor. /// /// This can be used to check the advancement of the cursor fn z_position(&mut self) -> Result; /// Read all bytes remaining in this input to `sink` until we hit eof /// /// # Returns /// - `Ok(usize)` The actual number of bytes added to the sink /// - `Err()` An error that occurred when reading bytes fn read_remaining(&mut self, sink: &mut alloc::vec::Vec) -> Result; } /// The writer trait implemented for zune-image library of encoders /// /// Anything that implements this trait can be used as a sink /// for writing encoded images pub trait ZByteWriterTrait { /// Write some bytes into the sink returning number of bytes written or /// an error if something bad happened /// /// An implementation is free to write less bytes that are in buf, so the bytes written /// cannot be guaranteed to be fully written fn write_bytes(&mut self, buf: &[u8]) -> Result; /// Write all bytes to the buffer or return an error if something occurred /// /// This will always write all bytes, if it can't fully write all bytes, it will /// error out fn write_all_bytes(&mut self, buf: &[u8]) -> Result<(), ZByteIoError>; /// Write a fixed number of bytes and error out if we can't write the bytes /// /// This is provided to allow for optimized writes where possible. (when the compiler can const fold them) fn write_const_bytes(&mut self, buf: &[u8; N]) -> Result<(), ZByteIoError>; /// Ensure bytes are written to the sink. /// /// Implementations should treat this like linux `fsync`, and should implement /// whatever writer's implementation of fsync should look like /// /// After this, the encoder should be able to guarantee that all in-core data is synced with the /// storage decive fn flush_bytes(&mut self) -> Result<(), ZByteIoError>; /// A hint to tell the implementation how big of a size we expect the image to be /// An implementation like in memory `Vec` can use this to reserve additional memory to /// prevent reallocation when encoding /// /// This is just a hint, akin to calling `Vec::reserve` and should be treated as such. /// If your implementation doesn't support such, e.g file or mutable slices, it's okay to return /// `Ok(())` fn reserve_capacity(&mut self, size: usize) -> Result<(), ZByteIoError>; }