auto merge of #17432 : nick29581/rust/contrib, r=brson

[rust.git] / src / doc / guide-lifetimes.md

diff --git a/src/doc/guide-lifetimes.md b/src/doc/guide-lifetimes.md
index 1f44b77d56abb1d47203c79527e4d06dcae22e1c..66faee3fa04c802e1ea199603477d95c71ae387e 100644 (file)
--- a/src/doc/guide-lifetimes.md
+++ b/src/doc/guide-lifetimes.md
@@ -67,7 +67,7 @@ Now we can call `compute_distance()`:
 # let on_the_stack :     Point  =     Point{x: 3.0, y: 4.0};
 # let on_the_heap  : 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, on_the_heap);
+compute_distance(&on_the_stack, &*on_the_heap);
 ~~~
 
 Here, the `&` operator takes the address of the variable
@@ -77,10 +77,9 @@ value. We also call this _borrowing_ the local variable
 `on_the_stack`, because we have created an alias: that is, another
 name for the same data.
 
-In the case of `on_the_heap`, however, no explicit action is necessary. 
-The compiler will automatically convert a box point to a reference like &point. 
-This is another form of borrowing; in this case, the contents of the owned box 
-are being lent out.
+Likewise, in the case of `on_the_heap`,
+the `&` operator is used in conjunction with the `*` operator
+to take a reference to the contents of the box.
 
 Whenever a caller lends data to a callee, there are some limitations on what
 the caller can do with the original. For example, if the contents of a
@@ -432,36 +431,6 @@ In any case, whatever the lifetime of `r` is, the pointer produced by
 field of a struct is valid as long as the struct is valid. Therefore,
 the compiler accepts the function `get_x()`.
 
-To emphasize this point, let’s look at a variation on the example, this
-time one that does not compile:
-
-~~~ {.ignore}
-struct Point {x: f64, y: f64}
-fn get_x_sh(p: &Point) -> &f64 {
-    &p.x // Error reported here
-}
-~~~
-
-Here, the function `get_x_sh()` takes a reference as input and
-returns a reference. As before, the lifetime of the reference
-that will be returned is a parameter (specified by the
-caller). That means that `get_x_sh()` promises to return a reference
-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.
-
-Within `get_x_sh()`, we see the expression `&p.x` which takes the
-address of a field of a Point. The presence of this expression
-implies that the compiler must guarantee that , so long as the
-resulting pointer is valid, the original Point won't be moved or changed.
-
-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 struct or box to create a
 reference, it will only be valid within the function
 and cannot be returned. This is why the typical way to return references