From 6d2fe2e8851ca87abe8f7dcb4e08b6a09b4cbcf1 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sun, 24 Aug 2014 04:00:41 +0200 Subject: [PATCH 01/20] doc: add missing word --- src/doc/guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/guide.md b/src/doc/guide.md index f1211c0788eef..11e46c155e02e 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -5526,7 +5526,7 @@ Guide can help you if you want to write your own. # Unsafe -Finally, there's one more concept that you should be aware in Rust: `unsafe`. +Finally, there's one more Rust concept that you should be aware of: `unsafe`. There are two circumstances where Rust's safety provisions don't work well. The first is when interfacing with C code, and the second is when building certain kinds of abstractions. From 2d723237db4fe0e7fc43ed1866c3e1952a1753ad Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sun, 24 Aug 2014 12:21:41 +0200 Subject: [PATCH 02/20] doc: use the more convenient 'cargo run' command This lovely command has already been introduced, so let's take advantage of it. --- src/doc/guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/doc/guide.md b/src/doc/guide.md index f1211c0788eef..ced88e9db00d0 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -2682,9 +2682,9 @@ $ cargo new modules --bin Let's double check our work by compiling: ```{bash,ignore} -$ cargo build +$ cargo run Compiling modules v0.0.1 (file:///home/you/projects/modules) -$ ./target/modules + Running `target/modules` Hello, world! ``` From 538ea3cd0567e742268c2f4cd750f314412d48c2 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sun, 24 Aug 2014 13:51:42 +0200 Subject: [PATCH 03/20] doc: slight consistency fix Others in this list are Capitalized, so do it here too. --- src/doc/guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/guide.md b/src/doc/guide.md index f1211c0788eef..14b49be790b1b 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -3025,7 +3025,7 @@ markers. Rust provides six attributes to indicate the stability level of various parts of your library. The six levels are: -* deprecated: this item should no longer be used. No guarantee of backwards +* deprecated: This item should no longer be used. No guarantee of backwards compatibility. * experimental: This item was only recently introduced or is otherwise in a state of flux. It may change significantly, or even be removed. No guarantee From c09c038e11d8ed84a965179903891628dd72573f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Gawdzik=20=E2=98=A2?= Date: Tue, 26 Aug 2014 02:56:22 -0400 Subject: [PATCH 04/20] Added a note for usage of abs with ::MIN. --- src/libcore/num/mod.rs | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/src/libcore/num/mod.rs b/src/libcore/num/mod.rs index 42f74ab429a6f..6d6ca59ce01ed 100644 --- a/src/libcore/num/mod.rs +++ b/src/libcore/num/mod.rs @@ -160,6 +160,8 @@ pub trait Signed: Num + Neg { /// Computes the absolute value. /// /// For `f32` and `f64`, `NaN` will be returned if the number is `NaN`. + /// + /// For signed integers, `::MIN` will be returned if the number is `::MIN`. fn abs(&self) -> Self; /// The positive difference of two numbers. @@ -176,7 +178,7 @@ pub trait Signed: Num + Neg { /// * `-1.0` if the number is negative, `-0.0` or `NEG_INFINITY` /// * `NaN` if the number is `NaN` /// - /// For `int`: + /// For signed integers: /// /// * `0` if the number is zero /// * `1` if the number is positive @@ -272,6 +274,8 @@ signed_float_impl!(f64, f64::NAN, f64::INFINITY, f64::NEG_INFINITY, /// Computes the absolute value. /// /// For `f32` and `f64`, `NaN` will be returned if the number is `NaN` +/// +/// For signed integers, `::MIN` will be returned if the number is `::MIN`. #[inline(always)] pub fn abs(value: T) -> T { value.abs() @@ -294,7 +298,7 @@ pub fn abs_sub(x: T, y: T) -> T { /// * `-1.0` if the number is negative, `-0.0` or `NEG_INFINITY` /// * `NaN` if the number is `NaN` /// -/// For int: +/// For signed integers: /// /// * `0` if the number is zero /// * `1` if the number is positive From 48a2876c2cd951c7e09922511b770b071a45b566 Mon Sep 17 00:00:00 2001 From: mdinger Date: Wed, 27 Aug 2014 00:26:50 -0400 Subject: [PATCH 05/20] Fix sorting order. Change `sync` to `share` --- src/doc/rust.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/doc/rust.md b/src/doc/rust.md index 4bbcba6c2f300..a31f886a4df07 100644 --- a/src/doc/rust.md +++ b/src/doc/rust.md @@ -2218,14 +2218,14 @@ These types help drive the compiler's analysis * `begin_unwind` : ___Needs filling in___ +* `managed_bound` + : This type implements "managed" * `no_copy_bound` : This type does not implement "copy", even if eligible * `no_send_bound` : This type does not implement "send", even if eligible -* `no_sync_bound` - : This type does not implement "sync", even if eligible -* `managed_bound` - : This type implements "managed" +* `no_share_bound` + : This type does not implement "share", even if eligible * `eh_personality` : ___Needs filling in___ * `exchange_free` From 687db5d887a700bccf6d752caf9b5cc8805641a0 Mon Sep 17 00:00:00 2001 From: Joseph Crail Date: Tue, 26 Aug 2014 19:46:20 -0400 Subject: [PATCH 06/20] Fix issue #15826. The implemented fix rounds half-way cases away from zero as described in the original comments. This rounding algorithm is sometimes called arithmetic rounding. It is described further here: http://en.wikipedia.org/wiki/Rounding#Round_half_away_from_zero I also added several new tests to prevent regressions. --- src/libnum/rational.rs | 35 +++++++++++++++++++++++++++++------ 1 file changed, 29 insertions(+), 6 deletions(-) diff --git a/src/libnum/rational.rs b/src/libnum/rational.rs index f3e4b0b21adf8..6f85460ab956e 100644 --- a/src/libnum/rational.rs +++ b/src/libnum/rational.rs @@ -137,15 +137,14 @@ impl } /// Rounds to the nearest integer. Rounds half-way cases away from zero. - /// - /// Note: This function is currently broken and always rounds away from zero. #[inline] pub fn round(&self) -> Ratio { - // FIXME(#15826) if *self < Zero::zero() { - Ratio::from_integer((self.numer - self.denom + One::one()) / self.denom) + // a/b - 1/2 = (2*a - b)/(2*b) + Ratio::from_integer((self.numer + self.numer - self.denom) / (self.denom + self.denom)) } else { - Ratio::from_integer((self.numer + self.denom - One::one()) / self.denom) + // a/b + 1/2 = (2*a + b)/(2*b) + Ratio::from_integer((self.numer + self.numer + self.denom) / (self.denom + self.denom)) } } @@ -388,7 +387,11 @@ mod test { pub static _2: Rational = Ratio { numer: 2, denom: 1}; pub static _1_2: Rational = Ratio { numer: 1, denom: 2}; pub static _3_2: Rational = Ratio { numer: 3, denom: 2}; - pub static _neg1_2: Rational = Ratio { numer: -1, denom: 2}; + pub static _neg1_2: Rational = Ratio { numer: -1, denom: 2}; + pub static _1_3: Rational = Ratio { numer: 1, denom: 3}; + pub static _neg1_3: Rational = Ratio { numer: -1, denom: 3}; + pub static _2_3: Rational = Ratio { numer: 2, denom: 3}; + pub static _neg2_3: Rational = Ratio { numer: -2, denom: 3}; pub fn to_big(n: Rational) -> BigRational { Ratio::new( @@ -578,6 +581,26 @@ mod test { #[test] fn test_round() { + assert_eq!(_1_3.ceil(), _1); + assert_eq!(_1_3.floor(), _0); + assert_eq!(_1_3.round(), _0); + assert_eq!(_1_3.trunc(), _0); + + assert_eq!(_neg1_3.ceil(), _0); + assert_eq!(_neg1_3.floor(), -_1); + assert_eq!(_neg1_3.round(), _0); + assert_eq!(_neg1_3.trunc(), _0); + + assert_eq!(_2_3.ceil(), _1); + assert_eq!(_2_3.floor(), _0); + assert_eq!(_2_3.round(), _1); + assert_eq!(_2_3.trunc(), _0); + + assert_eq!(_neg2_3.ceil(), _0); + assert_eq!(_neg2_3.floor(), -_1); + assert_eq!(_neg2_3.round(), -_1); + assert_eq!(_neg2_3.trunc(), _0); + assert_eq!(_1_2.ceil(), _1); assert_eq!(_1_2.floor(), _0); assert_eq!(_1_2.round(), _1); From 5f919cd7aaf99fcd2a6a9e9f5f61600c56f19cc2 Mon Sep 17 00:00:00 2001 From: Sebastian Zaha Date: Thu, 28 Aug 2014 22:47:45 +0200 Subject: [PATCH 07/20] Cargo begins version number at 0.0.1 instead of 0.1.0. --- src/doc/guide.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/src/doc/guide.md b/src/doc/guide.md index 8a634a083e8ad..5af2e60ba1b9e 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -315,7 +315,7 @@ Put this inside: [package] name = "hello_world" -version = "0.1.0" +version = "0.0.1" authors = [ "Your name " ] [[bin]] @@ -1813,7 +1813,7 @@ Try it out: ```{notrust,ignore} $ cargo run - Compiling guessing_game v0.1.0 (file:///home/you/projects/guessing_game) + Compiling guessing_game v0.0.1 (file:///home/you/projects/guessing_game) Running `target/guessing_game` Hello, world! ``` @@ -1959,7 +1959,7 @@ Try running our new program a few times: ```{notrust,ignore} $ cargo run - Compiling guessing_game v0.1.0 (file:///home/you/projects/guessing_game) + Compiling guessing_game v0.0.1 (file:///home/you/projects/guessing_game) Running `target/guessing_game` Guess the number! The secret number is: 7 @@ -2012,7 +2012,7 @@ And trying it out: ```{notrust,ignore} $ cargo run - Compiling guessing_game v0.1.0 (file:///home/you/projects/guessing_game) + Compiling guessing_game v0.0.1 (file:///home/you/projects/guessing_game) Running `target/guessing_game` Guess the number! The secret number is: 57 @@ -2283,7 +2283,7 @@ print an error message and return. Let's give this a shot: ```{notrust,ignore} $ cargo run - Compiling guessing_game v0.1.0 (file:///home/you/projects/guessing_game) + Compiling guessing_game v0.0.1 (file:///home/you/projects/guessing_game) Running `target/guessing_game` Guess the number! The secret number is: 17 @@ -2348,7 +2348,7 @@ Let's try it! ```{notrust,ignore} $ cargo run - Compiling guessing_game v0.1.0 (file:///home/you/projects/guessing_game) + Compiling guessing_game v0.0.1 (file:///home/you/projects/guessing_game) Running `target/guessing_game` Guess the number! The secret number is: 58 @@ -2425,7 +2425,7 @@ that `return`? If we give a non-number answer, we'll `return` and quit. Observe: ```{notrust,ignore} $ cargo run - Compiling guessing_game v0.1.0 (file:///home/you/projects/guessing_game) + Compiling guessing_game v0.0.1 (file:///home/you/projects/guessing_game) Running `target/guessing_game` Guess the number! The secret number is: 59 @@ -2557,7 +2557,7 @@ Now we should be good! Let's try: ```{notrust,ignore} $ cargo run - Compiling guessing_game v0.1.0 (file:///home/you/projects/guessing_game) + Compiling guessing_game v0.0.1 (file:///home/you/projects/guessing_game) Running `target/guessing_game` Guess the number! The secret number is: 61 From 6138e835f6af60854324fcb1c1096597fb058ada Mon Sep 17 00:00:00 2001 From: Sebastian Zaha Date: Thu, 28 Aug 2014 23:14:09 +0200 Subject: [PATCH 08/20] Fix guide typo. --- src/doc/guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/guide.md b/src/doc/guide.md index 8a634a083e8ad..d6402c964594e 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -3300,7 +3300,7 @@ To learn more, run the command again with --verbose. Rust can't find this function. That makes sense, as we didn't write it yet! -In order to share this codes with our tests, we'll need to make a library crate. +In order to share this code with our tests, we'll need to make a library crate. This is also just good software design: as we mentioned before, it's a good idea to put most of your functionality into a library crate, and have your executable crate use that library. This allows for code re-use. From 080449de0c3f5ad56189439e50ece02115c1778a Mon Sep 17 00:00:00 2001 From: Clark Gaebel Date: Thu, 28 Aug 2014 14:57:16 -0700 Subject: [PATCH 09/20] Fixed misleading docs in liballoc --- src/liballoc/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/liballoc/lib.rs b/src/liballoc/lib.rs index cacb9e28989ed..503c484e469d7 100644 --- a/src/liballoc/lib.rs +++ b/src/liballoc/lib.rs @@ -12,7 +12,7 @@ //! //! This is the lowest level library through which allocation in Rust can be //! performed where the allocation is assumed to succeed. This library will -//! trigger a task failure when allocation fails. +//! abort the process when allocation fails. //! //! This library, like libcore, is not intended for general usage, but rather as //! a building block of other libraries. The types and interfaces in this From db7c7c23a49081001bd4ceb652fec86b73d7806b Mon Sep 17 00:00:00 2001 From: Michael Sproul Date: Fri, 29 Aug 2014 10:03:30 +1000 Subject: [PATCH 10/20] doc: Clarify slice failure conditions. --- src/libcore/slice.rs | 61 ++++++++++++++++++++++++-------------------- 1 file changed, 33 insertions(+), 28 deletions(-) diff --git a/src/libcore/slice.rs b/src/libcore/slice.rs index 5a70cd8c847da..774365366cc39 100644 --- a/src/libcore/slice.rs +++ b/src/libcore/slice.rs @@ -57,31 +57,31 @@ use raw::Slice as RawSlice; // Extension traits // -/// Extension methods for vectors +/// Extension methods for immutable slices. #[unstable = "may merge with other traits; region parameter may disappear"] pub trait ImmutableSlice<'a, T> { - /** - * Returns a slice of self spanning the interval [`start`, `end`). - * - * Fails when the slice (or part of it) is outside the bounds of self, - * or when `start` > `end`. - */ + /// Returns a subslice spanning the interval [`start`, `end`). + /// + /// Fails when the end of the new slice lies beyond the end of the + /// original slice (i.e. when `end > self.len()`) or when `start > end`. + /// + /// Slicing with `start` equal to `end` yields an empty slice. #[unstable] fn slice(&self, start: uint, end: uint) -> &'a [T]; - /** - * Returns a slice of self from `start` to the end of the vec. - * - * Fails when `start` points outside the bounds of self. - */ + /// Returns a subslice from `start` to the end of the slice. + /// + /// Fails when `start` is strictly greater than the length of the original slice. + /// + /// Slicing from `self.len()` yields an empty slice. #[unstable] fn slice_from(&self, start: uint) -> &'a [T]; - /** - * Returns a slice of self from the start of the vec to `end`. - * - * Fails when `end` points outside the bounds of self. - */ + /// Returns a subslice from the start of the slice to `end`. + /// + /// Fails when `end` is strictly greater than the length of the original slice. + /// + /// Slicing to `0` yields an empty slice. #[unstable] fn slice_to(&self, end: uint) -> &'a [T]; @@ -486,21 +486,26 @@ pub trait MutableSlice<'a, T> { /// Primarily intended for getting a &mut [T] from a [T, ..N]. fn as_mut_slice(self) -> &'a mut [T]; - /// Return a slice that points into another slice. + /// Returns a mutable subslice spanning the interval [`start`, `end`). + /// + /// Fails when the end of the new slice lies beyond the end of the + /// original slice (i.e. when `end > self.len()`) or when `start > end`. + /// + /// Slicing with `start` equal to `end` yields an empty slice. fn mut_slice(self, start: uint, end: uint) -> &'a mut [T]; - /** - * Returns a slice of self from `start` to the end of the vec. - * - * Fails when `start` points outside the bounds of self. - */ + /// Returns a mutable subslice from `start` to the end of the slice. + /// + /// Fails when `start` is strictly greater than the length of the original slice. + /// + /// Slicing from `self.len()` yields an empty slice. fn mut_slice_from(self, start: uint) -> &'a mut [T]; - /** - * Returns a slice of self from the start of the vec to `end`. - * - * Fails when `end` points outside the bounds of self. - */ + /// Returns a mutable subslice from the start of the slice to `end`. + /// + /// Fails when `end` is strictly greater than the length of the original slice. + /// + /// Slicing to `0` yields an empty slice. fn mut_slice_to(self, end: uint) -> &'a mut [T]; /// Returns an iterator that allows modifying each value From 5bf1b03e5c8753680c231ebcb7735a9855de31a3 Mon Sep 17 00:00:00 2001 From: Jonas Hietala Date: Fri, 29 Aug 2014 09:18:05 +0200 Subject: [PATCH 11/20] Tweak error message for use of a keyword in ident position. Closes #15358 --- src/doc/guide.md | 2 +- src/libsyntax/parse/parser.rs | 2 +- src/test/compile-fail/bad-value-ident-false.rs | 2 +- src/test/compile-fail/bad-value-ident-true.rs | 2 +- src/test/compile-fail/keyword-super.rs | 2 +- src/test/compile-fail/keyword.rs | 2 +- src/test/compile-fail/removed-syntax-field-let.rs | 2 +- src/test/compile-fail/removed-syntax-mut-vec-expr.rs | 2 +- src/test/compile-fail/removed-syntax-mut-vec-ty.rs | 2 +- src/test/compile-fail/removed-syntax-uniq-mut-expr.rs | 2 +- src/test/compile-fail/removed-syntax-uniq-mut-ty.rs | 2 +- src/test/compile-fail/unsized2.rs | 2 +- 12 files changed, 12 insertions(+), 12 deletions(-) diff --git a/src/doc/guide.md b/src/doc/guide.md index 8a634a083e8ad..5bd88288caf43 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -630,7 +630,7 @@ In Rust, however, using `let` to introduce a binding is _not_ an expression. The following will produce a compile-time error: ```{ignore} -let x = (let y = 5i); // found `let` in ident position +let x = (let y = 5i); // expected identifier, found keyword `let` ``` The compiler is telling us here that it was expecting to see the beginning of diff --git a/src/libsyntax/parse/parser.rs b/src/libsyntax/parse/parser.rs index 37bda15ac2c41..e53ad42cb8e38 100644 --- a/src/libsyntax/parse/parser.rs +++ b/src/libsyntax/parse/parser.rs @@ -599,7 +599,7 @@ impl<'a> Parser<'a> { let token_str = self.this_token_to_string(); let span = self.span; self.span_err(span, - format!("found `{}` in ident position", + format!("expected identifier, found keyword `{}`", token_str).as_slice()); } } diff --git a/src/test/compile-fail/bad-value-ident-false.rs b/src/test/compile-fail/bad-value-ident-false.rs index 17157623863ad..ca10bdd9848ec 100644 --- a/src/test/compile-fail/bad-value-ident-false.rs +++ b/src/test/compile-fail/bad-value-ident-false.rs @@ -8,5 +8,5 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -fn false() { } //~ ERROR found `false` in ident position +fn false() { } //~ ERROR expected identifier, found keyword `false` fn main() { } diff --git a/src/test/compile-fail/bad-value-ident-true.rs b/src/test/compile-fail/bad-value-ident-true.rs index 5160471e95c80..4508d5219a217 100644 --- a/src/test/compile-fail/bad-value-ident-true.rs +++ b/src/test/compile-fail/bad-value-ident-true.rs @@ -8,5 +8,5 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -fn true() { } //~ ERROR found `true` in ident position +fn true() { } //~ ERROR expected identifier, found keyword `true` fn main() { } diff --git a/src/test/compile-fail/keyword-super.rs b/src/test/compile-fail/keyword-super.rs index 0a4ec841bd3ce..6cbc8aa1ea642 100644 --- a/src/test/compile-fail/keyword-super.rs +++ b/src/test/compile-fail/keyword-super.rs @@ -9,5 +9,5 @@ // except according to those terms. fn main() { - let super: int; //~ ERROR found `super` in ident position + let super: int; //~ ERROR expected identifier, found keyword `super` } diff --git a/src/test/compile-fail/keyword.rs b/src/test/compile-fail/keyword.rs index 2df56a0ab7c22..64eac47e69b32 100644 --- a/src/test/compile-fail/keyword.rs +++ b/src/test/compile-fail/keyword.rs @@ -9,5 +9,5 @@ // except according to those terms. pub mod break { - //~^ ERROR found `break` in ident position + //~^ ERROR expected identifier, found keyword `break` } diff --git a/src/test/compile-fail/removed-syntax-field-let.rs b/src/test/compile-fail/removed-syntax-field-let.rs index 2b76db4f160a4..c8711598163a0 100644 --- a/src/test/compile-fail/removed-syntax-field-let.rs +++ b/src/test/compile-fail/removed-syntax-field-let.rs @@ -10,6 +10,6 @@ struct s { let foo: (), - //~^ ERROR found `let` in ident position + //~^ ERROR expected identifier, found keyword `let` //~^^ ERROR expected `:`, found `foo` } diff --git a/src/test/compile-fail/removed-syntax-mut-vec-expr.rs b/src/test/compile-fail/removed-syntax-mut-vec-expr.rs index 9f0cc0107c1f8..b20da6346f775 100644 --- a/src/test/compile-fail/removed-syntax-mut-vec-expr.rs +++ b/src/test/compile-fail/removed-syntax-mut-vec-expr.rs @@ -10,6 +10,6 @@ fn f() { let v = [mut 1, 2, 3, 4]; - //~^ ERROR found `mut` in ident position + //~^ ERROR expected identifier, found keyword `mut` //~^^ ERROR expected `]`, found `1` } diff --git a/src/test/compile-fail/removed-syntax-mut-vec-ty.rs b/src/test/compile-fail/removed-syntax-mut-vec-ty.rs index 912952892e4f7..c5eec2ef6e199 100644 --- a/src/test/compile-fail/removed-syntax-mut-vec-ty.rs +++ b/src/test/compile-fail/removed-syntax-mut-vec-ty.rs @@ -9,5 +9,5 @@ // except according to those terms. type v = [mut int]; - //~^ ERROR found `mut` in ident position + //~^ ERROR expected identifier, found keyword `mut` //~^^ ERROR expected `]`, found `int` diff --git a/src/test/compile-fail/removed-syntax-uniq-mut-expr.rs b/src/test/compile-fail/removed-syntax-uniq-mut-expr.rs index f4fc5b696fa4b..124b3738fab5f 100644 --- a/src/test/compile-fail/removed-syntax-uniq-mut-expr.rs +++ b/src/test/compile-fail/removed-syntax-uniq-mut-expr.rs @@ -10,6 +10,6 @@ fn f() { let a_box = box mut 42; - //~^ ERROR found `mut` in ident position + //~^ ERROR expected identifier, found keyword `mut` //~^^ ERROR expected `;`, found `42` } diff --git a/src/test/compile-fail/removed-syntax-uniq-mut-ty.rs b/src/test/compile-fail/removed-syntax-uniq-mut-ty.rs index a3fc27d8cf2e0..579bfed1331ed 100644 --- a/src/test/compile-fail/removed-syntax-uniq-mut-ty.rs +++ b/src/test/compile-fail/removed-syntax-uniq-mut-ty.rs @@ -9,5 +9,5 @@ // except according to those terms. type mut_box = Box; - //~^ ERROR found `mut` in ident position + //~^ ERROR expected identifier, found keyword `mut` //~^^ ERROR expected `,`, found `int` diff --git a/src/test/compile-fail/unsized2.rs b/src/test/compile-fail/unsized2.rs index 0c9d05e298832..c5f9e8d599193 100644 --- a/src/test/compile-fail/unsized2.rs +++ b/src/test/compile-fail/unsized2.rs @@ -13,5 +13,5 @@ fn f() {} pub fn main() { - f(); //~ ERROR found `type` in ident position + f(); //~ ERROR expected identifier, found keyword `type` } From 13bb83ce40636bbd0696fb0cc37a7bc77743a4ca Mon Sep 17 00:00:00 2001 From: Zbigniew Siciarz Date: Fri, 29 Aug 2014 10:53:18 +0200 Subject: [PATCH 12/20] Updated mut_chunks doc comment to match argument name. --- src/libcore/slice.rs | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/libcore/slice.rs b/src/libcore/slice.rs index 5a70cd8c847da..ce20052116a23 100644 --- a/src/libcore/slice.rs +++ b/src/libcore/slice.rs @@ -515,14 +515,14 @@ pub trait MutableSlice<'a, T> { fn mut_split(self, pred: |&T|: 'a -> bool) -> MutSplits<'a, T>; /** - * Returns an iterator over `size` elements of the vector at a time. - * The chunks are mutable and do not overlap. If `size` does not divide the - * length of the vector, then the last chunk will not have length - * `size`. + * Returns an iterator over `chunk_size` elements of the vector at a time. + * The chunks are mutable and do not overlap. If `chunk_size` does + * not divide the length of the vector, then the last chunk will not + * have length `chunk_size`. * * # Failure * - * Fails if `size` is 0. + * Fails if `chunk_size` is 0. */ fn mut_chunks(self, chunk_size: uint) -> MutChunks<'a, T>; From 26b40be7ed751e90be39c328904db2e28b10e23b Mon Sep 17 00:00:00 2001 From: Jonas Hietala Date: Fri, 29 Aug 2014 12:00:39 +0200 Subject: [PATCH 13/20] doc: Runnable examples logging. Also use //! Instead of /*! in liblog. --- src/liblog/lib.rs | 262 ++++++++++++++++++++++++------------------- src/liblog/macros.rs | 115 ++++++++++++++----- 2 files changed, 236 insertions(+), 141 deletions(-) diff --git a/src/liblog/lib.rs b/src/liblog/lib.rs index 0bad742933b1c..32222fb16ce61 100644 --- a/src/liblog/lib.rs +++ b/src/liblog/lib.rs @@ -8,120 +8,154 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -/*! - -Utilities for program-wide and customizable logging - -## Example - -``` -#![feature(phase)] -#[phase(plugin, link)] extern crate log; - -fn main() { - debug!("this is a debug {}", "message"); - error!("this is printed by default"); - - if log_enabled!(log::INFO) { - let x = 3i * 4i; // expensive computation - info!("the answer was: {}", x); - } -} -``` - -## Logging Macros - -There are five macros that the logging subsystem uses: - -* `log!(level, ...)` - the generic logging macro, takes a level as a u32 and any - related `format!` arguments -* `debug!(...)` - a macro hard-wired to the log level of `DEBUG` -* `info!(...)` - a macro hard-wired to the log level of `INFO` -* `warn!(...)` - a macro hard-wired to the log level of `WARN` -* `error!(...)` - a macro hard-wired to the log level of `ERROR` - -All of these macros use the same style of syntax as the `format!` syntax -extension. Details about the syntax can be found in the documentation of -`std::fmt` along with the Rust tutorial/manual. - -If you want to check at runtime if a given logging level is enabled (e.g. if the -information you would want to log is expensive to produce), you can use the -following macro: - -* `log_enabled!(level)` - returns true if logging of the given level is enabled - -## Enabling logging - -Log levels are controlled on a per-module basis, and by default all logging is -disabled except for `error!` (a log level of 1). Logging is controlled via the -`RUST_LOG` environment variable. The value of this environment variable is a -comma-separated list of logging directives. A logging directive is of the form: - -```text -path::to::module=log_level -``` - -The path to the module is rooted in the name of the crate it was compiled for, -so if your program is contained in a file `hello.rs`, for example, to turn on -logging for this file you would use a value of `RUST_LOG=hello`. -Furthermore, this path is a prefix-search, so all modules nested in the -specified module will also have logging enabled. - -The actual `log_level` is optional to specify. If omitted, all logging will be -enabled. If specified, the it must be either a numeric in the range of 1-255, or -it must be one of the strings `debug`, `error`, `info`, or `warn`. If a numeric -is specified, then all logging less than or equal to that numeral is enabled. -For example, if logging level 3 is active, error, warn, and info logs will be -printed, but debug will be omitted. - -As the log level for a module is optional, the module to enable logging for is -also optional. If only a `log_level` is provided, then the global log level for -all modules is set to this value. - -Some examples of valid values of `RUST_LOG` are: - -* `hello` turns on all logging for the 'hello' module -* `info` turns on all info logging -* `hello=debug` turns on debug logging for 'hello' -* `hello=3` turns on info logging for 'hello' -* `hello,std::option` turns on hello, and std's option logging -* `error,hello=warn` turn on global error logging and also warn for hello - -## Filtering results - -A RUST_LOG directive may include a regex filter. The syntax is to append `/` -followed by a regex. Each message is checked against the regex, and is only -logged if it matches. Note that the matching is done after formatting the log -string but before adding any logging meta-data. There is a single filter for all -modules. - -Some examples: - -* `hello/foo` turns on all logging for the 'hello' module where the log message -includes 'foo'. -* `info/f.o` turns on all info logging where the log message includes 'foo', -'f1o', 'fao', etc. -* `hello=debug/foo*foo` turns on debug logging for 'hello' where the the log -message includes 'foofoo' or 'fofoo' or 'fooooooofoo', etc. -* `error,hello=warn/[0-9] scopes` turn on global error logging and also warn for - hello. In both cases the log message must include a single digit number - followed by 'scopes' - -## Performance and Side Effects - -Each of these macros will expand to code similar to: - -```rust,ignore -if log_level <= my_module_log_level() { - ::log::log(log_level, format!(...)); -} -``` - -What this means is that each of these macros are very cheap at runtime if -they're turned off (just a load and an integer comparison). This also means that -if logging is disabled, none of the components of the log will be executed. - -*/ +//! Utilities for program-wide and customizable logging +//! +//! ## Example +//! +//! ``` +//! #![feature(phase)] +//! #[phase(plugin, link)] extern crate log; +//! +//! fn main() { +//! debug!("this is a debug {}", "message"); +//! error!("this is printed by default"); +//! +//! if log_enabled!(log::INFO) { +//! let x = 3i * 4i; // expensive computation +//! info!("the answer was: {}", x); +//! } +//! } +//! ``` +//! +//! Assumes the binary is `main`: +//! +//! ```{.bash} +//! $ RUST_LOG=error ./main +//! ERROR:main: this is printed by default +//! ``` +//! +//! ```{.bash} +//! $ RUST_LOG=info ./main +//! ERROR:main: this is printed by default +//! INFO:main: the answer was: 12 +//! ``` +//! +//! ```{.bash} +//! $ RUST_LOG=debug ./main +//! DEBUG:main: this is a debug message +//! ERROR:main: this is printed by default +//! INFO:main: the answer was: 12 +//! ``` +//! +//! You can also set the log level on a per module basis: +//! +//! ```{.bash} +//! $ RUST_LOG=main=info ./main +//! ERROR:main: this is printed by default +//! INFO:main: the answer was: 12 +//! ``` +//! +//! And enable all logging: +//! +//! ```{.bash} +//! $ RUST_LOG=main ./main +//! DEBUG:main: this is a debug message +//! ERROR:main: this is printed by default +//! INFO:main: the answer was: 12 +//! ``` +//! +//! +//! ## Logging Macros +//! +//! There are five macros that the logging subsystem uses: +//! +//! * `log!(level, ...)` - the generic logging macro, takes a level as a u32 and any +//! related `format!` arguments +//! * `debug!(...)` - a macro hard-wired to the log level of `DEBUG` +//! * `info!(...)` - a macro hard-wired to the log level of `INFO` +//! * `warn!(...)` - a macro hard-wired to the log level of `WARN` +//! * `error!(...)` - a macro hard-wired to the log level of `ERROR` +//! +//! All of these macros use the same style of syntax as the `format!` syntax +//! extension. Details about the syntax can be found in the documentation of +//! `std::fmt` along with the Rust tutorial/manual. +//! +//! If you want to check at runtime if a given logging level is enabled (e.g. if the +//! information you would want to log is expensive to produce), you can use the +//! following macro: +//! +//! * `log_enabled!(level)` - returns true if logging of the given level is enabled +//! +//! ## Enabling logging +//! +//! Log levels are controlled on a per-module basis, and by default all logging is +//! disabled except for `error!` (a log level of 1). Logging is controlled via the +//! `RUST_LOG` environment variable. The value of this environment variable is a +//! comma-separated list of logging directives. A logging directive is of the form: +//! +//! ```text +//! path::to::module=log_level +//! ``` +//! +//! The path to the module is rooted in the name of the crate it was compiled for, +//! so if your program is contained in a file `hello.rs`, for example, to turn on +//! logging for this file you would use a value of `RUST_LOG=hello`. +//! Furthermore, this path is a prefix-search, so all modules nested in the +//! specified module will also have logging enabled. +//! +//! The actual `log_level` is optional to specify. If omitted, all logging will be +//! enabled. If specified, the it must be either a numeric in the range of 1-255, or +//! it must be one of the strings `debug`, `error`, `info`, or `warn`. If a numeric +//! is specified, then all logging less than or equal to that numeral is enabled. +//! For example, if logging level 3 is active, error, warn, and info logs will be +//! printed, but debug will be omitted. +//! +//! As the log level for a module is optional, the module to enable logging for is +//! also optional. If only a `log_level` is provided, then the global log level for +//! all modules is set to this value. +//! +//! Some examples of valid values of `RUST_LOG` are: +//! +//! * `hello` turns on all logging for the 'hello' module +//! * `info` turns on all info logging +//! * `hello=debug` turns on debug logging for 'hello' +//! * `hello=3` turns on info logging for 'hello' +//! * `hello,std::option` turns on hello, and std's option logging +//! * `error,hello=warn` turn on global error logging and also warn for hello +//! +//! ## Filtering results +//! +//! A RUST_LOG directive may include a regex filter. The syntax is to append `/` +//! followed by a regex. Each message is checked against the regex, and is only +//! logged if it matches. Note that the matching is done after formatting the log +//! string but before adding any logging meta-data. There is a single filter for all +//! modules. +//! +//! Some examples: +//! +//! * `hello/foo` turns on all logging for the 'hello' module where the log message +//! includes 'foo'. +//! * `info/f.o` turns on all info logging where the log message includes 'foo', +//! 'f1o', 'fao', etc. +//! * `hello=debug/foo*foo` turns on debug logging for 'hello' where the the log +//! message includes 'foofoo' or 'fofoo' or 'fooooooofoo', etc. +//! * `error,hello=warn/[0-9] scopes` turn on global error logging and also warn for +//! hello. In both cases the log message must include a single digit number +//! followed by 'scopes' +//! +//! ## Performance and Side Effects +//! +//! Each of these macros will expand to code similar to: +//! +//! ```rust,ignore +//! if log_level <= my_module_log_level() { +//! ::log::log(log_level, format!(...)); +//! } +//! ``` +//! +//! What this means is that each of these macros are very cheap at runtime if +//! they're turned off (just a load and an integer comparison). This also means that +//! if logging is disabled, none of the components of the log will be executed. #![crate_name = "log"] #![experimental] diff --git a/src/liblog/macros.rs b/src/liblog/macros.rs index fe74b7d67ffb9..4f8837083ae57 100644 --- a/src/liblog/macros.rs +++ b/src/liblog/macros.rs @@ -24,11 +24,31 @@ /// #![feature(phase)] /// #[phase(plugin, link)] extern crate log; /// -/// # fn main() { -/// log!(log::DEBUG, "this is a debug message"); -/// log!(log::WARN, "this is a warning {}", "message"); -/// log!(6, "this is a custom logging level: {level}", level=6u); -/// # } +/// fn main() { +/// log!(log::WARN, "this is a warning {}", "message"); +/// log!(log::DEBUG, "this is a debug message"); +/// log!(6, "this is a custom logging level: {level}", level=6u); +/// } +/// ``` +/// +/// Assumes the binary is `main`: +/// +/// ```{.bash} +/// $ RUST_LOG=warn ./main +/// WARN:main: this is a warning message +/// ``` +/// +/// ```{.bash} +/// $ RUST_LOG=debug ./main +/// DEBUG:main: this is a debug message +/// WARN:main: this is a warning message +/// ``` +/// +/// ```{.bash} +/// $ RUST_LOG=6 ./main +/// DEBUG:main: this is a debug message +/// WARN:main: this is a warning message +/// 6:main: this is a custom logging level: 6 /// ``` #[macro_export] macro_rules! log( @@ -53,11 +73,19 @@ macro_rules! log( /// #![feature(phase)] /// #[phase(plugin, link)] extern crate log; /// -/// # fn main() { -/// # let error = 3u; -/// error!("the build has failed with error code: {}", error); -/// # } +/// fn main() { +/// let error = 3u; +/// error!("the build has failed with error code: {}", error); +/// } +/// ``` +/// +/// Assumes the binary is `main`: +/// +/// ```{.bash} +/// $ RUST_LOG=error ./main +/// ERROR:main: the build has failed with error code: 3 /// ``` +/// #[macro_export] macro_rules! error( ($($arg:tt)*) => (log!(::log::ERROR, $($arg)*)) @@ -71,10 +99,17 @@ macro_rules! error( /// #![feature(phase)] /// #[phase(plugin, link)] extern crate log; /// -/// # fn main() { -/// # let code = 3u; -/// warn!("you may like to know that a process exited with: {}", code); -/// # } +/// fn main() { +/// let code = 3u; +/// warn!("you may like to know that a process exited with: {}", code); +/// } +/// ``` +/// +/// Assumes the binary is `main`: +/// +/// ```{.bash} +/// $ RUST_LOG=warn ./main +/// WARN:main: you may like to know that a process exited with: 3 /// ``` #[macro_export] macro_rules! warn( @@ -89,10 +124,17 @@ macro_rules! warn( /// #![feature(phase)] /// #[phase(plugin, link)] extern crate log; /// -/// # fn main() { -/// # let ret = 3i; -/// info!("this function is about to return: {}", ret); -/// # } +/// fn main() { +/// let ret = 3i; +/// info!("this function is about to return: {}", ret); +/// } +/// ``` +/// +/// Assumes the binary is `main`: +/// +/// ```{.bash} +/// $ RUST_LOG=info ./main +/// INFO:main: this function is about to return: 3 /// ``` #[macro_export] macro_rules! info( @@ -109,9 +151,16 @@ macro_rules! info( /// #![feature(phase)] /// #[phase(plugin, link)] extern crate log; /// -/// # fn main() { -/// debug!("x = {x}, y = {y}", x=10i, y=20i); -/// # } +/// fn main() { +/// debug!("x = {x}, y = {y}", x=10i, y=20i); +/// } +/// ``` +/// +/// Assumes the binary is `main`: +/// +/// ```{.bash} +/// $ RUST_LOG=debug ./main +/// DEBUG:main: x = 10, y = 20 /// ``` #[macro_export] macro_rules! debug( @@ -126,14 +175,26 @@ macro_rules! debug( /// #![feature(phase)] /// #[phase(plugin, link)] extern crate log; /// -/// # fn main() { -/// # struct Point { x: int, y: int } -/// # fn some_expensive_computation() -> Point { Point { x: 1, y: 2 } } -/// if log_enabled!(log::DEBUG) { -/// let x = some_expensive_computation(); -/// debug!("x.x = {}, x.y = {}", x.x, x.y); +/// struct Point { x: int, y: int } +/// fn some_expensive_computation() -> Point { Point { x: 1, y: 2 } } +/// +/// fn main() { +/// if log_enabled!(log::DEBUG) { +/// let x = some_expensive_computation(); +/// debug!("x.x = {}, x.y = {}", x.x, x.y); +/// } /// } -/// # } +/// ``` +/// +/// Assumes the binary is `main`: +/// +/// ```{.bash} +/// $ RUST_LOG=error ./main +/// ``` +/// +/// ```{.bash} +/// $ RUST_LOG=debug ./main +/// DEBUG:main: x.x = 1, x.y = 2 /// ``` #[macro_export] macro_rules! log_enabled( From 0a84308ebaaafb8fd89b2fd7c235198e3ec21384 Mon Sep 17 00:00:00 2001 From: Nick Howell Date: Fri, 29 Aug 2014 11:23:21 -0400 Subject: [PATCH 14/20] Fix spelling mistakes in the guide Also made some opinionated changes such as to prefer license over licence and judgment over judgement. --- src/doc/guide.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/doc/guide.md b/src/doc/guide.md index 8a634a083e8ad..40a31d0d9d459 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -297,7 +297,7 @@ $ mv hello_world.rs src/hello_world.rs ``` Cargo expects your source files to live inside a `src` directory. That leaves -the top level for other things, like READMEs, licence information, and anything +the top level for other things, like READMEs, license information, and anything not related to your code. Cargo helps us keep our projects nice and tidy. A place for everything, and everything in its place. @@ -1743,7 +1743,7 @@ fn main() { } ``` -Sometimes, this makes things more readable. Sometimes, less. Use your judgement +Sometimes, this makes things more readable. Sometimes, less. Use your judgment here. That's all you need to get basic input from the standard input! It's not too @@ -2659,7 +2659,7 @@ modules, which can contain other modules, as deeply as you'd like. Note that we haven't mentioned anything about files yet. Rust does not impose a particular relationship between your filesystem structure and your module structure. That said, there is a conventional approach to how Rust looks for -modules on the file system, but it's also overrideable. +modules on the file system, but it's also overridable. Enough talk, let's build something! Let's make a new project called `modules`. @@ -3511,7 +3511,7 @@ exporting the name again, somewhere else. We've now covered the basics of testing. Rust's tools are primitive, but they work well in the simple cases. There are some Rustaceans working on building -more complicated frameworks on top of all of this, but thery're just starting +more complicated frameworks on top of all of this, but they're just starting out. # Pointers @@ -5494,7 +5494,7 @@ fn main() { Whew! This isn't too terrible. You can see that we still `let x = 5i`, but then things get a little bit hairy. Three more bindings get set: a -static format string, an argument vector, and the aruments. We then +static format string, an argument vector, and the arguments. We then invoke the `println_args` function with the generated arguments. This is the code (well, the full version) that Rust actually compiles. You can From eb282371953cc9a5b53cd53848961c69d4905bfe Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Fri, 29 Aug 2014 15:35:51 -0400 Subject: [PATCH 15/20] desugar -> destructure wrong de- word. --- src/doc/guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/guide.md b/src/doc/guide.md index 8a634a083e8ad..52992952825ed 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -4063,7 +4063,7 @@ match x { } ``` -If you have a struct, you can desugar it inside of a pattern: +If you have a struct, you can destructure it inside of a pattern: ```{rust} struct Point { From d89b2a5c3d8a1c83bd96f45d9848ccaebf4c5ec5 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 30 Aug 2014 08:02:40 +0200 Subject: [PATCH 16/20] doc: make docs build Addresses this comment: https://github.com/rust-lang/rust/pull/16721#issuecomment-53946624 --- src/doc/guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/guide.md b/src/doc/guide.md index ced88e9db00d0..98ea24aa47860 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -2681,7 +2681,7 @@ $ cargo new modules --bin Let's double check our work by compiling: -```{bash,ignore} +```{bash,notrust} $ cargo run Compiling modules v0.0.1 (file:///home/you/projects/modules) Running `target/modules` From b79930eeb94ebc0422f919eab4fdf910d2d0fc3c Mon Sep 17 00:00:00 2001 From: Huon Wilson Date: Fri, 29 Aug 2014 18:03:13 +1000 Subject: [PATCH 17/20] Fix grammar of the accepted feature warning. --- src/librustc/front/feature_gate.rs | 2 +- src/test/compile-fail/gated-bad-feature.rs | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/librustc/front/feature_gate.rs b/src/librustc/front/feature_gate.rs index 931f0312f579c..ec680eaa49c94 100644 --- a/src/librustc/front/feature_gate.rs +++ b/src/librustc/front/feature_gate.rs @@ -403,7 +403,7 @@ pub fn check_crate(sess: &Session, krate: &ast::Crate) { sess.span_err(mi.span, "feature has been removed"); } Some(&(_, Accepted)) => { - sess.span_warn(mi.span, "feature has added to rust, \ + sess.span_warn(mi.span, "feature has been added to Rust, \ directive not necessary"); } None => { diff --git a/src/test/compile-fail/gated-bad-feature.rs b/src/test/compile-fail/gated-bad-feature.rs index 5a68afaceb93a..39cd3e3b86afe 100644 --- a/src/test/compile-fail/gated-bad-feature.rs +++ b/src/test/compile-fail/gated-bad-feature.rs @@ -20,4 +20,4 @@ #![feature = "foo"] //~ ERROR: malformed feature #![feature(test_removed_feature)] //~ ERROR: feature has been removed -#![feature(test_accepted_feature)] //~ WARNING: feature has added +#![feature(test_accepted_feature)] //~ WARNING: feature has been added From 02d96ac612bb176a0d3f53742ba969d403616407 Mon Sep 17 00:00:00 2001 From: Corey Richardson Date: Sat, 30 Aug 2014 12:39:52 -0400 Subject: [PATCH 18/20] guide: function -> closure in explanation of closures --- src/doc/guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/guide.md b/src/doc/guide.md index 8a634a083e8ad..c8f4968f7725a 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -4223,7 +4223,7 @@ don't need to declare one. This is different from named functions, which default to returning unit (`()`). There's one big difference between a closure and named functions, and it's in -the name: a function "closes over its environment." What's that mean? It means +the name: a closure "closes over its environment." What's that mean? It means this: ```{rust} From 7e4a1459e928791c3905ee4cb30813f222e4c8ca Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Thu, 28 Aug 2014 15:12:18 -0400 Subject: [PATCH 19/20] note about ref patterns in pointer guide Fixes #13602 --- src/doc/guide-pointers.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/src/doc/guide-pointers.md b/src/doc/guide-pointers.md index b196997b399c4..6492400a2cfc7 100644 --- a/src/doc/guide-pointers.md +++ b/src/doc/guide-pointers.md @@ -729,6 +729,31 @@ This part is coming soon. This part is coming soon. +# Patterns and `ref` + +When you're trying to match something that's stored in a pointer, there may be +a situation where matching directly isn't the best option available. Let's see +how to properly handle this: + +```{rust,ignore} +fn possibly_print(x: &Option) { + match *x { + // BAD: cannot move out of a `&` + Some(s) => println!("{}", s) + + // GOOD: instead take a reference into the memory of the `Option` + Some(ref s) => println!("{}", *s), + None => {} + } +} +``` + +The `ref s` here means that `s` will be of type `&String`, rather than type +`String`. + +This is important when the type you're trying to get access to has a destructor +and you don't want to move it, you just want a reference to it. + # Cheat Sheet Here's a quick rundown of Rust's pointer types: From ea888edf631d82f4a8fcdcc83c85ddb5e2b9cef4 Mon Sep 17 00:00:00 2001 From: nham Date: Wed, 27 Aug 2014 20:02:59 -0400 Subject: [PATCH 20/20] doc: Add another restriction to the list of ownership rules. --- src/doc/guide.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/src/doc/guide.md b/src/doc/guide.md index 8a634a083e8ad..5dedcde214cab 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -3668,15 +3668,20 @@ because it's easy. And if you need precise control over when something is deallocated, leaving it up to your runtime can make this difficult. Rust chooses a different path, and that path is called **ownership**. Any -binding that creates a resource is the **owner** of that resource. Being an -owner gives you three privileges, with two restrictions: +binding that creates a resource is the **owner** of that resource. + +Being an owner affords you some privileges: 1. You control when that resource is deallocated. 2. You may lend that resource, immutably, to as many borrowers as you'd like. -3. You may lend that resource, mutably, to a single borrower. **BUT** -4. Once you've done so, you may not also lend it out otherwise, mutably or - immutably. -5. You may not lend it out mutably if you're currently lending it to someone. +3. You may lend that resource, mutably, to a single borrower. + +But it also comes with some restrictions: + +1. If someone is borrowing your resource (either mutably or immutably), you may + not mutate the resource or mutably lend it to someone. +2. If someone is mutably borrowing your resource, you may not lend it out at + all (mutably or immutably) or access it in any way. What's up with all this 'lending' and 'borrowing'? When you allocate memory, you get a pointer to that memory. This pointer allows you to manipulate said