From 7a93a3a82150e933d254c2dc6563ce512927124e Mon Sep 17 00:00:00 2001 From: Bhargav Patel Date: Sun, 29 Nov 2015 22:18:13 -0500 Subject: [PATCH 1/7] Change verbiage in Stack & Heap page Made a small change in the sentence. It seemed confusing to read the word "actual" twice in the sentence; I removed it completely. --- src/doc/book/the-stack-and-the-heap.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/book/the-stack-and-the-heap.md b/src/doc/book/the-stack-and-the-heap.md index 0c78f876aa037..29f87539f717b 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. From 4a63d9fa2c21f55bc6f608f80abba028e0ddc741 Mon Sep 17 00:00:00 2001 From: Martin Pool Date: Mon, 30 Nov 2015 07:42:14 -0800 Subject: [PATCH 2/7] Remove broken explicit coercion example --- src/doc/book/casting-between-types.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/src/doc/book/casting-between-types.md b/src/doc/book/casting-between-types.md index e2b114b7e54b4..2339fe60bf00b 100644 --- a/src/doc/book/casting-between-types.md +++ b/src/doc/book/casting-between-types.md @@ -49,13 +49,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: From 7728742a4482b489111d8ebbfbbb283eb6615137 Mon Sep 17 00:00:00 2001 From: Mihaly Barasz Date: Mon, 30 Nov 2015 16:51:38 +0100 Subject: [PATCH 3/7] Fix pointer value in the 'complex example' The `f` argument will reference the actual value in the `d` box, not the box in the `bar`'s stack frame. --- src/doc/book/the-stack-and-the-heap.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/book/the-stack-and-the-heap.md b/src/doc/book/the-stack-and-the-heap.md index 0c78f876aa037..3c4fb0fb86501 100644 --- a/src/doc/book/the-stack-and-the-heap.md +++ b/src/doc/book/the-stack-and-the-heap.md @@ -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 | From f183d7a26ed5c39634612486a45240d067ba0abf Mon Sep 17 00:00:00 2001 From: Martin Pool Date: Mon, 30 Nov 2015 07:59:14 -0800 Subject: [PATCH 4/7] Additional text and examples around casting --- src/doc/book/casting-between-types.md | 26 +++++++++++++++++++------- 1 file changed, 19 insertions(+), 7 deletions(-) diff --git a/src/doc/book/casting-between-types.md b/src/doc/book/casting-between-types.md index e2b114b7e54b4..e0e9b75d464f3 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 coercion may be defined using [`Deref`](deref-coercions.md). + +Coercion is transitive. # `as` @@ -71,6 +77,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 +108,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: From b00b32cdaaa67033992ded2668e855635134597b Mon Sep 17 00:00:00 2001 From: Martin Pool Date: Mon, 30 Nov 2015 10:16:36 -0800 Subject: [PATCH 5/7] Correct grammar Thanks @Manishearth --- src/doc/book/casting-between-types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/book/casting-between-types.md b/src/doc/book/casting-between-types.md index e0e9b75d464f3..0e3db983a005a 100644 --- a/src/doc/book/casting-between-types.md +++ b/src/doc/book/casting-between-types.md @@ -29,7 +29,7 @@ References can also be coerced to raw pointers: * `&mut T` to `*mut T` -Custom coercion may be defined using [`Deref`](deref-coercions.md). +Custom coercions may be defined using [`Deref`](deref-coercions.md). Coercion is transitive. From a9b6975c87adde151407ad4eb695f78cf4828f39 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Mon, 30 Nov 2015 14:36:03 -0500 Subject: [PATCH 6/7] Write some docs for ToString Part of #29376 --- src/libcollections/string.rs | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/src/libcollections/string.rs b/src/libcollections/string.rs index 9f09facdaf7e2..5692d64884948 100644 --- a/src/libcollections/string.rs +++ b/src/libcollections/string.rs @@ -1179,10 +1179,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; } From 4bdb60cc34452507df4a7defa56bb49e55ae3585 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Mon, 30 Nov 2015 15:00:30 -0500 Subject: [PATCH 7/7] Fix path to TRPL in doc README --- src/doc/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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