---

yaml
---
r: 123865
b: refs/heads/snap-stage3
c: f9d3b9e
h: refs/heads/master
i:
  123863: 6a9e592
v: v3

Author: bors

[refs]

@@ -1,7 +1,7 @@
 ---
 refs/heads/master: 4e2da7cb79143b0e7206a684629ed942599ec8e9
 refs/heads/snap-stage1: e33de59e47c5076a89eadeb38f4934f58a3618a6
-refs/heads/snap-stage3: be7a17062b103b31798afcd525c51a9642038465
+refs/heads/snap-stage3: f9d3b9e488f88b5d9c9e23f9bcc7e933565a9649
 refs/heads/try: 296eb104620b346d88bc4a2c2ab7693e6d3db019
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b

branches/snap-stage3/src/libcore/any.rs

@@ -13,12 +13,61 @@
 //! This module implements the `Any` trait, which enables dynamic typing
 //! of any `'static` type through runtime reflection.
 //!
-//! `Any` itself can be used to get a `TypeId`, and has more features when used as a trait object.
-//! As `&Any` (a borrowed trait object), it has the `is` and `as_ref` methods, to test if the
-//! contained value is of a given type, and to get a reference to the inner value as a type. As
-//! `&mut Any`, there is also the `as_mut` method, for getting a mutable reference to the inner
-//! value. `Box<Any>` adds the `move` method, which will unwrap a `Box<T>` from the object.  See
-//! the extension traits (`*Ext`) for the full details.
+//! `Any` itself can be used to get a `TypeId`, and has more features when used
+//! as a trait object. As `&Any` (a borrowed trait object), it has the `is` and
+//! `as_ref` methods, to test if the contained value is of a given type, and to
+//! get a reference to the inner value as a type. As`&mut Any`, there is also
+//! the `as_mut` method, for getting a mutable reference to the inner value.
+//! `Box<Any>` adds the `move` method, which will unwrap a `Box<T>` from the
+//! object.  See the extension traits (`*Ext`) for the full details.
+//!
+//! Note that &Any is limited to testing whether a value is of a specified
+//! concrete type, and cannot be used to test whether a type implements a trait.
+//!
+//! # Examples
+//!
+//! Consider a situation where we want to log out a value passed to a function.
+//! We know the value we're working on implements Show, but we don't know its
+//! concrete type.  We want to give special treatment to certain types: in this
+//! case printing out the length of String values prior to their value.
+//! We don't know the concrete type of our value at compile time, so we need to
+//! use runtime reflection instead.
+//!
+//! ```rust
+//! use std::fmt::Show;
+//! use std::any::{Any, AnyRefExt};
+//!
+//! // Logger function for any type that implements Show.
+//! fn log<T: Any+Show>(value: &T) {
+//!     let value_any = value as &Any;
+//!
+//!     // try to convert our value to a String.  If successful, we want to
+//!     // output the String's length as well as its value.  If not, it's a
+//!     // different type: just print it out unadorned.
+//!     match value_any.as_ref::<String>() {
+//!         Some(as_string) => {
+//!             println!("String ({}): {}", as_string.len(), as_string);
+//!         }
+//!         None => {
+//!             println!("{}", value);
+//!         }
+//!     }
+//! }
+//!
+//! // This function wants to log its parameter out prior to doing work with it.
+//! fn do_work<T: Show>(value: &T) {
+//!     log(value);
+//!     // ...do some other work
+//! }
+//!
+//! fn main() {
+//!     let my_string = "Hello World".to_string();
+//!     do_work(&my_string);
+//!
+//!     let my_i8: i8 = 100;
+//!     do_work(&my_i8);
+//! }
+//! ```
 
 use mem::{transmute, transmute_copy};
 use option::{Option, Some, None};