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::{ 6 ReadI128, ReadI128Le, ReadI16, ReadI16Le, ReadI32, ReadI32Le, ReadI64, ReadI64Le, ReadI8, 7 }; 8 use crate::io::util::read_int::{ 9 ReadU128, ReadU128Le, ReadU16, ReadU16Le, ReadU32, ReadU32Le, ReadU64, ReadU64Le, ReadU8, 10 }; 11 use crate::io::util::read_to_end::{read_to_end, ReadToEnd}; 12 use crate::io::util::read_to_string::{read_to_string, ReadToString}; 13 use crate::io::util::take::{take, Take}; 14 use crate::io::AsyncRead; 15 16 use bytes::BufMut; 17 18 cfg_io_util! { 19 /// Defines numeric reader 20 macro_rules! read_impl { 21 ( 22 $( 23 $(#[$outer:meta])* 24 fn $name:ident(&mut self) -> $($fut:ident)*; 25 )* 26 ) => { 27 $( 28 $(#[$outer])* 29 fn $name<'a>(&'a mut self) -> $($fut)*<&'a mut Self> where Self: Unpin { 30 $($fut)*::new(self) 31 } 32 )* 33 } 34 } 35 36 /// Reads bytes from a source. 37 /// 38 /// Implemented as an extention trait, adding utility methods to all 39 /// [`AsyncRead`] types. Callers will tend to import this trait instead of 40 /// [`AsyncRead`]. 41 /// 42 /// As a convenience, this trait may be imported using the [`prelude`]: 43 /// 44 /// ```no_run 45 /// use tokio::fs::File; 46 /// use tokio::prelude::*; 47 /// 48 /// #[tokio::main] 49 /// async fn main() -> io::Result<()> { 50 /// let mut f = File::open("foo.txt").await?; 51 /// let mut buffer = [0; 10]; 52 /// 53 /// // The `read` method is defined by this trait. 54 /// let n = f.read(&mut buffer[..]).await?; 55 /// 56 /// Ok(()) 57 /// } 58 /// ``` 59 /// 60 /// See [module][crate::io] documentation for more details. 61 /// 62 /// [`AsyncRead`]: AsyncRead 63 /// [`prelude`]: crate::prelude 64 pub trait AsyncReadExt: AsyncRead { 65 /// Creates a new `AsyncRead` instance that chains this stream with 66 /// `next`. 67 /// 68 /// The returned `AsyncRead` instance will first read all bytes from this object 69 /// until EOF is encountered. Afterwards the output is equivalent to the 70 /// output of `next`. 71 /// 72 /// # Examples 73 /// 74 /// [`File`][crate::fs::File]s implement `AsyncRead`: 75 /// 76 /// ```no_run 77 /// use tokio::fs::File; 78 /// use tokio::io::{self, AsyncReadExt}; 79 /// 80 /// #[tokio::main] 81 /// async fn main() -> io::Result<()> { 82 /// let f1 = File::open("foo.txt").await?; 83 /// let f2 = File::open("bar.txt").await?; 84 /// 85 /// let mut handle = f1.chain(f2); 86 /// let mut buffer = String::new(); 87 /// 88 /// // read the value into a String. We could use any AsyncRead 89 /// // method here, this is just one example. 90 /// handle.read_to_string(&mut buffer).await?; 91 /// Ok(()) 92 /// } 93 /// ``` 94 fn chain<R>(self, next: R) -> Chain<Self, R> 95 where 96 Self: Sized, 97 R: AsyncRead, 98 { 99 chain(self, next) 100 } 101 102 /// Pulls some bytes from this source into the specified buffer, 103 /// returning how many bytes were read. 104 /// 105 /// Equivalent to: 106 /// 107 /// ```ignore 108 /// async fn read(&mut self, buf: &mut [u8]) -> io::Result<usize>; 109 /// ``` 110 /// 111 /// This function does not provide any guarantees about whether it 112 /// completes immediately or asynchronously 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 /// # Examples 143 /// 144 /// [`File`][crate::fs::File]s implement `Read`: 145 /// 146 /// ```no_run 147 /// use tokio::fs::File; 148 /// use tokio::io::{self, AsyncReadExt}; 149 /// 150 /// #[tokio::main] 151 /// async fn main() -> io::Result<()> { 152 /// let mut f = File::open("foo.txt").await?; 153 /// let mut buffer = [0; 10]; 154 /// 155 /// // read up to 10 bytes 156 /// let n = f.read(&mut buffer[..]).await?; 157 /// 158 /// println!("The bytes: {:?}", &buffer[..n]); 159 /// Ok(()) 160 /// } 161 /// ``` 162 fn read<'a>(&'a mut self, buf: &'a mut [u8]) -> Read<'a, Self> 163 where 164 Self: Unpin, 165 { 166 read(self, buf) 167 } 168 169 /// Pulls some bytes from this source into the specified buffer, 170 /// advancing the buffer's internal cursor. 171 /// 172 /// Equivalent to: 173 /// 174 /// ```ignore 175 /// async fn read_buf<B: BufMut>(&mut self, buf: &mut B) -> io::Result<usize>; 176 /// ``` 177 /// 178 /// Usually, only a single `read` syscall is issued, even if there is 179 /// more space in the supplied buffer. 180 /// 181 /// This function does not provide any guarantees about whether it 182 /// completes immediately or asynchronously 183 /// 184 /// # Return 185 /// 186 /// On a successful read, the number of read bytes is returned. If the 187 /// supplied buffer is not empty and the function returns `Ok(0)` then 188 /// the source as reached an "end-of-file" event. 189 /// 190 /// # Errors 191 /// 192 /// If this function encounters any form of I/O or other error, an error 193 /// variant will be returned. If an error is returned then it must be 194 /// guaranteed that no bytes were read. 195 /// 196 /// # Examples 197 /// 198 /// [`File`] implements `Read` and [`BytesMut`] implements [`BufMut`]: 199 /// 200 /// [`File`]: crate::fs::File 201 /// [`BytesMut`]: bytes::BytesMut 202 /// [`BufMut`]: bytes::BufMut 203 /// 204 /// ```no_run 205 /// use tokio::fs::File; 206 /// use tokio::io::{self, AsyncReadExt}; 207 /// 208 /// use bytes::BytesMut; 209 /// 210 /// #[tokio::main] 211 /// async fn main() -> io::Result<()> { 212 /// let mut f = File::open("foo.txt").await?; 213 /// let mut buffer = BytesMut::with_capacity(10); 214 /// 215 /// assert!(buffer.is_empty()); 216 /// 217 /// // read up to 10 bytes, note that the return value is not needed 218 /// // to access the data that was read as `buffer`'s internal 219 /// // cursor is updated. 220 /// f.read_buf(&mut buffer).await?; 221 /// 222 /// println!("The bytes: {:?}", &buffer[..]); 223 /// Ok(()) 224 /// } 225 /// ``` 226 fn read_buf<'a, B>(&'a mut self, buf: &'a mut B) -> ReadBuf<'a, Self, B> 227 where 228 Self: Sized + Unpin, 229 B: BufMut, 230 { 231 read_buf(self, buf) 232 } 233 234 /// Reads the exact number of bytes required to fill `buf`. 235 /// 236 /// Equivalent to: 237 /// 238 /// ```ignore 239 /// async fn read_exact(&mut self, buf: &mut [u8]) -> io::Result<usize>; 240 /// ``` 241 /// 242 /// This function reads as many bytes as necessary to completely fill 243 /// the specified buffer `buf`. 244 /// 245 /// # Errors 246 /// 247 /// If the operation encounters an "end of file" before completely 248 /// filling the buffer, it returns an error of the kind 249 /// [`ErrorKind::UnexpectedEof`]. The contents of `buf` are unspecified 250 /// in this case. 251 /// 252 /// If any other read error is encountered then the operation 253 /// immediately returns. The contents of `buf` are unspecified in this 254 /// case. 255 /// 256 /// If this operation returns an error, it is unspecified how many bytes 257 /// it has read, but it will never read more than would be necessary to 258 /// completely fill the buffer. 259 /// 260 /// # Examples 261 /// 262 /// [`File`][crate::fs::File]s implement `Read`: 263 /// 264 /// ```no_run 265 /// use tokio::fs::File; 266 /// use tokio::io::{self, AsyncReadExt}; 267 /// 268 /// #[tokio::main] 269 /// async fn main() -> io::Result<()> { 270 /// let mut f = File::open("foo.txt").await?; 271 /// let mut buffer = [0; 10]; 272 /// 273 /// // read exactly 10 bytes 274 /// f.read_exact(&mut buffer).await?; 275 /// Ok(()) 276 /// } 277 /// ``` 278 /// 279 /// [`ErrorKind::UnexpectedEof`]: std::io::ErrorKind::UnexpectedEof 280 fn read_exact<'a>(&'a mut self, buf: &'a mut [u8]) -> ReadExact<'a, Self> 281 where 282 Self: Unpin, 283 { 284 read_exact(self, buf) 285 } 286 287 read_impl! { 288 /// Reads an unsigned 8 bit integer from the underlying reader. 289 /// 290 /// Equivalent to: 291 /// 292 /// ```ignore 293 /// async fn read_u8(&mut self) -> io::Result<u8>; 294 /// ``` 295 /// 296 /// It is recommended to use a buffered reader to avoid excessive 297 /// syscalls. 298 /// 299 /// # Errors 300 /// 301 /// This method returns the same errors as [`AsyncReadExt::read_exact`]. 302 /// 303 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact 304 /// 305 /// # Examples 306 /// 307 /// Read unsigned 8 bit integers from an `AsyncRead`: 308 /// 309 /// ```rust 310 /// use tokio::io::{self, AsyncReadExt}; 311 /// 312 /// use std::io::Cursor; 313 /// 314 /// #[tokio::main] 315 /// async fn main() -> io::Result<()> { 316 /// let mut reader = Cursor::new(vec![2, 5]); 317 /// 318 /// assert_eq!(2, reader.read_u8().await?); 319 /// assert_eq!(5, reader.read_u8().await?); 320 /// 321 /// Ok(()) 322 /// } 323 /// ``` 324 fn read_u8(&mut self) -> ReadU8; 325 326 /// Reads a signed 8 bit integer from the underlying reader. 327 /// 328 /// Equivalent to: 329 /// 330 /// ```ignore 331 /// async fn read_i8(&mut self) -> io::Result<i8>; 332 /// ``` 333 /// 334 /// It is recommended to use a buffered reader to avoid excessive 335 /// syscalls. 336 /// 337 /// # Errors 338 /// 339 /// This method returns the same errors as [`AsyncReadExt::read_exact`]. 340 /// 341 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact 342 /// 343 /// # Examples 344 /// 345 /// Read unsigned 8 bit integers from an `AsyncRead`: 346 /// 347 /// ```rust 348 /// use tokio::io::{self, AsyncReadExt}; 349 /// 350 /// use std::io::Cursor; 351 /// 352 /// #[tokio::main] 353 /// async fn main() -> io::Result<()> { 354 /// let mut reader = Cursor::new(vec![0x02, 0xfb]); 355 /// 356 /// assert_eq!(2, reader.read_i8().await?); 357 /// assert_eq!(-5, reader.read_i8().await?); 358 /// 359 /// Ok(()) 360 /// } 361 /// ``` 362 fn read_i8(&mut self) -> ReadI8; 363 364 /// Reads an unsigned 16-bit integer in big-endian order from the 365 /// underlying reader. 366 /// 367 /// Equivalent to: 368 /// 369 /// ```ignore 370 /// async fn read_u16(&mut self) -> io::Result<u16>; 371 /// ``` 372 /// 373 /// It is recommended to use a buffered reader to avoid excessive 374 /// syscalls. 375 /// 376 /// # Errors 377 /// 378 /// This method returns the same errors as [`AsyncReadExt::read_exact`]. 379 /// 380 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact 381 /// 382 /// # Examples 383 /// 384 /// Read unsigned 16 bit big-endian integers from a `AsyncRead`: 385 /// 386 /// ```rust 387 /// use tokio::io::{self, AsyncReadExt}; 388 /// 389 /// use std::io::Cursor; 390 /// 391 /// #[tokio::main] 392 /// async fn main() -> io::Result<()> { 393 /// let mut reader = Cursor::new(vec![2, 5, 3, 0]); 394 /// 395 /// assert_eq!(517, reader.read_u16().await?); 396 /// assert_eq!(768, reader.read_u16().await?); 397 /// Ok(()) 398 /// } 399 /// ``` 400 fn read_u16(&mut self) -> ReadU16; 401 402 /// Reads a signed 16-bit integer in big-endian order from the 403 /// underlying reader. 404 /// 405 /// Equivalent to: 406 /// 407 /// ```ignore 408 /// async fn read_i16(&mut self) -> io::Result<i16>; 409 /// ``` 410 /// 411 /// It is recommended to use a buffered reader to avoid excessive 412 /// syscalls. 413 /// 414 /// # Errors 415 /// 416 /// This method returns the same errors as [`AsyncReadExt::read_exact`]. 417 /// 418 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact 419 /// 420 /// # Examples 421 /// 422 /// Read signed 16 bit big-endian integers from a `AsyncRead`: 423 /// 424 /// ```rust 425 /// use tokio::io::{self, AsyncReadExt}; 426 /// 427 /// use std::io::Cursor; 428 /// 429 /// #[tokio::main] 430 /// async fn main() -> io::Result<()> { 431 /// let mut reader = Cursor::new(vec![0x00, 0xc1, 0xff, 0x7c]); 432 /// 433 /// assert_eq!(193, reader.read_i16().await?); 434 /// assert_eq!(-132, reader.read_i16().await?); 435 /// Ok(()) 436 /// } 437 /// ``` 438 fn read_i16(&mut self) -> ReadI16; 439 440 /// Reads an unsigned 32-bit integer in big-endian order from the 441 /// underlying reader. 442 /// 443 /// Equivalent to: 444 /// 445 /// ```ignore 446 /// async fn read_u32(&mut self) -> io::Result<u32>; 447 /// ``` 448 /// 449 /// It is recommended to use a buffered reader to avoid excessive 450 /// syscalls. 451 /// 452 /// # Errors 453 /// 454 /// This method returns the same errors as [`AsyncReadExt::read_exact`]. 455 /// 456 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact 457 /// 458 /// # Examples 459 /// 460 /// Read unsigned 32-bit big-endian integers from a `AsyncRead`: 461 /// 462 /// ```rust 463 /// use tokio::io::{self, AsyncReadExt}; 464 /// 465 /// use std::io::Cursor; 466 /// 467 /// #[tokio::main] 468 /// async fn main() -> io::Result<()> { 469 /// let mut reader = Cursor::new(vec![0x00, 0x00, 0x01, 0x0b]); 470 /// 471 /// assert_eq!(267, reader.read_u32().await?); 472 /// Ok(()) 473 /// } 474 /// ``` 475 fn read_u32(&mut self) -> ReadU32; 476 477 /// Reads a signed 32-bit integer in big-endian order from the 478 /// underlying reader. 479 /// 480 /// 481 /// Equivalent to: 482 /// 483 /// ```ignore 484 /// async fn read_i32(&mut self) -> io::Result<i32>; 485 /// ``` 486 /// 487 /// It is recommended to use a buffered reader to avoid excessive 488 /// syscalls. 489 /// 490 /// # Errors 491 /// 492 /// This method returns the same errors as [`AsyncReadExt::read_exact`]. 493 /// 494 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact 495 /// 496 /// # Examples 497 /// 498 /// Read signed 32-bit big-endian integers from a `AsyncRead`: 499 /// 500 /// ```rust 501 /// use tokio::io::{self, AsyncReadExt}; 502 /// 503 /// use std::io::Cursor; 504 /// 505 /// #[tokio::main] 506 /// async fn main() -> io::Result<()> { 507 /// let mut reader = Cursor::new(vec![0xff, 0xff, 0x7a, 0x33]); 508 /// 509 /// assert_eq!(-34253, reader.read_i32().await?); 510 /// Ok(()) 511 /// } 512 /// ``` 513 fn read_i32(&mut self) -> ReadI32; 514 515 /// Reads an unsigned 64-bit integer in big-endian order from the 516 /// underlying reader. 517 /// 518 /// Equivalent to: 519 /// 520 /// ```ignore 521 /// async fn read_u64(&mut self) -> io::Result<u64>; 522 /// ``` 523 /// 524 /// It is recommended to use a buffered reader to avoid excessive 525 /// syscalls. 526 /// 527 /// # Errors 528 /// 529 /// This method returns the same errors as [`AsyncReadExt::read_exact`]. 530 /// 531 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact 532 /// 533 /// # Examples 534 /// 535 /// Read unsigned 64-bit big-endian integers from a `AsyncRead`: 536 /// 537 /// ```rust 538 /// use tokio::io::{self, AsyncReadExt}; 539 /// 540 /// use std::io::Cursor; 541 /// 542 /// #[tokio::main] 543 /// async fn main() -> io::Result<()> { 544 /// let mut reader = Cursor::new(vec![ 545 /// 0x00, 0x03, 0x43, 0x95, 0x4d, 0x60, 0x86, 0x83 546 /// ]); 547 /// 548 /// assert_eq!(918733457491587, reader.read_u64().await?); 549 /// Ok(()) 550 /// } 551 /// ``` 552 fn read_u64(&mut self) -> ReadU64; 553 554 /// Reads an signed 64-bit integer in big-endian order from the 555 /// underlying reader. 556 /// 557 /// Equivalent to: 558 /// 559 /// ```ignore 560 /// async fn read_i64(&mut self) -> io::Result<i64>; 561 /// ``` 562 /// 563 /// It is recommended to use a buffered reader to avoid excessive 564 /// syscalls. 565 /// 566 /// # Errors 567 /// 568 /// This method returns the same errors as [`AsyncReadExt::read_exact`]. 569 /// 570 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact 571 /// 572 /// # Examples 573 /// 574 /// Read signed 64-bit big-endian integers from a `AsyncRead`: 575 /// 576 /// ```rust 577 /// use tokio::io::{self, AsyncReadExt}; 578 /// 579 /// use std::io::Cursor; 580 /// 581 /// #[tokio::main] 582 /// async fn main() -> io::Result<()> { 583 /// let mut reader = Cursor::new(vec![0x80, 0, 0, 0, 0, 0, 0, 0]); 584 /// 585 /// assert_eq!(i64::min_value(), reader.read_i64().await?); 586 /// Ok(()) 587 /// } 588 /// ``` 589 fn read_i64(&mut self) -> ReadI64; 590 591 /// Reads an unsigned 128-bit integer in big-endian order from the 592 /// underlying reader. 593 /// 594 /// Equivalent to: 595 /// 596 /// ```ignore 597 /// async fn read_u128(&mut self) -> io::Result<u128>; 598 /// ``` 599 /// 600 /// It is recommended to use a buffered reader to avoid excessive 601 /// syscalls. 602 /// 603 /// # Errors 604 /// 605 /// This method returns the same errors as [`AsyncReadExt::read_exact`]. 606 /// 607 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact 608 /// 609 /// # Examples 610 /// 611 /// Read unsigned 128-bit big-endian integers from a `AsyncRead`: 612 /// 613 /// ```rust 614 /// use tokio::io::{self, AsyncReadExt}; 615 /// 616 /// use std::io::Cursor; 617 /// 618 /// #[tokio::main] 619 /// async fn main() -> io::Result<()> { 620 /// let mut reader = Cursor::new(vec![ 621 /// 0x00, 0x03, 0x43, 0x95, 0x4d, 0x60, 0x86, 0x83, 622 /// 0x00, 0x03, 0x43, 0x95, 0x4d, 0x60, 0x86, 0x83 623 /// ]); 624 /// 625 /// assert_eq!(16947640962301618749969007319746179, reader.read_u128().await?); 626 /// Ok(()) 627 /// } 628 /// ``` 629 fn read_u128(&mut self) -> ReadU128; 630 631 /// Reads an signed 128-bit integer in big-endian order from the 632 /// underlying reader. 633 /// 634 /// Equivalent to: 635 /// 636 /// ```ignore 637 /// async fn read_i128(&mut self) -> io::Result<i128>; 638 /// ``` 639 /// 640 /// It is recommended to use a buffered reader to avoid excessive 641 /// syscalls. 642 /// 643 /// # Errors 644 /// 645 /// This method returns the same errors as [`AsyncReadExt::read_exact`]. 646 /// 647 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact 648 /// 649 /// # Examples 650 /// 651 /// Read signed 128-bit big-endian integers from a `AsyncRead`: 652 /// 653 /// ```rust 654 /// use tokio::io::{self, AsyncReadExt}; 655 /// 656 /// use std::io::Cursor; 657 /// 658 /// #[tokio::main] 659 /// async fn main() -> io::Result<()> { 660 /// let mut reader = Cursor::new(vec![ 661 /// 0x80, 0, 0, 0, 0, 0, 0, 0, 662 /// 0, 0, 0, 0, 0, 0, 0, 0 663 /// ]); 664 /// 665 /// assert_eq!(i128::min_value(), reader.read_i128().await?); 666 /// Ok(()) 667 /// } 668 /// ``` 669 fn read_i128(&mut self) -> ReadI128; 670 671 /// Reads an unsigned 16-bit integer in little-endian order from the 672 /// underlying reader. 673 /// 674 /// Equivalent to: 675 /// 676 /// ```ignore 677 /// async fn read_u16_le(&mut self) -> io::Result<u16>; 678 /// ``` 679 /// 680 /// It is recommended to use a buffered reader to avoid excessive 681 /// syscalls. 682 /// 683 /// # Errors 684 /// 685 /// This method returns the same errors as [`AsyncReadExt::read_exact`]. 686 /// 687 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact 688 /// 689 /// # Examples 690 /// 691 /// Read unsigned 16 bit little-endian integers from a `AsyncRead`: 692 /// 693 /// ```rust 694 /// use tokio::io::{self, AsyncReadExt}; 695 /// 696 /// use std::io::Cursor; 697 /// 698 /// #[tokio::main] 699 /// async fn main() -> io::Result<()> { 700 /// let mut reader = Cursor::new(vec![2, 5, 3, 0]); 701 /// 702 /// assert_eq!(1282, reader.read_u16_le().await?); 703 /// assert_eq!(3, reader.read_u16_le().await?); 704 /// Ok(()) 705 /// } 706 /// ``` 707 fn read_u16_le(&mut self) -> ReadU16Le; 708 709 /// Reads a signed 16-bit integer in little-endian order from the 710 /// underlying reader. 711 /// 712 /// Equivalent to: 713 /// 714 /// ```ignore 715 /// async fn read_i16_le(&mut self) -> io::Result<i16>; 716 /// ``` 717 /// 718 /// It is recommended to use a buffered reader to avoid excessive 719 /// syscalls. 720 /// 721 /// # Errors 722 /// 723 /// This method returns the same errors as [`AsyncReadExt::read_exact`]. 724 /// 725 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact 726 /// 727 /// # Examples 728 /// 729 /// Read signed 16 bit little-endian integers from a `AsyncRead`: 730 /// 731 /// ```rust 732 /// use tokio::io::{self, AsyncReadExt}; 733 /// 734 /// use std::io::Cursor; 735 /// 736 /// #[tokio::main] 737 /// async fn main() -> io::Result<()> { 738 /// let mut reader = Cursor::new(vec![0x00, 0xc1, 0xff, 0x7c]); 739 /// 740 /// assert_eq!(-16128, reader.read_i16_le().await?); 741 /// assert_eq!(31999, reader.read_i16_le().await?); 742 /// Ok(()) 743 /// } 744 /// ``` 745 fn read_i16_le(&mut self) -> ReadI16Le; 746 747 /// Reads an unsigned 32-bit integer in little-endian order from the 748 /// underlying reader. 749 /// 750 /// Equivalent to: 751 /// 752 /// ```ignore 753 /// async fn read_u32_le(&mut self) -> io::Result<u32>; 754 /// ``` 755 /// 756 /// It is recommended to use a buffered reader to avoid excessive 757 /// syscalls. 758 /// 759 /// # Errors 760 /// 761 /// This method returns the same errors as [`AsyncReadExt::read_exact`]. 762 /// 763 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact 764 /// 765 /// # Examples 766 /// 767 /// Read unsigned 32-bit little-endian integers from a `AsyncRead`: 768 /// 769 /// ```rust 770 /// use tokio::io::{self, AsyncReadExt}; 771 /// 772 /// use std::io::Cursor; 773 /// 774 /// #[tokio::main] 775 /// async fn main() -> io::Result<()> { 776 /// let mut reader = Cursor::new(vec![0x00, 0x00, 0x01, 0x0b]); 777 /// 778 /// assert_eq!(184614912, reader.read_u32_le().await?); 779 /// Ok(()) 780 /// } 781 /// ``` 782 fn read_u32_le(&mut self) -> ReadU32Le; 783 784 /// Reads a signed 32-bit integer in little-endian order from the 785 /// underlying reader. 786 /// 787 /// 788 /// Equivalent to: 789 /// 790 /// ```ignore 791 /// async fn read_i32_le(&mut self) -> io::Result<i32>; 792 /// ``` 793 /// 794 /// It is recommended to use a buffered reader to avoid excessive 795 /// syscalls. 796 /// 797 /// # Errors 798 /// 799 /// This method returns the same errors as [`AsyncReadExt::read_exact`]. 800 /// 801 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact 802 /// 803 /// # Examples 804 /// 805 /// Read signed 32-bit little-endian integers from a `AsyncRead`: 806 /// 807 /// ```rust 808 /// use tokio::io::{self, AsyncReadExt}; 809 /// 810 /// use std::io::Cursor; 811 /// 812 /// #[tokio::main] 813 /// async fn main() -> io::Result<()> { 814 /// let mut reader = Cursor::new(vec![0xff, 0xff, 0x7a, 0x33]); 815 /// 816 /// assert_eq!(863698943, reader.read_i32_le().await?); 817 /// Ok(()) 818 /// } 819 /// ``` 820 fn read_i32_le(&mut self) -> ReadI32Le; 821 822 /// Reads an unsigned 64-bit integer in little-endian order from the 823 /// underlying reader. 824 /// 825 /// Equivalent to: 826 /// 827 /// ```ignore 828 /// async fn read_u64_le(&mut self) -> io::Result<u64>; 829 /// ``` 830 /// 831 /// It is recommended to use a buffered reader to avoid excessive 832 /// syscalls. 833 /// 834 /// # Errors 835 /// 836 /// This method returns the same errors as [`AsyncReadExt::read_exact`]. 837 /// 838 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact 839 /// 840 /// # Examples 841 /// 842 /// Read unsigned 64-bit little-endian integers from a `AsyncRead`: 843 /// 844 /// ```rust 845 /// use tokio::io::{self, AsyncReadExt}; 846 /// 847 /// use std::io::Cursor; 848 /// 849 /// #[tokio::main] 850 /// async fn main() -> io::Result<()> { 851 /// let mut reader = Cursor::new(vec![ 852 /// 0x00, 0x03, 0x43, 0x95, 0x4d, 0x60, 0x86, 0x83 853 /// ]); 854 /// 855 /// assert_eq!(9477368352180732672, reader.read_u64_le().await?); 856 /// Ok(()) 857 /// } 858 /// ``` 859 fn read_u64_le(&mut self) -> ReadU64Le; 860 861 /// Reads an signed 64-bit integer in little-endian order from the 862 /// underlying reader. 863 /// 864 /// Equivalent to: 865 /// 866 /// ```ignore 867 /// async fn read_i64_le(&mut self) -> io::Result<i64>; 868 /// ``` 869 /// 870 /// It is recommended to use a buffered reader to avoid excessive 871 /// syscalls. 872 /// 873 /// # Errors 874 /// 875 /// This method returns the same errors as [`AsyncReadExt::read_exact`]. 876 /// 877 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact 878 /// 879 /// # Examples 880 /// 881 /// Read signed 64-bit little-endian integers from a `AsyncRead`: 882 /// 883 /// ```rust 884 /// use tokio::io::{self, AsyncReadExt}; 885 /// 886 /// use std::io::Cursor; 887 /// 888 /// #[tokio::main] 889 /// async fn main() -> io::Result<()> { 890 /// let mut reader = Cursor::new(vec![0x80, 0, 0, 0, 0, 0, 0, 0]); 891 /// 892 /// assert_eq!(128, reader.read_i64_le().await?); 893 /// Ok(()) 894 /// } 895 /// ``` 896 fn read_i64_le(&mut self) -> ReadI64Le; 897 898 /// Reads an unsigned 128-bit integer in little-endian order from the 899 /// underlying reader. 900 /// 901 /// Equivalent to: 902 /// 903 /// ```ignore 904 /// async fn read_u128_le(&mut self) -> io::Result<u128>; 905 /// ``` 906 /// 907 /// It is recommended to use a buffered reader to avoid excessive 908 /// syscalls. 909 /// 910 /// # Errors 911 /// 912 /// This method returns the same errors as [`AsyncReadExt::read_exact`]. 913 /// 914 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact 915 /// 916 /// # Examples 917 /// 918 /// Read unsigned 128-bit little-endian integers from a `AsyncRead`: 919 /// 920 /// ```rust 921 /// use tokio::io::{self, AsyncReadExt}; 922 /// 923 /// use std::io::Cursor; 924 /// 925 /// #[tokio::main] 926 /// async fn main() -> io::Result<()> { 927 /// let mut reader = Cursor::new(vec![ 928 /// 0x00, 0x03, 0x43, 0x95, 0x4d, 0x60, 0x86, 0x83, 929 /// 0x00, 0x03, 0x43, 0x95, 0x4d, 0x60, 0x86, 0x83 930 /// ]); 931 /// 932 /// assert_eq!(174826588484952389081207917399662330624, reader.read_u128_le().await?); 933 /// Ok(()) 934 /// } 935 /// ``` 936 fn read_u128_le(&mut self) -> ReadU128Le; 937 938 /// Reads an signed 128-bit integer in little-endian order from the 939 /// underlying reader. 940 /// 941 /// Equivalent to: 942 /// 943 /// ```ignore 944 /// async fn read_i128_le(&mut self) -> io::Result<i128>; 945 /// ``` 946 /// 947 /// It is recommended to use a buffered reader to avoid excessive 948 /// syscalls. 949 /// 950 /// # Errors 951 /// 952 /// This method returns the same errors as [`AsyncReadExt::read_exact`]. 953 /// 954 /// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact 955 /// 956 /// # Examples 957 /// 958 /// Read signed 128-bit little-endian integers from a `AsyncRead`: 959 /// 960 /// ```rust 961 /// use tokio::io::{self, AsyncReadExt}; 962 /// 963 /// use std::io::Cursor; 964 /// 965 /// #[tokio::main] 966 /// async fn main() -> io::Result<()> { 967 /// let mut reader = Cursor::new(vec![ 968 /// 0x80, 0, 0, 0, 0, 0, 0, 0, 969 /// 0, 0, 0, 0, 0, 0, 0, 0 970 /// ]); 971 /// 972 /// assert_eq!(128, reader.read_i128_le().await?); 973 /// Ok(()) 974 /// } 975 /// ``` 976 fn read_i128_le(&mut self) -> ReadI128Le; 977 } 978 979 /// Reads all bytes until EOF in this source, placing them into `buf`. 980 /// 981 /// Equivalent to: 982 /// 983 /// ```ignore 984 /// async fn read_to_end(&mut self, buf: &mut Vec<u8>) -> io::Result<usize>; 985 /// ``` 986 /// 987 /// All bytes read from this source will be appended to the specified 988 /// buffer `buf`. This function will continuously call [`read()`] to 989 /// append more data to `buf` until [`read()`][read] returns `Ok(0)`. 990 /// 991 /// If successful, the total number of bytes read is returned. 992 /// 993 /// # Errors 994 /// 995 /// If a read error is encountered then the `read_to_end` operation 996 /// immediately completes. Any bytes which have already been read will 997 /// be appended to `buf`. 998 /// 999 /// # Examples 1000 /// 1001 /// [`File`][crate::fs::File]s implement `Read`: 1002 /// 1003 /// ```no_run 1004 /// use tokio::io::{self, AsyncReadExt}; 1005 /// use tokio::fs::File; 1006 /// 1007 /// #[tokio::main] 1008 /// async fn main() -> io::Result<()> { 1009 /// let mut f = File::open("foo.txt").await?; 1010 /// let mut buffer = Vec::new(); 1011 /// 1012 /// // read the whole file 1013 /// f.read_to_end(&mut buffer).await?; 1014 /// Ok(()) 1015 /// } 1016 /// ``` 1017 /// 1018 /// (See also the [`tokio::fs::read`] convenience function for reading from a 1019 /// file.) 1020 /// 1021 /// [`tokio::fs::read`]: crate::fs::read::read 1022 fn read_to_end<'a>(&'a mut self, buf: &'a mut Vec<u8>) -> ReadToEnd<'a, Self> 1023 where 1024 Self: Unpin, 1025 { 1026 read_to_end(self, buf) 1027 } 1028 1029 /// Reads all bytes until EOF in this source, appending them to `buf`. 1030 /// 1031 /// Equivalent to: 1032 /// 1033 /// ```ignore 1034 /// async fn read_to_string(&mut self, buf: &mut String) -> io::Result<usize>; 1035 /// ``` 1036 /// 1037 /// If successful, the number of bytes which were read and appended to 1038 /// `buf` is returned. 1039 /// 1040 /// # Errors 1041 /// 1042 /// If the data in this stream is *not* valid UTF-8 then an error is 1043 /// returned and `buf` is unchanged. 1044 /// 1045 /// See [`read_to_end`][AsyncReadExt::read_to_end] for other error semantics. 1046 /// 1047 /// # Examples 1048 /// 1049 /// [`File`][crate::fs::File]s implement `Read`: 1050 /// 1051 /// ```no_run 1052 /// use tokio::io::{self, AsyncReadExt}; 1053 /// use tokio::fs::File; 1054 /// 1055 /// #[tokio::main] 1056 /// async fn main() -> io::Result<()> { 1057 /// let mut f = File::open("foo.txt").await?; 1058 /// let mut buffer = String::new(); 1059 /// 1060 /// f.read_to_string(&mut buffer).await?; 1061 /// Ok(()) 1062 /// } 1063 /// ``` 1064 /// 1065 /// (See also the [`crate::fs::read_to_string`] convenience function for 1066 /// reading from a file.) 1067 /// 1068 /// [`crate::fs::read_to_string`]: crate::fs::read_to_string::read_to_string 1069 fn read_to_string<'a>(&'a mut self, dst: &'a mut String) -> ReadToString<'a, Self> 1070 where 1071 Self: Unpin, 1072 { 1073 read_to_string(self, dst) 1074 } 1075 1076 /// Creates an adaptor which reads at most `limit` bytes from it. 1077 /// 1078 /// This function returns a new instance of `AsyncRead` which will read 1079 /// at most `limit` bytes, after which it will always return EOF 1080 /// (`Ok(0)`). Any read errors will not count towards the number of 1081 /// bytes read and future calls to [`read()`][read] may succeed. 1082 /// 1083 /// # Examples 1084 /// 1085 /// [`File`][crate::fs::File]s implement `Read`: 1086 /// 1087 /// ```no_run 1088 /// use tokio::io::{self, AsyncReadExt}; 1089 /// use tokio::fs::File; 1090 /// 1091 /// #[tokio::main] 1092 /// async fn main() -> io::Result<()> { 1093 /// let f = File::open("foo.txt").await?; 1094 /// let mut buffer = [0; 5]; 1095 /// 1096 /// // read at most five bytes 1097 /// let mut handle = f.take(5); 1098 /// 1099 /// handle.read(&mut buffer).await?; 1100 /// Ok(()) 1101 /// } 1102 /// ``` 1103 fn take(self, limit: u64) -> Take<Self> 1104 where 1105 Self: Sized, 1106 { 1107 take(self, limit) 1108 } 1109 } 1110 } 1111 1112 impl<R: AsyncRead + ?Sized> AsyncReadExt for R {} 1113