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