async_std/io/seek/
mod.rs

1mod seek;
2
3use seek::SeekFuture;
4
5use crate::io::SeekFrom;
6
7extension_trait! {
8    use std::ops::{Deref, DerefMut};
9    use std::pin::Pin;
10
11    use crate::io;
12    use crate::task::{Context, Poll};
13
14    #[doc = r#"
15        Allows seeking through a byte stream.
16
17        This trait is a re-export of [`futures::io::AsyncSeek`] and is an async version of
18        [`std::io::Seek`].
19
20        The [provided methods] do not really exist in the trait itself, but they become
21        available when [`SeekExt`] the [prelude] is imported:
22
23        ```
24        # #[allow(unused_imports)]
25        use async_std::prelude::*;
26        ```
27
28        [`std::io::Seek`]: https://doc.rust-lang.org/std/io/trait.Seek.html
29        [`futures::io::AsyncSeek`]:
30        https://docs.rs/futures/0.3/futures/io/trait.AsyncSeek.html
31        [provided methods]: #provided-methods
32        [`SeekExt`]: ../io/prelude/trait.SeekExt.html
33        [prelude]: ../prelude/index.html
34    "#]
35    pub trait Seek {
36        #[doc = r#"
37            Attempt to seek to an offset, in bytes, in a stream.
38        "#]
39        fn poll_seek(
40            self: Pin<&mut Self>,
41            cx: &mut Context<'_>,
42            pos: SeekFrom,
43        ) -> Poll<io::Result<u64>>;
44    }
45
46    #[doc = r#"
47        Extension methods for [`Seek`].
48
49        [`Seek`]: ../trait.Seek.html
50    "#]
51    pub trait SeekExt: futures_io::AsyncSeek {
52        #[doc = r#"
53            Seeks to a new position in a byte stream.
54
55            Returns the new position in the byte stream.
56
57            A seek beyond the end of stream is allowed, but behavior is defined by the
58            implementation.
59
60            # Examples
61
62            ```no_run
63            # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
64            #
65            use async_std::fs::File;
66            use async_std::io::SeekFrom;
67            use async_std::prelude::*;
68
69            let mut file = File::open("a.txt").await?;
70
71            let file_len = file.seek(SeekFrom::End(0)).await?;
72            #
73            # Ok(()) }) }
74            ```
75        "#]
76        fn seek(
77            &mut self,
78            pos: SeekFrom,
79        ) -> impl Future<Output = io::Result<u64>> + '_ [SeekFuture<'_, Self>]
80        where
81            Self: Unpin,
82        {
83            SeekFuture { seeker: self, pos }
84        }
85    }
86
87    impl<T: Seek + Unpin + ?Sized> Seek for Box<T> {
88        fn poll_seek(
89            self: Pin<&mut Self>,
90            cx: &mut Context<'_>,
91            pos: SeekFrom,
92        ) -> Poll<io::Result<u64>> {
93            unreachable!("this impl only appears in the rendered docs")
94        }
95    }
96
97    impl<T: Seek + Unpin + ?Sized> Seek for &mut T {
98        fn poll_seek(
99            self: Pin<&mut Self>,
100            cx: &mut Context<'_>,
101            pos: SeekFrom,
102        ) -> Poll<io::Result<u64>> {
103            unreachable!("this impl only appears in the rendered docs")
104        }
105    }
106
107    impl<P> Seek for Pin<P>
108    where
109        P: DerefMut + Unpin,
110        <P as Deref>::Target: Seek,
111    {
112        fn poll_seek(
113            self: Pin<&mut Self>,
114            cx: &mut Context<'_>,
115            pos: SeekFrom,
116        ) -> Poll<io::Result<u64>> {
117            unreachable!("this impl only appears in the rendered docs")
118        }
119    }
120}
async_std/io/seek/mod.rs

async_std/io/seek/
mod.rs
