async_std/io/write/
mod.rs

1mod flush;
2mod write;
3mod write_all;
4mod write_fmt;
5mod write_vectored;
6
7use flush::FlushFuture;
8use write::WriteFuture;
9use write_all::WriteAllFuture;
10use write_fmt::WriteFmtFuture;
11use write_vectored::WriteVectoredFuture;
12
13use crate::io::{self, IoSlice};
14
15pub use futures_io::AsyncWrite as Write;
16
17#[doc = r#"
18    Extension methods for [`Write`].
19
20    [`Write`]: ../trait.Write.html
21"#]
22pub trait WriteExt: Write {
23    #[doc = r#"
24        Writes some bytes into the byte stream.
25
26        Returns the number of bytes written from the start of the buffer.
27
28        If the return value is `Ok(n)` then it must be guaranteed that
29        `0 <= n <= buf.len()`. A return value of `0` typically means that the underlying
30        object is no longer able to accept bytes and will likely not be able to in the
31        future as well, or that the buffer provided is empty.
32
33        # Examples
34
35        ```no_run
36        # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
37        #
38        use async_std::fs::File;
39        use async_std::prelude::*;
40
41        let mut file = File::create("a.txt").await?;
42
43        let n = file.write(b"hello world").await?;
44        #
45        # Ok(()) }) }
46        ```
47    "#]
48    fn write<'a>(
49        &'a mut self,
50        buf: &'a [u8],
51    ) -> WriteFuture<'a, Self>
52    where
53        Self: Unpin,
54    {
55        WriteFuture { writer: self, buf }
56    }
57
58    #[doc = r#"
59        Flushes the stream to ensure that all buffered contents reach their destination.
60
61        # Examples
62
63        ```no_run
64        # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
65        #
66        use async_std::fs::File;
67        use async_std::prelude::*;
68
69        let mut file = File::create("a.txt").await?;
70
71        file.write_all(b"hello world").await?;
72        file.flush().await?;
73        #
74        # Ok(()) }) }
75        ```
76    "#]
77    fn flush(&mut self) -> FlushFuture<'_, Self>
78    where
79        Self: Unpin,
80    {
81        FlushFuture { writer: self }
82    }
83
84    #[doc = r#"
85        Like [`write`], except that it writes from a slice of buffers.
86
87        Data is copied from each buffer in order, with the final buffer read from possibly
88        being only partially consumed. This method must behave as a call to [`write`] with
89        the buffers concatenated would.
90
91        The default implementation calls [`write`] with either the first nonempty buffer
92        provided, or an empty one if none exists.
93
94        [`write`]: #tymethod.write
95    "#]
96    fn write_vectored<'a>(
97        &'a mut self,
98        bufs: &'a [IoSlice<'a>],
99    ) -> WriteVectoredFuture<'a, Self>
100    where
101        Self: Unpin,
102    {
103        WriteVectoredFuture { writer: self, bufs }
104    }
105
106    #[doc = r#"
107        Writes an entire buffer into the byte stream.
108
109        This method will continuously call [`write`] until there is no more data to be
110        written or an error is returned. This method will not return until the entire
111        buffer has been successfully written or such an error occurs.
112
113        [`write`]: #tymethod.write
114
115        # Examples
116
117        ```no_run
118        # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
119        #
120        use async_std::fs::File;
121        use async_std::prelude::*;
122
123        let mut file = File::create("a.txt").await?;
124
125        file.write_all(b"hello world").await?;
126        #
127        # Ok(()) }) }
128        ```
129
130        [`write`]: #tymethod.write
131    "#]
132    fn write_all<'a>(
133        &'a mut self,
134        buf: &'a [u8],
135    ) -> WriteAllFuture<'a, Self>
136    where
137        Self: Unpin,
138    {
139        WriteAllFuture { writer: self, buf }
140    }
141
142    #[doc = r#"
143        Writes a formatted string into this writer, returning any error encountered.
144
145        This method will continuously call [`write`] until there is no more data to be
146        written or an error is returned. This future will not resolve until the entire
147        buffer has been successfully written or such an error occurs.
148
149        [`write`]: #tymethod.write
150
151        # Examples
152
153        ```no_run
154        # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
155        #
156        use async_std::io::prelude::*;
157        use async_std::fs::File;
158
159        let mut buffer = File::create("foo.txt").await?;
160
161        // this call
162        write!(buffer, "{:.*}", 2, 1.234567).await?;
163        // turns into this:
164        buffer.write_fmt(format_args!("{:.*}", 2, 1.234567)).await?;
165        #
166        # Ok(()) }) }
167        ```
168    "#]
169    fn write_fmt<'a>(
170        &'a mut self,
171        fmt: std::fmt::Arguments<'_>,
172    ) -> WriteFmtFuture<'a, Self>
173    where
174        Self: Unpin,
175    {
176        // In order to not have to implement an async version of `fmt` including private types
177        // and all, we convert `Arguments` to a `Result<Vec<u8>>` and pass that to the Future.
178        // Doing an owned conversion saves us from juggling references.
179        let mut string = String::new();
180        let res = std::fmt::write(&mut string, fmt)
181            .map(|_| string.into_bytes())
182            .map_err(|_| io::Error::new(io::ErrorKind::Other, "formatter error"));
183        WriteFmtFuture { writer: self, res: Some(res), buffer: None, amt: 0 }
184    }
185}
186
187impl<T: Write + ?Sized> WriteExt for T {}
async_std/io/write/mod.rs

async_std/io/write/
mod.rs
