tokio/io/util/
async_seek_ext.rs

1use crate::io::seek::{seek, Seek};
2use crate::io::AsyncSeek;
3use std::io::SeekFrom;
4
5cfg_io_util! {
6    /// An extension trait that adds utility methods to [`AsyncSeek`] types.
7    ///
8    /// # Examples
9    ///
10    /// ```
11    /// use std::io::{self, Cursor, SeekFrom};
12    /// use tokio::io::{AsyncSeekExt, AsyncReadExt};
13    ///
14    /// #[tokio::main]
15    /// async fn main() -> io::Result<()> {
16    ///     let mut cursor = Cursor::new(b"abcdefg");
17    ///
18    ///     // the `seek` method is defined by this trait
19    ///     cursor.seek(SeekFrom::Start(3)).await?;
20    ///
21    ///     let mut buf = [0; 1];
22    ///     let n = cursor.read(&mut buf).await?;
23    ///     assert_eq!(n, 1);
24    ///     assert_eq!(buf, [b'd']);
25    ///
26    ///     Ok(())
27    /// }
28    /// ```
29    ///
30    /// See [module][crate::io] documentation for more details.
31    ///
32    /// [`AsyncSeek`]: AsyncSeek
33    pub trait AsyncSeekExt: AsyncSeek {
34        /// Creates a future which will seek an IO object, and then yield the
35        /// new position in the object and the object itself.
36        ///
37        /// Equivalent to:
38        ///
39        /// ```ignore
40        /// async fn seek(&mut self, pos: SeekFrom) -> io::Result<u64>;
41        /// ```
42        ///
43        /// In the case of an error the buffer and the object will be discarded, with
44        /// the error yielded.
45        ///
46        /// # Examples
47        ///
48        /// ```no_run
49        /// use tokio::fs::File;
50        /// use tokio::io::{AsyncSeekExt, AsyncReadExt};
51        ///
52        /// use std::io::SeekFrom;
53        ///
54        /// # async fn dox() -> std::io::Result<()> {
55        /// let mut file = File::open("foo.txt").await?;
56        /// file.seek(SeekFrom::Start(6)).await?;
57        ///
58        /// let mut contents = vec![0u8; 10];
59        /// file.read_exact(&mut contents).await?;
60        /// # Ok(())
61        /// # }
62        /// ```
63        fn seek(&mut self, pos: SeekFrom) -> Seek<'_, Self>
64        where
65            Self: Unpin,
66        {
67            seek(self, pos)
68        }
69
70        /// Creates a future which will rewind to the beginning of the stream.
71        ///
72        /// This is convenience method, equivalent to `self.seek(SeekFrom::Start(0))`.
73        fn rewind(&mut self) -> Seek<'_, Self>
74        where
75            Self: Unpin,
76        {
77            self.seek(SeekFrom::Start(0))
78        }
79
80        /// Creates a future which will return the current seek position from the
81        /// start of the stream.
82        ///
83        /// This is equivalent to `self.seek(SeekFrom::Current(0))`.
84        fn stream_position(&mut self) -> Seek<'_, Self>
85        where
86            Self: Unpin,
87        {
88            self.seek(SeekFrom::Current(0))
89        }
90    }
91}
92
93impl<S: AsyncSeek + ?Sized> AsyncSeekExt for S {}
tokio/io/util/async_seek_ext.rs

tokio/io/util/
async_seek_ext.rs
