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 0c78f876aa03..29f87539f717 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 7728742a4482b489111d8ebbfbbb283eb6615137 Mon Sep 17 00:00:00 2001 From: Mihaly Barasz Date: Mon, 30 Nov 2015 16:51:38 +0100 Subject: [PATCH 2/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 0c78f876aa03..3c4fb0fb8650 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 3/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 e2b114b7e54b..e0e9b75d464f 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 4/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 e0e9b75d464f..0e3db983a005 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 5/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 9f09facdaf7e..5692d6488494 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 6/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 0882b073ea48..b5972f7ddb9e 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 From 23fb9743d33b218328699d64e792da877d470674 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Mon, 30 Nov 2015 14:47:14 -0500 Subject: [PATCH 7/7] Document std::string::ParseError Part of #29376 --- src/libcollections/string.rs | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/src/libcollections/string.rs b/src/libcollections/string.rs index 9f09facdaf7e..5a724473d610 100644 --- a/src/libcollections/string.rs +++ b/src/libcollections/string.rs @@ -1141,7 +1141,18 @@ impl ops::DerefMut for String { } } -/// Error returned from `String::from` +/// An error when parsing a `String`. +/// +/// This `enum` is slightly awkward: it will never actually exist. This error is +/// part of the type signature of the implementation of [`FromStr`] on +/// [`String`]. The return type of [`from_str()`], requires that an error be +/// defined, but, given that a [`String`] can always be made into a new +/// [`String`] without error, this type will never actually be returned. As +/// such, it is only here to satisfy said signature, and is useless otherwise. +/// +/// [`FromStr`]: ../str/trait.FromStr.html +/// [`String`]: struct.String.html +/// [`from_str()`]: ../str/trait.FromStr.html#tymethod.from_str #[stable(feature = "str_parse_error", since = "1.5.0")] #[derive(Copy)] pub enum ParseError {}