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