From 5d8e085369eabb6766b9ec9423716266719b1e34 Mon Sep 17 00:00:00 2001
From: Mathieu David <mathieudavid@mathieudavid.org>
Date: Sat, 30 May 2015 11:51:25 +0200
Subject: [PATCH 01/14] Proposal to explain the copy trait more clearly
As mentioned in #25893 the copy trait is not very well explained for beginners. There is no clear mention that all primitive types implement the copy trait and there are not a lot of examples.
With this change I try to make it more visible and understandable for new users.
I myself have struggled with this, see [my question on stackoverflow](http://stackoverflow.com/questions/30540419/why-are-booleans-copyable-even-though-the-documentation-doesnt-indicate-that). And I want to make it more transparent for others.
I filed issue #25893 but I thought that I could give it a shot myself to relieve some of the work from the devs :)
If it is not well written or there are some changes to be made before it can be merged, let me know.
Cheers,
Mathieu
---
src/doc/trpl/ownership.md | 43 +++++++++++++++++++++++++++++++++++++++
1 file changed, 43 insertions(+)
diff --git a/src/doc/trpl/ownership.md b/src/doc/trpl/ownership.md
index 0ba2b33759c..e94fe033407 100644
--- a/src/doc/trpl/ownership.md
+++ b/src/doc/trpl/ownership.md
@@ -156,6 +156,49 @@ that, just like a move, when we assign `v` to `v2`, a copy of the data is made.
But, unlike a move, we can still use `v` afterward. This is because an `i32`
has no pointers to data somewhere else, copying it is a full copy.
+All primitive types implement the `Copy` trait and their ownership is
+therefore not moved like one would assume, following the **ownership rules**.
+To give an example, the two following snippets of code only compile because the
+`i32` and `bool` types implement the `Copy` trait.
+
+```rust
+fn main() {
+ let a = 5;
+
+ let _y = double(a);
+ println!("{}", a);
+}
+
+fn double(x: i32) -> i32 {
+ x * 2
+}
+```
+
+```rust
+fn main() {
+ let a = true;
+
+ let _y = change_truth(a);
+ println!("{}", a);
+}
+
+fn change_truth(x: bool) -> bool {
+ !x
+}
+```
+
+If we would have used types that do not implement the `Copy` trait,
+we would have gotten a compile error because we tried to use a moved value.
+
+```text
+error: use of moved value: `a`
+println!("{}", a);
+ ^
+```
+
+This is quite important to understand, because it is an exception to the most
+fundamental rule in the Rust language.
+
We will discuss how to make your own types `Copy` in the [traits][traits]
section.
From ee4b58c7925a914abac8ebc7a0fc0be0cb6cb0c7 Mon Sep 17 00:00:00 2001
From: frankamp <frankamp@gmail.com>
Date: Sat, 30 May 2015 13:31:46 -0700
Subject: [PATCH 02/14] Fixes consistency in before/after example
The doc indicates that you can replace 'before' with 'after' showing the use of try!. The two examples should be equivalent, but they are not.
In the File::create we were inducing a panic before in case of error, not propagating. It is important for newbies (like myself) to understand that try! propagates failures, while unwrap can induce a panic.
The other alternative is to make the 'before' File::create also manually handle Err like the other calls. Either way it would be consistent.
---
src/doc/trpl/error-handling.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/src/doc/trpl/error-handling.md b/src/doc/trpl/error-handling.md
index 7b47559e0fc..2a0e8ed1643 100644
--- a/src/doc/trpl/error-handling.md
+++ b/src/doc/trpl/error-handling.md
@@ -284,7 +284,7 @@ struct Info {
}
fn write_info(info: &Info) -> io::Result<()> {
- let mut file = try!(File::create("my_best_friends.txt"));
+ let mut file = File::create("my_best_friends.txt").unwrap();
try!(writeln!(&mut file, "name: {}", info.name));
try!(writeln!(&mut file, "age: {}", info.age));
From 37dd7a24949813a48c8e2be7178a3c0b5ba5c998 Mon Sep 17 00:00:00 2001
From: Tshepang Lekhonkhobe <tshepang@gmail.com>
Date: Mon, 1 Jun 2015 23:06:23 +0200
Subject: [PATCH 03/14] book: some tiny improvements
---
src/doc/trpl/closures.md | 16 ++++++++--------
src/doc/trpl/trait-objects.md | 4 ++--
src/doc/trpl/traits.md | 6 +++---
3 files changed, 13 insertions(+), 13 deletions(-)
diff --git a/src/doc/trpl/closures.md b/src/doc/trpl/closures.md
index d2fe9c6e550..4479fdb7baa 100644
--- a/src/doc/trpl/closures.md
+++ b/src/doc/trpl/closures.md
@@ -33,8 +33,8 @@ let plus_two = |x| {
assert_eq!(4, plus_two(2));
```
-You’ll notice a few things about closures that are a bit different than regular
-functions defined with `fn`. The first of which is that we did not need to
+You’ll notice a few things about closures that are a bit different from regular
+functions defined with `fn`. The first is that we did not need to
annotate the types of arguments the closure takes or the values it returns. We
can:
@@ -48,10 +48,10 @@ But we don’t have to. Why is this? Basically, it was chosen for ergonomic reas
While specifying the full type for named functions is helpful with things like
documentation and type inference, the types of closures are rarely documented
since they’re anonymous, and they don’t cause the kinds of error-at-a-distance
-that inferring named function types can.
+problems that inferring named function types can.
The second is that the syntax is similar, but a bit different. I’ve added spaces
-here to make them look a little closer:
+here for easier comparison:
```rust
fn plus_one_v1 (x: i32) -> i32 { x + 1 }
@@ -59,7 +59,7 @@ let plus_one_v2 = |x: i32| -> i32 { x + 1 };
let plus_one_v3 = |x: i32| x + 1 ;
```
-Small differences, but they’re similar in ways.
+Small differences, but they’re similar.
# Closures and their environment
@@ -99,7 +99,7 @@ note: previous borrow ends here
fn main() {
let mut num = 5;
let plus_num = |x| x + num;
-
+
let y = &mut num;
}
^
@@ -161,7 +161,7 @@ of `num`. So what’s the difference?
```rust
let mut num = 5;
-{
+{
let mut add_num = |x: i32| num += x;
add_num(5);
@@ -180,7 +180,7 @@ If we change to a `move` closure, it’s different:
```rust
let mut num = 5;
-{
+{
let mut add_num = move |x: i32| num += x;
add_num(5);
diff --git a/src/doc/trpl/trait-objects.md b/src/doc/trpl/trait-objects.md
index c0112905741..3da29c9b817 100644
--- a/src/doc/trpl/trait-objects.md
+++ b/src/doc/trpl/trait-objects.md
@@ -261,7 +261,7 @@ static Foo_for_String_vtable: FooVtable = FooVtable {
```
The `destructor` field in each vtable points to a function that will clean up
-any resources of the vtable’s type, for `u8` it is trivial, but for `String` it
+any resources of the vtable’s type: for `u8` it is trivial, but for `String` it
will free the memory. This is necessary for owning trait objects like
`Box<Foo>`, which need to clean-up both the `Box` allocation as well as the
internal type when they go out of scope. The `size` and `align` fields store
@@ -270,7 +270,7 @@ essentially unused at the moment since the information is embedded in the
destructor, but will be used in the future, as trait objects are progressively
made more flexible.
-Suppose we’ve got some values that implement `Foo`, then the explicit form of
+Suppose we’ve got some values that implement `Foo`. The explicit form of
construction and use of `Foo` trait objects might look a bit like (ignoring the
type mismatches: they’re all just pointers anyway):
diff --git a/src/doc/trpl/traits.md b/src/doc/trpl/traits.md
index 2ef9e7ca22e..ae42b3af656 100644
--- a/src/doc/trpl/traits.md
+++ b/src/doc/trpl/traits.md
@@ -45,7 +45,7 @@ but we don’t define a body, just a type signature. When we `impl` a trait,
we use `impl Trait for Item`, rather than just `impl Item`.
We can use traits to constrain our generics. Consider this function, which
-does not compile, and gives us a similar error:
+does not compile:
```rust,ignore
fn print_area<T>(shape: T) {
@@ -212,8 +212,8 @@ This will compile without error.
This means that even if someone does something bad like add methods to `i32`,
it won’t affect you, unless you `use` that trait.
-There’s one more restriction on implementing traits. Either the trait or the
-type you’re writing the `impl` for must be defined by you. So, we could
+There’s one more restriction on implementing traits: either the trait, or the
+type you’re writing the `impl` for, must be defined by you. So, we could
implement the `HasArea` type for `i32`, because `HasArea` is in our code. But
if we tried to implement `Float`, a trait provided by Rust, for `i32`, we could
not, because neither the trait nor the type are in our code.
From dc99fdbd664a936d5f31783774a1362491b31e14 Mon Sep 17 00:00:00 2001
From: Tshepang Lekhonkhobe <tshepang@gmail.com>
Date: Mon, 1 Jun 2015 23:06:51 +0200
Subject: [PATCH 04/14] book: update error message
---
src/doc/trpl/traits.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/src/doc/trpl/traits.md b/src/doc/trpl/traits.md
index ae42b3af656..d3f50884a16 100644
--- a/src/doc/trpl/traits.md
+++ b/src/doc/trpl/traits.md
@@ -56,7 +56,7 @@ fn print_area<T>(shape: T) {
Rust complains:
```text
-error: type `T` does not implement any method in scope named `area`
+error: no method named `area` found for type `T` in the current scope
```
Because `T` can be any type, we can’t be sure that it implements the `area`
From 09c6203ad6508dcf3374cddfc2778b861cd9a6be Mon Sep 17 00:00:00 2001
From: Tshepang Lekhonkhobe <tshepang@gmail.com>
Date: Mon, 1 Jun 2015 23:07:42 +0200
Subject: [PATCH 05/14] booK: Float no longer exists
---
src/doc/trpl/traits.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/src/doc/trpl/traits.md b/src/doc/trpl/traits.md
index d3f50884a16..162a2db1ec7 100644
--- a/src/doc/trpl/traits.md
+++ b/src/doc/trpl/traits.md
@@ -215,7 +215,7 @@ it won’t affect you, unless you `use` that trait.
There’s one more restriction on implementing traits: either the trait, or the
type you’re writing the `impl` for, must be defined by you. So, we could
implement the `HasArea` type for `i32`, because `HasArea` is in our code. But
-if we tried to implement `Float`, a trait provided by Rust, for `i32`, we could
+if we tried to implement `ToString`, a trait provided by Rust, for `i32`, we could
not, because neither the trait nor the type are in our code.
One last thing about traits: generic functions with a trait bound use
From 6a92cf9ace765a590991e4a1688164f4ed54194f Mon Sep 17 00:00:00 2001
From: ben fleis <ben.fleis@gmail.com>
Date: Tue, 2 Jun 2015 22:55:39 +0200
Subject: [PATCH 06/14] Add note about expression vs. statement to dining
philosphers problem, to address
https://github.com/rust-lang/rust/issues/25488 .
---
src/doc/trpl/dining-philosophers.md | 4 +++-
1 file changed, 3 insertions(+), 1 deletion(-)
diff --git a/src/doc/trpl/dining-philosophers.md b/src/doc/trpl/dining-philosophers.md
index 7e37473ac8f..a18d9bb442d 100644
--- a/src/doc/trpl/dining-philosophers.md
+++ b/src/doc/trpl/dining-philosophers.md
@@ -432,7 +432,9 @@ an extra annotation, `move`, to indicate that the closure is going to take
ownership of the values it’s capturing. Primarily, the `p` variable of the
`map` function.
-Inside the thread, all we do is call `eat()` on `p`.
+Inside the thread, all we do is call `eat()` on `p`. Also note that the call to `thread::spawn` lacks a trailing semicolon, making this an expression. This distinction is important, yielding the correct return value. For more details, read [Expressions vs. Statements][es].
+
+[es]: functions.html#expressions-vs.-statements
```rust,ignore
}).collect();
From 675b3decadc149b400d9afc4c59e0703a0b100ff Mon Sep 17 00:00:00 2001
From: Chuck Bassett <iamchuckb@gmail.com>
Date: Sun, 7 Jun 2015 15:06:58 -0400
Subject: [PATCH 07/14] Update doctest in comments.md
For a user following the path of reading Chapter 5: Syntax & Symantics
prior to Chapter 4: Learn Rust, this will be the first time they have
encountered executable tests inside documentation comments.
The test will fail because the `add_one` function is not defined in
the context of the doctest. This might not be the optimal place to
introduce and explain the `/// #` notation but I think it is important
that this snippet pass as a test when `rustdoc --test` is run against
it if it is going to be shown.
---
src/doc/trpl/comments.md | 3 +++
1 file changed, 3 insertions(+)
diff --git a/src/doc/trpl/comments.md b/src/doc/trpl/comments.md
index fa27d1c226c..7687d2a57da 100644
--- a/src/doc/trpl/comments.md
+++ b/src/doc/trpl/comments.md
@@ -29,6 +29,9 @@ The other kind of comment is a doc comment. Doc comments use `///` instead of
/// let five = 5;
///
/// assert_eq!(6, add_one(5));
+/// # fn add_one(x: i32) -> i32 {
+/// # x + 1
+/// # }
/// ```
fn add_one(x: i32) -> i32 {
x + 1
From 33118eb17ae53abcda07832d25d9b5da094b61e2 Mon Sep 17 00:00:00 2001
From: diwic <diwic@users.noreply.github.com>
Date: Sun, 7 Jun 2015 23:14:01 +0200
Subject: [PATCH 08/14] Make all leaks safe in language reference
Since it was determined that no leaks were unsafe, some of the documentation is still not clear about this. Here's one example.
---
src/doc/reference.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/src/doc/reference.md b/src/doc/reference.md
index d56ecb360cf..6264e467886 100644
--- a/src/doc/reference.md
+++ b/src/doc/reference.md
@@ -1038,7 +1038,7 @@ be undesired.
* Deadlocks
* Reading data from private fields (`std::repr`)
-* Leaks due to reference count cycles, even in the global heap
+* Leaks of memory and other resources
* Exiting without calling destructors
* Sending signals
* Accessing/modifying the file system
From ebc3de22d8e3b7b1d6e2c77e444965bb9db51aa7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marcel=20M=C3=BCller?= <neikos@neikos.email>
Date: Mon, 8 Jun 2015 17:58:08 +0200
Subject: [PATCH 09/14] Fixed old occurences of the removed array syntax
As per RFC#520 the syntax for arrays has changed,
this changes the remaining comments to reflect
the new syntax.
---
src/librustc/middle/traits/select.rs | 4 ++--
src/librustc_typeck/check/coercion.rs | 4 ++--
src/librustc_typeck/check/method/README.md | 2 +-
src/librustc_typeck/check/mod.rs | 2 +-
4 files changed, 6 insertions(+), 6 deletions(-)
diff --git a/src/librustc/middle/traits/select.rs b/src/librustc/middle/traits/select.rs
index 4ea6f0cb26e..789d4f8b9d3 100644
--- a/src/librustc/middle/traits/select.rs
+++ b/src/librustc/middle/traits/select.rs
@@ -1663,11 +1663,11 @@ impl<'cx, 'tcx> SelectionContext<'cx, 'tcx> {
}
ty::ty_vec(element_ty, ref len) => {
- // [T, ..n] and [T]
+ // [T; n] and [T]
match bound {
ty::BoundCopy => {
match *len {
- // [T, ..n] is copy iff T is copy
+ // [T; n] is copy iff T is copy
Some(_) => ok_if(vec![element_ty]),
// [T] is unsized and hence affine
diff --git a/src/librustc_typeck/check/coercion.rs b/src/librustc_typeck/check/coercion.rs
index 92317aae089..624312dac38 100644
--- a/src/librustc_typeck/check/coercion.rs
+++ b/src/librustc_typeck/check/coercion.rs
@@ -234,8 +234,8 @@ impl<'f, 'tcx> Coerce<'f, 'tcx> {
}
- // &[T, ..n] or &mut [T, ..n] -> &[T]
- // or &mut [T, ..n] -> &mut [T]
+ // &[T; n] or &mut [T; n] -> &[T]
+ // or &mut [T; n] -> &mut [T]
// or &Concrete -> &Trait, etc.
fn coerce_unsized(&self,
source: Ty<'tcx>,
diff --git a/src/librustc_typeck/check/method/README.md b/src/librustc_typeck/check/method/README.md
index 367273dc635..b5d317d6025 100644
--- a/src/librustc_typeck/check/method/README.md
+++ b/src/librustc_typeck/check/method/README.md
@@ -18,7 +18,7 @@ into a more explicit UFCS form:
Here `ADJ` is some kind of adjustment, which is typically a series of
autoderefs and then possibly an autoref (e.g., `&**receiver`). However
we sometimes do other adjustments and coercions along the way, in
-particular unsizing (e.g., converting from `[T, ..n]` to `[T]`).
+particular unsizing (e.g., converting from `[T; n]` to `[T]`).
## The Two Phases
diff --git a/src/librustc_typeck/check/mod.rs b/src/librustc_typeck/check/mod.rs
index e37856bbb2e..6f97239ae93 100644
--- a/src/librustc_typeck/check/mod.rs
+++ b/src/librustc_typeck/check/mod.rs
@@ -2085,7 +2085,7 @@ fn lookup_indexing<'a, 'tcx>(fcx: &FnCtxt<'a, 'tcx>,
return final_mt;
}
- // After we have fully autoderef'd, if the resulting type is [T, ..n], then
+ // After we have fully autoderef'd, if the resulting type is [T; n], then
// do a final unsized coercion to yield [T].
if let ty::ty_vec(element_ty, Some(_)) = ty.sty {
let adjusted_ty = ty::mk_vec(fcx.tcx(), element_ty, None);
From 5efdcf268aed5139b8ec9de52db094edaf866822 Mon Sep 17 00:00:00 2001
From: Mathieu David <mathieudavid@mathieudavid.org>
Date: Mon, 8 Jun 2015 18:01:40 +0200
Subject: [PATCH 10/14] Updated with requested changes
---
src/doc/trpl/ownership.md | 5 +----
1 file changed, 1 insertion(+), 4 deletions(-)
diff --git a/src/doc/trpl/ownership.md b/src/doc/trpl/ownership.md
index e94fe033407..46af311acf3 100644
--- a/src/doc/trpl/ownership.md
+++ b/src/doc/trpl/ownership.md
@@ -157,7 +157,7 @@ But, unlike a move, we can still use `v` afterward. This is because an `i32`
has no pointers to data somewhere else, copying it is a full copy.
All primitive types implement the `Copy` trait and their ownership is
-therefore not moved like one would assume, following the **ownership rules**.
+therefore not moved like one would assume, following the ´ownership rules´.
To give an example, the two following snippets of code only compile because the
`i32` and `bool` types implement the `Copy` trait.
@@ -196,9 +196,6 @@ println!("{}", a);
^
```
-This is quite important to understand, because it is an exception to the most
-fundamental rule in the Rust language.
-
We will discuss how to make your own types `Copy` in the [traits][traits]
section.
From a6dd8718214fc4fb31bcb8fd8779ce435551200d Mon Sep 17 00:00:00 2001
From: saml <saml@users.noreply.github.com>
Date: Mon, 8 Jun 2015 15:42:33 -0400
Subject: [PATCH 11/14] Fixing typo, [[lib]] to [lib]
Cargo expects `lib` to be table, not an array of tables (only single lib per project).
---
src/doc/trpl/hello-cargo.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/src/doc/trpl/hello-cargo.md b/src/doc/trpl/hello-cargo.md
index 0e5bbea453c..9920e8e0068 100644
--- a/src/doc/trpl/hello-cargo.md
+++ b/src/doc/trpl/hello-cargo.md
@@ -36,7 +36,7 @@ Note that since we're creating an executable, we used `main.rs`. If we
want to make a library instead, we should use `lib.rs`. This convention is required
for Cargo to successfully compile our projects, but it can be overridden if we wish.
Custom file locations for the entry point can be specified
-with a [`[[lib]]` or `[[bin]]`][crates-custom] key in the TOML file described below.
+with a [`[lib]` or `[[bin]]`][crates-custom] key in the TOML file.
[crates-custom]: http://doc.crates.io/manifest.html#configuring-a-target
From e305674945aca47772356d9fbc7d4bacbd134c92 Mon Sep 17 00:00:00 2001
From: Tshepang Lekhonkhobe <tshepang@gmail.com>
Date: Mon, 8 Jun 2015 21:58:48 +0200
Subject: [PATCH 12/14] book: remove a sentence that is not clear
---
src/doc/trpl/generics.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/src/doc/trpl/generics.md b/src/doc/trpl/generics.md
index f8f1962e0cf..c28d7c71608 100644
--- a/src/doc/trpl/generics.md
+++ b/src/doc/trpl/generics.md
@@ -1,8 +1,8 @@
% Generics
Sometimes, when writing a function or data type, we may want it to work for
-multiple types of arguments. Luckily, Rust has a feature that gives us a better
-way: generics. Generics are called ‘parametric polymorphism’ in type theory,
+multiple types of arguments. In Rust, we can do this with generics.
+Generics are called ‘parametric polymorphism’ in type theory,
which means that they are types or functions that have multiple forms (‘poly’
is multiple, ‘morph’ is form) over a given parameter (‘parametric’).
From 7abb40c79ac8ed0d79fb45cd9ec4c3ba5c59fadf Mon Sep 17 00:00:00 2001
From: Tshepang Lekhonkhobe <tshepang@gmail.com>
Date: Tue, 9 Jun 2015 00:16:23 +0200
Subject: [PATCH 13/14] reference: improve readability
---
src/doc/reference.md | 10 +++++++---
1 file changed, 7 insertions(+), 3 deletions(-)
diff --git a/src/doc/reference.md b/src/doc/reference.md
index d56ecb360cf..c85f51b78cd 100644
--- a/src/doc/reference.md
+++ b/src/doc/reference.md
@@ -1418,9 +1418,13 @@ impl<T> Container for Vec<T> {
```
Generic functions may use traits as _bounds_ on their type parameters. This
-will have two effects: only types that have the trait may instantiate the
-parameter, and within the generic function, the methods of the trait can be
-called on values that have the parameter's type. For example:
+will have two effects:
+
+- Only types that have the trait may instantiate the parameter.
+- Within the generic function, the methods of the trait can be
+ called on values that have the parameter's type.
+
+For example:
```
# type Surface = i32;
From 76102b0aa7731574ac0b0882fe45dd6ce81b4031 Mon Sep 17 00:00:00 2001
From: Tshepang Lekhonkhobe <tshepang@gmail.com>
Date: Tue, 9 Jun 2015 00:20:51 +0200
Subject: [PATCH 14/14] reference: that looks better without those
abbreviations
---
src/doc/reference.md | 12 ++++++------
1 file changed, 6 insertions(+), 6 deletions(-)
diff --git a/src/doc/reference.md b/src/doc/reference.md
index d56ecb360cf..9ef5182b4e9 100644
--- a/src/doc/reference.md
+++ b/src/doc/reference.md
@@ -2831,13 +2831,13 @@ on the right-hand side.
An example of an `as` expression:
```
-# fn sum(v: &[f64]) -> f64 { 0.0 }
-# fn len(v: &[f64]) -> i32 { 0 }
+# fn sum(values: &[f64]) -> f64 { 0.0 }
+# fn len(values: &[f64]) -> i32 { 0 }
-fn avg(v: &[f64]) -> f64 {
- let sum: f64 = sum(v);
- let sz: f64 = len(v) as f64;
- return sum / sz;
+fn average(values: &[f64]) -> f64 {
+ let sum: f64 = sum(values);
+ let size: f64 = len(values) as f64;
+ sum / size
}
```