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<'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 1294 impl<R: AsyncRead + ?Sized> AsyncReadExt for R {} 1295