broker_tokio/io/util/async_read_ext.rs
1use crate::io::util::chain::{chain, Chain};
2use crate::io::util::read::{read, Read};
3use crate::io::util::read_buf::{read_buf, ReadBuf};
4use crate::io::util::read_exact::{read_exact, ReadExact};
5use crate::io::util::read_int::{ReadI128, ReadI16, ReadI32, ReadI64, ReadI8};
6use crate::io::util::read_int::{ReadU128, ReadU16, ReadU32, ReadU64, ReadU8};
7use crate::io::util::read_to_end::{read_to_end, ReadToEnd};
8use crate::io::util::read_to_string::{read_to_string, ReadToString};
9use crate::io::util::take::{take, Take};
10use crate::io::AsyncRead;
11
12use bytes::BufMut;
13
14cfg_io_util! {
15 /// Define numeric reader
16 macro_rules! read_impl {
17 (
18 $(
19 $(#[$outer:meta])*
20 fn $name:ident(&mut self) -> $($fut:ident)*;
21 )*
22 ) => {
23 $(
24 $(#[$outer])*
25 fn $name<'a>(&'a mut self) -> $($fut)*<&'a mut Self> where Self: Unpin {
26 $($fut)*::new(self)
27 }
28 )*
29 }
30 }
31
32 /// Read bytes from a source.
33 ///
34 /// Implemented as an extention trait, adding utility methods to all
35 /// [`AsyncRead`] types. Callers will tend to import this trait instead of
36 /// [`AsyncRead`].
37 ///
38 /// As a convenience, this trait may be imported using the [`prelude`]:
39 ///
40 /// ```no_run
41 /// use tokio::fs::File;
42 /// use tokio::prelude::*;
43 ///
44 /// #[tokio::main]
45 /// async fn main() -> io::Result<()> {
46 /// let mut f = File::open("foo.txt").await?;
47 /// let mut buffer = [0; 10];
48 ///
49 /// // The `read` method is defined by this trait.
50 /// let n = f.read(&mut buffer[..]).await?;
51 ///
52 /// Ok(())
53 /// }
54 /// ```
55 ///
56 /// See [module][crate::io] documentation for more details.
57 ///
58 /// [`AsyncRead`]: AsyncRead
59 /// [`prelude`]: crate::prelude
60 pub trait AsyncReadExt: AsyncRead {
61 /// Create a new `AsyncRead` instance that chains this stream with
62 /// `next`.
63 ///
64 /// The returned `AsyncRead` instance will first read all bytes from this object
65 /// until EOF is encountered. Afterwards the output is equivalent to the
66 /// output of `next`.
67 ///
68 /// # Examples
69 ///
70 /// [`File`][crate::fs::File]s implement `AsyncRead`:
71 ///
72 /// ```no_run
73 /// use tokio::fs::File;
74 /// use tokio::io::{self, AsyncReadExt};
75 ///
76 /// #[tokio::main]
77 /// async fn main() -> io::Result<()> {
78 /// let f1 = File::open("foo.txt").await?;
79 /// let f2 = File::open("bar.txt").await?;
80 ///
81 /// let mut handle = f1.chain(f2);
82 /// let mut buffer = String::new();
83 ///
84 /// // read the value into a String. We could use any AsyncRead
85 /// // method here, this is just one example.
86 /// handle.read_to_string(&mut buffer).await?;
87 /// Ok(())
88 /// }
89 /// ```
90 fn chain<R>(self, next: R) -> Chain<Self, R>
91 where
92 Self: Sized,
93 R: AsyncRead,
94 {
95 chain(self, next)
96 }
97
98 /// Pull some bytes from this source into the specified buffer,
99 /// returning how many bytes were read.
100 ///
101 /// Equivalent to:
102 ///
103 /// ```ignore
104 /// async fn read(&mut self, buf: &mut [u8]) -> io::Result<usize>;
105 /// ```
106 ///
107 /// This function does not provide any guarantees about whether it
108 /// completes immediately or asynchronously
109 ///
110 /// If the return value of this method is `Ok(n)`, then it must be
111 /// guaranteed that `0 <= n <= buf.len()`. A nonzero `n` value indicates
112 /// that the buffer `buf` has been filled in with `n` bytes of data from
113 /// this source. If `n` is `0`, then it can indicate one of two
114 /// scenarios:
115 ///
116 /// 1. This reader has reached its "end of file" and will likely no longer
117 /// be able to produce bytes. Note that this does not mean that the
118 /// reader will *always* no longer be able to produce bytes.
119 /// 2. The buffer specified was 0 bytes in length.
120 ///
121 /// No guarantees are provided about the contents of `buf` when this
122 /// function is called, implementations cannot rely on any property of the
123 /// contents of `buf` being true. It is recommended that *implementations*
124 /// only write data to `buf` instead of reading its contents.
125 ///
126 /// Correspondingly, however, *callers* of this method may not assume
127 /// any guarantees about how the implementation uses `buf`. It is
128 /// possible that the code that's supposed to write to the buffer might
129 /// also read from it. It is your responsibility to make sure that `buf`
130 /// is initialized before calling `read`.
131 ///
132 /// # Errors
133 ///
134 /// If this function encounters any form of I/O or other error, an error
135 /// variant will be returned. If an error is returned then it must be
136 /// guaranteed that no bytes were read.
137 ///
138 /// # Examples
139 ///
140 /// [`File`][crate::fs::File]s implement `Read`:
141 ///
142 /// ```no_run
143 /// use tokio::fs::File;
144 /// use tokio::io::{self, AsyncReadExt};
145 ///
146 /// #[tokio::main]
147 /// async fn main() -> io::Result<()> {
148 /// let mut f = File::open("foo.txt").await?;
149 /// let mut buffer = [0; 10];
150 ///
151 /// // read up to 10 bytes
152 /// let n = f.read(&mut buffer[..]).await?;
153 ///
154 /// println!("The bytes: {:?}", &buffer[..n]);
155 /// Ok(())
156 /// }
157 /// ```
158 fn read<'a>(&'a mut self, buf: &'a mut [u8]) -> Read<'a, Self>
159 where
160 Self: Unpin,
161 {
162 read(self, buf)
163 }
164
165 /// Pull some bytes from this source into the specified buffer,
166 /// advancing the buffer's internal cursor.
167 ///
168 /// Equivalent to:
169 ///
170 /// ```ignore
171 /// async fn read_buf<B: BufMut>(&mut self, buf: &mut B) -> io::Result<usize>;
172 /// ```
173 ///
174 /// Usually, only a single `read` syscall is issued, even if there is
175 /// more space in the supplied buffer.
176 ///
177 /// This function does not provide any guarantees about whether it
178 /// completes immediately or asynchronously
179 ///
180 /// # Return
181 ///
182 /// On a successful read, the number of read bytes is returned. If the
183 /// supplied buffer is not empty and the function returns `Ok(0)` then
184 /// the source as reached an "end-of-file" event.
185 ///
186 /// # Errors
187 ///
188 /// If this function encounters any form of I/O or other error, an error
189 /// variant will be returned. If an error is returned then it must be
190 /// guaranteed that no bytes were read.
191 ///
192 /// # Examples
193 ///
194 /// [`File`] implements `Read` and [`BytesMut`] implements [`BufMut`]:
195 ///
196 /// [`File`]: crate::fs::File
197 /// [`BytesMut`]: bytes::BytesMut
198 /// [`BufMut`]: bytes::BufMut
199 ///
200 /// ```no_run
201 /// use tokio::fs::File;
202 /// use tokio::io::{self, AsyncReadExt};
203 ///
204 /// use bytes::BytesMut;
205 ///
206 /// #[tokio::main]
207 /// async fn main() -> io::Result<()> {
208 /// let mut f = File::open("foo.txt").await?;
209 /// let mut buffer = BytesMut::with_capacity(10);
210 ///
211 /// assert!(buffer.is_empty());
212 ///
213 /// // read up to 10 bytes, note that the return value is not needed
214 /// // to access the data that was read as `buffer`'s internal
215 /// // cursor is updated.
216 /// f.read_buf(&mut buffer).await?;
217 ///
218 /// println!("The bytes: {:?}", &buffer[..]);
219 /// Ok(())
220 /// }
221 /// ```
222 fn read_buf<'a, B>(&'a mut self, buf: &'a mut B) -> ReadBuf<'a, Self, B>
223 where
224 Self: Sized,
225 B: BufMut,
226 {
227 read_buf(self, buf)
228 }
229
230 /// Read the exact number of bytes required to fill `buf`.
231 ///
232 /// Equivalent to:
233 ///
234 /// ```ignore
235 /// async fn read_exact(&mut self, buf: &mut [u8]) -> io::Result<usize>;
236 /// ```
237 ///
238 /// This function reads as many bytes as necessary to completely fill
239 /// the specified buffer `buf`.
240 ///
241 /// No guarantees are provided about the contents of `buf` when this
242 /// function is called, implementations cannot rely on any property of
243 /// the contents of `buf` being true. It is recommended that
244 /// implementations only write data to `buf` instead of reading its
245 /// contents.
246 ///
247 /// # Errors
248 ///
249 /// If the operation encounters an "end of file" before completely
250 /// filling the buffer, it returns an error of the kind
251 /// [`ErrorKind::UnexpectedEof`]. The contents of `buf` are unspecified
252 /// in this case.
253 ///
254 /// If any other read error is encountered then the operation
255 /// immediately returns. The contents of `buf` are unspecified in this
256 /// case.
257 ///
258 /// If this operation returns an error, it is unspecified how many bytes
259 /// it has read, but it will never read more than would be necessary to
260 /// completely fill the buffer.
261 ///
262 /// # Examples
263 ///
264 /// [`File`][crate::fs::File]s implement `Read`:
265 ///
266 /// ```no_run
267 /// use tokio::fs::File;
268 /// use tokio::io::{self, AsyncReadExt};
269 ///
270 /// #[tokio::main]
271 /// async fn main() -> io::Result<()> {
272 /// let mut f = File::open("foo.txt").await?;
273 /// let mut buffer = [0; 10];
274 ///
275 /// // read exactly 10 bytes
276 /// f.read_exact(&mut buffer).await?;
277 /// Ok(())
278 /// }
279 /// ```
280 ///
281 /// [`ErrorKind::UnexpectedEof`]: std::io::ErrorKind::UnexpectedEof
282 fn read_exact<'a>(&'a mut self, buf: &'a mut [u8]) -> ReadExact<'a, Self>
283 where
284 Self: Unpin,
285 {
286 read_exact(self, buf)
287 }
288
289 read_impl! {
290 /// Reads an unsigned 8 bit integer from the underlying reader.
291 ///
292 /// Equivalent to:
293 ///
294 /// ```ignore
295 /// async fn read_u8(&mut self) -> io::Result<u8>;
296 /// ```
297 ///
298 /// It is recommended to use a buffered reader to avoid excessive
299 /// syscalls.
300 ///
301 /// # Errors
302 ///
303 /// This method returns the same errors as [`AsyncReadExt::read_exact`].
304 ///
305 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
306 ///
307 /// # Examples
308 ///
309 /// Read unsigned 8 bit integers from an `AsyncRead`:
310 ///
311 /// ```rust
312 /// use tokio::io::{self, AsyncReadExt};
313 ///
314 /// use std::io::Cursor;
315 ///
316 /// #[tokio::main]
317 /// async fn main() -> io::Result<()> {
318 /// let mut reader = Cursor::new(vec![2, 5]);
319 ///
320 /// assert_eq!(2, reader.read_u8().await?);
321 /// assert_eq!(5, reader.read_u8().await?);
322 ///
323 /// Ok(())
324 /// }
325 /// ```
326 fn read_u8(&mut self) -> ReadU8;
327
328 /// Reads a signed 8 bit integer from the underlying reader.
329 ///
330 /// Equivalent to:
331 ///
332 /// ```ignore
333 /// async fn read_i8(&mut self) -> io::Result<i8>;
334 /// ```
335 ///
336 /// It is recommended to use a buffered reader to avoid excessive
337 /// syscalls.
338 ///
339 /// # Errors
340 ///
341 /// This method returns the same errors as [`AsyncReadExt::read_exact`].
342 ///
343 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
344 ///
345 /// # Examples
346 ///
347 /// Read unsigned 8 bit integers from an `AsyncRead`:
348 ///
349 /// ```rust
350 /// use tokio::io::{self, AsyncReadExt};
351 ///
352 /// use std::io::Cursor;
353 ///
354 /// #[tokio::main]
355 /// async fn main() -> io::Result<()> {
356 /// let mut reader = Cursor::new(vec![0x02, 0xfb]);
357 ///
358 /// assert_eq!(2, reader.read_i8().await?);
359 /// assert_eq!(-5, reader.read_i8().await?);
360 ///
361 /// Ok(())
362 /// }
363 /// ```
364 fn read_i8(&mut self) -> ReadI8;
365
366 /// Reads an unsigned 16-bit integer in big-endian order from the
367 /// underlying reader.
368 ///
369 /// Equivalent to:
370 ///
371 /// ```ignore
372 /// async fn read_u16(&mut self) -> io::Result<u16>;
373 /// ```
374 ///
375 /// It is recommended to use a buffered reader to avoid excessive
376 /// syscalls.
377 ///
378 /// # Errors
379 ///
380 /// This method returns the same errors as [`AsyncReadExt::read_exact`].
381 ///
382 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
383 ///
384 /// # Examples
385 ///
386 /// Read unsigned 16 bit big-endian integers from a `AsyncRead`:
387 ///
388 /// ```rust
389 /// use tokio::io::{self, AsyncReadExt};
390 ///
391 /// use std::io::Cursor;
392 ///
393 /// #[tokio::main]
394 /// async fn main() -> io::Result<()> {
395 /// let mut reader = Cursor::new(vec![2, 5, 3, 0]);
396 ///
397 /// assert_eq!(517, reader.read_u16().await?);
398 /// assert_eq!(768, reader.read_u16().await?);
399 /// Ok(())
400 /// }
401 /// ```
402 fn read_u16(&mut self) -> ReadU16;
403
404 /// Reads a signed 16-bit integer in big-endian order from the
405 /// underlying reader.
406 ///
407 /// Equivalent to:
408 ///
409 /// ```ignore
410 /// async fn read_i16(&mut self) -> io::Result<i16>;
411 /// ```
412 ///
413 /// It is recommended to use a buffered reader to avoid excessive
414 /// syscalls.
415 ///
416 /// # Errors
417 ///
418 /// This method returns the same errors as [`AsyncReadExt::read_exact`].
419 ///
420 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
421 ///
422 /// # Examples
423 ///
424 /// Read signed 16 bit big-endian integers from a `AsyncRead`:
425 ///
426 /// ```rust
427 /// use tokio::io::{self, AsyncReadExt};
428 ///
429 /// use std::io::Cursor;
430 ///
431 /// #[tokio::main]
432 /// async fn main() -> io::Result<()> {
433 /// let mut reader = Cursor::new(vec![0x00, 0xc1, 0xff, 0x7c]);
434 ///
435 /// assert_eq!(193, reader.read_i16().await?);
436 /// assert_eq!(-132, reader.read_i16().await?);
437 /// Ok(())
438 /// }
439 /// ```
440 fn read_i16(&mut self) -> ReadI16;
441
442 /// Reads an unsigned 32-bit integer in big-endian order from the
443 /// underlying reader.
444 ///
445 /// Equivalent to:
446 ///
447 /// ```ignore
448 /// async fn read_u32(&mut self) -> io::Result<u32>;
449 /// ```
450 ///
451 /// It is recommended to use a buffered reader to avoid excessive
452 /// syscalls.
453 ///
454 /// # Errors
455 ///
456 /// This method returns the same errors as [`AsyncReadExt::read_exact`].
457 ///
458 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
459 ///
460 /// # Examples
461 ///
462 /// Read unsigned 32-bit big-endian integers from a `AsyncRead`:
463 ///
464 /// ```rust
465 /// use tokio::io::{self, AsyncReadExt};
466 ///
467 /// use std::io::Cursor;
468 ///
469 /// #[tokio::main]
470 /// async fn main() -> io::Result<()> {
471 /// let mut reader = Cursor::new(vec![0x00, 0x00, 0x01, 0x0b]);
472 ///
473 /// assert_eq!(267, reader.read_u32().await?);
474 /// Ok(())
475 /// }
476 /// ```
477 fn read_u32(&mut self) -> ReadU32;
478
479 /// Reads a signed 32-bit integer in big-endian order from the
480 /// underlying reader.
481 ///
482 ///
483 /// Equivalent to:
484 ///
485 /// ```ignore
486 /// async fn read_i32(&mut self) -> io::Result<i32>;
487 /// ```
488 ///
489 /// It is recommended to use a buffered reader to avoid excessive
490 /// syscalls.
491 ///
492 /// # Errors
493 ///
494 /// This method returns the same errors as [`AsyncReadExt::read_exact`].
495 ///
496 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
497 ///
498 /// # Examples
499 ///
500 /// Read signed 32-bit big-endian integers from a `AsyncRead`:
501 ///
502 /// ```rust
503 /// use tokio::io::{self, AsyncReadExt};
504 ///
505 /// use std::io::Cursor;
506 ///
507 /// #[tokio::main]
508 /// async fn main() -> io::Result<()> {
509 /// let mut reader = Cursor::new(vec![0xff, 0xff, 0x7a, 0x33]);
510 ///
511 /// assert_eq!(-34253, reader.read_i32().await?);
512 /// Ok(())
513 /// }
514 /// ```
515 fn read_i32(&mut self) -> ReadI32;
516
517 /// Reads an unsigned 64-bit integer in big-endian order from the
518 /// underlying reader.
519 ///
520 /// Equivalent to:
521 ///
522 /// ```ignore
523 /// async fn read_u64(&mut self) -> io::Result<u64>;
524 /// ```
525 ///
526 /// It is recommended to use a buffered reader to avoid excessive
527 /// syscalls.
528 ///
529 /// # Errors
530 ///
531 /// This method returns the same errors as [`AsyncReadExt::read_exact`].
532 ///
533 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
534 ///
535 /// # Examples
536 ///
537 /// Read unsigned 64-bit big-endian integers from a `AsyncRead`:
538 ///
539 /// ```rust
540 /// use tokio::io::{self, AsyncReadExt};
541 ///
542 /// use std::io::Cursor;
543 ///
544 /// #[tokio::main]
545 /// async fn main() -> io::Result<()> {
546 /// let mut reader = Cursor::new(vec![
547 /// 0x00, 0x03, 0x43, 0x95, 0x4d, 0x60, 0x86, 0x83
548 /// ]);
549 ///
550 /// assert_eq!(918733457491587, reader.read_u64().await?);
551 /// Ok(())
552 /// }
553 /// ```
554 fn read_u64(&mut self) -> ReadU64;
555
556 /// Reads an signed 64-bit integer in big-endian order from the
557 /// underlying reader.
558 ///
559 /// Equivalent to:
560 ///
561 /// ```ignore
562 /// async fn read_i64(&mut self) -> io::Result<i64>;
563 /// ```
564 ///
565 /// It is recommended to use a buffered reader to avoid excessive
566 /// syscalls.
567 ///
568 /// # Errors
569 ///
570 /// This method returns the same errors as [`AsyncReadExt::read_exact`].
571 ///
572 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
573 ///
574 /// # Examples
575 ///
576 /// Read signed 64-bit big-endian integers from a `AsyncRead`:
577 ///
578 /// ```rust
579 /// use tokio::io::{self, AsyncReadExt};
580 ///
581 /// use std::io::Cursor;
582 ///
583 /// #[tokio::main]
584 /// async fn main() -> io::Result<()> {
585 /// let mut reader = Cursor::new(vec![0x80, 0, 0, 0, 0, 0, 0, 0]);
586 ///
587 /// assert_eq!(i64::min_value(), reader.read_i64().await?);
588 /// Ok(())
589 /// }
590 /// ```
591 fn read_i64(&mut self) -> ReadI64;
592
593 /// Reads an unsigned 128-bit integer in big-endian order from the
594 /// underlying reader.
595 ///
596 /// Equivalent to:
597 ///
598 /// ```ignore
599 /// async fn read_u128(&mut self) -> io::Result<u128>;
600 /// ```
601 ///
602 /// It is recommended to use a buffered reader to avoid excessive
603 /// syscalls.
604 ///
605 /// # Errors
606 ///
607 /// This method returns the same errors as [`AsyncReadExt::read_exact`].
608 ///
609 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
610 ///
611 /// # Examples
612 ///
613 /// Read unsigned 128-bit big-endian integers from a `AsyncRead`:
614 ///
615 /// ```rust
616 /// use tokio::io::{self, AsyncReadExt};
617 ///
618 /// use std::io::Cursor;
619 ///
620 /// #[tokio::main]
621 /// async fn main() -> io::Result<()> {
622 /// let mut reader = Cursor::new(vec![
623 /// 0x00, 0x03, 0x43, 0x95, 0x4d, 0x60, 0x86, 0x83,
624 /// 0x00, 0x03, 0x43, 0x95, 0x4d, 0x60, 0x86, 0x83
625 /// ]);
626 ///
627 /// assert_eq!(16947640962301618749969007319746179, reader.read_u128().await?);
628 /// Ok(())
629 /// }
630 /// ```
631 fn read_u128(&mut self) -> ReadU128;
632
633 /// Reads an signed 128-bit integer in big-endian order from the
634 /// underlying reader.
635 ///
636 /// Equivalent to:
637 ///
638 /// ```ignore
639 /// async fn read_i128(&mut self) -> io::Result<i128>;
640 /// ```
641 ///
642 /// It is recommended to use a buffered reader to avoid excessive
643 /// syscalls.
644 ///
645 /// # Errors
646 ///
647 /// This method returns the same errors as [`AsyncReadExt::read_exact`].
648 ///
649 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
650 ///
651 /// # Examples
652 ///
653 /// Read signed 128-bit big-endian integers from a `AsyncRead`:
654 ///
655 /// ```rust
656 /// use tokio::io::{self, AsyncReadExt};
657 ///
658 /// use std::io::Cursor;
659 ///
660 /// #[tokio::main]
661 /// async fn main() -> io::Result<()> {
662 /// let mut reader = Cursor::new(vec![
663 /// 0x80, 0, 0, 0, 0, 0, 0, 0,
664 /// 0, 0, 0, 0, 0, 0, 0, 0
665 /// ]);
666 ///
667 /// assert_eq!(i128::min_value(), reader.read_i128().await?);
668 /// Ok(())
669 /// }
670 /// ```
671 fn read_i128(&mut self) -> ReadI128;
672 }
673
674 /// Read all bytes until EOF in this source, placing them into `buf`.
675 ///
676 /// Equivalent to:
677 ///
678 /// ```ignore
679 /// async fn read_to_end(&mut self, buf: &mut Vec<u8>) -> io::Result<usize>;
680 /// ```
681 ///
682 /// All bytes read from this source will be appended to the specified
683 /// buffer `buf`. This function will continuously call [`read()`] to
684 /// append more data to `buf` until [`read()`][read] returns `Ok(0)`.
685 ///
686 /// If successful, the total number of bytes read is returned.
687 ///
688 /// # Errors
689 ///
690 /// If a read error is encountered then the `read_to_end` operation
691 /// immediately completes. Any bytes which have already been read will
692 /// be appended to `buf`.
693 ///
694 /// # Examples
695 ///
696 /// [`File`][crate::fs::File]s implement `Read`:
697 ///
698 /// ```no_run
699 /// use tokio::io::{self, AsyncReadExt};
700 /// use tokio::fs::File;
701 ///
702 /// #[tokio::main]
703 /// async fn main() -> io::Result<()> {
704 /// let mut f = File::open("foo.txt").await?;
705 /// let mut buffer = Vec::new();
706 ///
707 /// // read the whole file
708 /// f.read_to_end(&mut buffer).await?;
709 /// Ok(())
710 /// }
711 /// ```
712 ///
713 /// (See also the [`tokio::fs::read`] convenience function for reading from a
714 /// file.)
715 ///
716 /// [`tokio::fs::read`]: crate::fs::read::read
717 fn read_to_end<'a>(&'a mut self, buf: &'a mut Vec<u8>) -> ReadToEnd<'a, Self>
718 where
719 Self: Unpin,
720 {
721 read_to_end(self, buf)
722 }
723
724 /// Read all bytes until EOF in this source, appending them to `buf`.
725 ///
726 /// Equivalent to:
727 ///
728 /// ```ignore
729 /// async fn read_to_string(&mut self, buf: &mut String) -> io::Result<usize>;
730 /// ```
731 ///
732 /// If successful, the number of bytes which were read and appended to
733 /// `buf` is returned.
734 ///
735 /// # Errors
736 ///
737 /// If the data in this stream is *not* valid UTF-8 then an error is
738 /// returned and `buf` is unchanged.
739 ///
740 /// See [`read_to_end`][AsyncReadExt::read_to_end] for other error semantics.
741 ///
742 /// # Examples
743 ///
744 /// [`File`][crate::fs::File]s implement `Read`:
745 ///
746 /// ```no_run
747 /// use tokio::io::{self, AsyncReadExt};
748 /// use tokio::fs::File;
749 ///
750 /// #[tokio::main]
751 /// async fn main() -> io::Result<()> {
752 /// let mut f = File::open("foo.txt").await?;
753 /// let mut buffer = String::new();
754 ///
755 /// f.read_to_string(&mut buffer).await?;
756 /// Ok(())
757 /// }
758 /// ```
759 ///
760 /// (See also the [`crate::fs::read_to_string`] convenience function for
761 /// reading from a file.)
762 ///
763 /// [`crate::fs::read_to_string`]: crate::fs::read_to_string::read_to_string
764 fn read_to_string<'a>(&'a mut self, dst: &'a mut String) -> ReadToString<'a, Self>
765 where
766 Self: Unpin,
767 {
768 read_to_string(self, dst)
769 }
770
771 /// Creates an adaptor which reads at most `limit` bytes from it.
772 ///
773 /// This function returns a new instance of `AsyncRead` which will read
774 /// at most `limit` bytes, after which it will always return EOF
775 /// (`Ok(0)`). Any read errors will not count towards the number of
776 /// bytes read and future calls to [`read()`][read] may succeed.
777 ///
778 /// # Examples
779 ///
780 /// [`File`][crate::fs::File]s implement `Read`:
781 ///
782 /// ```no_run
783 /// use tokio::io::{self, AsyncReadExt};
784 /// use tokio::fs::File;
785 ///
786 /// #[tokio::main]
787 /// async fn main() -> io::Result<()> {
788 /// let f = File::open("foo.txt").await?;
789 /// let mut buffer = [0; 5];
790 ///
791 /// // read at most five bytes
792 /// let mut handle = f.take(5);
793 ///
794 /// handle.read(&mut buffer).await?;
795 /// Ok(())
796 /// }
797 /// ```
798 fn take(self, limit: u64) -> Take<Self>
799 where
800 Self: Sized,
801 {
802 take(self, limit)
803 }
804 }
805}
806
807impl<R: AsyncRead + ?Sized> AsyncReadExt for R {}