---

yaml
---
r: 139450
b: refs/heads/try2
c: 85ed840
h: refs/heads/master
v: v3

Author: thestinger

[refs]

@@ -5,7 +5,7 @@ refs/heads/snap-stage3: 78a7676898d9f80ab540c6df5d4c9ce35bb50463
 refs/heads/try: 519addf6277dbafccbb4159db4b710c37eaa2ec5
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b
-refs/heads/try2: 777ad8b20452d94111f9c834d0f277575a564ca3
+refs/heads/try2: 85ed840e234184b7975d9ee7b022c0ca2cb5d8ff
 refs/heads/dist-snap: ba4081a5a8573875fed17545846f6f6902c8ba8d
 refs/tags/release-0.2: c870d2dffb391e14efb05aa27898f1f6333a9596
 refs/tags/release-0.3: b5f0d0f648d9a6153664837026ba1be43d3e2503

branches/try2/doc/tutorial.md

@@ -1002,11 +1002,46 @@ refer to that through a pointer.
 
 ## Owned boxes
 
-An owned box (`~`) is a uniquely owned allocation on the heap. An owned box
-inherits the mutability and lifetime of the owner as it would if there was no
-box. The purpose of an owned box is to add a layer of indirection in order to
-create recursive data structures or cheaply pass around an object larger than a
-pointer.
+An owned box (`~`) is a uniquely owned allocation on the heap. It inherits the
+mutability and lifetime of the owner as it would if there was no box.
+
+~~~~
+let x = 5; // immutable
+let mut y = 5; // mutable
+y += 2;
+
+let x = ~5; // immutable
+let mut y = ~5; // mutable
+*y += 2; // the * operator is needed to access the contained value
+~~~~
+
+The purpose of an owned box is to add a layer of indirection in order to create
+recursive data structures or cheaply pass around an object larger than a
+pointer. Since an owned box has a unique owner, it can be used to represent any
+tree data structure.
+
+The following struct won't compile, because the lack of indirection would mean
+it has an infinite size:
+
+~~~~ {.xfail-test}
+struct Foo {
+    child: Option<Foo>
+}
+~~~~
+
+> ***Note:*** The `Option` type is an enum that represents an *optional* value.
+> It's comparable to a nullable pointer in many other languages, but stores the
+> contained value unboxed.
+
+Adding indirection with an owned pointer allocates the child outside of the
+struct on the heap, which makes it a finite size and won't result in a
+compile-time error:
+
+~~~~
+struct Foo {
+    child: Option<~Foo>
+}
+~~~~
 
 ## Managed boxes