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