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
//! 用于类型之间的转换 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`] 自动解引用
//! - [`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::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 = vec![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]
pub const fn identity<T>(x: T) -> T {
    x
}

/// 用于执行廉价的引用到引用转换。
///
/// 一个类似于 [`AsMut`] 的 trait,用于在可变引用之间进行转换。
/// 如果您需要进行代价高昂的转换,最好用 `&T` 类型实现 [`From`],或者编写一个自定义函数。
///
/// `AsRef` 与 [`Borrow`] 具有相同的签名,但 [`Borrow`] 在几个方面有所不同:
///
/// - 与 `AsRef` 不同,[`Borrow`] 对任何 `T` 都有一个毯子暗示,可用于接受引用或值。
/// - [`Borrow`] 还要求借用值的 [`Hash`]、[`Eq`] 和 [`Ord`] 与拥有的值相等。
/// 因此,如果只想借用一个结构体的单个字段,则可以实现 `AsRef`,而不能实现 [`Borrow`]。
///
/// **注意:此 trait 一定不能失败**。如果转换失败,请使用专用方法返回 [`Option<T>`] 或 [`Result<T, E>`]。
///
/// # 泛型实现
///
/// - 如果内部类型是引用或可变引用,则 `AsRef` 自动解引用 (例如:如果 `foo` 具有类型 `&mut Foo` 或 `&&mut Foo`,则 `foo.as_ref()` 将同样有效)
///
///
/// # Examples
///
/// 通过使用 trait bounds,我们可以接受不同类型的参数,只要它们可以转换为指定的 `T` 类型即可。
///
/// 例如:通过创建一个采用 `AsRef<str>` 的泛型函数,我们表示我们希望接受所有可以转换为 [`&str`] 的引用作为参数。
/// 由于 [`String`] 和 [`&str`] 都实现了 `AsRef<str>`,因此我们可以将两者都用作输入参数。
///
/// [`&str`]: [email protected]
/// [`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 ()` 将工作相同)
///
///
/// # Examples
///
/// 使用 `AsMut` 作为泛型函数的 trait bound,我们可以接受所有可以转换为 `&mut T` 类型的变量引用。
/// 因为 [`Box<T>`] 实现了 `AsMut<T>`,所以我们可以编写一个函数 `add_one`,该函数采用可以转换为 `&mut u64` 的所有参数。
/// 由于 [`Box<T>`] 实现 `AsMut<T>`,因此 `add_one` 也接受 `&mut Box<u64>` 类型的参数:
///
/// ```
/// fn add_one<T: AsMut<u64>>(num: &mut T) {
///     *num.as_mut() += 1;
/// }
///
/// let mut boxed_num = Box::new(0);
/// add_one(&mut boxed_num);
/// assert_eq!(*boxed_num, 1);
/// ```
///
/// [`Box<T>`]: ../../std/boxed/struct.Box.html
///
///
///
///
///
#[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 一定不能失败**。如果转换可能失败,请使用 [`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 {
    /// 执行转换。
    #[lang = "from"]
    #[must_use]
    #[stable(feature = "rust1", since = "1.0.0")]
    fn from(_: 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>` 可以实现如下:
///
/// ```
/// use std::convert::TryFrom;
///
/// 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 value superior than zero!")
///         } else {
///             Ok(GreaterThanZero(value))
///         }
///     }
/// }
/// ```
///
/// # Examples
///
/// 如上所述,[`i32`] 实现了 `TryFrom<`[`i64`]`>`:
///
/// ```
/// use std::convert::TryFrom;
///
/// 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
////////////////////////////////////////////////////////////////////////////////

// As lifts over &
#[stable(feature = "rust1", since = "1.0.0")]
impl<T: ?Sized, U: ?Sized> AsRef<U> for &T
where
    T: AsRef<U>,
{
    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>,
{
    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>,
{
    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>,
{
    fn into(self) -> U {
        U::from(self)
    }
}

// From (因此 Into) 是反射性的
#[stable(feature = "rust1", since = "1.0.0")]
#[rustc_const_unstable(feature = "const_convert", issue = "88674")]
impl<T> const From<T> for T {
    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"]
#[rustc_const_unstable(feature = "const_convert", issue = "88674")]
impl<T> const 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;

    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;

    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] {
    fn as_ref(&self) -> &[T] {
        self
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T> AsMut<[T]> for [T] {
    fn as_mut(&mut self) -> &mut [T] {
        self
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl AsRef<str> for str {
    #[inline]
    fn as_ref(&self) -> &str {
        self
    }
}

#[stable(feature = "as_mut_str_for_str", since = "1.51.0")]
impl AsMut<str> for str {
    #[inline]
    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 = "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")]
#[rustc_const_unstable(feature = "const_convert", issue = "88674")]
impl const From<!> for Infallible {
    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 {}
    }
}