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