---

yaml
---
r: 30711
b: refs/heads/incoming
c: 690525e
h: refs/heads/master
i:
  30709: 1109af9
  30707: 9cfe9df
  30703: 537d31e
v: v3

Author: brson

[refs]

@@ -6,7 +6,7 @@ refs/heads/try: d324a424d8f84b1eb049b12cf34182bda91b0024
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b
 refs/heads/try2: d0c6ce338884ee21843f4b40bf6bf18d222ce5df
-refs/heads/incoming: 2d3396bef191e06568ecbb7c7dd55667db1d8809
+refs/heads/incoming: 690525ed814d3a60560188d7d76e2727d6f22347
 refs/heads/dist-snap: 2f32a1581f522e524009138b33b1c7049ced668d
 refs/tags/release-0.2: c870d2dffb391e14efb05aa27898f1f6333a9596
 refs/tags/release-0.3: b5f0d0f648d9a6153664837026ba1be43d3e2503

branches/incoming/doc/tutorial.md

@@ -918,9 +918,9 @@ garbage-collected heap to manage all of the objects. This approach is
 straightforward both in concept and in implementation, but has
 significant costs. Languages that take this approach tend to
 aggressively pursue ways to ameliorate allocation costs (think the
-Java Virtual Machine). Rust supports this strategy with _shared
-boxes_: memory allocated on the heap that may be referred to (shared)
-by multiple variables.
+Java Virtual Machine). Rust supports this strategy with _managed
+boxes_: memory allocated on the heap whose lifetime is managed
+by the garbage collector.
 
 By comparison, languages like C++ offer very precise control over
 where objects are allocated. In particular, it is common to put them
@@ -950,16 +950,16 @@ inefficient for large data structures.  Because of this, Rust also
 employs a global _exchange heap_. Objects allocated in the exchange
 heap have _ownership semantics_, meaning that there is only a single
 variable that refers to them. For this reason, they are referred to as
-_unique boxes_. All tasks may allocate objects on the exchange heap,
+_owned boxes_. All tasks may allocate objects on the exchange heap,
 then transfer ownership of those objects to other tasks, avoiding
 expensive copies.
 
 ## What to be aware of
 
 Rust has three "realms" in which objects can be allocated: the stack,
 the local heap, and the exchange heap. These realms have corresponding
-pointer types: the borrowed pointer (`&T`), the shared box (`@T`),
-and the unique box (`~T`). These three sigils will appear
+pointer types: the borrowed pointer (`&T`), the managed box (`@T`),
+and the owned box (`~T`). These three sigils will appear
 repeatedly as we explore the language. Learning the appropriate role
 of each is key to using Rust effectively.
 
@@ -978,17 +978,22 @@ records with mutable fields, it can be useful to have a single copy on
 the heap, and refer to that through a pointer.
 
 Rust supports several types of pointers. The safe pointer types are
-`@T` for shared boxes allocated on the local heap, `~T`, for
+`@T` for managed boxes allocated on the local heap, `~T`, for
 uniquely-owned boxes allocated on the exchange heap, and `&T`, for
 borrowed pointers, which may point to any memory, and whose lifetimes
 are governed by the call stack.
 
 All pointer types can be dereferenced with the `*` unary operator.
 
-## Shared boxes
+> ***Note***: You may also hear managed boxes referred to as 'shared
+> boxes' or 'shared pointers', and owned boxes as 'unique boxes/pointers'.
+> Borrowed pointers are sometimes called 'region pointers'. The preferred
+> terminology is as presented here.
 
-Shared boxes are pointers to heap-allocated, garbage collected memory.
-Creating a shared box is done by simply applying the unary `@`
+## Managed boxes
+
+Managed boxes are pointers to heap-allocated, garbage collected memory.
+Creating a managed box is done by simply applying the unary `@`
 operator to an expression. The result of the expression will be boxed,
 resulting in a box of the right type. Copying a shared box, as happens
 during assignment, only copies a pointer, never the contents of the
@@ -1000,22 +1005,24 @@ let y = x; // Copy the pointer, increase refcount
 // When x and y go out of scope, refcount goes to 0, box is freed
 ~~~~
 
-Shared boxes never cross task boundaries.
+Managed boxes never cross task boundaries.
 
-> ***Note:*** shared boxes are currently reclaimed through reference
+> ***Note:*** managed boxes are currently reclaimed through reference
 > counting and cycle collection, but we will switch to a tracing
-> garbage collector.
+> garbage collector eventually.
 
-## Unique boxes
+## Owned boxes
 
-In contrast to shared boxes, unique boxes have a single owner and thus
-two unique boxes may not refer to the same memory. All unique boxes
-across all tasks are allocated on a single _exchange heap_, where
-their uniquely owned nature allows them to be passed between tasks.
+In contrast to maneged boxes, owned boxes have a single owning memory
+slot and thus two owned boxes may not refer to the same memory. All
+owned boxes across all tasks are allocated on a single _exchange
+heap_, where their uniquely owned nature allows them to be passed
+between tasks.
 
-Because unique boxes are uniquely owned, copying them involves allocating
-a new unique box and duplicating the contents. Copying unique boxes
-is expensive so the compiler will complain if you do.
+Because owned boxes are uniquely owned, copying them involves allocating
+a new owned box and duplicating the contents. Copying owned boxes
+is expensive so the compiler will complain if you do so without writing
+the word `copy`.
 
 ~~~~
 let x = ~10;
@@ -1029,23 +1036,23 @@ let x = ~10;
 let y = copy x;
 ~~~~
 
-This is where the 'move' (`<-`) operator comes in. It is similar to
-`=`, but it de-initializes its source. Thus, the unique box can move
+This is where the 'move' operator comes in. It is similar to
+`copy`, but it de-initializes its source. Thus, the owned box can move
 from `x` to `y`, without violating the constraint that it only has a
 single owner (if you used assignment instead of the move operator, the
 box would, in principle, be copied).
 
 ~~~~
 let x = ~10;
-let y <- x;
+let y = move x;
 ~~~~
 
 > ***Note:*** this discussion of copying vs moving does not account
 > for the "last use" rules that automatically promote copy operations
 > to moves. This is an evolving area of the language that will
 > continue to change.
 
-Unique boxes, when they do not contain any shared boxes, can be sent
+Owned boxes, when they do not contain any managed boxes, can be sent
 to other tasks. The sending task will give up ownership of the box,
 and won't be able to access it afterwards. The receiving task will
 become the sole owner of the box.
@@ -1054,7 +1061,7 @@ become the sole owner of the box.
 
 Rust borrowed pointers are a general purpose reference/pointer type,
 similar to the C++ reference type, but guaranteed to point to valid
-memory. In contrast to unique pointers, where the holder of a unique
+memory. In contrast to owned pointers, where the holder of a unique
 pointer is the owner of the pointed-to memory, borrowed pointers never
 imply ownership. Pointers may be borrowed from any type, in which case
 the pointer is guaranteed not to outlive the value it points to.
@@ -1095,11 +1102,12 @@ fn increase_contents(pt: @mut int) {
 }
 ~~~~
 
-# Vectors
+# Vectors and strings
 
 Vectors are a contiguous section of memory containing zero or more
 values of the same type. Like other types in Rust, vectors can be
-stored on the stack, the local heap, or the exchange heap.
+stored on the stack, the local heap, or the exchange heap. Borrowed
+pointers to vectors are also called 'slices'.
 
 ~~~
 enum Crayon {
@@ -1108,24 +1116,19 @@ enum Crayon {
     BananaMania, Beaver, Bittersweet
 }
 
-// A stack vector of crayons
+// A fixed-size stack vector
+let stack_crayons: [Crayon * 3] = [Almond, AntiqueBrass, Apricot];
+
+// A borrowed pointer to stack allocated vector
 let stack_crayons: &[Crayon] = &[Almond, AntiqueBrass, Apricot];
-// A local heap (shared) vector of crayons
+
+// A local heap (managed) vector of crayons
 let local_crayons: @[Crayon] = @[Aquamarine, Asparagus, AtomicTangerine];
-// An exchange heap (unique) vector of crayons
+
+// An exchange heap (owned) vector of crayons
 let exchange_crayons: ~[Crayon] = ~[BananaMania, Beaver, Bittersweet];
 ~~~
 
-> ***Note:*** Until recently Rust only had unique vectors, using the
-> unadorned `[]` syntax for literals. This syntax is still supported
-> but is deprecated. In the future it will probably represent some
-> "reasonable default" vector type.
->
-> Unique vectors are the currently-recommended vector type for general
-> use as they are the most tested and well-supported by existing
-> libraries. There will be a gradual shift toward using more
-> stack and local vectors in the coming releases.
-
 Vector literals are enclosed in square brackets and dereferencing is
 also done with square brackets (zero-based):
 
@@ -1135,24 +1138,24 @@ also done with square brackets (zero-based):
 #               BananaMania, Beaver, Bittersweet };
 # fn draw_scene(c: Crayon) { }
 
-let crayons = ~[BananaMania, Beaver, Bittersweet];
+let crayons = [BananaMania, Beaver, Bittersweet];
 match crayons[0] {
     Bittersweet => draw_scene(crayons[0]),
     _ => ()
 }
 ~~~~
 
 By default, vectors are immutable—you can not replace their elements.
-The type written as `~[mut T]` is a vector with mutable
-elements. Mutable vector literals are written `~[mut]` (empty) or `~[mut
+The type written as `[mut T]` is a vector with mutable
+elements. Mutable vector literals are written `[mut]` (empty) or `[mut
 1, 2, 3]` (with elements).
 
 ~~~~
 # enum Crayon { Almond, AntiqueBrass, Apricot,
 #               Aquamarine, Asparagus, AtomicTangerine,
 #               BananaMania, Beaver, Bittersweet };
 
-let crayons = ~[mut BananaMania, Beaver, Bittersweet];
+let crayons = [mut BananaMania, Beaver, Bittersweet];
 crayons[0] = AtomicTangerine;
 ~~~~
 
@@ -1183,7 +1186,30 @@ let your_crayons = ~[BananaMania, Beaver, Bittersweet];
 my_crayons += your_crayons;
 ~~~~
 
-## Vector and string methods
+> ***Note:*** The above examples of vector addition use owned
+> vectors. Some operations on slices and stack vectors are
+> not well supported yet, owned vectors are often the most
+> usable.
+
+Strings are simply vectors of `[u8]`, though they have a distinct
+type. They support most of the same allocation aptions as
+vectors, though the string literal without a storage sigil, e.g.
+`"foo"` is treated differently than a comparable vector (`[foo]`).
+Where
+
+~~~
+// A plain string is a slice to read-only (static) memory
+let stack_crayons: &str = "Almond, AntiqueBrass, Apricot";
+
+// The same thing, but without
+let stack_crayons: &str = &"Almond, AntiqueBrass, Apricot";
+
+// A local heap (managed) string
+let local_crayons: @str = @"Aquamarine, Asparagus, AtomicTangerine";
+
+// An exchange heap (owned) string
+let exchange_crayons: ~str = ~"BananaMania, Beaver, Bittersweet";
+~~~
 
 Both vectors and strings support a number of useful
 [methods](#implementation).  While we haven't covered methods yet,
@@ -1202,7 +1228,7 @@ brief look at a few common ones.
 # fn store_crayon_in_nasal_cavity(i: uint, c: Crayon) { }
 # fn crayon_to_str(c: Crayon) -> ~str { ~"" }
 
-let crayons = ~[Almond, AntiqueBrass, Apricot];
+let crayons = &[Almond, AntiqueBrass, Apricot];
 
 // Check the length of the vector
 assert crayons.len() == 3;
@@ -1282,15 +1308,15 @@ position and cannot be stored in structures nor returned from
 functions. Despite the limitations stack closures are used
 pervasively in Rust code.
 
-## Shared closures
+## Managed closures
 
 When you need to store a closure in a data structure, a stack closure
 will not do, since the compiler will refuse to let you store it. For
 this purpose, Rust provides a type of closure that has an arbitrary
 lifetime, written `fn@` (boxed closure, analogous to the `@` pointer
 type described earlier).
 
-A boxed closure does not directly access its environment, but merely
+A managed closure does not directly access its environment, but merely
 copies out the values that it closes over into a private data
 structure. This means that it can not assign to these variables, and
 will not 'see' updates to them.
@@ -1315,7 +1341,7 @@ This example uses the long closure syntax, `fn@(s: ~str) ...`,
 making the fact that we are declaring a box closure explicit. In
 practice boxed closures are usually defined with the short closure
 syntax introduced earlier, in which case the compiler will infer
-the type of closure. Thus our boxed closure example could also
+the type of closure. Thus our managed closure example could also
 be written:
 
 ~~~~
@@ -1324,13 +1350,13 @@ fn mk_appender(suffix: ~str) -> fn@(~str) -> ~str {
 }
 ~~~~
 
-## Unique closures
+## Owned closures
 
-Unique closures, written `fn~` in analogy to the `~` pointer type,
+Owned closures, written `fn~` in analogy to the `~` pointer type,
 hold on to things that can safely be sent between
-processes. They copy the values they close over, much like boxed
+processes. They copy the values they close over, much like managed
 closures, but they also 'own' them—meaning no other code can access
-them. Unique closures are used in concurrent code, particularly
+them. Owned closures are used in concurrent code, particularly
 for spawning [tasks](#tasks).
 
 ## Closure compatibility
@@ -1346,12 +1372,16 @@ that callers have the flexibility to pass whatever they want.
 fn call_twice(f: fn()) { f(); f(); }
 call_twice(|| { ~"I am an inferred stack closure"; } );
 call_twice(fn&() { ~"I am also a stack closure"; } );
-call_twice(fn@() { ~"I am a boxed closure"; });
-call_twice(fn~() { ~"I am a unique closure"; });
+call_twice(fn@() { ~"I am a managed closure"; });
+call_twice(fn~() { ~"I am a owned closure"; });
 fn bare_function() { ~"I am a plain function"; }
 call_twice(bare_function);
 ~~~~
 
+> ***Note:*** Both the syntax and the semantics will be changing
+> in small ways. At the moment they can be unsound in multiple
+> scenarios, particularly with non-copyable types.
+
 ## Do syntax
 
 Closures in Rust are frequently used in combination with higher-order
@@ -1360,7 +1390,7 @@ functions to simulate control structures like `if` and
 integers, passing in a pointer to each integer in the vector:
 
 ~~~~
-fn each(v: ~[int], op: fn(v: &int)) {
+fn each(v: &[int], op: fn(v: &int)) {
    let mut n = 0;
    while n < v.len() {
        op(&v[n]);
@@ -1378,9 +1408,9 @@ closure to provide the final operator argument, we can write it in a
 way that has a pleasant, block-like structure.
 
 ~~~~
-# fn each(v: ~[int], op: fn(v: &int)) { }
+# fn each(v: &[int], op: fn(v: &int)) { }
 # fn do_some_work(i: int) { }
-each(~[1, 2, 3], |n| {
+each(&[1, 2, 3], |n| {
     debug!("%i", *n);
     do_some_work(*n);
 });
@@ -1390,9 +1420,9 @@ This is such a useful pattern that Rust has a special form of function
 call that can be written more like a built-in control structure:
 
 ~~~~
-# fn each(v: ~[int], op: fn(v: &int)) { }
+# fn each(v: &[int], op: fn(v: &int)) { }
 # fn do_some_work(i: int) { }
-do each(~[1, 2, 3]) |n| {
+do each(&[1, 2, 3]) |n| {
     debug!("%i", *n);
     do_some_work(*n);
 }
@@ -1438,7 +1468,7 @@ Consider again our `each` function, this time improved to
 break early when the iteratee returns `false`:
 
 ~~~~
-fn each(v: ~[int], op: fn(v: &int) -> bool) {
+fn each(v: &[int], op: fn(v: &int) -> bool) {
    let mut n = 0;
    while n < v.len() {
        if !op(&v[n]) {
@@ -1454,7 +1484,7 @@ And using this function to iterate over a vector:
 ~~~~
 # use each = vec::each;
 # use println = io::println;
-each(~[2, 4, 8, 5, 16], |n| {
+each(&[2, 4, 8, 5, 16], |n| {
     if *n % 2 != 0 {
         println(~"found odd number!");
         false
@@ -1471,7 +1501,7 @@ to the next iteration, write `again`.
 ~~~~
 # use each = vec::each;
 # use println = io::println;
-for each(~[2, 4, 8, 5, 16]) |n| {
+for each(&[2, 4, 8, 5, 16]) |n| {
     if *n % 2 != 0 {
         println(~"found odd number!");
         break;
@@ -1486,7 +1516,7 @@ function, not just the loop body.
 
 ~~~~
 # use each = vec::each;
-fn contains(v: ~[int], elt: int) -> bool {
+fn contains(v: &[int], elt: int) -> bool {
     for each(v) |x| {
         if (*x == elt) { return true; }
     }