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 {}
    }
}