auto merge of #13958 : pcwalton/rust/detilde, r=pcwalton

for `~str`/`~[]`.

Note that `~self` still remains, since I forgot to add support for
`Box<self>` before the snapshot.

r? @brson or @alexcrichton or whoever

Author: bors

src/doc/guide-ffi.md

@@ -285,7 +285,7 @@ extern {
 
 fn main() {
     // Create the object that will be referenced in the callback
-    let mut rust_object = ~RustObject{ a: 5 };
+    let mut rust_object = box RustObject { a: 5 };
 
     unsafe {
         register_callback(&mut *rust_object, callback);

src/doc/guide-lifetimes.md

@@ -41,9 +41,9 @@ point, but allocated in a different place:
 
 ~~~
 # struct Point {x: f64, y: f64}
-let on_the_stack :  Point =  Point {x: 3.0, y: 4.0};
-let managed_box  : @Point = @Point {x: 5.0, y: 1.0};
-let owned_box    : ~Point = ~Point {x: 7.0, y: 9.0};
+let on_the_stack :  Point     =     Point {x: 3.0, y: 4.0};
+let managed_box  : @Point     =    @Point {x: 5.0, y: 1.0};
+let owned_box    : Box<Point> = box Point {x: 7.0, y: 9.0};
 ~~~
 
 Suppose we wanted to write a procedure that computed the distance between any
@@ -72,9 +72,9 @@ Now we can call `compute_distance()` in various ways:
 
 ~~~
 # struct Point {x: f64, y: f64}
-# let on_the_stack :  Point =  Point{x: 3.0, y: 4.0};
-# let managed_box  : @Point = @Point{x: 5.0, y: 1.0};
-# let owned_box    : ~Point = ~Point{x: 7.0, y: 9.0};
+# let on_the_stack :     Point  =     Point{x: 3.0, y: 4.0};
+# let managed_box  :    @Point  =    @Point{x: 5.0, y: 1.0};
+# let owned_box    : Box<Point> = box Point{x: 7.0, y: 9.0};
 # fn compute_distance(p1: &Point, p2: &Point) -> f64 { 0.0 }
 compute_distance(&on_the_stack, managed_box);
 compute_distance(managed_box, owned_box);
@@ -151,12 +151,12 @@ Now, as before, we can define rectangles in a few different ways:
 # struct Point {x: f64, y: f64}
 # struct Size {w: f64, h: f64} // as before
 # struct Rectangle {origin: Point, size: Size}
-let rect_stack   = &Rectangle {origin: Point {x: 1.0, y: 2.0},
-                               size: Size {w: 3.0, h: 4.0}};
-let rect_managed = @Rectangle {origin: Point {x: 3.0, y: 4.0},
-                               size: Size {w: 3.0, h: 4.0}};
-let rect_owned   = ~Rectangle {origin: Point {x: 5.0, y: 6.0},
-                               size: Size {w: 3.0, h: 4.0}};
+let rect_stack   =    &Rectangle {origin: Point {x: 1.0, y: 2.0},
+                                  size: Size {w: 3.0, h: 4.0}};
+let rect_managed =    @Rectangle {origin: Point {x: 3.0, y: 4.0},
+                                  size: Size {w: 3.0, h: 4.0}};
+let rect_owned   = box Rectangle {origin: Point {x: 5.0, y: 6.0},
+                                  size: Size {w: 3.0, h: 4.0}};
 ~~~
 
 In each case, we can extract out individual subcomponents with the `&`
@@ -168,7 +168,7 @@ operator. For example, I could write:
 # struct Rectangle {origin: Point, size: Size}
 # let rect_stack  = &Rectangle {origin: Point {x: 1.0, y: 2.0}, size: Size {w: 3.0, h: 4.0}};
 # let rect_managed = @Rectangle {origin: Point {x: 3.0, y: 4.0}, size: Size {w: 3.0, h: 4.0}};
-# let rect_owned = ~Rectangle {origin: Point {x: 5.0, y: 6.0}, size: Size {w: 3.0, h: 4.0}};
+# let rect_owned = box Rectangle {origin: Point {x: 5.0, y: 6.0}, size: Size {w: 3.0, h: 4.0}};
 # fn compute_distance(p1: &Point, p2: &Point) -> f64 { 0.0 }
 compute_distance(&rect_stack.origin, &rect_managed.origin);
 ~~~
@@ -276,12 +276,12 @@ the following function is legal:
 # fn some_condition() -> bool { true }
 # struct Foo { f: int }
 fn example3() -> int {
-    let mut x = ~Foo {f: 3};
+    let mut x = box Foo {f: 3};
     if some_condition() {
         let y = &x.f;      // -+ L
         return *y;         //  |
     }                      // -+
-    x = ~Foo {f: 4};
+    x = box Foo {f: 4};
     // ...
 # return 0;
 }
@@ -301,9 +301,9 @@ rejected by the compiler):
 
 ~~~ {.ignore}
 fn example3() -> int {
-    let mut x = ~X {f: 3};
+    let mut x = box X {f: 3};
     let y = &x.f;
-    x = ~X {f: 4};  // Error reported here.
+    x = box X {f: 4};  // Error reported here.
     *y
 }
 ~~~
@@ -314,27 +314,27 @@ memory immediately before the re-assignment of `x`:
 ~~~ {.notrust}
     Stack               Exchange Heap
 
-  x +----------+
-    | ~{f:int} | ----+
-  y +----------+     |
-    | &int     | ----+
-    +----------+     |    +---------+
-                     +--> |  f: 3   |
-                          +---------+
+  x +-------------+
+    | box {f:int} | ----+
+  y +-------------+     |
+    | &int        | ----+
+    +-------------+     |    +---------+
+                        +--> |  f: 3   |
+                             +---------+
 ~~~
 
 Once the reassignment occurs, the memory will look like this:
 
 ~~~ {.notrust}
     Stack               Exchange Heap
 
-  x +----------+          +---------+
-    | ~{f:int} | -------> |  f: 4   |
-  y +----------+          +---------+
-    | &int     | ----+
-    +----------+     |    +---------+
-                     +--> | (freed) |
-                          +---------+
+  x +-------------+          +---------+
+    | box {f:int} | -------> |  f: 4   |
+  y +-------------+          +---------+
+    | &int        | ----+
+    +-------------+     |    +---------+
+                        +--> | (freed) |
+                             +---------+
 ~~~
 
 Here you can see that the variable `y` still points at the old box,
@@ -349,12 +349,12 @@ mutations:
 ~~~ {.ignore}
 fn example3() -> int {
     struct R { g: int }
-    struct S { f: ~R }
+    struct S { f: Box<R> }
 
-    let mut x = ~S {f: ~R {g: 3}};
+    let mut x = box S {f: box R {g: 3}};
     let y = &x.f.g;
-    x = ~S {f: ~R {g: 4}};  // Error reported here.
-    x.f = ~R {g: 5};        // Error reported here.
+    x = box S {f: box R {g: 4}};  // Error reported here.
+    x.f = box R {g: 5};           // Error reported here.
     *y
 }
 ~~~

src/doc/guide-pointers.md

@@ -182,21 +182,22 @@ trait. Therefore, unboxed traits don't make any sense, and aren't allowed.
 Sometimes, you need a recursive data structure. The simplest is known as a 'cons list':
 
 ~~~rust
+
 enum List<T> {
     Nil,
-    Cons(T, ~List<T>),
+    Cons(T, Box<List<T>>),
 }
 
 fn main() {
-    let list: List<int> = Cons(1, ~Cons(2, ~Cons(3, ~Nil)));
+    let list: List<int> = Cons(1, box Cons(2, box Cons(3, box Nil)));
     println!("{:?}", list);
 }
 ~~~
 
 This prints:
 
 ~~~ {.notrust}
-Cons(1, ~Cons(2, ~Cons(3, ~Nil)))
+Cons(1, box Cons(2, box Cons(3, box Nil)))
 ~~~
 
 The inner lists _must_ be an owned pointer, because we can't know how many
@@ -237,7 +238,7 @@ struct Point {
 }
 
 fn main() {
-    let a = ~Point { x: 10, y: 20 };
+    let a = box Point { x: 10, y: 20 };
     spawn(proc() {
         println!("{}", a.x);
     });
@@ -268,7 +269,7 @@ struct Point {
 }
 
 fn main() {
-    let a = ~Point { x: 10, y: 20 };
+    let a = box Point { x: 10, y: 20 };
     let b = a;
     println!("{}", b.x);
     println!("{}", a.x);
@@ -285,7 +286,7 @@ note: in expansion of format_args!
 <std-macros>:158:27: 158:81 note: expansion site
 <std-macros>:157:5: 159:6 note: in expansion of println!
 test.rs:10:5: 10:25 note: expansion site
-test.rs:8:9: 8:10 note: `a` moved here because it has type `~Point`, which is moved by default (use `ref` to override)
+test.rs:8:9: 8:10 note: `a` moved here because it has type `Box<Point>`, which is moved by default (use `ref` to override)
 test.rs:8     let b = a;
                   ^
 ~~~
@@ -345,8 +346,8 @@ fn compute_distance(p1: &Point, p2: &Point) -> f32 {
 }
 
 fn main() {
-    let origin = @Point { x: 0.0, y: 0.0 };
-    let p1     = ~Point { x: 5.0, y: 3.0 };
+    let origin =    @Point { x: 0.0, y: 0.0 };
+    let p1     = box Point { x: 5.0, y: 3.0 };
 
     println!("{:?}", compute_distance(origin, p1));
 }
@@ -381,7 +382,7 @@ duration a 'lifetime'. Let's try a more complex example:
 
 ~~~rust
 fn main() {
-    let mut x = ~5;
+    let mut x = box 5;
     if *x < 10 {
         let y = &x;
         println!("Oh no: {:?}", y);
@@ -398,7 +399,7 @@ mutated, and therefore, lets us pass. This wouldn't work:
 
 ~~~rust{.ignore}
 fn main() {
-    let mut x = ~5;
+    let mut x = box 5;
     if *x < 10 {
         let y = &x;
         *x -= 1;
@@ -437,39 +438,39 @@ is best.
 What does that mean? Don't do this:
 
 ~~~rust
-fn foo(x: ~int) -> ~int {
-    return ~*x;
+fn foo(x: Box<int>) -> Box<int> {
+    return box *x;
 }
 
 fn main() {
-    let x = ~5;
+    let x = box 5;
     let y = foo(x);
 }
 ~~~
 
 Do this:
 
 ~~~rust
-fn foo(x: ~int) -> int {
+fn foo(x: Box<int>) -> int {
     return *x;
 }
 
 fn main() {
-    let x = ~5;
-    let y = ~foo(x);
+    let x = box 5;
+    let y = box foo(x);
 }
 ~~~
 
 This gives you flexibility, without sacrificing performance. For example, this will
 also work:
 
 ~~~rust
-fn foo(x: ~int) -> int {
+fn foo(x: Box<int>) -> int {
     return *x;
 }
 
 fn main() {
-    let x = ~5;
+    let x = box 5;
     let y = @foo(x);
 }
 ~~~

src/doc/guide-unsafe.md

@@ -258,10 +258,10 @@ impl<T: Send> Drop for Unique<T> {
     }
 }
 
-// A comparison between the built-in ~ and this reimplementation
+// A comparison between the built-in `Box` and this reimplementation
 fn main() {
     {
-        let mut x = ~5;
+        let mut x = box 5;
         *x = 10;
     } // `x` is freed here
 

src/doc/intro.md

@@ -127,12 +127,13 @@ That's a great example for stack memory,
 but what about heap memory?
 Rust has a second kind of pointer,
 an 'owned box',
-that you can create with a `~`.
+that you can create with the `box` operator.
 Check it out:
 
 ```
-fn dangling() -> ~int {
-    let i = ~1234;
+
+fn dangling() -> Box<int> {
+    let i = box 1234;
     return i;
 }
 
@@ -143,15 +144,15 @@ fn add_one() -> int {
 ```
 
 Now instead of a stack allocated `1234`,
-we have a heap allocated `~1234`.
+we have a heap allocated `box 1234`.
 Whereas `&` borrows a pointer to existing memory,
 creating an owned box allocates memory on the heap and places a value in it,
 giving you the sole pointer to that memory.
 You can roughly compare these two lines:
 
 ```
 // Rust
-let i = ~1234;
+let i = box 1234;
 ```
 
 ```notrust