diff --git a/src/doc/README.md b/src/doc/README.md index 0882b073ea48c..b5972f7ddb9ee 100644 --- a/src/doc/README.md +++ b/src/doc/README.md @@ -29,4 +29,4 @@ rustdoc reference.md An overview of how to use the `rustdoc` command is available [in the docs][1]. Further details are available from the command line by with `rustdoc --help`. -[1]: https://github.com/rust-lang/rust/blob/master/src/doc/trpl/documentation.md +[1]: https://github.com/rust-lang/rust/blob/master/src/doc/book/documentation.md diff --git a/src/doc/book/casting-between-types.md b/src/doc/book/casting-between-types.md index e2b114b7e54b4..7108d957eddcc 100644 --- a/src/doc/book/casting-between-types.md +++ b/src/doc/book/casting-between-types.md @@ -14,18 +14,24 @@ Coercion occurs in `let`, `const`, and `static` statements; in function call arguments; in field values in struct initialization; and in a function result. -The main cases of coercion are: +The most common case of coercion is removing mutability from a reference: * `&mut T` to `&T` + +An analogous conversion is to remove mutability from a +[raw pointer](raw-pointers.md): * `*mut T` to `*const T` + +References can also be coerced to raw pointers: * `&T` to `*const T` * `&mut T` to `*mut T` - - * A custom coercion using [`Deref`](deref-coercions.md) - + +Custom coercions may be defined using [`Deref`](deref-coercions.md). + +Coercion is transitive. # `as` @@ -49,13 +55,6 @@ expression, `e as U2` is not necessarily so (in fact it will only be valid if A cast `e as U` is valid if `e` has type `T` and `T` *coerces* to `U`. -For example: - -```rust -let a = "hello"; -let b = a as String; -``` - ## Numeric casts A cast `e as U` is also valid in any of the following cases: @@ -71,6 +70,7 @@ For example ```rust let one = true as u8; let at_sign = 64 as char; +let two_hundred = -56i8 as u8; ``` The semantics of numeric casts are: @@ -101,9 +101,14 @@ The semantics of numeric casts are: ## Pointer casts -Perhaps surprisingly, it is safe to cast pointers to and from integers, and -to cast between pointers to different types subject to some constraints. It -is only unsafe to dereference the pointer. +Perhaps surprisingly, it is safe to cast [raw pointers](raw-pointers.md) to and +from integers, and to cast between pointers to different types subject to +some constraints. It is only unsafe to dereference the pointer: + +```rust +let a = 300 as *const char; // a pointer to location 300 +let b = a as u32; +``` `e as U` is a valid pointer cast in any of the following cases: diff --git a/src/doc/book/the-stack-and-the-heap.md b/src/doc/book/the-stack-and-the-heap.md index 0c78f876aa037..9cc3e12aa04ac 100644 --- a/src/doc/book/the-stack-and-the-heap.md +++ b/src/doc/book/the-stack-and-the-heap.md @@ -109,7 +109,7 @@ stack frame. It grows upward, the more functions we call. There are some important things we have to take note of here. The numbers 0, 1, and 2 are all solely for illustrative purposes, and bear no relationship to the -actual numbers the computer will actually use. In particular, the series of +address values the computer will use in reality. In particular, the series of addresses are in reality going to be separated by some number of bytes that separate each address, and that separation may even exceed the size of the value being stored. @@ -464,7 +464,7 @@ At the end of `bar()`, it calls `baz()`: | (230) - 2 | | 5 | | ... | ... | ... | | 12 | g | 100 | -| 11 | f | → 9 | +| 11 | f | → (230) - 2 | | 10 | e | → 9 | | 9 | d | → (230) - 2 | | 8 | c | 5 | diff --git a/src/libcollections/string.rs b/src/libcollections/string.rs index 5a724473d610d..ac24ab422917a 100644 --- a/src/libcollections/string.rs +++ b/src/libcollections/string.rs @@ -1190,10 +1190,28 @@ impl PartialEq for ParseError { #[stable(feature = "str_parse_error", since = "1.5.0")] impl Eq for ParseError {} -/// A generic trait for converting a value to a string +/// A trait for converting a value to a `String`. +/// +/// This trait is automatically implemented for any type which implements the +/// [`Display`] trait. As such, `ToString` shouldn't be implemented directly: +/// [`Display`] should be implemented instead, and you get the `ToString` +/// implementation for free. +/// +/// [`Display`]: ../fmt/trait.Display.html #[stable(feature = "rust1", since = "1.0.0")] pub trait ToString { - /// Converts the value of `self` to an owned string + /// Converts the given value to a `String`. + /// + /// # Examples + /// + /// Basic usage: + /// + /// ``` + /// let i = 5; + /// let five = String::from("5"); + /// + /// assert_eq!(five, i.to_string()); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] fn to_string(&self) -> String; }