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 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299
//! 用于动态类型或类型反射的实用工具。
//!
//! # `Any` 和 `TypeId`
//!
//! `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);
//! }
//! ```
//!
//! # `Provider` 和 `Demand`
//!
//! `Provider` 和相关的 API 支持泛型、类型驱动的数据访问,以及实现者提供此类数据的机制。
//! 该接口的关键部分是用于提供数据的对象的 `Provider` trait,以及用于从实现 `Provider` 的对象请求数据的 [`request_value`] 和 [`request_ref`] 函数。
//! 通常,最终用户不应该直接调用 `request_*`,它们是中间实现者用来实现面向用户的接口的辅助函数。
//! 这纯粹是为了人体工程学,这里没有安全问题; 中间实现者通常可以支持方法而不是 free 函数,并使用更具体的名称。
//!
//! 通常,数据提供者是扩展 `Provider` 的 trait 的 trait 对象。用户将通过指定数据的类型从 trait 对象请求数据。
//!
//! ## 数据流
//!
//! * 用户请求特定类型的对象,该对象委托给 `request_value` 或 `request_ref`
//! * `request_*` 创建一个 `Demand` 对象并将其传递给 `Provider::provide`
//! * `Provider::provide` 的数据提供者实现尝试使用 `Demand::provide_*` 提供不同类型的值。如果类型与用户请求的类型匹配,则该值将存储在 `Demand` 对象中。
//! * `request_*` 解包 `Demand` 对象并将任何存储的值返回给用户。
//!
//! ## Examples
//!
//! ```
//! # #![feature(provide_any)]
//! use std::any::{Provider, Demand, request_ref};
//!
//! // MyTrait 的定义,一个数据提供者。
//! trait MyTrait: Provider {
//! // ...
//! }
//!
//! // `MyTrait` trait 对象的方法。
//! impl dyn MyTrait + '_ {
//! /// 获取对实现结构体的字段的引用。
//! pub fn get_context_by_ref<T: ?Sized + 'static>(&self) -> Option<&T> {
//! request_ref::<T>(self)
//! }
//! }
//!
//! // `MyTrait` 和 `Provider` 的下游实现。
//! # struct SomeConcreteType { some_string: String }
//! impl MyTrait for SomeConcreteType {
//! // ...
//! }
//!
//! impl Provider for SomeConcreteType {
//! fn provide<'a>(&'a self, demand: &mut Demand<'a>) {
//! // 提供一个字符串引用。
//! // 我们可以在这里提供不同类型的多个值。
//! demand.provide_ref::<String>(&self.some_string);
//! }
//! }
//!
//! // `MyTrait` 的下游用法。
//! fn use_my_trait(obj: &dyn MyTrait) {
//! // 向 obj 请求 &String。
//! let _ = obj.get_context_by_ref::<String>().unwrap();
//! }
//! ```
//!
//! 在这个例子中,如果 `use_my_trait` 中 `obj` 的具体类型是 `SomeConcreteType`,那么 `get_context_by_ref` 调用将返回一个引用给 `&String` 类型的 `obj.some_string`。
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
#![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 {
/// 如果内部类型与 `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
}
/// 如果内部值的类型为 `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.downcast_ref_unchecked()) }
} else {
None
}
}
/// 如果内部值的类型为 `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(self.downcast_mut_unchecked()) }
} else {
None
}
}
/// 返回对内部值的引用,类型为 `dyn T`。
///
/// # Examples
///
/// ```
/// #![feature(downcast_unchecked)]
///
/// use std::any::Any;
///
/// let x: Box<dyn Any> = Box::new(1_usize);
///
/// unsafe {
/// assert_eq!(*x.downcast_ref_unchecked::<usize>(), 1);
/// }
/// ```
///
/// # Safety
///
/// 包含的值必须是 `T` 类型。
/// 使用不正确的类型调用此方法是 *未定义的行为*。
#[unstable(feature = "downcast_unchecked", issue = "90850")]
#[inline]
pub unsafe fn downcast_ref_unchecked<T: Any>(&self) -> &T {
debug_assert!(self.is::<T>());
// SAFETY: 调用者保证 T 是正确的类型
unsafe { &*(self as *const dyn Any as *const T) }
}
/// 返回对内部值的可变引用,类型为 `dyn T`
///
/// # Examples
///
/// ```
/// #![feature(downcast_unchecked)]
///
/// use std::any::Any;
///
/// let mut x: Box<dyn Any> = Box::new(1_usize);
///
/// unsafe {
/// *x.downcast_mut_unchecked::<usize>() += 1;
/// }
///
/// assert_eq!(*x.downcast_ref::<usize>().unwrap(), 2);
/// ```
///
/// # Safety
///
/// 包含的值必须是 `T` 类型。
/// 使用不正确的类型调用此方法是 *未定义的行为*。
#[unstable(feature = "downcast_unchecked", issue = "90850")]
#[inline]
pub unsafe fn downcast_mut_unchecked<T: Any>(&mut self) -> &mut T {
debug_assert!(self.is::<T>());
// SAFETY: 调用者保证 T 是正确的类型
unsafe { &mut *(self as *mut dyn Any as *mut T) }
}
}
impl dyn Any + Send {
/// 转发到在类型 `dyn 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)
}
/// 转发到在类型 `dyn 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)
}
/// 转发到在类型 `dyn 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)
}
/// 转发到在类型 `dyn Any` 上定义的方法。
///
/// # Examples
///
/// ```
/// #![feature(downcast_unchecked)]
///
/// use std::any::Any;
///
/// let x: Box<dyn Any> = Box::new(1_usize);
///
/// unsafe {
/// assert_eq!(*x.downcast_ref_unchecked::<usize>(), 1);
/// }
/// ```
///
/// # Safety
///
/// 与 `dyn Any` 类型上的方法相同。
#[unstable(feature = "downcast_unchecked", issue = "90850")]
#[inline]
pub unsafe fn downcast_ref_unchecked<T: Any>(&self) -> &T {
// SAFETY: 由调用者保证
unsafe { <dyn Any>::downcast_ref_unchecked::<T>(self) }
}
/// 转发到在类型 `dyn Any` 上定义的方法。
///
/// # Examples
///
/// ```
/// #![feature(downcast_unchecked)]
///
/// use std::any::Any;
///
/// let mut x: Box<dyn Any> = Box::new(1_usize);
///
/// unsafe {
/// *x.downcast_mut_unchecked::<usize>() += 1;
/// }
///
/// assert_eq!(*x.downcast_ref::<usize>().unwrap(), 2);
/// ```
///
/// # Safety
///
/// 与 `dyn Any` 类型上的方法相同。
#[unstable(feature = "downcast_unchecked", issue = "90850")]
#[inline]
pub unsafe fn downcast_mut_unchecked<T: Any>(&mut self) -> &mut T {
// SAFETY: 由调用者保证
unsafe { <dyn Any>::downcast_mut_unchecked::<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)
}
/// 转发到在 `Any` 类型上定义的方法。
///
/// # Examples
///
/// ```
/// #![feature(downcast_unchecked)]
///
/// use std::any::Any;
///
/// let x: Box<dyn Any> = Box::new(1_usize);
///
/// unsafe {
/// assert_eq!(*x.downcast_ref_unchecked::<usize>(), 1);
/// }
/// ```
#[unstable(feature = "downcast_unchecked", issue = "90850")]
#[inline]
pub unsafe fn downcast_ref_unchecked<T: Any>(&self) -> &T {
// SAFETY: 由调用者保证
unsafe { <dyn Any>::downcast_ref_unchecked::<T>(self) }
}
/// 转发到在 `Any` 类型上定义的方法。
///
/// # Examples
///
/// ```
/// #![feature(downcast_unchecked)]
///
/// use std::any::Any;
///
/// let mut x: Box<dyn Any> = Box::new(1_usize);
///
/// unsafe {
/// *x.downcast_mut_unchecked::<usize>() += 1;
/// }
///
/// assert_eq!(*x.downcast_ref::<usize>().unwrap(), 2);
/// ```
#[unstable(feature = "downcast_unchecked", issue = "90850")]
#[inline]
pub unsafe fn downcast_mut_unchecked<T: Any>(&mut self) -> &mut T {
// SAFETY: 由调用者保证
unsafe { <dyn Any>::downcast_mut_unchecked::<T>(self) }
}
}
///////////////////////////////////////////////////////////////////////////////
// TypeID 及其方法
///////////////////////////////////////////////////////////////////////////////
/// `TypeId` 代表类型的全局唯一标识符。
///
/// 每个 `TypeId` 是不透明的对象,它不允许检查内部内容,但可以进行基本操作,例如克隆,比较,打印和显示。
///
///
/// `TypeId` 当前仅适用于归因于 `'static` 的类型,但是可以在 future 中消除此限制。
///
/// 虽然 `TypeId` 实现 `Hash`,`PartialOrd` 和 `Ord`,但值得注意的是,在 Rust 版本之间,哈希值和顺序将有所不同。
/// 注意不要在代码中依赖它们!
///
///
///
#[derive(Clone, Copy, Debug, Hash, Eq, PartialOrd, Ord)]
#[stable(feature = "rust1", since = "1.0.0")]
pub struct TypeId {
t: u64,
}
#[stable(feature = "rust1", since = "1.0.0")]
impl PartialEq for TypeId {
#[inline]
fn eq(&self, other: &Self) -> bool {
self.t == other.t
}
}
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>()
}
///////////////////////////////////////////////////////////////////////////////
// Provider trait
///////////////////////////////////////////////////////////////////////////////
/// Trait 由可以根据类型动态提供值的类型实现。
#[unstable(feature = "provide_any", issue = "96024")]
pub trait Provider {
/// 数据提供者应实现此方法以提供他们能够通过使用 `demand` 提供的*所有*值。
///
/// 请注意,`Demand` 上的 `provide_*` 方法具有短路语义: 如果较早的方法已成功提供值,则以后的方法将没有机会提供。
///
///
/// # Examples
///
/// 提供对类型为 `String` 的字段的引用作为 `&str`,以及类型为 `i32` 的值。
///
/// ```rust
/// # #![feature(provide_any)]
/// use std::any::{Provider, Demand};
/// # struct SomeConcreteType { field: String, num_field: i32 }
///
/// impl Provider for SomeConcreteType {
/// fn provide<'a>(&'a self, demand: &mut Demand<'a>) {
/// demand.provide_ref::<str>(&self.field)
/// .provide_value::<i32>(self.num_field);
/// }
/// }
/// ```
///
///
///
#[unstable(feature = "provide_any", issue = "96024")]
fn provide<'a>(&'a self, demand: &mut Demand<'a>);
}
/// 从 `Provider` 请求一个值。
///
/// # Examples
///
/// 从提供者处获取字符串值。
///
/// ```rust
/// # #![feature(provide_any)]
/// use std::any::{Provider, request_value};
///
/// fn get_string(provider: &impl Provider) -> String {
/// request_value::<String>(provider).unwrap()
/// }
/// ```
#[unstable(feature = "provide_any", issue = "96024")]
pub fn request_value<'a, T>(provider: &'a (impl Provider + ?Sized)) -> Option<T>
where
T: 'static,
{
request_by_type_tag::<'a, tags::Value<T>>(provider)
}
/// 从 `Provider` 请求引用。
///
/// # Examples
///
/// 从提供者处获取字符串引用。
///
/// ```rust
/// # #![feature(provide_any)]
/// use std::any::{Provider, request_ref};
///
/// fn get_str(provider: &impl Provider) -> &str {
/// request_ref::<str>(provider).unwrap()
/// }
/// ```
#[unstable(feature = "provide_any", issue = "96024")]
pub fn request_ref<'a, T>(provider: &'a (impl Provider + ?Sized)) -> Option<&'a T>
where
T: 'static + ?Sized,
{
request_by_type_tag::<'a, tags::Ref<tags::MaybeSizedValue<T>>>(provider)
}
/// 通过 `Provider` 的标签请求特定值。
fn request_by_type_tag<'a, I>(provider: &'a (impl Provider + ?Sized)) -> Option<I::Reified>
where
I: tags::Type<'a>,
{
let mut tagged = TaggedOption::<'a, I>(None);
provider.provide(tagged.as_demand());
tagged.0
}
///////////////////////////////////////////////////////////////////////////////
// 需求及其方法
///////////////////////////////////////////////////////////////////////////////
/// 用于按类型提供数据的帮助器对象。
///
/// 数据提供者通过调用此类型的提供方法来提供值。
#[unstable(feature = "provide_any", issue = "96024")]
#[cfg_attr(not(doc), repr(transparent))] // work around https://github.com/rust-lang/rust/issues/90435
pub struct Demand<'a>(dyn Erased<'a> + 'a);
impl<'a> Demand<'a> {
/// 从 `&mut dyn Erased` trait 对象创建一个新的 `&mut Demand`。
fn new<'b>(erased: &'b mut (dyn Erased<'a> + 'a)) -> &'b mut Demand<'a> {
// SAFETY: 将 `&mut (dyn Erased<'a> + 'a)` 转换为 `&mut Demand<'a>` 是安全的,因为 `Demand` 是 repr(transparent)。
//
unsafe { &mut *(erased as *mut dyn Erased<'a> as *mut Demand<'a>) }
}
/// 提供仅具有静态生命周期的值或其他类型。
///
/// # Examples
///
/// 提供 `u8`。
///
/// ```rust
/// #![feature(provide_any)]
///
/// use std::any::{Provider, Demand};
/// # struct SomeConcreteType { field: u8 }
///
/// impl Provider for SomeConcreteType {
/// fn provide<'a>(&'a self, demand: &mut Demand<'a>) {
/// demand.provide_value::<u8>(self.field);
/// }
/// }
/// ```
#[unstable(feature = "provide_any", issue = "96024")]
pub fn provide_value<T>(&mut self, value: T) -> &mut Self
where
T: 'static,
{
self.provide::<tags::Value<T>>(value)
}
/// 提供仅使用闭包计算的静态生命周期的值或其他类型。
///
/// # Examples
///
/// 通过克隆提供 `String`。
///
/// ```rust
/// #![feature(provide_any)]
///
/// use std::any::{Provider, Demand};
/// # struct SomeConcreteType { field: String }
///
/// impl Provider for SomeConcreteType {
/// fn provide<'a>(&'a self, demand: &mut Demand<'a>) {
/// demand.provide_value_with::<String>(|| self.field.clone());
/// }
/// }
/// ```
#[unstable(feature = "provide_any", issue = "96024")]
pub fn provide_value_with<T>(&mut self, fulfil: impl FnOnce() -> T) -> &mut Self
where
T: 'static,
{
self.provide_with::<tags::Value<T>>(fulfil)
}
/// 提供引用。
/// 裁判类型必须以 `'static` 为界,但可以是未定义大小的。
///
/// # Examples
///
/// 以 `&str` 的形式提供对字段的引用。
///
/// ```rust
/// #![feature(provide_any)]
///
/// use std::any::{Provider, Demand};
/// # struct SomeConcreteType { field: String }
///
/// impl Provider for SomeConcreteType {
/// fn provide<'a>(&'a self, demand: &mut Demand<'a>) {
/// demand.provide_ref::<str>(&self.field);
/// }
/// }
/// ```
#[unstable(feature = "provide_any", issue = "96024")]
pub fn provide_ref<T: ?Sized + 'static>(&mut self, value: &'a T) -> &mut Self {
self.provide::<tags::Ref<tags::MaybeSizedValue<T>>>(value)
}
/// 提供使用闭包计算的引用。
/// 裁判类型必须以 `'static` 为界,但可以是未定义大小的。
///
/// # Examples
///
/// 以 `&str` 的形式提供对字段的引用。
///
/// ```rust
/// #![feature(provide_any)]
///
/// use std::any::{Provider, Demand};
/// # struct SomeConcreteType { business: String, party: String }
/// # fn today_is_a_weekday() -> bool { true }
///
/// impl Provider for SomeConcreteType {
/// fn provide<'a>(&'a self, demand: &mut Demand<'a>) {
/// demand.provide_ref_with::<str>(|| {
/// if today_is_a_weekday() {
/// &self.business
/// } else {
/// &self.party
/// }
/// });
/// }
/// }
/// ```
#[unstable(feature = "provide_any", issue = "96024")]
pub fn provide_ref_with<T: ?Sized + 'static>(
&mut self,
fulfil: impl FnOnce() -> &'a T,
) -> &mut Self {
self.provide_with::<tags::Ref<tags::MaybeSizedValue<T>>>(fulfil)
}
/// 使用给定的 `Type` 标记提供一个值。
fn provide<I>(&mut self, value: I::Reified) -> &mut Self
where
I: tags::Type<'a>,
{
if let Some(res @ TaggedOption(None)) = self.0.downcast_mut::<I>() {
res.0 = Some(value);
}
self
}
/// 使用给定的 `Type` 标记提供一个值,使用闭包来防止不必要的工作。
fn provide_with<I>(&mut self, fulfil: impl FnOnce() -> I::Reified) -> &mut Self
where
I: tags::Type<'a>,
{
if let Some(res @ TaggedOption(None)) = self.0.downcast_mut::<I>() {
res.0 = Some(fulfil());
}
self
}
/// 如果提供指定类型的值,请检查是否满足 `Demand`。
/// 如果类型不匹配或已提供,则返回 false。
///
/// # Examples
///
/// 检查是否仍需要提供 `u8`,然后提供。
///
/// ```rust
/// #![feature(provide_any)]
///
/// use std::any::{Provider, Demand};
///
/// struct Parent(Option<u8>);
///
/// impl Provider for Parent {
/// fn provide<'a>(&'a self, demand: &mut Demand<'a>) {
/// if let Some(v) = self.0 {
/// demand.provide_value::<u8>(v);
/// }
/// }
/// }
///
/// struct Child {
/// parent: Parent,
/// }
///
/// impl Child {
/// // 假装这需要大量资源来评估。
/// fn an_expensive_computation(&self) -> Option<u8> {
/// Some(99)
/// }
/// }
///
/// impl Provider for Child {
/// fn provide<'a>(&'a self, demand: &mut Demand<'a>) {
/// // 一般来说,我们不知道这个调用会不会提供一个 `u8` 值...
/////
/// self.parent.provide(demand);
///
/// // ...所以我们在运行昂贵的计算之前检查是否需要 `u8`。
/////
/// if demand.would_be_satisfied_by_value_of::<u8>() {
/// if let Some(v) = self.an_expensive_computation() {
/// demand.provide_value::<u8>(v);
/// }
/// }
///
/// // 无论父母提供值还是我们提供值,现在都将满足需求。
/////
/// assert!(!demand.would_be_satisfied_by_value_of::<u8>());
/// }
/// }
///
/// let parent = Parent(Some(42));
/// let child = Child { parent };
/// assert_eq!(Some(42), std::any::request_value::<u8>(&child));
///
/// let parent = Parent(None);
/// let child = Child { parent };
/// assert_eq!(Some(99), std::any::request_value::<u8>(&child));
/// ```
///
///
#[unstable(feature = "provide_any", issue = "96024")]
pub fn would_be_satisfied_by_value_of<T>(&self) -> bool
where
T: 'static,
{
self.would_be_satisfied_by::<tags::Value<T>>()
}
/// 如果提供对指定类型值的引用,检查是否满足 `Demand`。
/// 如果类型不匹配或已提供,则返回 false。
///
/// # Examples
///
/// 检查是否仍需要提供 `&str`,然后提供。
///
/// ```rust
/// #![feature(provide_any)]
///
/// use std::any::{Provider, Demand};
///
/// struct Parent(Option<String>);
///
/// impl Provider for Parent {
/// fn provide<'a>(&'a self, demand: &mut Demand<'a>) {
/// if let Some(v) = &self.0 {
/// demand.provide_ref::<str>(v);
/// }
/// }
/// }
///
/// struct Child {
/// parent: Parent,
/// name: String,
/// }
///
/// impl Child {
/// // 假装这需要大量资源来评估。
/// fn an_expensive_computation(&self) -> Option<&str> {
/// Some(&self.name)
/// }
/// }
///
/// impl Provider for Child {
/// fn provide<'a>(&'a self, demand: &mut Demand<'a>) {
/// // 一般来说,不知道这个调用会不会提供 `str` 引用...
/////
/// self.parent.provide(demand);
///
/// // ...所以我们在运行昂贵的计算之前检查是否需要 `&str`。
/////
/// if demand.would_be_satisfied_by_ref_of::<str>() {
/// if let Some(v) = self.an_expensive_computation() {
/// demand.provide_ref::<str>(v);
/// }
/// }
///
/// // 无论父母是否提供了引用或我们提供了,现在都将满足需求。
/////
/// assert!(!demand.would_be_satisfied_by_ref_of::<str>());
/// }
/// }
///
/// let parent = Parent(Some("parent".into()));
/// let child = Child { parent, name: "child".into() };
/// assert_eq!(Some("parent"), std::any::request_ref::<str>(&child));
///
/// let parent = Parent(None);
/// let child = Child { parent, name: "child".into() };
/// assert_eq!(Some("child"), std::any::request_ref::<str>(&child));
/// ```
///
///
#[unstable(feature = "provide_any", issue = "96024")]
pub fn would_be_satisfied_by_ref_of<T>(&self) -> bool
where
T: ?Sized + 'static,
{
self.would_be_satisfied_by::<tags::Ref<tags::MaybeSizedValue<T>>>()
}
fn would_be_satisfied_by<I>(&self) -> bool
where
I: tags::Type<'a>,
{
matches!(self.0.downcast::<I>(), Some(TaggedOption(None)))
}
}
#[unstable(feature = "provide_any", issue = "96024")]
impl<'a> fmt::Debug for Demand<'a> {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("Demand").finish_non_exhaustive()
}
}
///////////////////////////////////////////////////////////////////////////////
// 类型标签
///////////////////////////////////////////////////////////////////////////////
mod tags {
//! 类型标签用于使用单独的值来标识类型。这个模块包括一些非常常见的类型的类型标签。
//!
//! 当前类型标签不向用户公开。
//! 但是在 future 中,如果您想使用更复杂类型的 Provider API (通常包括生命周期参数),您需要编写自己的标签。
//!
//!
use crate::marker::PhantomData;
/// 这个 trait 由特定的标签类型实现,以便允许描述可以为给定的生命周期 `'a` 请求的类型。
///
/// 在这个模块中可以找到一些类型驱动标签的示例实现,尽管 crates 也可以为具有内部生命周期的更复杂类型实现自己的标签。
///
///
///
pub trait Type<'a>: Sized + 'static {
/// 对于给定的生命周期,此标签可能标记的值的类型。
///
type Reified: 'a;
}
/// 与 [`Type`] trait 类似,但表示可能是未定义大小的类型 (即,具有 `?Sized` 边界)。
/// 例如,`str`。
pub trait MaybeSizedType<'a>: Sized + 'static {
type Reified: 'a + ?Sized;
}
impl<'a, T: Type<'a>> MaybeSizedType<'a> for T {
type Reified = T::Reified;
}
/// 以 `'static` 为界的类型的基于类型的标记,即没有借用元素。
#[derive(Debug)]
pub struct Value<T: 'static>(PhantomData<T>);
impl<'a, T: 'static> Type<'a> for Value<T> {
type Reified = T;
}
/// 基于类型的标记类似于 [`Value`],但可能是未定义大小的 (即,具有 `?Sized` 边界)。
#[derive(Debug)]
pub struct MaybeSizedValue<T: ?Sized + 'static>(PhantomData<T>);
impl<'a, T: ?Sized + 'static> MaybeSizedType<'a> for MaybeSizedValue<T> {
type Reified = T;
}
/// 引用类型的基于类型的标记 (`&'a T`,其中 T 由 `<I as MaybeSizedType<'a>>::Reified` 表示。
///
#[derive(Debug)]
pub struct Ref<I>(PhantomData<I>);
impl<'a, I: MaybeSizedType<'a>> Type<'a> for Ref<I> {
type Reified = &'a I::Reified;
}
}
/// 带有类型标签 `I` 的 `Option`。
///
/// 由于这个结构体实现了 `Erased`,所以类型可以是 erased 来做一个动态类型的选项。
/// 可以使用 `Erased::tag_id` 动态检查类型,并且由于这是针对具体类型静态检查的,因此存在一定程度的类型安全性。
///
#[repr(transparent)]
struct TaggedOption<'a, I: tags::Type<'a>>(Option<I::Reified>);
impl<'a, I: tags::Type<'a>> TaggedOption<'a, I> {
fn as_demand(&mut self) -> &mut Demand<'a> {
Demand::new(self as &mut (dyn Erased<'a> + 'a))
}
}
/// 表示一个类型为 erased 但可识别的对象。
///
/// 这个 trait 是由 `TaggedOption` 类型专门实现的。
unsafe trait Erased<'a>: 'a {
/// erased 类型的 `TypeId`。
fn tag_id(&self) -> TypeId;
}
unsafe impl<'a, I: tags::Type<'a>> Erased<'a> for TaggedOption<'a, I> {
fn tag_id(&self) -> TypeId {
TypeId::of::<I>()
}
}
#[unstable(feature = "provide_any", issue = "96024")]
impl<'a> dyn Erased<'a> + 'a {
/// 如果它被标记为 `I`,则返回一些对动态值的引用,否则返回 `None`。
///
#[inline]
fn downcast<I>(&self) -> Option<&TaggedOption<'a, I>>
where
I: tags::Type<'a>,
{
if self.tag_id() == TypeId::of::<I>() {
// SAFETY: 刚刚检查了我们是否指向一个 I。
Some(unsafe { &*(self as *const Self).cast::<TaggedOption<'a, I>>() })
} else {
None
}
}
/// 如果它被标记为 `I`,则返回一些对动态值的引用,否则返回 `None`。
///
#[inline]
fn downcast_mut<I>(&mut self) -> Option<&mut TaggedOption<'a, I>>
where
I: tags::Type<'a>,
{
if self.tag_id() == TypeId::of::<I>() {
// SAFETY: 刚刚检查了我们是否指向一个 I。
Some(unsafe { &mut *(self as *mut Self).cast::<TaggedOption<'a, I>>() })
} else {
None
}
}
}