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`]`>` 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 { inner: std::io::Cursor, } impl Cursor { /// 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>) {} /// # force_inference(&buff); /// ``` pub fn new(inner: T) -> Cursor { 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>) {} /// # 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>) {} /// # 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>) {} /// # 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 Seek for Cursor where T: AsRef<[u8]> + Unpin, { fn poll_seek( mut self: Pin<&mut Self>, _: &mut Context<'_>, pos: SeekFrom, ) -> Poll> { Poll::Ready(std::io::Seek::seek(&mut self.inner, pos)) } } impl Read for Cursor where T: AsRef<[u8]> + Unpin, { fn poll_read( mut self: Pin<&mut Self>, _cx: &mut Context<'_>, buf: &mut [u8], ) -> Poll> { 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> { Poll::Ready(std::io::Read::read_vectored(&mut self.inner, bufs)) } } impl BufRead for Cursor where T: AsRef<[u8]> + Unpin, { fn poll_fill_buf(self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll> { 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> { Poll::Ready(std::io::Write::write(&mut self.inner, buf)) } fn poll_write_vectored( mut self: Pin<&mut Self>, _: &mut Context<'_>, bufs: &[IoSlice<'_>], ) -> Poll> { Poll::Ready(std::io::Write::write_vectored(&mut self.inner, bufs)) } fn poll_flush(mut self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll> { Poll::Ready(std::io::Write::flush(&mut self.inner)) } fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll> { self.poll_flush(cx) } } impl Write for Cursor<&mut Vec> { fn poll_write( mut self: Pin<&mut Self>, _: &mut Context<'_>, buf: &[u8], ) -> Poll> { Poll::Ready(std::io::Write::write(&mut self.inner, buf)) } fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll> { self.poll_flush(cx) } fn poll_flush(mut self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll> { Poll::Ready(std::io::Write::flush(&mut self.inner)) } } impl Write for Cursor> { fn poll_write( mut self: Pin<&mut Self>, _: &mut Context<'_>, buf: &[u8], ) -> Poll> { Poll::Ready(std::io::Write::write(&mut self.inner, buf)) } fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll> { self.poll_flush(cx) } fn poll_flush(mut self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll> { Poll::Ready(std::io::Write::flush(&mut self.inner)) } }