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