---

yaml
---
r: 35803
b: refs/heads/try2
c: 194d378
h: refs/heads/master
i:
  35801: 30e6645
  35799: 3bb7995
v: v3

Author: killerswan

[refs]

@@ -5,7 +5,7 @@ refs/heads/snap-stage3: eb8fd119c65c67f3b1b8268cc7341c22d39b7b61
 refs/heads/try: d324a424d8f84b1eb049b12cf34182bda91b0024
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b
-refs/heads/try2: de4687c378b9d83903896ee28413db847644ff77
+refs/heads/try2: 194d3786a7a03fa516057e446fc87cbb213d39d5
 refs/heads/incoming: d9317a174e434d4c99fc1a37fd7dc0d2f5328d37
 refs/heads/dist-snap: 22efa39382d41b084fde1719df7ae8ce5697d8c9
 refs/tags/release-0.2: c870d2dffb391e14efb05aa27898f1f6333a9596

branches/try2/doc/tutorial-borrowed-ptr.md

@@ -447,11 +447,11 @@ the block restricts the scope of `y`, making the move legal.
 
 # Borrowing and enums
 
-The previous example showed that the type system forbids any borrowing
-of unique boxes found in aliasable, mutable memory. This restriction
-prevents pointers from pointing into freed memory. There is one other
-case where the compiler must be very careful to ensure that pointers
-remain valid: pointers into the interior of an `enum`.
+The previous example showed that borrowing unique boxes found in
+aliasable, mutable memory is not permitted, so as to prevent pointers
+into freed memory. There is one other case where the compiler must be
+very careful to ensure that pointers remain valid: pointers into the
+interior of an enum.
 
 As an example, let’s look at the following `shape` type that can
 represent both rectangles and circles:
@@ -465,9 +465,9 @@ enum Shape {
 }
 ~~~
 
-Now we might write a function to compute the area of a shape. This
-function takes a borrowed pointer to a shape, to avoid the need for
-copying.
+Now I might write a function to compute the area of a shape. This
+function takes a borrowed pointer to a shape to avoid the need of
+copying them.
 
 ~~~
 # struct Point {x: float, y: float}; // as before
@@ -485,21 +485,21 @@ fn compute_area(shape: &Shape) -> float {
 }
 ~~~
 
-The first case matches against circles. Here, the pattern extracts the
-radius from the shape variant and the action uses it to compute the
-area of the circle. (Like any up-to-date engineer, we use the [tau
-circle constant][tau] and not that dreadfully outdated notion of pi).
+The first case matches against circles. Here the radius is extracted
+from the shape variant and used to compute the area of the circle
+(Like any up-to-date engineer, we use the [tau circle constant][tau]
+and not that dreadfully outdated notion of pi).
 
 [tau]: http://www.math.utah.edu/~palais/pi.html
 
 The second match is more interesting. Here we match against a
-rectangle and extract its size: but rather than copy the `size`
-struct, we use a by-reference binding to create a pointer to it. In
-other words, a pattern binding like `ref size` binds the name `size`
-to a pointer of type `&size` into the _interior of the enum_.
+rectangle and extract its size: but rather than copy the `size` struct,
+we use a by-reference binding to create a pointer to it. In other
+words, a pattern binding like `ref size` in fact creates a pointer of
+type `&size` into the _interior of the enum_.
 
-To make this more clear, let's look at a diagram of memory layout in
-the case where `shape` points at a rectangle:
+To make this more clear, let’s look at a diagram of how things are
+laid out in memory in the case where `shape` points at a rectangle:
 
 ~~~ {.notrust}
 Stack             Memory
@@ -523,8 +523,8 @@ the shape.
 Perhaps you can see where the danger lies: if the shape were somehow
 to be reassigned, perhaps to a circle, then although the memory used
 to store that shape value would still be valid, _it would have a
-different type_! The following diagram shows what memory would look
-like if code overwrote `shape` with a circle:
+different type_! This is shown in the following diagram, depicting what
+the state of memory would be if shape were overwritten with a circle:
 
 ~~~ {.notrust}
 Stack             Memory
@@ -538,23 +538,20 @@ Stack             Memory
                   +---------------+
 ~~~
 
-As you can see, the `size` pointer would be pointing at a `float`
-instead of a struct. This is not good: dereferencing the second field
-of a `float` as if it were a struct with two fields would be a memory
-safety violation.
+As you can see, the `size` pointer would not be pointing at a `float` and
+not a struct. This is not good.
 
 So, in fact, for every `ref` binding, the compiler will impose the
 same rules as the ones we saw for borrowing the interior of a unique
-box: it must be able to guarantee that the `enum` will not be
-overwritten for the duration of the borrow.  In fact, the compiler
-would accept the example we gave earlier. The example is safe because
-the shape pointer has type `&Shape`, which means "borrowed pointer to
-immutable memory containing a `shape`". If, however, the type of that
-pointer were `&const Shape` or `&mut Shape`, then the ref binding
-would be ill-typed. Just as with unique boxes, the compiler will
-permit `ref` bindings into data owned by the stack frame even if the
-data are mutable, but otherwise it requires that the data reside in
-immutable memory.
+box: it must be able to guarantee that the enum will not be
+overwritten for the duration of the borrow.  In fact, the example I
+gave earlier would be considered safe. This is because the shape
+pointer has type `&Shape`, which means “borrowed pointer to immutable
+memory containing a shape”. If however the type of that pointer were
+`&const Shape` or `&mut Shape`, then the ref binding would not be
+permitted. Just as with unique boxes, the compiler will permit ref
+bindings into data owned by the stack frame even if it is mutable, but
+otherwise it requires that the data reside in immutable memory.
 
 > ***Note:*** Right now, pattern bindings not explicitly annotated
 > with `ref` or `copy` use a special mode of "implicit by reference".
@@ -563,11 +560,11 @@ immutable memory.
 
 # Returning borrowed pointers
 
-So far, all of the examples we've looked at use borrowed pointers in a
-“downward” direction. That is, a method or code block creates a
-borrowed pointer, then uses it within the same scope. It is also
-possible to return borrowed pointers as the result of a function, but
-as we'll see, doing so requires some explicit annotation.
+So far, all of the examples we’ve looked at use borrowed pointers in a
+“downward” direction. That is, the borrowed pointer is created and
+then used during the method or code block which created it. It is also
+possible to return borrowed pointers to the caller, but as we'll see
+this requires some explicit annotation.
 
 For example, we could write a subroutine like this:
 
@@ -576,25 +573,23 @@ struct Point {x: float, y: float}
 fn get_x(p: &r/Point) -> &r/float { &p.x }
 ~~~
 
-Here, the function `get_x()` returns a pointer into the structure it
-was given. The type of the parameter (`&r/Point`) and return type
-(`&r/float`) both use a new syntactic form that we have not seen so
-far.  Here the identifier `r` names the lifetime of the pointer
-explicitly. So in effect, this function declares that it takes a
-pointer with lifetime `r` and returns a pointer with that same
-lifetime.
+Here, the function `get_x()` returns a pointer into the structure it was
+given. The type of the parameter (`&r/Point`) and return type (`&r/float`) both
+make use of a new syntactic form that we have not seen so far.  Here the identifier `r`
+serves as an explicit name for the lifetime of the pointer.  So in effect
+this function is declaring that it takes in a pointer with lifetime `r` and returns
+a pointer with that same lifetime.
 
 In general, it is only possible to return borrowed pointers if they
-are derived from a parameter to the procedure. In that case, the
-pointer result will always have the same lifetime as one of the
-parameters; named lifetimes indicate which parameter that
-is.
+are derived from a borrowed pointer which was given as input to the
+procedure.  In that case, they will always have the same lifetime as
+one of the parameters; named lifetimes are used to indicate which
+parameter that is.
 
-In the previous examples, function parameter types did not include a
-lifetime name. In those examples, the compiler simply creates a fresh
-name for the lifetime automatically: that is, the lifetime name is
-guaranteed to refer to a distinct lifetime from the lifetimes of all
-other parameters.
+In the examples before, function parameter types did not include a
+lifetime name.  In this case, the compiler simply creates a new,
+anonymous name, meaning that the parameter is assumed to have a
+distinct lifetime from all other parameters.
 
 Named lifetimes that appear in function signatures are conceptually
 the same as the other lifetimes we've seen before, but they are a bit
@@ -604,13 +599,13 @@ lifetime `r` is actually a kind of *lifetime parameter*: it is defined
 by the caller to `get_x()`, just as the value for the parameter `p` is
 defined by that caller.
 
-In any case, whatever the lifetime of `r` is, the pointer produced by
-`&p.x` always has the same lifetime as `p` itself: a pointer to a
+In any case, whatever the lifetime `r` is, the pointer produced by
+`&p.x` always has the same lifetime as `p` itself, as a pointer to a
 field of a struct is valid as long as the struct is valid. Therefore,
-the compiler accepts the function `get_x()`.
+the compiler is satisfied with the function `get_x()`.
 
-To emphasize this point, let’s look at a variation on the example, this
-time one that does not compile:
+To drill in this point, let’s look at a variation on the example, this
+time one which does not compile:
 
 ~~~ {.xfail-test}
 struct Point {x: float, y: float}
@@ -622,21 +617,22 @@ fn get_x_sh(p: @Point) -> &float {
 Here, the function `get_x_sh()` takes a managed box as input and
 returns a borrowed pointer. As before, the lifetime of the borrowed
 pointer that will be returned is a parameter (specified by the
-caller). That means that `get_x_sh()` promises to return a borrowed
-pointer that is valid for as long as the caller would like: this is
-subtly different from the first example, which promised to return a
-pointer that was valid for as long as its pointer argument was valid.
+caller). That means that effectively `get_x_sh()` is promising to
+return a borrowed pointer that is valid for as long as the caller
+would like: this is subtly different from the first example, which
+promised to return a pointer that was valid for as long as the pointer
+it was given.
 
 Within `get_x_sh()`, we see the expression `&p.x` which takes the
-address of a field of a managed box. The presence of this expression
-implies that the compiler must guarantee that, so long as the
-resulting pointer is valid, the managed box will not be reclaimed by
-the garbage collector. But recall that `get_x_sh()` also promised to
-return a pointer that was valid for as long as the caller wanted it to
-be. Clearly, `get_x_sh()` is not in a position to make both of these
-guarantees; in fact, it cannot guarantee that the pointer will remain
-valid at all once it returns, as the parameter `p` may or may not be
-live in the caller. Therefore, the compiler will report an error here.
+address of a field of a managed box. This implies that the compiler
+must guarantee that, so long as the resulting pointer is valid, the
+managed box will not be reclaimed by the garbage collector. But recall
+that `get_x_sh()` also promised to return a pointer that was valid for
+as long as the caller wanted it to be. Clearly, `get_x_sh()` is not in
+a position to make both of these guarantees; in fact, it cannot
+guarantee that the pointer will remain valid at all once it returns,
+as the parameter `p` may or may not be live in the caller. Therefore,
+the compiler will report an error here.
 
 In general, if you borrow a managed (or unique) box to create a
 borrowed pointer, the pointer will only be valid within the function
@@ -647,9 +643,9 @@ points at a static constant).
 
 # Named lifetimes
 
-Let's look at named lifetimes in more detail. Named lifetimes allow
-for grouping of parameters by lifetime. For example, consider this
-function:
+Let's look at named lifetimes in more detail.  In effect, the use of
+named lifetimes allows you to group parameters by lifetime.  For
+example, consider this function:
 
 ~~~
 # struct Point {x: float, y: float}; // as before
@@ -722,10 +718,10 @@ fn select<T>(shape: &tmp/Shape, threshold: float,
 }
 ~~~
 
-Here you can see that `shape`'s lifetime is now named `tmp`. The
-parameters `a`, `b`, and the return value all have the lifetime `r`.
-However, since the lifetime `tmp` is not returned, it would be more
-concise to just omit the named lifetime for `shape` altogether:
+Here you can see the lifetime of shape is now being called `tmp`. The
+parameters `a`, `b`, and the return value are all given the lifetime
+`r`.  However, since the lifetime `tmp` is not returned, it would be shorter
+to just omit the named lifetime for `shape` altogether:
 
 ~~~
 # struct Point {x: float, y: float}; // as before
@@ -746,22 +742,17 @@ This is equivalent to the previous definition.
 # Purity
 
 As mentioned before, the Rust compiler offers a kind of escape hatch
-that permits borrowing of any data, as long as the actions that occur
+that permits borrowing of any data, but only if the actions that occur
 during the lifetime of the borrow are pure. Pure actions are those
-that only modify data owned by the current stack frame. The compiler
+which only modify data owned by the current stack frame. The compiler
 can therefore permit arbitrary pointers into the heap, secure in the
 knowledge that no pure action will ever cause them to become
 invalidated (the compiler must still track data on the stack which is
-borrowed and enforce those rules normally, of course). A pure function
-in Rust is referentially transparent: it returns the same results
-given the same (observably equivalent) inputs. That is because while
-pure functions are allowed to modify data, they may only modify
-*stack-local* data, which cannot be observed outside the scope of the
-function itself. (Using an `unsafe` block invalidates this guarantee.)
-
-Let’s revisit a previous example and show how purity can affect
-typechecking. Here is `example5a()`, which borrows the interior of a
-unique box found in an aliasable, mutable location, only now we’ve
+borrowed and enforce those rules normally, of course).
+
+Let’s revisit a previous example and show how purity can affect the
+compiler’s result. Here is `example5a()`, which borrows the interior of
+a unique box found in an aliasable, mutable location, only now we’ve
 replaced the `...` with some specific code:
 
 ~~~
@@ -773,8 +764,8 @@ fn example5a(x: @S ...) -> int {
 }
 ~~~
 
-The new code simply returns an incremented version of `y`. This code
-clearly doesn't mutate the heap, so the compiler is satisfied.
+The new code simply returns an incremented version of `y`. This clearly
+doesn’t do mutate anything in the heap, so the compiler is satisfied.
 
 But suppose we wanted to pull the increment code into a helper, like
 this:
@@ -796,8 +787,8 @@ fn example5a(x: @S ...) -> int {
 ~~~
 
 But now the compiler will report an error again. The reason is that it
-only considers one function at a time (like most typecheckers), and
-so it does not know that `add_one()` consists of pure code. We can
+only considers one function at a time (like most type checkers), and
+so it does not know that `add_one()` only takes pure actions. We can
 help the compiler by labeling `add_one()` as pure:
 
 ~~~
@@ -808,7 +799,7 @@ With this change, the modified version of `example5a()` will again compile.
 
 # Conclusion
 
-So there you have it: a (relatively) brief tour of the borrowed pointer
-system. For more details, we refer to the (yet to be written) reference
+So there you have it. A (relatively) brief tour of borrowed pointer
+system. For more details, I refer to the (yet to be written) reference
 document on borrowed pointers, which will explain the full notation
 and give more examples.