---

yaml
---
r: 97528
b: refs/heads/snap-stage3
c: 7cfce50
h: refs/heads/master
v: v3

Author: huonw

[refs]

@@ -1,7 +1,7 @@
 ---
 refs/heads/master: 0da105a8b7b6b1e0568e8ff20f6ff4b13cc7ecc2
 refs/heads/snap-stage1: e33de59e47c5076a89eadeb38f4934f58a3618a6
-refs/heads/snap-stage3: 2d8dd6afd4ef36742b4e8a4e848e13ddbe275fe8
+refs/heads/snap-stage3: 7cfce50b24cecaa04fae94cbc06ef97a0a9f3958
 refs/heads/try: c274a6888410ce3e357e014568b43310ed787d36
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b

branches/snap-stage3/doc/guide-pointers.md

@@ -3,7 +3,7 @@
 Rust's pointers are one of its more unique and compelling features. Pointers
 are also one of the more confusing topics for newcomers to Rust. They can also
 be confusing for people coming from other languages that support pointers, such
-as C++. This tutorial will help you understand this important topic.
+as C++. This guide will help you understand this important topic.
 
 # You don't actually need pointers
 
@@ -13,8 +13,7 @@ that emphasizes safety. Pointers, as the joke goes, are very pointy: it's easy
 to accidentally stab yourself. Therefore, Rust is made in a way such that you
 don't need them very often.
 
-"But tutorial!" you may cry. "My co-worker wrote a function that looks like
-this:
+"But guide!" you may cry. "My co-worker wrote a function that looks like this:
 
 ~~~rust
 fn succ(x: &int) -> int { *x + 1 }
@@ -250,6 +249,12 @@ struct.
 
 # Managed Pointers
 
+> **Note**: the `@` form of managed pointers is deprecated and behind a
+> feature gate (it requires a `#[feature(managed_pointers)];` attribute on
+> the crate root; remember the semicolon!). There are replacements, currently 
+> there is `std::rc::Rc` and `std::gc::Gc` for shared ownership via reference
+> counting and garbage collection respectively.
+
 Managed pointers, notated by an `@`, are used when having a single owner for
 some data isn't convenient or possible. This generally happens when your
 program is very large and complicated.
@@ -375,12 +380,12 @@ duration a 'lifetime'. Let's try a more complex example:
 ~~~rust
 fn main() {
     let mut x = ~5;
-    if(*x < 10) {
+    if *x < 10 {
         let y = &x;
         println!("Oh no: {:?}", y);
         return;
     }
-    *x = *x - 1;
+    *x -= 1;
     println!("Oh no: {:?}", x);
 }
 ~~~
@@ -392,14 +397,14 @@ mutated, and therefore, lets us pass. This wouldn't work:
 ~~~rust {.xfail-test}
 fn main() {
     let mut x = ~5;
-    if(*x < 10) {
+    if *x < 10 {
         let y = &x;
-        *x = *x - 1;
+        *x -= 1;
 
         println!("Oh no: {:?}", y);
         return;
     }
-    *x = *x - 1;
+    *x -= 1;
     println!("Oh no: {:?}", x);
 }
 ~~~
@@ -408,7 +413,7 @@ It gives this error:
 
 ~~~ {.notrust}
 test.rs:5:8: 5:10 error: cannot assign to `*x` because it is borrowed
-test.rs:5         *x = *x - 1;
+test.rs:5         *x -= 1;
                   ^~
 test.rs:4:16: 4:18 note: borrow of `*x` occurs here
 test.rs:4         let y = &x;
@@ -469,8 +474,9 @@ fn main() {
 You may think that this gives us terrible performance: return a value and then
 immediately box it up?!?! Isn't that the worst of both worlds? Rust is smarter
 than that. There is no copy in this code. `main` allocates enough room for the
-`@int`, passes it into `foo` as `x`, and then `foo` writes the value into the
-new box. This writes the return value directly into the allocated box.
+`@int`, passes a pointer to that memory into `foo` as `x`, and then `foo` writes 
+the value straight into that pointer. This writes the return value directly into
+the allocated box.
 
 This is important enough that it bears repeating: pointers are not for optimizing
 returning values from your code. Allow the caller to choose how they want to
@@ -479,4 +485,4 @@ use your output.
 
 # Related Resources
 
-* [Lifetimes tutorial](tutorial-lifetimes.html)
+* [Lifetimes guide](guide-lifetimes.html)