1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929
//! 用于类型之间的转换 traits。
//!
//! 此模块中的 traits 提供了一种从一种类型转换为另一种类型的方法。
//! 每个 trait 都有不同的用途:
//!
//! - 实现 [`AsRef`] trait 以实现廉价的引用到引用转换
//! - 实现 [`AsMut`] trait 进行廉价的变量到变量转换
//! - 实现 [`From`] trait 以进行值到值的转换
//! - 实现 [`Into`] trait,以便将值转换为当前 crate 之外的类型
//! - [`TryFrom`] 和 [`TryInto`] traits 的行为类似于 [`From`] 和 [`Into`],但应在转换失败时实现。
//!
//! 此模块中的 traits 通常用作泛型函数的 trait bounds,以便支持多种类型的参数。有关示例,请参见每个 trait 的文档。
//!
//! 作为库作者,您应该总是更喜欢实现 [`From<T>`][`From`] 或 [`TryFrom<T>`][`TryFrom`],而不是 [`Into<U>`][`Into`] 或 [`TryInto<U>`][`TryInto`],因为 [`From`] 和 [`TryFrom`] 提供了更大的灵活性,并免费提供了等效的 [`Into`] 或 [`TryInto`] 实现,这要归功于标准库中的全面实现。
//! 当定位到 Rust 1.41 之前的版本时,当转换为当前 crate 之外的类型时,可能有必要直接实现 [`Into`] 或 [`TryInto`]。
//!
//! # 泛型实现
//!
//! - 如果内部类型是引用,则 [`AsRef`] 和 [`AsMut`] 自动解引用 (但通常不适用于所有 [dereferenceable types][core::ops::Deref])
//! - [`From`]`<U> for T` 意味着 [`Into`]`<T> for U`
//! - [`TryFrom`]`<U> for T` 意味着 [`TryInto`]`<T> for U`
//! - [`From`] 和 [`Into`] 是反射的,这意味着所有类型都可以 `into` 自己和 `from` 自己
//!
//! 有关用法示例,请参见每个 trait。
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
#![stable(feature = "rust1", since = "1.0.0")]
use crate::error::Error;
use crate::fmt;
use crate::hash::{Hash, Hasher};
mod num;
#[unstable(feature = "convert_float_to_int", issue = "67057")]
pub use num::FloatToInt;
/// identity 函数。
///
/// 关于此函数,有两点需要注意:
///
/// - 它并不总是等同于 `|x| x` 之类的闭包,因为闭包可能会将 `x` 强制转换为其他类型。
///
/// - 它将输入 `x` 传递给函数。
///
/// 虽然有一个只返回输入的函数似乎很奇怪,但是有一些有趣的用法。
///
///
/// # Examples
///
/// 使用 `identity` 在其他有趣的函数序列中什么也不做:
///
/// ```rust
/// use std::convert::identity;
///
/// fn manipulation(x: u32) -> u32 {
/// // 让我们假设添加一个是一个有趣的函数。
/// x + 1
/// }
///
/// let _arr = &[identity, manipulation];
/// ```
///
/// 在条件中将 `identity` 用作 "什么也不做" 的基本情况:
///
/// ```rust
/// use std::convert::identity;
///
/// # let condition = true;
/// #
/// # fn manipulation(x: u32) -> u32 { x + 1 }
/// #
/// let do_stuff = if condition { manipulation } else { identity };
///
/// // 做更多有趣的事...
///
/// let _results = do_stuff(42);
/// ```
///
/// 使用 `identity` 保留 `Option<T>` 迭代器的 `Some` 变体:
///
/// ```rust
/// use std::convert::identity;
///
/// let iter = [Some(1), None, Some(3)].into_iter();
/// let filtered = iter.filter_map(identity).collect::<Vec<_>>();
/// assert_eq!(vec![1, 3], filtered);
/// ```
///
///
#[stable(feature = "convert_id", since = "1.33.0")]
#[rustc_const_stable(feature = "const_identity", since = "1.33.0")]
#[inline(always)]
pub const fn identity<T>(x: T) -> T {
x
}
/// 用于执行廉价的引用到引用转换。
///
/// 一个类似于 [`AsMut`] 的 trait,用于在可变引用之间进行转换。
/// 如果您需要进行代价高昂的转换,最好用 `&T` 类型实现 [`From`],或者编写一个自定义函数。
///
/// # 与 `Borrow` 的关系
///
/// `AsRef` 与 [`Borrow`] 具有相同的签名,但 [`Borrow`] 在以下几个方面有所不同:
///
/// - 与 `AsRef` 不同,[`Borrow`] 对任何 `T` 都有一个毯子暗示,可用于接受引用或值。(另请参见下面关于 `AsRef` 的反射性的注释。)
/// - [`Borrow`] 还要求借用值的 [`Hash`]、[`Eq`] 和 [`Ord`] 与拥有值的值相等。因此,如果只想借用一个结构体的单个字段,则可以实现 `AsRef`,而不能实现 [`Borrow`]。
///
/// **注意:此 trait 一定不能失败**。如果转换失败,请使用专用方法返回 [`Option<T>`] 或 [`Result<T, E>`]。
///
/// # 泛型实现
///
/// `AsRef` 自动引用,如果内部类型是一个引用或一个,可变引用 (例如: 如果 `foo` 具有 `&mut Foo` 或 `&&mut Foo` 类型,`foo.as_ref()` 将同样工作)。
///
/// 请注意,由于历史原因,上述内容目前并不适用于所有 [dereferenceable types],例如 `foo.as_ref()`*不会*与 `Box::new(foo).as_ref()` 一样工作。
/// 相反,许多智能指针提供了一个 `as_ref` 实现,它简单地将一个引用返回给 [pointed-to value] (但不对该值执行廉价的引用 - 到 - 引用转换)。
/// 但是,[`AsRef::as_ref`] 不应仅用于解引用; 可以使用 ['`Deref` coercion'] 代替:
///
/// [dereferenceable types]: core::ops::Deref
/// [pointed-to value]: core::ops::Deref::Target
/// ['`Deref` coercion']: core::ops::Deref#more-on-deref-coercion
///
/// ```
/// let x = Box::new(5i32);
/// // 避免这种情况:
/// // let y: &i32 = x.as_ref();
/// // 最好只写:
/// let y: &i32 = &x;
/// ```
///
/// 实现 [`Deref`] 的类型应考虑实现 `AsRef<T>`,如下所示:
///
/// [`Deref`]: core::ops::Deref
///
/// ```
/// # use core::ops::Deref;
/// # struct SomeType;
/// # impl Deref for SomeType {
/// # type Target = [u8];
/// # fn deref(&self) -> &[u8] {
/// # &[]
/// # }
/// # }
/// impl<T> AsRef<T> for SomeType
/// where
/// T: ?Sized,
/// <SomeType as Deref>::Target: AsRef<T>,
/// {
/// fn as_ref(&self) -> &T {
/// self.deref().as_ref()
/// }
/// }
/// ```
///
/// # Reflexivity
///
/// 理想情况下,`AsRef` 将是自反的,即有一个 `impl<T: ?Sized> AsRef<T> for T` 与 [`as_ref`] 简单地返回其参数不变。
/// 由于 Rust 类型系统的技术限制,目前*不*提供这样的一揽子实现 (它将与 `&T where T: AsRef<U>` 的另一个现有一揽子实现重叠,它允许 `AsRef` 自动解引用,请参见上面的 "Generic Implementations")。
///
///
/// [`as_ref`]: AsRef::as_ref
///
/// 必须在需要或需要的地方为特定类型 `T` 显式添加 `AsRef<T> for T` 的简单实现。但是请注意,并非 `std` 中的所有类型都包含这样的实现,并且由于孤儿规则,这些类型不能由外部代码添加。
///
/// # Examples
///
/// 通过使用 trait bounds,我们可以接受不同类型的参数,只要它们可以转换为指定的 `T` 类型即可。
///
/// 例如:通过创建一个采用 `AsRef<str>` 的泛型函数,我们表示我们希望接受所有可以转换为 [`&str`] 的引用作为参数。
/// 由于 [`String`] 和 [`&str`] 都实现了 `AsRef<str>`,因此我们可以将两者都用作输入参数。
///
/// [`&str`]: primitive@str
/// [`Borrow`]: crate::borrow::Borrow
/// [`Eq`]: crate::cmp::Eq
/// [`Ord`]: crate::cmp::Ord
/// [`String`]: ../../std/string/struct.String.html
///
/// ```
/// fn is_hello<T: AsRef<str>>(s: T) {
/// assert_eq!("hello", s.as_ref());
/// }
///
/// let s = "hello";
/// is_hello(s);
///
/// let s = "hello".to_string();
/// is_hello(s);
/// ```
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
#[cfg_attr(not(test), rustc_diagnostic_item = "AsRef")]
pub trait AsRef<T: ?Sized> {
/// 将此类型转换为 (通常是推断的) 输入类型的共享引用。
#[stable(feature = "rust1", since = "1.0.0")]
fn as_ref(&self) -> &T;
}
/// 用于进行廉价的可变到可变引用转换。
///
/// 一个与 [`AsRef`] 类似的 trait,但用于在可变引用之间进行转换。如果需要进行昂贵的转换,最好用 `&mut T` 类型实现 [`From`] 或编写自定义函数。
///
/// **注意:此 trait 一定不能失败**。如果转换失败,请使用专用方法返回 [`Option<T>`] 或 [`Result<T, E>`]。
///
/// # 泛型实现
///
/// `AsMut` 自动解引用,如果内部类型是不兼容引用 (例如: 如果 `foo` 具有 `&mut Foo` 或 `&mut &mut Foo` 类型,`foo.as_mut()` 将工作相同)。
///
/// 请注意,由于历史原因,上述内容目前并不适用于所有 [mutably dereferenceable types],例如 `foo.as_mut()`*不会*与 `Box::new(foo).as_mut()` 一样工作。
/// 相反,许多智能指针提供了一个 `as_mut` 实现,它简单地将一个引用返回给 [pointed-to value] (但不对该值执行廉价的引用 - 到 - 引用转换)。
/// 但是,[`AsMut::as_mut`] 不应仅用于无效解引用; 可以使用 ['`Deref` coercion'] 代替:
///
/// [mutably dereferenceable types]: core::ops::DerefMut
/// [pointed-to value]: core::ops::Deref::Target
/// ['`Deref` coercion']: core::ops::DerefMut#more-on-deref-coercion
///
/// ```
/// let mut x = Box::new(5i32);
/// // 避免这种情况:
/// // let y: &mut i32 = x.as_mut();
/// // 最好只写:
/// let y: &mut i32 = &mut x;
/// ```
///
/// 实现 [`DerefMut`] 的类型应考虑添加 `AsMut<T>` 的实现,如下所示:
///
/// [`DerefMut`]: core::ops::DerefMut
///
/// ```
/// # use core::ops::{Deref, DerefMut};
/// # struct SomeType;
/// # impl Deref for SomeType {
/// # type Target = [u8];
/// # fn deref(&self) -> &[u8] {
/// # &[]
/// # }
/// # }
/// # impl DerefMut for SomeType {
/// # fn deref_mut(&mut self) -> &mut [u8] {
/// # &mut []
/// # }
/// # }
/// impl<T> AsMut<T> for SomeType
/// where
/// <SomeType as Deref>::Target: AsMut<T>,
/// {
/// fn as_mut(&mut self) -> &mut T {
/// self.deref_mut().as_mut()
/// }
/// }
/// ```
///
/// # Reflexivity
///
/// 理想情况下,`AsMut` 将是自反的,即有一个 `impl<T: ?Sized> AsMut<T> for T` 与 [`as_mut`] 简单地返回其参数不变。
/// 由于 Rust 类型系统的技术限制,目前*不*提供这样的一揽子实现 (它将与 `&mut T where T: AsMut<U>` 的另一个现有一揽子实现重叠,它允许 `AsMut` 自动解引用,请参见上面的 "Generic Implementations")。
///
///
/// [`as_mut`]: AsMut::as_mut
///
/// 必须在需要或需要的地方为特定类型 `T` 显式添加 `AsMut<T> for T` 的简单实现。但是请注意,并非 `std` 中的所有类型都包含这样的实现,并且由于孤儿规则,这些类型不能由外部代码添加。
///
/// # Examples
///
/// 使用 `AsMut` 作为 trait bound 作为泛型函数,我们可以接受所有可以转换为 `&mut T` 类型的引用。
/// 与只有一个 [target type] 的 [dereference] 不同,一个类型可以有多个 `AsMut` 实现。特别是,`Vec<T>` 实现了 `AsMut<Vec<T>>` 和 `AsMut<[T]>`。
///
/// 在下文中,示例函数 `caesar` 和 `null_terminate` 提供了泛型接口,该接口适用于任何类型,可以通过廉价的转换为字节切片 (`[u8]`) 或字节 vector (`Vec<u8>`) 分别转换为字节切片 (`[u8]`) 或字节 vector (`Vec<u8>`)。
///
/// [dereference]: core::ops::DerefMut
/// [target type]: core::ops::Deref::Target
///
/// ```
/// struct Document {
/// info: String,
/// content: Vec<u8>,
/// }
///
/// impl<T: ?Sized> AsMut<T> for Document
/// where
/// Vec<u8>: AsMut<T>,
/// {
/// fn as_mut(&mut self) -> &mut T {
/// self.content.as_mut()
/// }
/// }
///
/// fn caesar<T: AsMut<[u8]>>(data: &mut T, key: u8) {
/// for byte in data.as_mut() {
/// *byte = byte.wrapping_add(key);
/// }
/// }
///
/// fn null_terminate<T: AsMut<Vec<u8>>>(data: &mut T) {
/// // 使用包含大部分功能的非泛型内部函数有助于最小化单态化开销。
/////
/// fn doit(data: &mut Vec<u8>) {
/// let len = data.len();
/// if len == 0 || data[len-1] != 0 {
/// data.push(0);
/// }
/// }
/// doit(data.as_mut());
/// }
///
/// fn main() {
/// let mut v: Vec<u8> = vec![1, 2, 3];
/// caesar(&mut v, 5);
/// assert_eq!(v, [6, 7, 8]);
/// null_terminate(&mut v);
/// assert_eq!(v, [6, 7, 8, 0]);
/// let mut doc = Document {
/// info: String::from("Example"),
/// content: vec![17, 19, 8],
/// };
/// caesar(&mut doc, 1);
/// assert_eq!(doc.content, [18, 20, 9]);
/// null_terminate(&mut doc);
/// assert_eq!(doc.content, [18, 20, 9, 0]);
/// }
/// ```
///
/// 但是请注意,API 不必是泛型。在许多情况下,例如使用 `&mut [u8]` 或 `&mut Vec<u8>` 是更好的选择 (调用者需要传递正确的类型)。
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
#[cfg_attr(not(test), rustc_diagnostic_item = "AsMut")]
pub trait AsMut<T: ?Sized> {
/// 将此类型转换为 (通常是推断的) 输入类型的错误引用。
#[stable(feature = "rust1", since = "1.0.0")]
fn as_mut(&mut self) -> &mut T;
}
/// 消耗输入值的值到值转换。与 [`From`] 相反。
///
/// 应该避免实现 [`Into`],而应实现 [`From`]。
/// 由于标准库中的全面实现,因此 [`From`] 的自动实现为 [`Into`] 的实现提供了一个实现。
///
/// 在泛型函数上指定 trait bounds 时,最好使用 [`Into`] 而不是 [`From`],以确保也可以使用仅实现 [`Into`] 的类型。
///
/// **注意:此 trait 一定不能失败**。如果转换可能失败,请使用 [`TryInto`]。
///
/// # 泛型实现
///
/// - [`From`]`<T> for U` 意味着 `Into<U> for T`
/// - [`Into`] 是反射的,这意味着 `Into<T> for T` 被实现
///
/// # 在旧版本的 Rust 中实现 [`Into`] 转换为外部类型
///
/// 在 Rust 1.41 之前,如果目标类型不是当前 crate 的一部分,那么您将无法直接实现 [`From`]。
/// 例如,使用以下代码:
///
/// ```
/// struct Wrapper<T>(Vec<T>);
/// impl<T> From<Wrapper<T>> for Vec<T> {
/// fn from(w: Wrapper<T>) -> Vec<T> {
/// w.0
/// }
/// }
/// ```
/// 由于 Rust 的孤儿规则过去要严格一些,因此无法在较旧的语言版本中进行编译。
/// 要绕过它,您可以直接实现 [`Into`]:
///
/// ```
/// struct Wrapper<T>(Vec<T>);
/// impl<T> Into<Vec<T>> for Wrapper<T> {
/// fn into(self) -> Vec<T> {
/// self.0
/// }
/// }
/// ```
///
/// 重要的是要了解 [`Into`] 不提供 [`From`] 实现 (就像 [`From`] 与 [`Into`] 一样)。
/// 因此,您应该始终尝试实现 [`From`],如果无法实现 [`From`],则应回退到 [`Into`]。
///
/// # Examples
///
/// [`String`] 实现 [`Into`]`<`[`Vec`]`<`[`u8`]`>>`:
///
/// 为了表示我们希望泛型函数采用所有可以转换为指定类型 `T` 的参数,我们可以使用 [`Into`]`<T>` 的 trait bound。
///
/// 例如:函数 `is_hello` 接受所有可以转换为 [`Vec`]`<`[`u8`]`>` 的参数。
///
/// ```
/// fn is_hello<T: Into<Vec<u8>>>(s: T) {
/// let bytes = b"hello".to_vec();
/// assert_eq!(bytes, s.into());
/// }
///
/// let s = "hello".to_string();
/// is_hello(s);
/// ```
///
/// [`String`]: ../../std/string/struct.String.html
/// [`Vec`]: ../../std/vec/struct.Vec.html
///
///
///
///
///
///
#[rustc_diagnostic_item = "Into"]
#[stable(feature = "rust1", since = "1.0.0")]
pub trait Into<T>: Sized {
/// 将此类型转换为 (通常是推断的) 输入类型。
#[must_use]
#[stable(feature = "rust1", since = "1.0.0")]
fn into(self) -> T;
}
/// 用于在消耗输入值的同时进行值到值的转换。它是 [`Into`] 的倒数。
///
/// 与标准 [`Into`] 相比,人们应该总是更喜欢实现 `From`,因为由于标准库中的全面实现,实现 `From` 会自动为 [`Into`] 提供一个 [`Into`] 的实现。
///
///
/// 仅当针对 Rust 1.41 之前的版本并将其转换为当前 crate 以外的类型时,才实现 [`Into`]。
/// 由于 Rust 的孤儿规则,`From` 在早期版本中无法进行这些类型的转换。
/// 有关更多详细信息,请参见 [`Into`]。
///
/// 在泛型函数上指定 trait bounds 时,优先使用 [`Into`]。
/// 这样,直接实现 [`Into`] 的类型也可以用作参数。
///
/// `From` 在执行错误处理时也非常有用。当创建一个能够失败的函数时,返回类型通常为 `Result<T, E>` 形式。
/// `From` trait 通过允许函数返回封装了多种错误类型的单个错误类型,简化了错误处理。有关更多详细信息,请参见示例部分和这本 [书][book]。
///
/// **注意:此 trait 一定不能失败**。`From` trait 旨在实现完美转换。
/// 如果转换失败或不完美,请使用 [`TryFrom`]。
///
/// # 泛型实现
///
/// - `From<T> for U` 意味着 [`Into`]`<U> for T`
/// - `From` 是反射的,这意味着 `From<T> for T` 被实现
///
/// # Examples
///
/// [`String`] 实现 `From<&str>`:
///
/// 从 `&str` 到字符串的显式转换如下:
///
/// ```
/// let string = "hello".to_string();
/// let other_string = String::from("hello");
///
/// assert_eq!(string, other_string);
/// ```
///
/// 在执行错误处理时,通常对于您自己的错误类型实现 `From` 很有用。
/// 通过将底层错误类型转换为封装底层错误类型的自定义错误类型,我们可以返回单个错误类型,而不会丢失有关底层原因的信息。
/// '?' 运算符通过调用 `Into<CliError>::into` 自动将底层错误类型转换为我们的自定义错误类型,该 `Into<CliError>::into` 是在实现 `From` 时自动提供的。
/// 然后,编译器会推断应使用 `Into` 的哪种实现。
///
/// ```
/// use std::fs;
/// use std::io;
/// use std::num;
///
/// enum CliError {
/// IoError(io::Error),
/// ParseError(num::ParseIntError),
/// }
///
/// impl From<io::Error> for CliError {
/// fn from(error: io::Error) -> Self {
/// CliError::IoError(error)
/// }
/// }
///
/// impl From<num::ParseIntError> for CliError {
/// fn from(error: num::ParseIntError) -> Self {
/// CliError::ParseError(error)
/// }
/// }
///
/// fn open_and_parse_file(file_name: &str) -> Result<i32, CliError> {
/// let mut contents = fs::read_to_string(&file_name)?;
/// let num: i32 = contents.trim().parse()?;
/// Ok(num)
/// }
/// ```
///
/// [`String`]: ../../std/string/struct.String.html
/// [`from`]: From::from
/// [book]: ../../book/ch09-00-error-handling.html
///
///
///
///
///
///
///
///
///
#[rustc_diagnostic_item = "From"]
#[stable(feature = "rust1", since = "1.0.0")]
#[rustc_on_unimplemented(on(
all(_Self = "&str", T = "std::string::String"),
note = "to coerce a `{T}` into a `{Self}`, use `&*` as a prefix",
))]
pub trait From<T>: Sized {
/// 从输入类型转换为此类型。
#[rustc_diagnostic_item = "from_fn"]
#[must_use]
#[stable(feature = "rust1", since = "1.0.0")]
fn from(value: T) -> Self;
}
/// 消耗 `self` 的尝试转换,这可能很昂贵,也可能不昂贵。
///
/// 库作者通常不应直接实现此 trait,而应首选实现 [`TryFrom`] trait,它具有更大的灵活性,并免费提供了等效的 `TryInto` 实现,这要归功于标准库中的全面实现。
/// 有关此的更多信息,请参见 [`Into`] 的文档。
///
/// # 实现 `TryInto`
///
/// 这与实现 [`Into`] 受到相同的限制和推理,有关详细信息,请参见此处。
///
///
///
///
///
///
#[rustc_diagnostic_item = "TryInto"]
#[stable(feature = "try_from", since = "1.34.0")]
pub trait TryInto<T>: Sized {
/// 发生转换错误时返回的类型。
#[stable(feature = "try_from", since = "1.34.0")]
type Error;
/// 执行转换。
#[stable(feature = "try_from", since = "1.34.0")]
fn try_into(self) -> Result<T, Self::Error>;
}
/// 简单安全的类型转换在某些情况下可能会以受控方式失败。它是 [`TryInto`] 的倒数。
///
/// 当您进行的类型转换可能会成功完成但可能还需要特殊处理时,这很有用。
/// 例如,无法使用 [`From`] trait 将 [`i64`] 转换为 [`i32`],因为 [`i64`] 可能包含 [`i32`] 无法表示的值,因此转换将丢失数据。
///
/// 这可以通过将 [`i64`] 截断为 [`i32`] (本质上给 [`i64`] 的值取 [`i32::MAX`] 模) 或通过简单地返回 [`i32::MAX`] 或其他方法来处理。
/// [`From`] trait 用于完美的转换,因此 `TryFrom` trait 会通知程序员类型转换何时会变差,并让他们决定如何处理它。
///
/// # 泛型实现
///
/// - `TryFrom<T> for U` 意味着 [`TryInto`]`<U> for T`
/// - [`try_from`] 是反射的,这意味着 `TryFrom<T> for T` 已实现并且不会失败 -- 用于在类型 `T` 上调用 `T::try_from()` 的关联 `Error` 类型是 [`Infallible`]。
/// 当 [`!`] 类型稳定后,[`Infallible`] 和 [`!`] 将等效。
///
/// `TryFrom<T>` 可以实现如下:
///
/// ```
/// struct GreaterThanZero(i32);
///
/// impl TryFrom<i32> for GreaterThanZero {
/// type Error = &'static str;
///
/// fn try_from(value: i32) -> Result<Self, Self::Error> {
/// if value <= 0 {
/// Err("GreaterThanZero only accepts values greater than zero!")
/// } else {
/// Ok(GreaterThanZero(value))
/// }
/// }
/// }
/// ```
///
/// # Examples
///
/// 如上所述,[`i32`] 实现了 `TryFrom<`[`i64`]`>`:
///
/// ```
/// let big_number = 1_000_000_000_000i64;
/// // 默默地截断 `big_number`,事实之后需要检测并处理该截断。
/////
/// let smaller_number = big_number as i32;
/// assert_eq!(smaller_number, -727379968);
///
/// // 由于 `big_number` 太大而无法容纳在 `i32` 中,因此返回错误。
/////
/// let try_smaller_number = i32::try_from(big_number);
/// assert!(try_smaller_number.is_err());
///
/// // 返回 `Ok(3)`。
/// let try_successful_smaller_number = i32::try_from(3);
/// assert!(try_successful_smaller_number.is_ok());
/// ```
///
/// [`try_from`]: TryFrom::try_from
///
///
///
///
///
///
///
///
///
///
#[rustc_diagnostic_item = "TryFrom"]
#[stable(feature = "try_from", since = "1.34.0")]
pub trait TryFrom<T>: Sized {
/// 发生转换错误时返回的类型。
#[stable(feature = "try_from", since = "1.34.0")]
type Error;
/// 执行转换。
#[stable(feature = "try_from", since = "1.34.0")]
fn try_from(value: T) -> Result<Self, Self::Error>;
}
////////////////////////////////////////////////////////////////////////////////
// 泛型 IMPLS
////////////////////////////////////////////////////////////////////////////////
// 作为 lifts 结束 &
#[stable(feature = "rust1", since = "1.0.0")]
impl<T: ?Sized, U: ?Sized> AsRef<U> for &T
where
T: AsRef<U>,
{
#[inline]
fn as_ref(&self) -> &U {
<T as AsRef<U>>::as_ref(*self)
}
}
// As lifts over &mut
#[stable(feature = "rust1", since = "1.0.0")]
impl<T: ?Sized, U: ?Sized> AsRef<U> for &mut T
where
T: AsRef<U>,
{
#[inline]
fn as_ref(&self) -> &U {
<T as AsRef<U>>::as_ref(*self)
}
}
// FIXME (#45742): 用以下更通用的替代替换 &/&mut 的上述 impls:
// // As lifts over &mut
// impl<D: ?Sized + Deref<Target: AsRef<U>>, U: ?Sized> AsRef<U> for D { fn as_ref(&self) -> &U { self.deref().as_ref() } }
//
//
//
//
// AsMut lifts over &mut
#[stable(feature = "rust1", since = "1.0.0")]
impl<T: ?Sized, U: ?Sized> AsMut<U> for &mut T
where
T: AsMut<U>,
{
#[inline]
fn as_mut(&mut self) -> &mut U {
(*self).as_mut()
}
}
// FIXME (#45742): 用以下更通用的替代替换 &mut 的上述隐含内容:
// // AsMut lifts over DerefMut
// impl<D: ?Sized + Deref<Target: AsMut<U>>, U: ?Sized> AsMut<U> for D { fn as_mut(&mut self) -> &mut U { self.deref_mut().as_mut() } }
//
//
//
//
// From 暗指 Into
#[stable(feature = "rust1", since = "1.0.0")]
impl<T, U> Into<U> for T
where
U: From<T>,
{
/// 调用 `U::from(self)`。
///
/// 也就是说,这种转换是 <code>[From]\<T> for U</code> 实现选择执行的任何操作。
///
#[inline]
fn into(self) -> U {
U::from(self)
}
}
// From (因此 Into) 是反射性的
#[stable(feature = "rust1", since = "1.0.0")]
impl<T> From<T> for T {
/// 返回未更改的参数。
#[inline(always)]
fn from(t: T) -> T {
t
}
}
/// **稳定性注意事项:** 该 impl 尚不存在,但我们 "保留空间" 以在将来添加它。
/// 有关详细信息,请参见 [rust-lang/rust#64715][#64715]。
///
/// [#64715]: https://github.com/rust-lang/rust/issues/64715
///
#[stable(feature = "convert_infallible", since = "1.34.0")]
#[allow(unused_attributes)] // FIXME(#58633): 做一个有原则的修复。
#[rustc_reservation_impl = "permitting this impl would forbid us from adding \
`impl<T> From<!> for T` later; see rust-lang/rust#64715 for details"]
impl<T> From<!> for T {
fn from(t: !) -> T {
t
}
}
// TryFrom 表示 TryInto
#[stable(feature = "try_from", since = "1.34.0")]
impl<T, U> TryInto<U> for T
where
U: TryFrom<T>,
{
type Error = U::Error;
#[inline]
fn try_into(self) -> Result<U, U::Error> {
U::try_from(self)
}
}
// 可靠的转换在语义上等同于错误类型没有错误的可靠的转换。
//
#[stable(feature = "try_from", since = "1.34.0")]
impl<T, U> TryFrom<U> for T
where
U: Into<T>,
{
type Error = Infallible;
#[inline]
fn try_from(value: U) -> Result<Self, Self::Error> {
Ok(U::into(value))
}
}
////////////////////////////////////////////////////////////////////////////////
// CONCRETE IMPLS
////////////////////////////////////////////////////////////////////////////////
#[stable(feature = "rust1", since = "1.0.0")]
impl<T> AsRef<[T]> for [T] {
#[inline(always)]
fn as_ref(&self) -> &[T] {
self
}
}
#[stable(feature = "rust1", since = "1.0.0")]
impl<T> AsMut<[T]> for [T] {
#[inline(always)]
fn as_mut(&mut self) -> &mut [T] {
self
}
}
#[stable(feature = "rust1", since = "1.0.0")]
impl AsRef<str> for str {
#[inline(always)]
fn as_ref(&self) -> &str {
self
}
}
#[stable(feature = "as_mut_str_for_str", since = "1.51.0")]
impl AsMut<str> for str {
#[inline(always)]
fn as_mut(&mut self) -> &mut str {
self
}
}
////////////////////////////////////////////////////////////////////////////////
// NO-ERROR 错误类型
////////////////////////////////////////////////////////////////////////////////
/// 永远不会发生的错误的错误类型。
///
/// 由于此枚举没有变体,因此这种类型的值实际上永远不会存在。
/// 这对于使用 [`Result`] 并参数化错误类型的泛型 API 很有用,以指示结果始终为 [`Ok`]。
///
/// 例如,对于存在反向 [`Into`] 实现的所有类型,[`TryFrom`] trait (返回 [`Result`] 的转换) 都具有通用实现。
///
/// ```ignore (illustrates std code, duplicating the impl in a doctest would be an error)
/// impl<T, U> TryFrom<U> for T where U: Into<T> {
/// type Error = Infallible;
///
/// fn try_from(value: U) -> Result<Self, Infallible> {
/// Ok(U::into(value)) // 永不返回 `Err`
/// }
/// }
/// ```
///
/// # Future 兼容性
///
/// 该枚举与 [never 类型 (`!`)][never] 具有相同的作用,在此版本的 Rust 中是不稳定的。
/// 当 `!` 稳定后,我们计划将 `Infallible` 用作它的类型别名:
///
/// ```ignore (illustrates future std change)
/// pub type Infallible = !;
/// ```
///
/// … 并最终弃用 `Infallible`。
///
/// 但是,在一种情况下,可以在将 `!` 稳定为完整类型之前使用 `!` 语法:在函数的返回类型位置。
/// 具体来说,可以实现两种不同的函数指针类型:
///
/// ```
/// trait MyTrait {}
/// impl MyTrait for fn() -> ! {}
/// impl MyTrait for fn() -> std::convert::Infallible {}
/// ```
///
/// `Infallible` 是一个枚举,这个代码是有效的。
/// 但是,当 `Infallible` 成为 never type 的别名时,两个 `impl` 将开始重叠,因此将被语言的 trait 一致性规则所禁止。
///
///
///
///
///
///
#[stable(feature = "convert_infallible", since = "1.34.0")]
#[derive(Copy)]
pub enum Infallible {}
#[stable(feature = "convert_infallible", since = "1.34.0")]
impl Clone for Infallible {
fn clone(&self) -> Infallible {
match *self {}
}
}
#[stable(feature = "convert_infallible", since = "1.34.0")]
impl fmt::Debug for Infallible {
fn fmt(&self, _: &mut fmt::Formatter<'_>) -> fmt::Result {
match *self {}
}
}
#[stable(feature = "convert_infallible", since = "1.34.0")]
impl fmt::Display for Infallible {
fn fmt(&self, _: &mut fmt::Formatter<'_>) -> fmt::Result {
match *self {}
}
}
#[stable(feature = "str_parse_error2", since = "1.8.0")]
impl Error for Infallible {
fn description(&self) -> &str {
match *self {}
}
}
#[stable(feature = "convert_infallible", since = "1.34.0")]
impl PartialEq for Infallible {
fn eq(&self, _: &Infallible) -> bool {
match *self {}
}
}
#[stable(feature = "convert_infallible", since = "1.34.0")]
impl Eq for Infallible {}
#[stable(feature = "convert_infallible", since = "1.34.0")]
impl PartialOrd for Infallible {
fn partial_cmp(&self, _other: &Self) -> Option<crate::cmp::Ordering> {
match *self {}
}
}
#[stable(feature = "convert_infallible", since = "1.34.0")]
impl Ord for Infallible {
fn cmp(&self, _other: &Self) -> crate::cmp::Ordering {
match *self {}
}
}
#[stable(feature = "convert_infallible", since = "1.34.0")]
impl From<!> for Infallible {
#[inline]
fn from(x: !) -> Self {
x
}
}
#[stable(feature = "convert_infallible_hash", since = "1.44.0")]
impl Hash for Infallible {
fn hash<H: Hasher>(&self, _: &mut H) {
match *self {}
}
}