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