1use futures_core::task::{Context, Poll};
2use futures_io::{AsyncBufRead, AsyncRead, AsyncSeek, AsyncWrite, IoSlice, IoSliceMut, SeekFrom};
3use std::io;
4use std::pin::Pin;
5
6/// A `Cursor` wraps an in-memory buffer and provides it with a
7/// [`AsyncSeek`] implementation.
8///
9/// `Cursor`s are used with in-memory buffers, anything implementing
10/// `AsRef<[u8]>`, to allow them to implement [`AsyncRead`] and/or [`AsyncWrite`],
11/// allowing these buffers to be used anywhere you might use a reader or writer
12/// that does actual I/O.
13///
14/// This library implements some I/O traits on various types which
15/// are commonly used as a buffer, like `Cursor<`[`Vec`]`<u8>>` and
16/// `Cursor<`[`&[u8]`][bytes]`>`.
17///
18/// [`AsyncSeek`]: trait.AsyncSeek.html
19/// [`AsyncRead`]: trait.AsyncRead.html
20/// [`AsyncWrite`]: trait.AsyncWrite.html
21/// [bytes]: https://doc.rust-lang.org/std/primitive.slice.html
22#[derive(Clone, Debug, Default)]
23pub struct Cursor<T> {
24 inner: io::Cursor<T>,
25}
26
27impl<T> Cursor<T> {
28 /// Creates a new cursor wrapping the provided underlying in-memory buffer.
29 ///
30 /// Cursor initial position is `0` even if underlying buffer (e.g., `Vec`)
31 /// is not empty. So writing to cursor starts with overwriting `Vec`
32 /// content, not with appending to it.
33 ///
34 /// # Examples
35 ///
36 /// ```
37 /// use futures::io::Cursor;
38 ///
39 /// let buff = Cursor::new(Vec::new());
40 /// # fn force_inference(_: &Cursor<Vec<u8>>) {}
41 /// # force_inference(&buff);
42 /// ```
43 pub fn new(inner: T) -> Self {
44 Self { inner: io::Cursor::new(inner) }
45 }
46
47 /// Consumes this cursor, returning the underlying value.
48 ///
49 /// # Examples
50 ///
51 /// ```
52 /// use futures::io::Cursor;
53 ///
54 /// let buff = Cursor::new(Vec::new());
55 /// # fn force_inference(_: &Cursor<Vec<u8>>) {}
56 /// # force_inference(&buff);
57 ///
58 /// let vec = buff.into_inner();
59 /// ```
60 pub fn into_inner(self) -> T {
61 self.inner.into_inner()
62 }
63
64 /// Gets a reference to the underlying value in this cursor.
65 ///
66 /// # Examples
67 ///
68 /// ```
69 /// use futures::io::Cursor;
70 ///
71 /// let buff = Cursor::new(Vec::new());
72 /// # fn force_inference(_: &Cursor<Vec<u8>>) {}
73 /// # force_inference(&buff);
74 ///
75 /// let reference = buff.get_ref();
76 /// ```
77 pub fn get_ref(&self) -> &T {
78 self.inner.get_ref()
79 }
80
81 /// Gets a mutable reference to the underlying value in this cursor.
82 ///
83 /// Care should be taken to avoid modifying the internal I/O state of the
84 /// underlying value as it may corrupt this cursor's position.
85 ///
86 /// # Examples
87 ///
88 /// ```
89 /// use futures::io::Cursor;
90 ///
91 /// let mut buff = Cursor::new(Vec::new());
92 /// # fn force_inference(_: &Cursor<Vec<u8>>) {}
93 /// # force_inference(&buff);
94 ///
95 /// let reference = buff.get_mut();
96 /// ```
97 pub fn get_mut(&mut self) -> &mut T {
98 self.inner.get_mut()
99 }
100
101 /// Returns the current position of this cursor.
102 ///
103 /// # Examples
104 ///
105 /// ```
106 /// # futures::executor::block_on(async {
107 /// use futures::io::{AsyncSeekExt, Cursor, SeekFrom};
108 ///
109 /// let mut buff = Cursor::new(vec![1, 2, 3, 4, 5]);
110 ///
111 /// assert_eq!(buff.position(), 0);
112 ///
113 /// buff.seek(SeekFrom::Current(2)).await?;
114 /// assert_eq!(buff.position(), 2);
115 ///
116 /// buff.seek(SeekFrom::Current(-1)).await?;
117 /// assert_eq!(buff.position(), 1);
118 /// # Ok::<(), Box<dyn std::error::Error>>(()) }).unwrap();
119 /// ```
120 pub fn position(&self) -> u64 {
121 self.inner.position()
122 }
123
124 /// Sets the position of this cursor.
125 ///
126 /// # Examples
127 ///
128 /// ```
129 /// use futures::io::Cursor;
130 ///
131 /// let mut buff = Cursor::new(vec![1, 2, 3, 4, 5]);
132 ///
133 /// assert_eq!(buff.position(), 0);
134 ///
135 /// buff.set_position(2);
136 /// assert_eq!(buff.position(), 2);
137 ///
138 /// buff.set_position(4);
139 /// assert_eq!(buff.position(), 4);
140 /// ```
141 pub fn set_position(&mut self, pos: u64) {
142 self.inner.set_position(pos)
143 }
144}
145
146impl<T> AsyncSeek for Cursor<T>
147where
148 T: AsRef<[u8]> + Unpin,
149{
150 fn poll_seek(
151 mut self: Pin<&mut Self>,
152 _: &mut Context<'_>,
153 pos: SeekFrom,
154 ) -> Poll<io::Result<u64>> {
155 Poll::Ready(io::Seek::seek(&mut self.inner, pos))
156 }
157}
158
159impl<T: AsRef<[u8]> + Unpin> AsyncRead for Cursor<T> {
160 fn poll_read(
161 mut self: Pin<&mut Self>,
162 _cx: &mut Context<'_>,
163 buf: &mut [u8],
164 ) -> Poll<io::Result<usize>> {
165 Poll::Ready(io::Read::read(&mut self.inner, buf))
166 }
167
168 fn poll_read_vectored(
169 mut self: Pin<&mut Self>,
170 _: &mut Context<'_>,
171 bufs: &mut [IoSliceMut<'_>],
172 ) -> Poll<io::Result<usize>> {
173 Poll::Ready(io::Read::read_vectored(&mut self.inner, bufs))
174 }
175}
176
177impl<T> AsyncBufRead for Cursor<T>
178where
179 T: AsRef<[u8]> + Unpin,
180{
181 fn poll_fill_buf(self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<io::Result<&[u8]>> {
182 Poll::Ready(io::BufRead::fill_buf(&mut self.get_mut().inner))
183 }
184
185 fn consume(mut self: Pin<&mut Self>, amt: usize) {
186 io::BufRead::consume(&mut self.inner, amt)
187 }
188}
189
190macro_rules! delegate_async_write_to_stdio {
191 () => {
192 fn poll_write(
193 mut self: Pin<&mut Self>,
194 _: &mut Context<'_>,
195 buf: &[u8],
196 ) -> Poll<io::Result<usize>> {
197 Poll::Ready(io::Write::write(&mut self.inner, buf))
198 }
199
200 fn poll_write_vectored(
201 mut self: Pin<&mut Self>,
202 _: &mut Context<'_>,
203 bufs: &[IoSlice<'_>],
204 ) -> Poll<io::Result<usize>> {
205 Poll::Ready(io::Write::write_vectored(&mut self.inner, bufs))
206 }
207
208 fn poll_flush(mut self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<io::Result<()>> {
209 Poll::Ready(io::Write::flush(&mut self.inner))
210 }
211
212 fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> {
213 self.poll_flush(cx)
214 }
215 };
216}
217
218impl AsyncWrite for Cursor<&mut [u8]> {
219 delegate_async_write_to_stdio!();
220}
221
222impl AsyncWrite for Cursor<&mut Vec<u8>> {
223 delegate_async_write_to_stdio!();
224}
225
226impl AsyncWrite for Cursor<Vec<u8>> {
227 delegate_async_write_to_stdio!();
228}
229
230impl AsyncWrite for Cursor<Box<[u8]>> {
231 delegate_async_write_to_stdio!();
232}
233