Skip to content

Commit ff028bb

Browse files
author
Stjepan Glavina
committed
Improve compile times and add comments
1 parent 79eab9e commit ff028bb

File tree

7 files changed

+632
-510
lines changed

7 files changed

+632
-510
lines changed

‎src/io/buf_read/mod.rs

Lines changed: 163 additions & 151 deletions
Original file line numberDiff line numberDiff line change
@@ -22,91 +22,99 @@ cfg_if! {
2222
}
2323

2424
extension_trait! {
25-
/// Allows reading from a buffered byte stream.
26-
///
27-
/// This trait is a re-export of [`futures::io::AsyncBufRead`] and is an async version of
28-
/// [`std::io::BufRead`].
29-
///
30-
/// The [provided methods] do not really exist in the trait itself, but they become
31-
/// available when the prelude is imported:
32-
///
33-
/// ```
34-
/// # #[allow(unused_imports)]
35-
/// use async_std::prelude::*;
36-
/// ```
37-
///
38-
/// [`std::io::BufRead`]: https://doc.rust-lang.org/std/io/trait.BufRead.html
39-
/// [`futures::io::AsyncBufRead`]:
40-
/// https://docs.rs/futures-preview/0.3.0-alpha.17/futures/io/trait.AsyncBufRead.html
41-
/// [provided methods]: #provided-methods
25+
#[doc = r#"
26+
Allows reading from a buffered byte stream.
27+
28+
This trait is a re-export of [`futures::io::AsyncBufRead`] and is an async version of
29+
[`std::io::BufRead`].
30+
31+
The [provided methods] do not really exist in the trait itself, but they become
32+
available when the prelude is imported:
33+
34+
```
35+
# #[allow(unused_imports)]
36+
use async_std::prelude::*;
37+
```
38+
39+
[`std::io::BufRead`]: https://doc.rust-lang.org/std/io/trait.BufRead.html
40+
[`futures::io::AsyncBufRead`]:
41+
https://docs.rs/futures-preview/0.3.0-alpha.17/futures/io/trait.AsyncBufRead.html
42+
[provided methods]: #provided-methods
43+
"#]
4244
pub trait BufRead [BufReadExt: futures_io::AsyncBufRead] {
43-
/// Returns the contents of the internal buffer, filling it with more data from the
44-
/// inner reader if it is empty.
45-
///
46-
/// This function is a lower-level call. It needs to be paired with the [`consume`]
47-
/// method to function properly. When calling this method, none of the contents will be
48-
/// "read" in the sense that later calling `read` may return the same contents. As
49-
/// such, [`consume`] must be called with the number of bytes that are consumed from
50-
/// this buffer to ensure that the bytes are never returned twice.
51-
///
52-
/// [`consume`]: #tymethod.consume
53-
///
54-
/// An empty buffer returned indicates that the stream has reached EOF.
45+
#[doc = r#"
46+
Returns the contents of the internal buffer, filling it with more data from the
47+
inner reader if it is empty.
48+
49+
This function is a lower-level call. It needs to be paired with the [`consume`]
50+
method to function properly. When calling this method, none of the contents will be
51+
"read" in the sense that later calling `read` may return the same contents. As
52+
such, [`consume`] must be called with the number of bytes that are consumed from
53+
this buffer to ensure that the bytes are never returned twice.
54+
55+
[`consume`]: #tymethod.consume
56+
57+
An empty buffer returned indicates that the stream has reached EOF.
58+
"#]
5559
// TODO: write a proper doctest with `consume`
5660
fn poll_fill_buf(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<&[u8]>>;
5761

58-
/// Tells this buffer that `amt` bytes have been consumed from the buffer, so they
59-
/// should no longer be returned in calls to `read`.
62+
#[doc = r#"
63+
Tells this buffer that `amt` bytes have been consumed from the buffer, so they
64+
should no longer be returned in calls to `read`.
65+
"#]
6066
fn consume(self: Pin<&mut Self>, amt: usize);
6167

62-
/// Reads all bytes into `buf` until the delimiter `byte` or EOF is reached.
63-
///
64-
/// This function will read bytes from the underlying stream until the delimiter or EOF
65-
/// is found. Once found, all bytes up to, and including, the delimiter (if found) will
66-
/// be appended to `buf`.
67-
///
68-
/// If successful, this function will return the total number of bytes read.
69-
///
70-
/// # Examples
71-
///
72-
/// ```no_run
73-
/// # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
74-
/// #
75-
/// use async_std::fs::File;
76-
/// use async_std::io::BufReader;
77-
/// use async_std::prelude::*;
78-
///
79-
/// let mut file = BufReader::new(File::open("a.txt").await?);
80-
///
81-
/// let mut buf = Vec::with_capacity(1024);
82-
/// let n = file.read_until(b'\n', &mut buf).await?;
83-
/// #
84-
/// # Ok(()) }) }
85-
/// ```
86-
///
87-
/// Multiple successful calls to `read_until` append all bytes up to and including to
88-
/// `buf`:
89-
/// ```
90-
/// # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
91-
/// #
92-
/// use async_std::io::BufReader;
93-
/// use async_std::prelude::*;
94-
///
95-
/// let from: &[u8] = b"append\nexample\n";
96-
/// let mut reader = BufReader::new(from);
97-
/// let mut buf = vec![];
98-
///
99-
/// let mut size = reader.read_until(b'\n', &mut buf).await?;
100-
/// assert_eq!(size, 7);
101-
/// assert_eq!(buf, b"append\n");
102-
///
103-
/// size += reader.read_until(b'\n', &mut buf).await?;
104-
/// assert_eq!(size, from.len());
105-
///
106-
/// assert_eq!(buf, from);
107-
/// #
108-
/// # Ok(()) }) }
109-
/// ```
68+
#[doc = r#"
69+
Reads all bytes into `buf` until the delimiter `byte` or EOF is reached.
70+
71+
This function will read bytes from the underlying stream until the delimiter or EOF
72+
is found. Once found, all bytes up to, and including, the delimiter (if found) will
73+
be appended to `buf`.
74+
75+
If successful, this function will return the total number of bytes read.
76+
77+
# Examples
78+
79+
```no_run
80+
# fn main() -> std::io::Result<()> { async_std::task::block_on(async {
81+
#
82+
use async_std::fs::File;
83+
use async_std::io::BufReader;
84+
use async_std::prelude::*;
85+
86+
let mut file = BufReader::new(File::open("a.txt").await?);
87+
88+
let mut buf = Vec::with_capacity(1024);
89+
let n = file.read_until(b'\n', &mut buf).await?;
90+
#
91+
# Ok(()) }) }
92+
```
93+
94+
Multiple successful calls to `read_until` append all bytes up to and including to
95+
`buf`:
96+
```
97+
# fn main() -> std::io::Result<()> { async_std::task::block_on(async {
98+
#
99+
use async_std::io::BufReader;
100+
use async_std::prelude::*;
101+
102+
let from: &[u8] = b"append\nexample\n";
103+
let mut reader = BufReader::new(from);
104+
let mut buf = vec![];
105+
106+
let mut size = reader.read_until(b'\n', &mut buf).await?;
107+
assert_eq!(size, 7);
108+
assert_eq!(buf, b"append\n");
109+
110+
size += reader.read_until(b'\n', &mut buf).await?;
111+
assert_eq!(size, from.len());
112+
113+
assert_eq!(buf, from);
114+
#
115+
# Ok(()) }) }
116+
```
117+
"#]
110118
fn read_until<'a>(
111119
&'a mut self,
112120
byte: u8,
@@ -123,42 +131,44 @@ extension_trait! {
123131
}
124132
}
125133

126-
/// Reads all bytes and appends them into `buf` until a newline (the 0xA byte) is
127-
/// reached.
128-
///
129-
/// This function will read bytes from the underlying stream until the newline
130-
/// delimiter (the 0xA byte) or EOF is found. Once found, all bytes up to, and
131-
/// including, the delimiter (if found) will be appended to `buf`.
132-
///
133-
/// If successful, this function will return the total number of bytes read.
134-
///
135-
/// If this function returns `Ok(0)`, the stream has reached EOF.
136-
///
137-
/// # Errors
138-
///
139-
/// This function has the same error semantics as [`read_until`] and will also return
140-
/// an error if the read bytes are not valid UTF-8. If an I/O error is encountered then
141-
/// `buf` may contain some bytes already read in the event that all data read so far
142-
/// was valid UTF-8.
143-
///
144-
/// [`read_until`]: #method.read_until
145-
///
146-
/// # Examples
147-
///
148-
/// ```no_run
149-
/// # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
150-
/// #
151-
/// use async_std::fs::File;
152-
/// use async_std::io::BufReader;
153-
/// use async_std::prelude::*;
154-
///
155-
/// let mut file = BufReader::new(File::open("a.txt").await?);
156-
///
157-
/// let mut buf = String::new();
158-
/// file.read_line(&mut buf).await?;
159-
/// #
160-
/// # Ok(()) }) }
161-
/// ```
134+
#[doc = r#"
135+
Reads all bytes and appends them into `buf` until a newline (the 0xA byte) is
136+
reached.
137+
138+
This function will read bytes from the underlying stream until the newline
139+
delimiter (the 0xA byte) or EOF is found. Once found, all bytes up to, and
140+
including, the delimiter (if found) will be appended to `buf`.
141+
142+
If successful, this function will return the total number of bytes read.
143+
144+
If this function returns `Ok(0)`, the stream has reached EOF.
145+
146+
# Errors
147+
148+
This function has the same error semantics as [`read_until`] and will also return
149+
an error if the read bytes are not valid UTF-8. If an I/O error is encountered then
150+
`buf` may contain some bytes already read in the event that all data read so far
151+
was valid UTF-8.
152+
153+
[`read_until`]: #method.read_until
154+
155+
# Examples
156+
157+
```no_run
158+
# fn main() -> std::io::Result<()> { async_std::task::block_on(async {
159+
#
160+
use async_std::fs::File;
161+
use async_std::io::BufReader;
162+
use async_std::prelude::*;
163+
164+
let mut file = BufReader::new(File::open("a.txt").await?);
165+
166+
let mut buf = String::new();
167+
file.read_line(&mut buf).await?;
168+
#
169+
# Ok(()) }) }
170+
```
171+
"#]
162172
fn read_line<'a>(
163173
&'a mut self,
164174
buf: &'a mut String,
@@ -174,35 +184,37 @@ extension_trait! {
174184
}
175185
}
176186

177-
/// Returns a stream over the lines of this byte stream.
178-
///
179-
/// The stream returned from this function will yield instances of
180-
/// [`io::Result`]`<`[`String`]`>`. Each string returned will *not* have a newline byte
181-
/// (the 0xA byte) or CRLF (0xD, 0xA bytes) at the end.
182-
///
183-
/// [`io::Result`]: type.Result.html
184-
/// [`String`]: https://doc.rust-lang.org/std/string/struct.String.html
185-
///
186-
/// # Examples
187-
///
188-
/// ```no_run
189-
/// # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
190-
/// #
191-
/// use async_std::fs::File;
192-
/// use async_std::io::BufReader;
193-
/// use async_std::prelude::*;
194-
///
195-
/// let file = File::open("a.txt").await?;
196-
/// let mut lines = BufReader::new(file).lines();
197-
/// let mut count = 0;
198-
///
199-
/// while let Some(line) = lines.next().await {
200-
/// line?;
201-
/// count += 1;
202-
/// }
203-
/// #
204-
/// # Ok(()) }) }
205-
/// ```
187+
#[doc = r#"
188+
Returns a stream over the lines of this byte stream.
189+
190+
The stream returned from this function will yield instances of
191+
[`io::Result`]`<`[`String`]`>`. Each string returned will *not* have a newline byte
192+
(the 0xA byte) or CRLF (0xD, 0xA bytes) at the end.
193+
194+
[`io::Result`]: type.Result.html
195+
[`String`]: https://doc.rust-lang.org/std/string/struct.String.html
196+
197+
# Examples
198+
199+
```no_run
200+
# fn main() -> std::io::Result<()> { async_std::task::block_on(async {
201+
#
202+
use async_std::fs::File;
203+
use async_std::io::BufReader;
204+
use async_std::prelude::*;
205+
206+
let file = File::open("a.txt").await?;
207+
let mut lines = BufReader::new(file).lines();
208+
let mut count = 0;
209+
210+
while let Some(line) = lines.next().await {
211+
line?;
212+
count += 1;
213+
}
214+
#
215+
# Ok(()) }) }
216+
```
217+
"#]
206218
fn lines(self) -> Lines<Self>
207219
where
208220
Self: Unpin + Sized,
@@ -221,11 +233,11 @@ extension_trait! {
221233
self: Pin<&mut Self>,
222234
cx: &mut Context<'_>,
223235
) -> Poll<io::Result<&[u8]>> {
224-
unreachable!()
236+
unreachable!("this impl only appears in the rendered docs")
225237
}
226238

227239
fn consume(self: Pin<&mut Self>, amt: usize) {
228-
unreachable!()
240+
unreachable!("this impl only appears in the rendered docs")
229241
}
230242
}
231243

@@ -234,11 +246,11 @@ extension_trait! {
234246
self: Pin<&mut Self>,
235247
cx: &mut Context<'_>,
236248
) -> Poll<io::Result<&[u8]>> {
237-
unreachable!()
249+
unreachable!("this impl only appears in the rendered docs")
238250
}
239251

240252
fn consume(self: Pin<&mut Self>, amt: usize) {
241-
unreachable!()
253+
unreachable!("this impl only appears in the rendered docs")
242254
}
243255
}
244256

@@ -251,11 +263,11 @@ extension_trait! {
251263
self: Pin<&mut Self>,
252264
cx: &mut Context<'_>,
253265
) -> Poll<io::Result<&[u8]>> {
254-
unreachable!()
266+
unreachable!("this impl only appears in the rendered docs")
255267
}
256268

257269
fn consume(self: Pin<&mut Self>, amt: usize) {
258-
unreachable!()
270+
unreachable!("this impl only appears in the rendered docs")
259271
}
260272
}
261273

@@ -268,7 +280,7 @@ extension_trait! {
268280
}
269281

270282
fn consume(self: Pin<&mut Self>, amt: usize) {
271-
unreachable!()
283+
unreachable!("this impl only appears in the rendered docs")
272284
}
273285
}
274286
}

0 commit comments

Comments
 (0)