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
//! 该模块实现了 `Any` trait,它可以通过运行时反射来动态键入任何 `'static` 类型。
//!
//! `Any` 本身可以用来得到一个 `TypeId`,当用作 trait 对象时,它有更多的特性。
//! 作为 `&dyn Any` (借用的 trait 对象),它具有 `is` 和 `downcast_ref` 方法,以测试所包含的值是否为给定类型,并对该类型的内部值进行引用。
//! 作为 `&mut dyn Any`,还有 `downcast_mut` 方法,用于获取内部值的变量引用。
//! `Box<dyn Any>` 添加了 `downcast` 方法,该方法尝试转换为 `Box<T>`。
//! 有关完整的详细信息,请参见 [`Box`] 文档。
//!
//! 请注意,`&dyn Any` 仅限于测试值是否为指定的具体类型,而不能用于测试某个类型是否实现 trait。
//!
//! [`Box`]: ../../std/boxed/struct.Box.html
//!
//! # 智能指针和 `dyn Any`
//!
//! 将 `Any` 用作 trait 对象时要记住的一种行为,尤其是对于 `Box<dyn Any>` 或 `Arc<dyn Any>` 之类的类型,只需在值上调用 `.type_id()` 即可生成容器的 `TypeId`,而不是底层 trait 对象。
//!
//! 可以通过将智能指针转换为 `&dyn Any` 来避免,这将返回对象的 `TypeId`。
//! 例如:
//!
//! ```
//! use std::any::{Any, TypeId};
//!
//! let boxed: Box<dyn Any> = Box::new(3_i32);
//!
//! // 您更可能希望这样做:
//! let actual_id = (&*boxed).type_id();
//! // ... 比这个:
//! let boxed_id = boxed.type_id();
//!
//! assert_eq!(actual_id, TypeId::of::<i32>());
//! assert_eq!(boxed_id, TypeId::of::<Box<dyn Any>>());
//! ```
//!
//! # Examples
//!
//! 考虑一下我们要注销传递给函数的值的情况。
//! 我们知道我们正在实现的值实现了 Debug,但是我们不知道它的具体类型。我们要对某些类型进行特殊处理:在这种情况下,应先打印 String 值的长度,然后再打印它们的值。
//! 我们在编译时不知道我们值的具体类型,因此我们需要使用运行时反射。
//!
//! ```rust
//! use std::fmt::Debug;
//! use std::any::Any;
//!
//! // 用于实现 Debug 的任何类型的 Logger 函数。
//! fn log<T: Any + Debug>(value: &T) {
//!     let value_any = value as &dyn Any;
//!
//!     // 尝试将我们的值转换为 `String`。
//!     // 如果成功,我们要输出 String 的长度及其值。
//!     // 如果不是,那就是另一种类型:只需将其打印出来即可。
//!     match value_any.downcast_ref::<String>() {
//!         Some(as_string) => {
//!             println!("String ({}): {}", as_string.len(), as_string);
//!         }
//!         None => {
//!             println!("{:?}", value);
//!         }
//!     }
//! }
//!
//! // 该函数要先注销其参数,然后再使用它。
//! fn do_work<T: Any + Debug>(value: &T) {
//!     log(value);
//!     // ... 做一些其他的工作
//! }
//!
//! fn main() {
//!     let my_string = "Hello World".to_string();
//!     do_work(&my_string);
//!
//!     let my_i8: i8 = 100;
//!     do_work(&my_i8);
//! }
//! ```
//!
//!
//!
//!
//!
//!
//!
//!
//!

#![stable(feature = "rust1", since = "1.0.0")]

use crate::fmt;
use crate::intrinsics;

///////////////////////////////////////////////////////////////////////////////
// 任何 trait
///////////////////////////////////////////////////////////////////////////////

/// 一个用来模拟动态类型的 trait。
///
/// 大多数类型都实现了 `Any`。但是,任何包含非 `static' 引用的类型都不会。
/// 有关更多详细信息,请参见 [模块级文档][mod]。
///
/// [mod]: crate::any
// 这个 trait 并不是不安全的,尽管我们依靠不安全代码 (例如 `downcast`) 中唯一的 impl 的 `type_id` 函数的细节。通常,这将是一个问题,但是由于 `Any` 的唯一含义是全面实现,因此没有其他代码可以实现 `Any`。
//
// 我们可以合理地使此 trait 不安全 - 因为我们控制所有实现,因此不会造成破坏 - 但我们选择不这样做,因为这既不是真正必要的,并且可能使用户混淆不安全的 traits 和不安全的方法 (即,`type_id` 仍然可以安全调用,但我们可能希望在文档中对此进行说明。
//
//
//
//
//
//
//
#[stable(feature = "rust1", since = "1.0.0")]
#[cfg_attr(not(test), rustc_diagnostic_item = "Any")]
pub trait Any: 'static {
    /// 获取 `self` 的 `TypeId`。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::any::{Any, TypeId};
    ///
    /// fn is_string(s: &dyn Any) -> bool {
    ///     TypeId::of::<String>() == s.type_id()
    /// }
    ///
    /// assert_eq!(is_string(&0), false);
    /// assert_eq!(is_string(&"cookie monster".to_string()), true);
    /// ```
    #[stable(feature = "get_type_id", since = "1.34.0")]
    fn type_id(&self) -> TypeId;
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T: 'static + ?Sized> Any for T {
    fn type_id(&self) -> TypeId {
        TypeId::of::<T>()
    }
}

///////////////////////////////////////////////////////////////////////////////
// 任何 trait 对象的扩展方法。
///////////////////////////////////////////////////////////////////////////////

#[stable(feature = "rust1", since = "1.0.0")]
impl fmt::Debug for dyn Any {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Any").finish_non_exhaustive()
    }
}

// 确保可以打印出例如连接螺纹的结果,并因此可以与 `unwrap` 一起使用。
// 如果调度与向上转换一起使用,则最终可能不再需要。
//
#[stable(feature = "rust1", since = "1.0.0")]
impl fmt::Debug for dyn Any + Send {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Any").finish_non_exhaustive()
    }
}

#[stable(feature = "any_send_sync_methods", since = "1.28.0")]
impl fmt::Debug for dyn Any + Send + Sync {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Any").finish_non_exhaustive()
    }
}

impl dyn Any {
    /// 如果 boxed 类型与 `T` 相同,则返回 `true`。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::any::Any;
    ///
    /// fn is_string(s: &dyn Any) {
    ///     if s.is::<String>() {
    ///         println!("It's a string!");
    ///     } else {
    ///         println!("Not a string...");
    ///     }
    /// }
    ///
    /// is_string(&0);
    /// is_string(&"cookie monster".to_string());
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    #[inline]
    pub fn is<T: Any>(&self) -> bool {
        // 获取实例化此函数的类型的 `TypeId`。
        let t = TypeId::of::<T>();

        // 在 trait 对象 (`self`) 中获取该类型的 `TypeId`。
        let concrete = self.type_id();

        // 比较两个 `TypeId` 的相等性。
        t == concrete
    }

    /// 如果 boxed 的类型为 `T`,则返回一些引用,如果不是,则返回 `None`。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::any::Any;
    ///
    /// fn print_if_string(s: &dyn Any) {
    ///     if let Some(string) = s.downcast_ref::<String>() {
    ///         println!("It's a string({}): '{}'", string.len(), string);
    ///     } else {
    ///         println!("Not a string...");
    ///     }
    /// }
    ///
    /// print_if_string(&0);
    /// print_if_string(&"cookie monster".to_string());
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    #[inline]
    pub fn downcast_ref<T: Any>(&self) -> Option<&T> {
        if self.is::<T>() {
            // SAFETY: 只需检查我们是否指向正确的类型,就可以依靠该检查来检查内存安全性,因为我们对所有类型都实现了 Any; 没有其他迹象可能会存在,因为它们会与我们的迹象发生冲突。
            //
            //
            unsafe { Some(&*(self as *const dyn Any as *const T)) }
        } else {
            None
        }
    }

    /// 如果 boxed 的类型为 `T`,则返回一些可变引用; 如果不是,则返回 `None`。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::any::Any;
    ///
    /// fn modify_if_u32(s: &mut dyn Any) {
    ///     if let Some(num) = s.downcast_mut::<u32>() {
    ///         *num = 42;
    ///     }
    /// }
    ///
    /// let mut x = 10u32;
    /// let mut s = "starlord".to_string();
    ///
    /// modify_if_u32(&mut x);
    /// modify_if_u32(&mut s);
    ///
    /// assert_eq!(x, 42);
    /// assert_eq!(&s, "starlord");
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    #[inline]
    pub fn downcast_mut<T: Any>(&mut self) -> Option<&mut T> {
        if self.is::<T>() {
            // SAFETY: 只需检查我们是否指向正确的类型,就可以依靠该检查来检查内存安全性,因为我们对所有类型都实现了 Any; 没有其他迹象可能会存在,因为它们会与我们的迹象发生冲突。
            //
            //
            unsafe { Some(&mut *(self as *mut dyn Any as *mut T)) }
        } else {
            None
        }
    }
}

impl dyn Any + Send {
    /// 转发到在 `Any` 类型上定义的方法。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::any::Any;
    ///
    /// fn is_string(s: &(dyn Any + Send)) {
    ///     if s.is::<String>() {
    ///         println!("It's a string!");
    ///     } else {
    ///         println!("Not a string...");
    ///     }
    /// }
    ///
    /// is_string(&0);
    /// is_string(&"cookie monster".to_string());
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    #[inline]
    pub fn is<T: Any>(&self) -> bool {
        <dyn Any>::is::<T>(self)
    }

    /// 转发到在 `Any` 类型上定义的方法。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::any::Any;
    ///
    /// fn print_if_string(s: &(dyn Any + Send)) {
    ///     if let Some(string) = s.downcast_ref::<String>() {
    ///         println!("It's a string({}): '{}'", string.len(), string);
    ///     } else {
    ///         println!("Not a string...");
    ///     }
    /// }
    ///
    /// print_if_string(&0);
    /// print_if_string(&"cookie monster".to_string());
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    #[inline]
    pub fn downcast_ref<T: Any>(&self) -> Option<&T> {
        <dyn Any>::downcast_ref::<T>(self)
    }

    /// 转发到在 `Any` 类型上定义的方法。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::any::Any;
    ///
    /// fn modify_if_u32(s: &mut (dyn Any + Send)) {
    ///     if let Some(num) = s.downcast_mut::<u32>() {
    ///         *num = 42;
    ///     }
    /// }
    ///
    /// let mut x = 10u32;
    /// let mut s = "starlord".to_string();
    ///
    /// modify_if_u32(&mut x);
    /// modify_if_u32(&mut s);
    ///
    /// assert_eq!(x, 42);
    /// assert_eq!(&s, "starlord");
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    #[inline]
    pub fn downcast_mut<T: Any>(&mut self) -> Option<&mut T> {
        <dyn Any>::downcast_mut::<T>(self)
    }
}

impl dyn Any + Send + Sync {
    /// 转发到在 `Any` 类型上定义的方法。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::any::Any;
    ///
    /// fn is_string(s: &(dyn Any + Send + Sync)) {
    ///     if s.is::<String>() {
    ///         println!("It's a string!");
    ///     } else {
    ///         println!("Not a string...");
    ///     }
    /// }
    ///
    /// is_string(&0);
    /// is_string(&"cookie monster".to_string());
    /// ```
    #[stable(feature = "any_send_sync_methods", since = "1.28.0")]
    #[inline]
    pub fn is<T: Any>(&self) -> bool {
        <dyn Any>::is::<T>(self)
    }

    /// 转发到在 `Any` 类型上定义的方法。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::any::Any;
    ///
    /// fn print_if_string(s: &(dyn Any + Send + Sync)) {
    ///     if let Some(string) = s.downcast_ref::<String>() {
    ///         println!("It's a string({}): '{}'", string.len(), string);
    ///     } else {
    ///         println!("Not a string...");
    ///     }
    /// }
    ///
    /// print_if_string(&0);
    /// print_if_string(&"cookie monster".to_string());
    /// ```
    #[stable(feature = "any_send_sync_methods", since = "1.28.0")]
    #[inline]
    pub fn downcast_ref<T: Any>(&self) -> Option<&T> {
        <dyn Any>::downcast_ref::<T>(self)
    }

    /// 转发到在 `Any` 类型上定义的方法。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::any::Any;
    ///
    /// fn modify_if_u32(s: &mut (dyn Any + Send + Sync)) {
    ///     if let Some(num) = s.downcast_mut::<u32>() {
    ///         *num = 42;
    ///     }
    /// }
    ///
    /// let mut x = 10u32;
    /// let mut s = "starlord".to_string();
    ///
    /// modify_if_u32(&mut x);
    /// modify_if_u32(&mut s);
    ///
    /// assert_eq!(x, 42);
    /// assert_eq!(&s, "starlord");
    /// ```
    #[stable(feature = "any_send_sync_methods", since = "1.28.0")]
    #[inline]
    pub fn downcast_mut<T: Any>(&mut self) -> Option<&mut T> {
        <dyn Any>::downcast_mut::<T>(self)
    }
}

///////////////////////////////////////////////////////////////////////////////
// TypeID 及其方法
///////////////////////////////////////////////////////////////////////////////

/// `TypeId` 代表类型的全局唯一标识符。
///
/// 每个 `TypeId` 是不透明的对象,它不允许检查内部内容,但可以进行基本操作,例如克隆,比较,打印和显示。
///
///
/// `TypeId` 当前仅适用于归因于 `'static` 的类型,但是可以在 future 中消除此限制。
///
/// 虽然 `TypeId` 实现 `Hash`,`PartialOrd` 和 `Ord`,但值得注意的是,在 Rust 版本之间,哈希值和顺序将有所不同。
/// 注意不要在代码中依赖它们!
///
///
///
#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Debug, Hash)]
#[stable(feature = "rust1", since = "1.0.0")]
pub struct TypeId {
    t: u64,
}

impl TypeId {
    /// 返回已实例化此泛型函数的类型的 `TypeId`。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::any::{Any, TypeId};
    ///
    /// fn is_string<T: ?Sized + Any>(_s: &T) -> bool {
    ///     TypeId::of::<String>() == TypeId::of::<T>()
    /// }
    ///
    /// assert_eq!(is_string(&0), false);
    /// assert_eq!(is_string(&"cookie monster".to_string()), true);
    /// ```
    #[must_use]
    #[stable(feature = "rust1", since = "1.0.0")]
    #[rustc_const_unstable(feature = "const_type_id", issue = "77125")]
    pub const fn of<T: ?Sized + 'static>() -> TypeId {
        TypeId { t: intrinsics::type_id::<T>() }
    }
}

/// 以字符串切片的形式返回类型的名称。
///
/// # Note
///
/// 这旨在用于诊断。
/// 除了作为尽力而为的类型描述之外,未指定返回的字符串的确切内容和格式。
/// 例如,在 `type_name::<Option<String>>()` 可能返回的字符串中,有 `"Option<String>"` 和 `"std::option::Option<std::string::String>"`。
///
///
/// 返回的字符串不得视为类型的唯一标识符,因为多个类型可能会 map 变为相同的类型名称。
/// 同样,不能保证类型的所有部分都将出现在返回的字符串中:例如,当前不包括生命周期说明符。
/// 此外,输出可能会在编译器的版本之间改变。
///
/// 当前的实现使用与编译器诊断和 debuginfo 相同的基础结构,但这不能保证。
///
/// # Examples
///
/// ```rust
/// assert_eq!(
///     std::any::type_name::<Option<String>>(),
///     "core::option::Option<alloc::string::String>",
/// );
/// ```
///
///
///
///
#[must_use]
#[stable(feature = "type_name", since = "1.38.0")]
#[rustc_const_unstable(feature = "const_type_name", issue = "63084")]
pub const fn type_name<T: ?Sized>() -> &'static str {
    intrinsics::type_name::<T>()
}

/// 以字符串切片的形式返回指向的值的类型的名称。
/// 这与 `type_name::<T>()` 相同,但是可以在不容易获得变量类型的地方使用。
///
/// # Note
///
/// 这旨在用于诊断。没有指定字符串的确切内容和格式,只是对类型的尽力描述。
/// 例如,`type_name_of_val::<Option<String>>(None)` 可以返回 `"Option<String>"` 或 `"std::option::Option<std::string::String>"`,但不能返回 `"foobar"`。
///
/// 此外,输出可能会在编译器的版本之间改变。
///
/// 此函数不能解析 trait 对象,这意味着 `type_name_of_val(&7u32 as &dyn Debug)` 可以返回 `"dyn Debug"`,但不能返回 `"u32"`。
///
/// 类型名称不应视为类型的唯一标识符;
/// 多个类型可以共享相同的类型名称。
///
/// 当前的实现使用与编译器诊断和 debuginfo 相同的基础结构,但这不能保证。
///
/// # Examples
///
/// 打印默认的整数和浮点类型。
///
/// ```rust
/// #![feature(type_name_of_val)]
/// use std::any::type_name_of_val;
///
/// let x = 1;
/// println!("{}", type_name_of_val(&x));
/// let y = 1.0;
/// println!("{}", type_name_of_val(&y));
/// ```
///
///
///
///
///
///
#[must_use]
#[unstable(feature = "type_name_of_val", issue = "66359")]
#[rustc_const_unstable(feature = "const_type_name", issue = "63084")]
pub const fn type_name_of_val<T: ?Sized>(_val: &T) -> &'static str {
    type_name::<T>()
}