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