src/libcore/any.rs

   1 // Copyright 2013-2014 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10
  11 //! This module implements the `Any` trait, which enables dynamic typing
  12 //! of any `'static` type through runtime reflection.
  13 //!
  14 //! `Any` itself can be used to get a `TypeId`, and has more features when used
  15 //! as a trait object. As `&Any` (a borrowed trait object), it has the `is` and
  16 //! `downcast_ref` methods, to test if the contained value is of a given type,
  17 //! and to get a reference to the inner value as a type. As `&mut Any`, there
  18 //! is also the `downcast_mut` method, for getting a mutable reference to the
  19 //! inner value. `Box<Any>` adds the `move` method, which will unwrap a
  20 //! `Box<T>` from the object. See the extension traits (`*Ext`) for the full
  21 //! details.
  22 //!
  23 //! Note that &Any is limited to testing whether a value is of a specified
  24 //! concrete type, and cannot be used to test whether a type implements a trait.
  25 //!
  26 //! # Examples
  27 //!
  28 //! Consider a situation where we want to log out a value passed to a function.
  29 //! We know the value we're working on implements Debug, but we don't know its
  30 //! concrete type.  We want to give special treatment to certain types: in this
  31 //! case printing out the length of String values prior to their value.
  32 //! We don't know the concrete type of our value at compile time, so we need to
  33 //! use runtime reflection instead.
  34 //!
  35 //! ```rust
  36 //! use std::fmt::Debug;
  37 //! use std::any::Any;
  38 //!
  39 //! // Logger function for any type that implements Debug.
  40 //! fn log<T: Any + Debug>(value: &T) {
  41 //!     let value_any = value as &Any;
  42 //!
  43 //!     // try to convert our value to a String.  If successful, we want to
  44 //!     // output the String's length as well as its value.  If not, it's a
  45 //!     // different type: just print it out unadorned.
  46 //!     match value_any.downcast_ref::<String>() {
  47 //!         Some(as_string) => {
  48 //!             println!("String ({}): {}", as_string.len(), as_string);
  49 //!         }
  50 //!         None => {
  51 //!             println!("{:?}", value);
  52 //!         }
  53 //!     }
  54 //! }
  55 //!
  56 //! // This function wants to log its parameter out prior to doing work with it.
  57 //! fn do_work<T: Any + Debug>(value: &T) {
  58 //!     log(value);
  59 //!     // ...do some other work
  60 //! }
  61 //!
  62 //! fn main() {
  63 //!     let my_string = "Hello World".to_string();
  64 //!     do_work(&my_string);
  65 //!
  66 //!     let my_i8: i8 = 100;
  67 //!     do_work(&my_i8);
  68 //! }
  69 //! ```
  70
  71 #![stable(feature = "rust1", since = "1.0.0")]
  72
  73 use fmt;
  74 use marker::Send;
  75 use mem::transmute;
  76 use option::Option::{self, Some, None};
  77 use raw::TraitObject;
  78 use intrinsics;
  79 use marker::{Reflect, Sized};
  80
  81 ///////////////////////////////////////////////////////////////////////////////
  82 // Any trait
  83 ///////////////////////////////////////////////////////////////////////////////
  84
  85 /// A type to emulate dynamic typing.
  86 ///
  87 /// Every type with no non-`'static` references implements `Any`.
  88 /// See the [module-level documentation][mod] for more details.
  89 ///
  90 /// [mod]: index.html
  91 #[stable(feature = "rust1", since = "1.0.0")]
  92 pub trait Any: Reflect + 'static {
  93     /// Gets the `TypeId` of `self`.
  94     #[unstable(feature = "get_type_id",
  95                reason = "this method will likely be replaced by an associated static",
  96                issue = "27745")]
  97     fn get_type_id(&self) -> TypeId;
  98 }
  99
 100 impl<T: Reflect + 'static> Any for T {
 101     fn get_type_id(&self) -> TypeId { TypeId::of::<T>() }
 102 }
 103
 104 ///////////////////////////////////////////////////////////////////////////////
 105 // Extension methods for Any trait objects.
 106 ///////////////////////////////////////////////////////////////////////////////
 107
 108 #[stable(feature = "rust1", since = "1.0.0")]
 109 impl fmt::Debug for Any {
 110     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 111         f.pad("Any")
 112     }
 113 }
 114
 115 // Ensure that the result of e.g. joining a thread can be printed and
 116 // hence used with `unwrap`. May eventually no longer be needed if
 117 // dispatch works with upcasting.
 118 #[stable(feature = "rust1", since = "1.0.0")]
 119 impl fmt::Debug for Any + Send {
 120     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 121         f.pad("Any")
 122     }
 123 }
 124
 125 impl Any {
 126     /// Returns true if the boxed type is the same as `T`
 127     #[stable(feature = "rust1", since = "1.0.0")]
 128     #[inline]
 129     pub fn is<T: Any>(&self) -> bool {
 130         // Get TypeId of the type this function is instantiated with
 131         let t = TypeId::of::<T>();
 132
 133         // Get TypeId of the type in the trait object
 134         let boxed = self.get_type_id();
 135
 136         // Compare both TypeIds on equality
 137         t == boxed
 138     }
 139
 140     /// Returns some reference to the boxed value if it is of type `T`, or
 141     /// `None` if it isn't.
 142     #[stable(feature = "rust1", since = "1.0.0")]
 143     #[inline]
 144     pub fn downcast_ref<T: Any>(&self) -> Option<&T> {
 145         if self.is::<T>() {
 146             unsafe {
 147                 // Get the raw representation of the trait object
 148                 let to: TraitObject = transmute(self);
 149
 150                 // Extract the data pointer
 151                 Some(&*(to.data as *const T))
 152             }
 153         } else {
 154             None
 155         }
 156     }
 157
 158     /// Returns some mutable reference to the boxed value if it is of type `T`, or
 159     /// `None` if it isn't.
 160     #[stable(feature = "rust1", since = "1.0.0")]
 161     #[inline]
 162     pub fn downcast_mut<T: Any>(&mut self) -> Option<&mut T> {
 163         if self.is::<T>() {
 164             unsafe {
 165                 // Get the raw representation of the trait object
 166                 let to: TraitObject = transmute(self);
 167
 168                 // Extract the data pointer
 169                 Some(&mut *(to.data as *const T as *mut T))
 170             }
 171         } else {
 172             None
 173         }
 174     }
 175 }
 176
 177 impl Any+Send {
 178     /// Forwards to the method defined on the type `Any`.
 179     #[stable(feature = "rust1", since = "1.0.0")]
 180     #[inline]
 181     pub fn is<T: Any>(&self) -> bool {
 182         Any::is::<T>(self)
 183     }
 184
 185     /// Forwards to the method defined on the type `Any`.
 186     #[stable(feature = "rust1", since = "1.0.0")]
 187     #[inline]
 188     pub fn downcast_ref<T: Any>(&self) -> Option<&T> {
 189         Any::downcast_ref::<T>(self)
 190     }
 191
 192     /// Forwards to the method defined on the type `Any`.
 193     #[stable(feature = "rust1", since = "1.0.0")]
 194     #[inline]
 195     pub fn downcast_mut<T: Any>(&mut self) -> Option<&mut T> {
 196         Any::downcast_mut::<T>(self)
 197     }
 198 }
 199
 200
 201 ///////////////////////////////////////////////////////////////////////////////
 202 // TypeID and its methods
 203 ///////////////////////////////////////////////////////////////////////////////
 204
 205 /// A `TypeId` represents a globally unique identifier for a type.
 206 ///
 207 /// Each `TypeId` is an opaque object which does not allow inspection of what's
 208 /// inside but does allow basic operations such as cloning, comparison,
 209 /// printing, and showing.
 210 ///
 211 /// A `TypeId` is currently only available for types which ascribe to `'static`,
 212 /// but this limitation may be removed in the future.
 213 #[derive(Clone, Copy, PartialEq, Eq, Debug, Hash)]
 214 #[stable(feature = "rust1", since = "1.0.0")]
 215 pub struct TypeId {
 216     t: u64,
 217 }
 218
 219 impl TypeId {
 220     /// Returns the `TypeId` of the type this generic function has been
 221     /// instantiated with
 222     #[stable(feature = "rust1", since = "1.0.0")]
 223     pub fn of<T: ?Sized + Reflect + 'static>() -> TypeId {
 224         TypeId {
 225             t: unsafe { intrinsics::type_id::<T>() },
 226         }
 227     }
 228 }