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::{ReadF32, ReadF32Le, ReadF64, ReadF64Le};
6use crate::io::util::read_int::{
7 ReadI128, ReadI128Le, ReadI16, ReadI16Le, ReadI32, ReadI32Le, ReadI64, ReadI64Le, ReadI8,
8};
9use crate::io::util::read_int::{
10 ReadU128, ReadU128Le, ReadU16, ReadU16Le, ReadU32, ReadU32Le, ReadU64, ReadU64Le, ReadU8,
11};
12use crate::io::util::read_to_end::{read_to_end, ReadToEnd};
13use crate::io::util::read_to_string::{read_to_string, ReadToString};
14use crate::io::util::take::{take, Take};
15use crate::io::AsyncRead;
16
17use bytes::BufMut;
18
19cfg_io_util! {
20 /// Defines numeric reader
21 macro_rules! read_impl {
22 (
23 $(
24 $(#[$outer:meta])*
25 fn $name:ident(&mut self) -> $($fut:ident)*;
26 )*
27 ) => {
28 $(
29 $(#[$outer])*
30 fn $name(&mut self) -> $($fut)*<&mut Self> where Self: Unpin {
31 $($fut)*::new(self)
32 }
33 )*
34 }
35 }
36
37 /// Reads bytes from a source.
38 ///
39 /// Implemented as an extension trait, adding utility methods to all
40 /// [`AsyncRead`] types. Callers will tend to import this trait instead of
41 /// [`AsyncRead`].
42 ///
43 /// ```no_run
44 /// use tokio::fs::File;
45 /// use tokio::io::{self, AsyncReadExt};
46 ///
47 /// #[tokio::main]
48 /// async fn main() -> io::Result<()> {
49 /// let mut f = File::open("foo.txt").await?;
50 /// let mut buffer = [0; 10];
51 ///
52 /// // The `read` method is defined by this trait.
53 /// let n = f.read(&mut buffer[..]).await?;
54 ///
55 /// Ok(())
56 /// }
57 /// ```
58 ///
59 /// See [module][crate::io] documentation for more details.
60 ///
61 /// [`AsyncRead`]: AsyncRead
62 pub trait AsyncReadExt: AsyncRead {
63 /// Creates a new `AsyncRead` instance that chains this stream with
64 /// `next`.
65 ///
66 /// The returned `AsyncRead` instance will first read all bytes from this object
67 /// until EOF is encountered. Afterwards the output is equivalent to the
68 /// output of `next`.
69 ///
70 /// # Examples
71 ///
72 /// [`File`][crate::fs::File]s implement `AsyncRead`:
73 ///
74 /// ```no_run
75 /// use tokio::fs::File;
76 /// use tokio::io::{self, AsyncReadExt};
77 ///
78 /// #[tokio::main]
79 /// async fn main() -> io::Result<()> {
80 /// let f1 = File::open("foo.txt").await?;
81 /// let f2 = File::open("bar.txt").await?;
82 ///
83 /// let mut handle = f1.chain(f2);
84 /// let mut buffer = String::new();
85 ///
86 /// // read the value into a String. We could use any AsyncRead
87 /// // method here, this is just one example.
88 /// handle.read_to_string(&mut buffer).await?;
89 /// Ok(())
90 /// }
91 /// ```
92 fn chain<R>(self, next: R) -> Chain<Self, R>
93 where
94 Self: Sized,
95 R: AsyncRead,
96 {
97 chain(self, next)
98 }
99
100 /// Pulls some bytes from this source into the specified buffer,
101 /// returning how many bytes were read.
102 ///
103 /// Equivalent to:
104 ///
105 /// ```ignore
106 /// async fn read(&mut self, buf: &mut [u8]) -> io::Result<usize>;
107 /// ```
108 ///
109 /// This method does not provide any guarantees about whether it
110 /// completes immediately or asynchronously.
111 ///
112 /// # Return
113 ///
114 /// If the return value of this method is `Ok(n)`, then it must be
115 /// guaranteed that `0 <= n <= buf.len()`. A nonzero `n` value indicates
116 /// that the buffer `buf` has been filled in with `n` bytes of data from
117 /// this source. If `n` is `0`, then it can indicate one of two
118 /// scenarios:
119 ///
120 /// 1. This reader has reached its "end of file" and will likely no longer
121 /// be able to produce bytes. Note that this does not mean that the
122 /// reader will *always* no longer be able to produce bytes.
123 /// 2. The buffer specified was 0 bytes in length.
124 ///
125 /// No guarantees are provided about the contents of `buf` when this
126 /// function is called, implementations cannot rely on any property of the
127 /// contents of `buf` being true. It is recommended that *implementations*
128 /// only write data to `buf` instead of reading its contents.
129 ///
130 /// Correspondingly, however, *callers* of this method may not assume
131 /// any guarantees about how the implementation uses `buf`. It is
132 /// possible that the code that's supposed to write to the buffer might
133 /// also read from it. It is your responsibility to make sure that `buf`
134 /// is initialized before calling `read`.
135 ///
136 /// # Errors
137 ///
138 /// If this function encounters any form of I/O or other error, an error
139 /// variant will be returned. If an error is returned then it must be
140 /// guaranteed that no bytes were read.
141 ///
142 /// # Cancel safety
143 ///
144 /// This method is cancel safe. If you use it as the event in a
145 /// [`tokio::select!`](crate::select) statement and some other branch
146 /// completes first, then it is guaranteed that no data was read.
147 ///
148 /// # Examples
149 ///
150 /// [`File`][crate::fs::File]s implement `Read`:
151 ///
152 /// ```no_run
153 /// use tokio::fs::File;
154 /// use tokio::io::{self, AsyncReadExt};
155 ///
156 /// #[tokio::main]
157 /// async fn main() -> io::Result<()> {
158 /// let mut f = File::open("foo.txt").await?;
159 /// let mut buffer = [0; 10];
160 ///
161 /// // read up to 10 bytes
162 /// let n = f.read(&mut buffer[..]).await?;
163 ///
164 /// println!("The bytes: {:?}", &buffer[..n]);
165 /// Ok(())
166 /// }
167 /// ```
168 fn read<'a>(&'a mut self, buf: &'a mut [u8]) -> Read<'a, Self>
169 where
170 Self: Unpin,
171 {
172 read(self, buf)
173 }
174
175 /// Pulls some bytes from this source into the specified buffer,
176 /// advancing the buffer's internal cursor.
177 ///
178 /// Equivalent to:
179 ///
180 /// ```ignore
181 /// async fn read_buf<B: BufMut>(&mut self, buf: &mut B) -> io::Result<usize>;
182 /// ```
183 ///
184 /// Usually, only a single `read` syscall is issued, even if there is
185 /// more space in the supplied buffer.
186 ///
187 /// This method does not provide any guarantees about whether it
188 /// completes immediately or asynchronously.
189 ///
190 /// # Return
191 ///
192 /// A nonzero `n` value indicates that the buffer `buf` has been filled
193 /// in with `n` bytes of data from this source. If `n` is `0`, then it
194 /// can indicate one of two scenarios:
195 ///
196 /// 1. This reader has reached its "end of file" and will likely no longer
197 /// be able to produce bytes. Note that this does not mean that the
198 /// reader will *always* no longer be able to produce bytes.
199 /// 2. The buffer specified had a remaining capacity of zero.
200 ///
201 /// # Errors
202 ///
203 /// If this function encounters any form of I/O or other error, an error
204 /// variant will be returned. If an error is returned then it must be
205 /// guaranteed that no bytes were read.
206 ///
207 /// # Cancel safety
208 ///
209 /// This method is cancel safe. If you use it as the event in a
210 /// [`tokio::select!`](crate::select) statement and some other branch
211 /// completes first, then it is guaranteed that no data was read.
212 ///
213 /// # Examples
214 ///
215 /// [`File`] implements `Read` and [`BytesMut`] implements [`BufMut`]:
216 ///
217 /// [`File`]: crate::fs::File
218 /// [`BytesMut`]: bytes::BytesMut
219 /// [`BufMut`]: bytes::BufMut
220 ///
221 /// ```no_run
222 /// use tokio::fs::File;
223 /// use tokio::io::{self, AsyncReadExt};
224 ///
225 /// use bytes::BytesMut;
226 ///
227 /// #[tokio::main]
228 /// async fn main() -> io::Result<()> {
229 /// let mut f = File::open("foo.txt").await?;
230 /// let mut buffer = BytesMut::with_capacity(10);
231 ///
232 /// assert!(buffer.is_empty());
233 /// assert!(buffer.capacity() >= 10);
234 ///
235 /// // note that the return value is not needed to access the data
236 /// // that was read as `buffer`'s internal cursor is updated.
237 /// //
238 /// // this might read more than 10 bytes if the capacity of `buffer`
239 /// // is larger than 10.
240 /// f.read_buf(&mut buffer).await?;
241 ///
242 /// println!("The bytes: {:?}", &buffer[..]);
243 /// Ok(())
244 /// }
245 /// ```
246 fn read_buf<'a, B>(&'a mut self, buf: &'a mut B) -> ReadBuf<'a, Self, B>
247 where
248 Self: Unpin,
249 B: BufMut + ?Sized,
250 {
251 read_buf(self, buf)
252 }
253
254 /// Reads the exact number of bytes required to fill `buf`.
255 ///
256 /// Equivalent to:
257 ///
258 /// ```ignore
259 /// async fn read_exact(&mut self, buf: &mut [u8]) -> io::Result<usize>;
260 /// ```
261 ///
262 /// This function reads as many bytes as necessary to completely fill
263 /// the specified buffer `buf`.
264 ///
265 /// # Errors
266 ///
267 /// If the operation encounters an "end of file" before completely
268 /// filling the buffer, it returns an error of the kind
269 /// [`ErrorKind::UnexpectedEof`]. The contents of `buf` are unspecified
270 /// in this case.
271 ///
272 /// If any other read error is encountered then the operation
273 /// immediately returns. The contents of `buf` are unspecified in this
274 /// case.
275 ///
276 /// If this operation returns an error, it is unspecified how many bytes
277 /// it has read, but it will never read more than would be necessary to
278 /// completely fill the buffer.
279 ///
280 /// # Cancel safety
281 ///
282 /// This method is not cancellation safe. If the method is used as the
283 /// event in a [`tokio::select!`](crate::select) statement and some
284 /// other branch completes first, then some data may already have been
285 /// read into `buf`.
286 ///
287 /// # Examples
288 ///
289 /// [`File`][crate::fs::File]s implement `Read`:
290 ///
291 /// ```no_run
292 /// use tokio::fs::File;
293 /// use tokio::io::{self, AsyncReadExt};
294 ///
295 /// #[tokio::main]
296 /// async fn main() -> io::Result<()> {
297 /// let mut f = File::open("foo.txt").await?;
298 /// let len = 10;
299 /// let mut buffer = vec![0; len];
300 ///
301 /// // read exactly 10 bytes
302 /// f.read_exact(&mut buffer).await?;
303 /// Ok(())
304 /// }
305 /// ```
306 ///
307 /// [`ErrorKind::UnexpectedEof`]: std::io::ErrorKind::UnexpectedEof
308 fn read_exact<'a>(&'a mut self, buf: &'a mut [u8]) -> ReadExact<'a, Self>
309 where
310 Self: Unpin,
311 {
312 read_exact(self, buf)
313 }
314
315 read_impl! {
316 /// Reads an unsigned 8 bit integer from the underlying reader.
317 ///
318 /// Equivalent to:
319 ///
320 /// ```ignore
321 /// async fn read_u8(&mut self) -> io::Result<u8>;
322 /// ```
323 ///
324 /// It is recommended to use a buffered reader to avoid excessive
325 /// syscalls.
326 ///
327 /// # Errors
328 ///
329 /// This method returns the same errors as [`AsyncReadExt::read_exact`].
330 ///
331 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
332 ///
333 /// # Cancel safety
334 ///
335 /// This method is cancel safe. If this method is used as an event in a
336 /// [`tokio::select!`](crate::select) statement and some other branch
337 /// completes first, it is guaranteed that no data were read.
338 ///
339 /// # Examples
340 ///
341 /// Read unsigned 8 bit integers from an `AsyncRead`:
342 ///
343 /// ```rust
344 /// use tokio::io::{self, AsyncReadExt};
345 ///
346 /// use std::io::Cursor;
347 ///
348 /// #[tokio::main]
349 /// async fn main() -> io::Result<()> {
350 /// let mut reader = Cursor::new(vec![2, 5]);
351 ///
352 /// assert_eq!(2, reader.read_u8().await?);
353 /// assert_eq!(5, reader.read_u8().await?);
354 ///
355 /// Ok(())
356 /// }
357 /// ```
358 fn read_u8(&mut self) -> ReadU8;
359
360 /// Reads a signed 8 bit integer from the underlying reader.
361 ///
362 /// Equivalent to:
363 ///
364 /// ```ignore
365 /// async fn read_i8(&mut self) -> io::Result<i8>;
366 /// ```
367 ///
368 /// It is recommended to use a buffered reader to avoid excessive
369 /// syscalls.
370 ///
371 /// # Errors
372 ///
373 /// This method returns the same errors as [`AsyncReadExt::read_exact`].
374 ///
375 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
376 ///
377 /// # Cancel safety
378 ///
379 /// This method is cancel safe. If this method is used as an event in a
380 /// [`tokio::select!`](crate::select) statement and some other branch
381 /// completes first, it is guaranteed that no data were read.
382 ///
383 /// # Examples
384 ///
385 /// Read unsigned 8 bit integers from an `AsyncRead`:
386 ///
387 /// ```rust
388 /// use tokio::io::{self, AsyncReadExt};
389 ///
390 /// use std::io::Cursor;
391 ///
392 /// #[tokio::main]
393 /// async fn main() -> io::Result<()> {
394 /// let mut reader = Cursor::new(vec![0x02, 0xfb]);
395 ///
396 /// assert_eq!(2, reader.read_i8().await?);
397 /// assert_eq!(-5, reader.read_i8().await?);
398 ///
399 /// Ok(())
400 /// }
401 /// ```
402 fn read_i8(&mut self) -> ReadI8;
403
404 /// Reads an unsigned 16-bit integer in big-endian order from the
405 /// underlying reader.
406 ///
407 /// Equivalent to:
408 ///
409 /// ```ignore
410 /// async fn read_u16(&mut self) -> io::Result<u16>;
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 /// # Cancel safety
423 ///
424 /// This method is not cancellation safe. If the method is used as the
425 /// event in a [`tokio::select!`](crate::select) statement and some
426 /// other branch completes first, then some data may be lost.
427 ///
428 /// # Examples
429 ///
430 /// Read unsigned 16 bit big-endian integers from a `AsyncRead`:
431 ///
432 /// ```rust
433 /// use tokio::io::{self, AsyncReadExt};
434 ///
435 /// use std::io::Cursor;
436 ///
437 /// #[tokio::main]
438 /// async fn main() -> io::Result<()> {
439 /// let mut reader = Cursor::new(vec![2, 5, 3, 0]);
440 ///
441 /// assert_eq!(517, reader.read_u16().await?);
442 /// assert_eq!(768, reader.read_u16().await?);
443 /// Ok(())
444 /// }
445 /// ```
446 fn read_u16(&mut self) -> ReadU16;
447
448 /// Reads a signed 16-bit integer in big-endian order from the
449 /// underlying reader.
450 ///
451 /// Equivalent to:
452 ///
453 /// ```ignore
454 /// async fn read_i16(&mut self) -> io::Result<i16>;
455 /// ```
456 ///
457 /// It is recommended to use a buffered reader to avoid excessive
458 /// syscalls.
459 ///
460 /// # Errors
461 ///
462 /// This method returns the same errors as [`AsyncReadExt::read_exact`].
463 ///
464 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
465 ///
466 /// # Cancel safety
467 ///
468 /// This method is not cancellation safe. If the method is used as the
469 /// event in a [`tokio::select!`](crate::select) statement and some
470 /// other branch completes first, then some data may be lost.
471 ///
472 /// # Examples
473 ///
474 /// Read signed 16 bit big-endian integers from a `AsyncRead`:
475 ///
476 /// ```rust
477 /// use tokio::io::{self, AsyncReadExt};
478 ///
479 /// use std::io::Cursor;
480 ///
481 /// #[tokio::main]
482 /// async fn main() -> io::Result<()> {
483 /// let mut reader = Cursor::new(vec![0x00, 0xc1, 0xff, 0x7c]);
484 ///
485 /// assert_eq!(193, reader.read_i16().await?);
486 /// assert_eq!(-132, reader.read_i16().await?);
487 /// Ok(())
488 /// }
489 /// ```
490 fn read_i16(&mut self) -> ReadI16;
491
492 /// Reads an unsigned 32-bit integer in big-endian order from the
493 /// underlying reader.
494 ///
495 /// Equivalent to:
496 ///
497 /// ```ignore
498 /// async fn read_u32(&mut self) -> io::Result<u32>;
499 /// ```
500 ///
501 /// It is recommended to use a buffered reader to avoid excessive
502 /// syscalls.
503 ///
504 /// # Errors
505 ///
506 /// This method returns the same errors as [`AsyncReadExt::read_exact`].
507 ///
508 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
509 ///
510 /// # Cancel safety
511 ///
512 /// This method is not cancellation safe. If the method is used as the
513 /// event in a [`tokio::select!`](crate::select) statement and some
514 /// other branch completes first, then some data may be lost.
515 ///
516 /// # Examples
517 ///
518 /// Read unsigned 32-bit big-endian integers from a `AsyncRead`:
519 ///
520 /// ```rust
521 /// use tokio::io::{self, AsyncReadExt};
522 ///
523 /// use std::io::Cursor;
524 ///
525 /// #[tokio::main]
526 /// async fn main() -> io::Result<()> {
527 /// let mut reader = Cursor::new(vec![0x00, 0x00, 0x01, 0x0b]);
528 ///
529 /// assert_eq!(267, reader.read_u32().await?);
530 /// Ok(())
531 /// }
532 /// ```
533 fn read_u32(&mut self) -> ReadU32;
534
535 /// Reads a signed 32-bit integer in big-endian order from the
536 /// underlying reader.
537 ///
538 ///
539 /// Equivalent to:
540 ///
541 /// ```ignore
542 /// async fn read_i32(&mut self) -> io::Result<i32>;
543 /// ```
544 ///
545 /// It is recommended to use a buffered reader to avoid excessive
546 /// syscalls.
547 ///
548 /// # Errors
549 ///
550 /// This method returns the same errors as [`AsyncReadExt::read_exact`].
551 ///
552 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
553 ///
554 /// # Cancel safety
555 ///
556 /// This method is not cancellation safe. If the method is used as the
557 /// event in a [`tokio::select!`](crate::select) statement and some
558 /// other branch completes first, then some data may be lost.
559 ///
560 /// # Examples
561 ///
562 /// Read signed 32-bit big-endian integers from a `AsyncRead`:
563 ///
564 /// ```rust
565 /// use tokio::io::{self, AsyncReadExt};
566 ///
567 /// use std::io::Cursor;
568 ///
569 /// #[tokio::main]
570 /// async fn main() -> io::Result<()> {
571 /// let mut reader = Cursor::new(vec![0xff, 0xff, 0x7a, 0x33]);
572 ///
573 /// assert_eq!(-34253, reader.read_i32().await?);
574 /// Ok(())
575 /// }
576 /// ```
577 fn read_i32(&mut self) -> ReadI32;
578
579 /// Reads an unsigned 64-bit integer in big-endian order from the
580 /// underlying reader.
581 ///
582 /// Equivalent to:
583 ///
584 /// ```ignore
585 /// async fn read_u64(&mut self) -> io::Result<u64>;
586 /// ```
587 ///
588 /// It is recommended to use a buffered reader to avoid excessive
589 /// syscalls.
590 ///
591 /// # Errors
592 ///
593 /// This method returns the same errors as [`AsyncReadExt::read_exact`].
594 ///
595 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
596 ///
597 /// # Cancel safety
598 ///
599 /// This method is not cancellation safe. If the method is used as the
600 /// event in a [`tokio::select!`](crate::select) statement and some
601 /// other branch completes first, then some data may be lost.
602 ///
603 /// # Examples
604 ///
605 /// Read unsigned 64-bit big-endian integers from a `AsyncRead`:
606 ///
607 /// ```rust
608 /// use tokio::io::{self, AsyncReadExt};
609 ///
610 /// use std::io::Cursor;
611 ///
612 /// #[tokio::main]
613 /// async fn main() -> io::Result<()> {
614 /// let mut reader = Cursor::new(vec![
615 /// 0x00, 0x03, 0x43, 0x95, 0x4d, 0x60, 0x86, 0x83
616 /// ]);
617 ///
618 /// assert_eq!(918733457491587, reader.read_u64().await?);
619 /// Ok(())
620 /// }
621 /// ```
622 fn read_u64(&mut self) -> ReadU64;
623
624 /// Reads an signed 64-bit integer in big-endian order from the
625 /// underlying reader.
626 ///
627 /// Equivalent to:
628 ///
629 /// ```ignore
630 /// async fn read_i64(&mut self) -> io::Result<i64>;
631 /// ```
632 ///
633 /// It is recommended to use a buffered reader to avoid excessive
634 /// syscalls.
635 ///
636 /// # Errors
637 ///
638 /// This method returns the same errors as [`AsyncReadExt::read_exact`].
639 ///
640 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
641 ///
642 /// # Cancel safety
643 ///
644 /// This method is not cancellation safe. If the method is used as the
645 /// event in a [`tokio::select!`](crate::select) statement and some
646 /// other branch completes first, then some data may be lost.
647 ///
648 /// # Examples
649 ///
650 /// Read signed 64-bit big-endian integers from a `AsyncRead`:
651 ///
652 /// ```rust
653 /// use tokio::io::{self, AsyncReadExt};
654 ///
655 /// use std::io::Cursor;
656 ///
657 /// #[tokio::main]
658 /// async fn main() -> io::Result<()> {
659 /// let mut reader = Cursor::new(vec![0x80, 0, 0, 0, 0, 0, 0, 0]);
660 ///
661 /// assert_eq!(i64::MIN, reader.read_i64().await?);
662 /// Ok(())
663 /// }
664 /// ```
665 fn read_i64(&mut self) -> ReadI64;
666
667 /// Reads an unsigned 128-bit integer in big-endian order from the
668 /// underlying reader.
669 ///
670 /// Equivalent to:
671 ///
672 /// ```ignore
673 /// async fn read_u128(&mut self) -> io::Result<u128>;
674 /// ```
675 ///
676 /// It is recommended to use a buffered reader to avoid excessive
677 /// syscalls.
678 ///
679 /// # Errors
680 ///
681 /// This method returns the same errors as [`AsyncReadExt::read_exact`].
682 ///
683 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
684 ///
685 /// # Cancel safety
686 ///
687 /// This method is not cancellation safe. If the method is used as the
688 /// event in a [`tokio::select!`](crate::select) statement and some
689 /// other branch completes first, then some data may be lost.
690 ///
691 /// # Examples
692 ///
693 /// Read unsigned 128-bit big-endian integers from a `AsyncRead`:
694 ///
695 /// ```rust
696 /// use tokio::io::{self, AsyncReadExt};
697 ///
698 /// use std::io::Cursor;
699 ///
700 /// #[tokio::main]
701 /// async fn main() -> io::Result<()> {
702 /// let mut reader = Cursor::new(vec![
703 /// 0x00, 0x03, 0x43, 0x95, 0x4d, 0x60, 0x86, 0x83,
704 /// 0x00, 0x03, 0x43, 0x95, 0x4d, 0x60, 0x86, 0x83
705 /// ]);
706 ///
707 /// assert_eq!(16947640962301618749969007319746179, reader.read_u128().await?);
708 /// Ok(())
709 /// }
710 /// ```
711 fn read_u128(&mut self) -> ReadU128;
712
713 /// Reads an signed 128-bit integer in big-endian order from the
714 /// underlying reader.
715 ///
716 /// Equivalent to:
717 ///
718 /// ```ignore
719 /// async fn read_i128(&mut self) -> io::Result<i128>;
720 /// ```
721 ///
722 /// It is recommended to use a buffered reader to avoid excessive
723 /// syscalls.
724 ///
725 /// # Errors
726 ///
727 /// This method returns the same errors as [`AsyncReadExt::read_exact`].
728 ///
729 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
730 ///
731 /// # Cancel safety
732 ///
733 /// This method is not cancellation safe. If the method is used as the
734 /// event in a [`tokio::select!`](crate::select) statement and some
735 /// other branch completes first, then some data may be lost.
736 ///
737 /// # Examples
738 ///
739 /// Read signed 128-bit big-endian integers from a `AsyncRead`:
740 ///
741 /// ```rust
742 /// use tokio::io::{self, AsyncReadExt};
743 ///
744 /// use std::io::Cursor;
745 ///
746 /// #[tokio::main]
747 /// async fn main() -> io::Result<()> {
748 /// let mut reader = Cursor::new(vec![
749 /// 0x80, 0, 0, 0, 0, 0, 0, 0,
750 /// 0, 0, 0, 0, 0, 0, 0, 0
751 /// ]);
752 ///
753 /// assert_eq!(i128::MIN, reader.read_i128().await?);
754 /// Ok(())
755 /// }
756 /// ```
757 fn read_i128(&mut self) -> ReadI128;
758
759 /// Reads an 32-bit floating point type in big-endian order from the
760 /// underlying reader.
761 ///
762 /// Equivalent to:
763 ///
764 /// ```ignore
765 /// async fn read_f32(&mut self) -> io::Result<f32>;
766 /// ```
767 ///
768 /// It is recommended to use a buffered reader to avoid excessive
769 /// syscalls.
770 ///
771 /// # Errors
772 ///
773 /// This method returns the same errors as [`AsyncReadExt::read_exact`].
774 ///
775 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
776 ///
777 /// # Cancel safety
778 ///
779 /// This method is not cancellation safe. If the method is used as the
780 /// event in a [`tokio::select!`](crate::select) statement and some
781 /// other branch completes first, then some data may be lost.
782 ///
783 /// # Examples
784 ///
785 /// Read 32-bit floating point type from a `AsyncRead`:
786 ///
787 /// ```rust
788 /// use tokio::io::{self, AsyncReadExt};
789 ///
790 /// use std::io::Cursor;
791 ///
792 /// #[tokio::main]
793 /// async fn main() -> io::Result<()> {
794 /// let mut reader = Cursor::new(vec![0xff, 0x7f, 0xff, 0xff]);
795 ///
796 /// assert_eq!(f32::MIN, reader.read_f32().await?);
797 /// Ok(())
798 /// }
799 /// ```
800 fn read_f32(&mut self) -> ReadF32;
801
802 /// Reads an 64-bit floating point type in big-endian order from the
803 /// underlying reader.
804 ///
805 /// Equivalent to:
806 ///
807 /// ```ignore
808 /// async fn read_f64(&mut self) -> io::Result<f64>;
809 /// ```
810 ///
811 /// It is recommended to use a buffered reader to avoid excessive
812 /// syscalls.
813 ///
814 /// # Errors
815 ///
816 /// This method returns the same errors as [`AsyncReadExt::read_exact`].
817 ///
818 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
819 ///
820 /// # Cancel safety
821 ///
822 /// This method is not cancellation safe. If the method is used as the
823 /// event in a [`tokio::select!`](crate::select) statement and some
824 /// other branch completes first, then some data may be lost.
825 ///
826 /// # Examples
827 ///
828 /// Read 64-bit floating point type from a `AsyncRead`:
829 ///
830 /// ```rust
831 /// use tokio::io::{self, AsyncReadExt};
832 ///
833 /// use std::io::Cursor;
834 ///
835 /// #[tokio::main]
836 /// async fn main() -> io::Result<()> {
837 /// let mut reader = Cursor::new(vec![
838 /// 0xff, 0xef, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff
839 /// ]);
840 ///
841 /// assert_eq!(f64::MIN, reader.read_f64().await?);
842 /// Ok(())
843 /// }
844 /// ```
845 fn read_f64(&mut self) -> ReadF64;
846
847 /// Reads an unsigned 16-bit integer in little-endian order from the
848 /// underlying reader.
849 ///
850 /// Equivalent to:
851 ///
852 /// ```ignore
853 /// async fn read_u16_le(&mut self) -> io::Result<u16>;
854 /// ```
855 ///
856 /// It is recommended to use a buffered reader to avoid excessive
857 /// syscalls.
858 ///
859 /// # Errors
860 ///
861 /// This method returns the same errors as [`AsyncReadExt::read_exact`].
862 ///
863 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
864 ///
865 /// # Cancel safety
866 ///
867 /// This method is not cancellation safe. If the method is used as the
868 /// event in a [`tokio::select!`](crate::select) statement and some
869 /// other branch completes first, then some data may be lost.
870 ///
871 /// # Examples
872 ///
873 /// Read unsigned 16 bit little-endian integers from a `AsyncRead`:
874 ///
875 /// ```rust
876 /// use tokio::io::{self, AsyncReadExt};
877 ///
878 /// use std::io::Cursor;
879 ///
880 /// #[tokio::main]
881 /// async fn main() -> io::Result<()> {
882 /// let mut reader = Cursor::new(vec![2, 5, 3, 0]);
883 ///
884 /// assert_eq!(1282, reader.read_u16_le().await?);
885 /// assert_eq!(3, reader.read_u16_le().await?);
886 /// Ok(())
887 /// }
888 /// ```
889 fn read_u16_le(&mut self) -> ReadU16Le;
890
891 /// Reads a signed 16-bit integer in little-endian order from the
892 /// underlying reader.
893 ///
894 /// Equivalent to:
895 ///
896 /// ```ignore
897 /// async fn read_i16_le(&mut self) -> io::Result<i16>;
898 /// ```
899 ///
900 /// It is recommended to use a buffered reader to avoid excessive
901 /// syscalls.
902 ///
903 /// # Errors
904 ///
905 /// This method returns the same errors as [`AsyncReadExt::read_exact`].
906 ///
907 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
908 ///
909 /// # Cancel safety
910 ///
911 /// This method is not cancellation safe. If the method is used as the
912 /// event in a [`tokio::select!`](crate::select) statement and some
913 /// other branch completes first, then some data may be lost.
914 ///
915 /// # Examples
916 ///
917 /// Read signed 16 bit little-endian integers from a `AsyncRead`:
918 ///
919 /// ```rust
920 /// use tokio::io::{self, AsyncReadExt};
921 ///
922 /// use std::io::Cursor;
923 ///
924 /// #[tokio::main]
925 /// async fn main() -> io::Result<()> {
926 /// let mut reader = Cursor::new(vec![0x00, 0xc1, 0xff, 0x7c]);
927 ///
928 /// assert_eq!(-16128, reader.read_i16_le().await?);
929 /// assert_eq!(31999, reader.read_i16_le().await?);
930 /// Ok(())
931 /// }
932 /// ```
933 fn read_i16_le(&mut self) -> ReadI16Le;
934
935 /// Reads an unsigned 32-bit integer in little-endian order from the
936 /// underlying reader.
937 ///
938 /// Equivalent to:
939 ///
940 /// ```ignore
941 /// async fn read_u32_le(&mut self) -> io::Result<u32>;
942 /// ```
943 ///
944 /// It is recommended to use a buffered reader to avoid excessive
945 /// syscalls.
946 ///
947 /// # Errors
948 ///
949 /// This method returns the same errors as [`AsyncReadExt::read_exact`].
950 ///
951 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
952 ///
953 /// # Cancel safety
954 ///
955 /// This method is not cancellation safe. If the method is used as the
956 /// event in a [`tokio::select!`](crate::select) statement and some
957 /// other branch completes first, then some data may be lost.
958 ///
959 /// # Examples
960 ///
961 /// Read unsigned 32-bit little-endian integers from a `AsyncRead`:
962 ///
963 /// ```rust
964 /// use tokio::io::{self, AsyncReadExt};
965 ///
966 /// use std::io::Cursor;
967 ///
968 /// #[tokio::main]
969 /// async fn main() -> io::Result<()> {
970 /// let mut reader = Cursor::new(vec![0x00, 0x00, 0x01, 0x0b]);
971 ///
972 /// assert_eq!(184614912, reader.read_u32_le().await?);
973 /// Ok(())
974 /// }
975 /// ```
976 fn read_u32_le(&mut self) -> ReadU32Le;
977
978 /// Reads a signed 32-bit integer in little-endian order from the
979 /// underlying reader.
980 ///
981 ///
982 /// Equivalent to:
983 ///
984 /// ```ignore
985 /// async fn read_i32_le(&mut self) -> io::Result<i32>;
986 /// ```
987 ///
988 /// It is recommended to use a buffered reader to avoid excessive
989 /// syscalls.
990 ///
991 /// # Errors
992 ///
993 /// This method returns the same errors as [`AsyncReadExt::read_exact`].
994 ///
995 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
996 ///
997 /// # Cancel safety
998 ///
999 /// This method is not cancellation safe. If the method is used as the
1000 /// event in a [`tokio::select!`](crate::select) statement and some
1001 /// other branch completes first, then some data may be lost.
1002 ///
1003 /// # Examples
1004 ///
1005 /// Read signed 32-bit little-endian integers from a `AsyncRead`:
1006 ///
1007 /// ```rust
1008 /// use tokio::io::{self, AsyncReadExt};
1009 ///
1010 /// use std::io::Cursor;
1011 ///
1012 /// #[tokio::main]
1013 /// async fn main() -> io::Result<()> {
1014 /// let mut reader = Cursor::new(vec![0xff, 0xff, 0x7a, 0x33]);
1015 ///
1016 /// assert_eq!(863698943, reader.read_i32_le().await?);
1017 /// Ok(())
1018 /// }
1019 /// ```
1020 fn read_i32_le(&mut self) -> ReadI32Le;
1021
1022 /// Reads an unsigned 64-bit integer in little-endian order from the
1023 /// underlying reader.
1024 ///
1025 /// Equivalent to:
1026 ///
1027 /// ```ignore
1028 /// async fn read_u64_le(&mut self) -> io::Result<u64>;
1029 /// ```
1030 ///
1031 /// It is recommended to use a buffered reader to avoid excessive
1032 /// syscalls.
1033 ///
1034 /// # Errors
1035 ///
1036 /// This method returns the same errors as [`AsyncReadExt::read_exact`].
1037 ///
1038 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
1039 ///
1040 /// # Cancel safety
1041 ///
1042 /// This method is not cancellation safe. If the method is used as the
1043 /// event in a [`tokio::select!`](crate::select) statement and some
1044 /// other branch completes first, then some data may be lost.
1045 ///
1046 /// # Examples
1047 ///
1048 /// Read unsigned 64-bit little-endian integers from a `AsyncRead`:
1049 ///
1050 /// ```rust
1051 /// use tokio::io::{self, AsyncReadExt};
1052 ///
1053 /// use std::io::Cursor;
1054 ///
1055 /// #[tokio::main]
1056 /// async fn main() -> io::Result<()> {
1057 /// let mut reader = Cursor::new(vec![
1058 /// 0x00, 0x03, 0x43, 0x95, 0x4d, 0x60, 0x86, 0x83
1059 /// ]);
1060 ///
1061 /// assert_eq!(9477368352180732672, reader.read_u64_le().await?);
1062 /// Ok(())
1063 /// }
1064 /// ```
1065 fn read_u64_le(&mut self) -> ReadU64Le;
1066
1067 /// Reads an signed 64-bit integer in little-endian order from the
1068 /// underlying reader.
1069 ///
1070 /// Equivalent to:
1071 ///
1072 /// ```ignore
1073 /// async fn read_i64_le(&mut self) -> io::Result<i64>;
1074 /// ```
1075 ///
1076 /// It is recommended to use a buffered reader to avoid excessive
1077 /// syscalls.
1078 ///
1079 /// # Errors
1080 ///
1081 /// This method returns the same errors as [`AsyncReadExt::read_exact`].
1082 ///
1083 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
1084 ///
1085 /// # Cancel safety
1086 ///
1087 /// This method is not cancellation safe. If the method is used as the
1088 /// event in a [`tokio::select!`](crate::select) statement and some
1089 /// other branch completes first, then some data may be lost.
1090 ///
1091 /// # Examples
1092 ///
1093 /// Read signed 64-bit little-endian integers from a `AsyncRead`:
1094 ///
1095 /// ```rust
1096 /// use tokio::io::{self, AsyncReadExt};
1097 ///
1098 /// use std::io::Cursor;
1099 ///
1100 /// #[tokio::main]
1101 /// async fn main() -> io::Result<()> {
1102 /// let mut reader = Cursor::new(vec![0x80, 0, 0, 0, 0, 0, 0, 0]);
1103 ///
1104 /// assert_eq!(128, reader.read_i64_le().await?);
1105 /// Ok(())
1106 /// }
1107 /// ```
1108 fn read_i64_le(&mut self) -> ReadI64Le;
1109
1110 /// Reads an unsigned 128-bit integer in little-endian order from the
1111 /// underlying reader.
1112 ///
1113 /// Equivalent to:
1114 ///
1115 /// ```ignore
1116 /// async fn read_u128_le(&mut self) -> io::Result<u128>;
1117 /// ```
1118 ///
1119 /// It is recommended to use a buffered reader to avoid excessive
1120 /// syscalls.
1121 ///
1122 /// # Errors
1123 ///
1124 /// This method returns the same errors as [`AsyncReadExt::read_exact`].
1125 ///
1126 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
1127 ///
1128 /// # Cancel safety
1129 ///
1130 /// This method is not cancellation safe. If the method is used as the
1131 /// event in a [`tokio::select!`](crate::select) statement and some
1132 /// other branch completes first, then some data may be lost.
1133 ///
1134 /// # Examples
1135 ///
1136 /// Read unsigned 128-bit little-endian integers from a `AsyncRead`:
1137 ///
1138 /// ```rust
1139 /// use tokio::io::{self, AsyncReadExt};
1140 ///
1141 /// use std::io::Cursor;
1142 ///
1143 /// #[tokio::main]
1144 /// async fn main() -> io::Result<()> {
1145 /// let mut reader = Cursor::new(vec![
1146 /// 0x00, 0x03, 0x43, 0x95, 0x4d, 0x60, 0x86, 0x83,
1147 /// 0x00, 0x03, 0x43, 0x95, 0x4d, 0x60, 0x86, 0x83
1148 /// ]);
1149 ///
1150 /// assert_eq!(174826588484952389081207917399662330624, reader.read_u128_le().await?);
1151 /// Ok(())
1152 /// }
1153 /// ```
1154 fn read_u128_le(&mut self) -> ReadU128Le;
1155
1156 /// Reads an signed 128-bit integer in little-endian order from the
1157 /// underlying reader.
1158 ///
1159 /// Equivalent to:
1160 ///
1161 /// ```ignore
1162 /// async fn read_i128_le(&mut self) -> io::Result<i128>;
1163 /// ```
1164 ///
1165 /// It is recommended to use a buffered reader to avoid excessive
1166 /// syscalls.
1167 ///
1168 /// # Errors
1169 ///
1170 /// This method returns the same errors as [`AsyncReadExt::read_exact`].
1171 ///
1172 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
1173 ///
1174 /// # Cancel safety
1175 ///
1176 /// This method is not cancellation safe. If the method is used as the
1177 /// event in a [`tokio::select!`](crate::select) statement and some
1178 /// other branch completes first, then some data may be lost.
1179 ///
1180 /// # Examples
1181 ///
1182 /// Read signed 128-bit little-endian integers from a `AsyncRead`:
1183 ///
1184 /// ```rust
1185 /// use tokio::io::{self, AsyncReadExt};
1186 ///
1187 /// use std::io::Cursor;
1188 ///
1189 /// #[tokio::main]
1190 /// async fn main() -> io::Result<()> {
1191 /// let mut reader = Cursor::new(vec![
1192 /// 0x80, 0, 0, 0, 0, 0, 0, 0,
1193 /// 0, 0, 0, 0, 0, 0, 0, 0
1194 /// ]);
1195 ///
1196 /// assert_eq!(128, reader.read_i128_le().await?);
1197 /// Ok(())
1198 /// }
1199 /// ```
1200 fn read_i128_le(&mut self) -> ReadI128Le;
1201
1202 /// Reads an 32-bit floating point type in little-endian order from the
1203 /// underlying reader.
1204 ///
1205 /// Equivalent to:
1206 ///
1207 /// ```ignore
1208 /// async fn read_f32_le(&mut self) -> io::Result<f32>;
1209 /// ```
1210 ///
1211 /// It is recommended to use a buffered reader to avoid excessive
1212 /// syscalls.
1213 ///
1214 /// # Errors
1215 ///
1216 /// This method returns the same errors as [`AsyncReadExt::read_exact`].
1217 ///
1218 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
1219 ///
1220 /// # Cancel safety
1221 ///
1222 /// This method is not cancellation safe. If the method is used as the
1223 /// event in a [`tokio::select!`](crate::select) statement and some
1224 /// other branch completes first, then some data may be lost.
1225 ///
1226 /// # Examples
1227 ///
1228 /// Read 32-bit floating point type from a `AsyncRead`:
1229 ///
1230 /// ```rust
1231 /// use tokio::io::{self, AsyncReadExt};
1232 ///
1233 /// use std::io::Cursor;
1234 ///
1235 /// #[tokio::main]
1236 /// async fn main() -> io::Result<()> {
1237 /// let mut reader = Cursor::new(vec![0xff, 0xff, 0x7f, 0xff]);
1238 ///
1239 /// assert_eq!(f32::MIN, reader.read_f32_le().await?);
1240 /// Ok(())
1241 /// }
1242 /// ```
1243 fn read_f32_le(&mut self) -> ReadF32Le;
1244
1245 /// Reads an 64-bit floating point type in little-endian order from the
1246 /// underlying reader.
1247 ///
1248 /// Equivalent to:
1249 ///
1250 /// ```ignore
1251 /// async fn read_f64_le(&mut self) -> io::Result<f64>;
1252 /// ```
1253 ///
1254 /// It is recommended to use a buffered reader to avoid excessive
1255 /// syscalls.
1256 ///
1257 /// # Errors
1258 ///
1259 /// This method returns the same errors as [`AsyncReadExt::read_exact`].
1260 ///
1261 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
1262 ///
1263 /// # Cancel safety
1264 ///
1265 /// This method is not cancellation safe. If the method is used as the
1266 /// event in a [`tokio::select!`](crate::select) statement and some
1267 /// other branch completes first, then some data may be lost.
1268 ///
1269 /// # Examples
1270 ///
1271 /// Read 64-bit floating point type from a `AsyncRead`:
1272 ///
1273 /// ```rust
1274 /// use tokio::io::{self, AsyncReadExt};
1275 ///
1276 /// use std::io::Cursor;
1277 ///
1278 /// #[tokio::main]
1279 /// async fn main() -> io::Result<()> {
1280 /// let mut reader = Cursor::new(vec![
1281 /// 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xef, 0xff
1282 /// ]);
1283 ///
1284 /// assert_eq!(f64::MIN, reader.read_f64_le().await?);
1285 /// Ok(())
1286 /// }
1287 /// ```
1288 fn read_f64_le(&mut self) -> ReadF64Le;
1289 }
1290
1291 /// Reads all bytes until EOF in this source, placing them into `buf`.
1292 ///
1293 /// Equivalent to:
1294 ///
1295 /// ```ignore
1296 /// async fn read_to_end(&mut self, buf: &mut Vec<u8>) -> io::Result<usize>;
1297 /// ```
1298 ///
1299 /// All bytes read from this source will be appended to the specified
1300 /// buffer `buf`. This function will continuously call [`read()`] to
1301 /// append more data to `buf` until [`read()`] returns `Ok(0)`.
1302 ///
1303 /// If successful, the total number of bytes read is returned.
1304 ///
1305 /// [`read()`]: AsyncReadExt::read
1306 ///
1307 /// # Errors
1308 ///
1309 /// If a read error is encountered then the `read_to_end` operation
1310 /// immediately completes. Any bytes which have already been read will
1311 /// be appended to `buf`.
1312 ///
1313 /// # Examples
1314 ///
1315 /// [`File`][crate::fs::File]s implement `Read`:
1316 ///
1317 /// ```no_run
1318 /// use tokio::io::{self, AsyncReadExt};
1319 /// use tokio::fs::File;
1320 ///
1321 /// #[tokio::main]
1322 /// async fn main() -> io::Result<()> {
1323 /// let mut f = File::open("foo.txt").await?;
1324 /// let mut buffer = Vec::new();
1325 ///
1326 /// // read the whole file
1327 /// f.read_to_end(&mut buffer).await?;
1328 /// Ok(())
1329 /// }
1330 /// ```
1331 ///
1332 /// (See also the [`tokio::fs::read`] convenience function for reading from a
1333 /// file.)
1334 ///
1335 /// [`tokio::fs::read`]: fn@crate::fs::read
1336 fn read_to_end<'a>(&'a mut self, buf: &'a mut Vec<u8>) -> ReadToEnd<'a, Self>
1337 where
1338 Self: Unpin,
1339 {
1340 read_to_end(self, buf)
1341 }
1342
1343 /// Reads all bytes until EOF in this source, appending them to `buf`.
1344 ///
1345 /// Equivalent to:
1346 ///
1347 /// ```ignore
1348 /// async fn read_to_string(&mut self, buf: &mut String) -> io::Result<usize>;
1349 /// ```
1350 ///
1351 /// If successful, the number of bytes which were read and appended to
1352 /// `buf` is returned.
1353 ///
1354 /// # Errors
1355 ///
1356 /// If the data in this stream is *not* valid UTF-8 then an error is
1357 /// returned and `buf` is unchanged.
1358 ///
1359 /// See [`read_to_end`][AsyncReadExt::read_to_end] for other error semantics.
1360 ///
1361 /// # Examples
1362 ///
1363 /// [`File`][crate::fs::File]s implement `Read`:
1364 ///
1365 /// ```no_run
1366 /// use tokio::io::{self, AsyncReadExt};
1367 /// use tokio::fs::File;
1368 ///
1369 /// #[tokio::main]
1370 /// async fn main() -> io::Result<()> {
1371 /// let mut f = File::open("foo.txt").await?;
1372 /// let mut buffer = String::new();
1373 ///
1374 /// f.read_to_string(&mut buffer).await?;
1375 /// Ok(())
1376 /// }
1377 /// ```
1378 ///
1379 /// (See also the [`crate::fs::read_to_string`] convenience function for
1380 /// reading from a file.)
1381 ///
1382 /// [`crate::fs::read_to_string`]: fn@crate::fs::read_to_string
1383 fn read_to_string<'a>(&'a mut self, dst: &'a mut String) -> ReadToString<'a, Self>
1384 where
1385 Self: Unpin,
1386 {
1387 read_to_string(self, dst)
1388 }
1389
1390 /// Creates an adaptor which reads at most `limit` bytes from it.
1391 ///
1392 /// This function returns a new instance of `AsyncRead` which will read
1393 /// at most `limit` bytes, after which it will always return EOF
1394 /// (`Ok(0)`). Any read errors will not count towards the number of
1395 /// bytes read and future calls to [`read()`] may succeed.
1396 ///
1397 /// [`read()`]: fn@crate::io::AsyncReadExt::read
1398 ///
1399 /// [read]: AsyncReadExt::read
1400 ///
1401 /// # Examples
1402 ///
1403 /// [`File`][crate::fs::File]s implement `Read`:
1404 ///
1405 /// ```no_run
1406 /// use tokio::io::{self, AsyncReadExt};
1407 /// use tokio::fs::File;
1408 ///
1409 /// #[tokio::main]
1410 /// async fn main() -> io::Result<()> {
1411 /// let f = File::open("foo.txt").await?;
1412 /// let mut buffer = [0; 5];
1413 ///
1414 /// // read at most five bytes
1415 /// let mut handle = f.take(5);
1416 ///
1417 /// handle.read(&mut buffer).await?;
1418 /// Ok(())
1419 /// }
1420 /// ```
1421 fn take(self, limit: u64) -> Take<Self>
1422 where
1423 Self: Sized,
1424 {
1425 take(self, limit)
1426 }
1427 }
1428}
1429
1430impl<R: AsyncRead + ?Sized> AsyncReadExt for R {}
1431