| use std::pin::Pin; |
| |
| use crate::io::{self, BufRead, IoSlice, IoSliceMut, Read, Seek, SeekFrom, Write}; |
| use crate::task::{Context, Poll}; |
| |
| /// A `Cursor` wraps an in-memory buffer and provides it with a |
| /// [`Seek`] implementation. |
| /// |
| /// `Cursor`s are used with in-memory buffers, anything implementing |
| /// `AsRef<[u8]>`, to allow them to implement [`Read`] and/or [`Write`], |
| /// allowing these buffers to be used anywhere you might use a reader or writer |
| /// that does actual I/O. |
| /// |
| /// The standard library implements some I/O traits on various types which |
| /// are commonly used as a buffer, like `Cursor<`[`Vec`]`<u8>>` and |
| /// `Cursor<`[`&[u8]`][bytes]`>`. |
| /// |
| /// [`Seek`]: trait.Seek.html |
| /// [`Read`]: trait.Read.html |
| /// [`Write`]: trait.Write.html |
| /// [`Vec`]: https://doc.rust-lang.org/std/vec/struct.Vec.html |
| /// [bytes]: https://doc.rust-lang.org/std/primitive.slice.html |
| /// [`File`]: struct.File.html |
| #[derive(Clone, Debug, Default)] |
| pub struct Cursor<T> { |
| inner: std::io::Cursor<T>, |
| } |
| |
| impl<T> Cursor<T> { |
| /// Creates a new cursor wrapping the provided underlying in-memory buffer. |
| /// |
| /// Cursor initial position is `0` even if underlying buffer (e.g., `Vec`) |
| /// is not empty. So writing to cursor starts with overwriting `Vec` |
| /// content, not with appending to it. |
| /// |
| /// # Examples |
| /// |
| /// ``` |
| /// use async_std::io::Cursor; |
| /// |
| /// let buff = Cursor::new(Vec::new()); |
| /// # fn force_inference(_: &Cursor<Vec<u8>>) {} |
| /// # force_inference(&buff); |
| /// ``` |
| pub fn new(inner: T) -> Cursor<T> { |
| Cursor { |
| inner: std::io::Cursor::new(inner), |
| } |
| } |
| |
| /// Consumes this cursor, returning the underlying value. |
| /// |
| /// # Examples |
| /// |
| /// ``` |
| /// use async_std::io::Cursor; |
| /// |
| /// let buff = Cursor::new(Vec::new()); |
| /// # fn force_inference(_: &Cursor<Vec<u8>>) {} |
| /// # force_inference(&buff); |
| /// |
| /// let vec = buff.into_inner(); |
| /// ``` |
| pub fn into_inner(self) -> T { |
| self.inner.into_inner() |
| } |
| |
| /// Gets a reference to the underlying value in this cursor. |
| /// |
| /// # Examples |
| /// |
| /// ``` |
| /// use async_std::io::Cursor; |
| /// |
| /// let buff = Cursor::new(Vec::new()); |
| /// # fn force_inference(_: &Cursor<Vec<u8>>) {} |
| /// # force_inference(&buff); |
| /// |
| /// let reference = buff.get_ref(); |
| /// ``` |
| pub fn get_ref(&self) -> &T { |
| self.inner.get_ref() |
| } |
| |
| /// Gets a mutable reference to the underlying value in this cursor. |
| /// |
| /// Care should be taken to avoid modifying the internal I/O state of the |
| /// underlying value as it may corrupt this cursor's position. |
| /// |
| /// # Examples |
| /// |
| /// ``` |
| /// use async_std::io::Cursor; |
| /// |
| /// let mut buff = Cursor::new(Vec::new()); |
| /// # fn force_inference(_: &Cursor<Vec<u8>>) {} |
| /// # force_inference(&buff); |
| /// |
| /// let reference = buff.get_mut(); |
| /// ``` |
| pub fn get_mut(&mut self) -> &mut T { |
| self.inner.get_mut() |
| } |
| |
| /// Returns the current position of this cursor. |
| /// |
| /// # Examples |
| /// |
| /// ``` |
| /// # fn main() -> std::io::Result<()> { async_std::task::block_on(async { |
| /// # |
| /// use async_std::io::Cursor; |
| /// use async_std::io::prelude::*; |
| /// use async_std::io::SeekFrom; |
| /// |
| /// let mut buff = Cursor::new(vec![1, 2, 3, 4, 5]); |
| /// |
| /// assert_eq!(buff.position(), 0); |
| /// |
| /// buff.seek(SeekFrom::Current(2)).await?; |
| /// assert_eq!(buff.position(), 2); |
| /// |
| /// buff.seek(SeekFrom::Current(-1)).await?; |
| /// assert_eq!(buff.position(), 1); |
| /// # |
| /// # Ok(()) }) } |
| /// ``` |
| pub fn position(&self) -> u64 { |
| self.inner.position() |
| } |
| |
| /// Sets the position of this cursor. |
| /// |
| /// # Examples |
| /// |
| /// ``` |
| /// use async_std::io::Cursor; |
| /// |
| /// let mut buff = Cursor::new(vec![1, 2, 3, 4, 5]); |
| /// |
| /// assert_eq!(buff.position(), 0); |
| /// |
| /// buff.set_position(2); |
| /// assert_eq!(buff.position(), 2); |
| /// |
| /// buff.set_position(4); |
| /// assert_eq!(buff.position(), 4); |
| /// ``` |
| pub fn set_position(&mut self, pos: u64) { |
| self.inner.set_position(pos) |
| } |
| } |
| |
| impl<T> Seek for Cursor<T> |
| where |
| T: AsRef<[u8]> + Unpin, |
| { |
| fn poll_seek( |
| mut self: Pin<&mut Self>, |
| _: &mut Context<'_>, |
| pos: SeekFrom, |
| ) -> Poll<io::Result<u64>> { |
| Poll::Ready(std::io::Seek::seek(&mut self.inner, pos)) |
| } |
| } |
| |
| impl<T> Read for Cursor<T> |
| where |
| T: AsRef<[u8]> + Unpin, |
| { |
| fn poll_read( |
| mut self: Pin<&mut Self>, |
| _cx: &mut Context<'_>, |
| buf: &mut [u8], |
| ) -> Poll<io::Result<usize>> { |
| Poll::Ready(std::io::Read::read(&mut self.inner, buf)) |
| } |
| |
| fn poll_read_vectored( |
| mut self: Pin<&mut Self>, |
| _: &mut Context<'_>, |
| bufs: &mut [IoSliceMut<'_>], |
| ) -> Poll<io::Result<usize>> { |
| Poll::Ready(std::io::Read::read_vectored(&mut self.inner, bufs)) |
| } |
| } |
| |
| impl<T> BufRead for Cursor<T> |
| where |
| T: AsRef<[u8]> + Unpin, |
| { |
| fn poll_fill_buf(self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<io::Result<&[u8]>> { |
| Poll::Ready(std::io::BufRead::fill_buf(&mut self.get_mut().inner)) |
| } |
| |
| fn consume(mut self: Pin<&mut Self>, amt: usize) { |
| std::io::BufRead::consume(&mut self.inner, amt) |
| } |
| } |
| |
| impl Write for Cursor<&mut [u8]> { |
| fn poll_write( |
| mut self: Pin<&mut Self>, |
| _: &mut Context<'_>, |
| buf: &[u8], |
| ) -> Poll<io::Result<usize>> { |
| Poll::Ready(std::io::Write::write(&mut self.inner, buf)) |
| } |
| |
| fn poll_write_vectored( |
| mut self: Pin<&mut Self>, |
| _: &mut Context<'_>, |
| bufs: &[IoSlice<'_>], |
| ) -> Poll<io::Result<usize>> { |
| Poll::Ready(std::io::Write::write_vectored(&mut self.inner, bufs)) |
| } |
| |
| fn poll_flush(mut self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<io::Result<()>> { |
| Poll::Ready(std::io::Write::flush(&mut self.inner)) |
| } |
| |
| fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> { |
| self.poll_flush(cx) |
| } |
| } |
| |
| impl Write for Cursor<&mut Vec<u8>> { |
| fn poll_write( |
| mut self: Pin<&mut Self>, |
| _: &mut Context<'_>, |
| buf: &[u8], |
| ) -> Poll<io::Result<usize>> { |
| Poll::Ready(std::io::Write::write(&mut self.inner, buf)) |
| } |
| |
| fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> { |
| self.poll_flush(cx) |
| } |
| |
| fn poll_flush(mut self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<io::Result<()>> { |
| Poll::Ready(std::io::Write::flush(&mut self.inner)) |
| } |
| } |
| |
| impl Write for Cursor<Vec<u8>> { |
| fn poll_write( |
| mut self: Pin<&mut Self>, |
| _: &mut Context<'_>, |
| buf: &[u8], |
| ) -> Poll<io::Result<usize>> { |
| Poll::Ready(std::io::Write::write(&mut self.inner, buf)) |
| } |
| |
| fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> { |
| self.poll_flush(cx) |
| } |
| |
| fn poll_flush(mut self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<io::Result<()>> { |
| Poll::Ready(std::io::Write::flush(&mut self.inner)) |
| } |
| } |