rust/doc/po/tutorial-borrowed-ptr.md.pot

# SOME DESCRIPTIVE TITLE
# Copyright (C) YEAR Free Software Foundation, Inc.
# This file is distributed under the same license as the PACKAGE package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: PACKAGE VERSION\n"
"POT-Creation-Date: 2013-07-07 21:10+0300\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"Language: \n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=CHARSET\n"
"Content-Transfer-Encoding: 8bit\n"

#. type: Plain text
#: doc/rust.md:4 doc/rustpkg.md:4 doc/tutorial.md:4
#: doc/tutorial-borrowed-ptr.md:4 doc/tutorial-ffi.md:4
#: doc/tutorial-macros.md:4 doc/tutorial-tasks.md:4 doc/tut.md:4
msgid "# Introduction"
msgstr ""

#. type: Plain text
#: doc/tutorial.md:1110 doc/tutorial-borrowed-ptr.md:72
msgid "Now we can call `compute_distance()` in various ways:"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:2
msgid "% Rust Borrowed Pointers Tutorial"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:14
msgid ""
"Borrowed pointers are one of the more flexible and powerful tools available "
"in Rust. A borrowed pointer can point anywhere: into the managed or exchange "
"heap, into the stack, and even into the interior of another data structure. "
"A borrowed pointer is as flexible as a C pointer or C++ reference. However, "
"unlike C and C++ compilers, the Rust compiler includes special static checks "
"that ensure that programs use borrowed pointers safely. Another advantage of "
"borrowed pointers is that they are invisible to the garbage collector, so "
"working with borrowed pointers helps reduce the overhead of automatic memory "
"management."
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:18
msgid ""
"Despite their complete safety, a borrowed pointer's representation at "
"runtime is the same as that of an ordinary pointer in a C program. They "
"introduce zero overhead. The compiler does all safety checks at compile time."
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:24
msgid ""
"Although borrowed pointers have rather elaborate theoretical underpinnings "
"(region pointers), the core concepts will be familiar to anyone who has "
"worked with C or C++. Therefore, the best way to explain how they are "
"usedand their limitationsis probably just to work through several examples."
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:26
msgid "# By example"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:31
msgid ""
"Borrowed pointers are called *borrowed* because they are only valid for a "
"limited duration. Borrowed pointers never claim any kind of ownership over "
"the data that they point to: instead, they are used for cases where you "
"would like to use data for a short time."
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:33
msgid "As an example, consider a simple struct type `Point`:"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:37
msgid "~~~ struct Point {x: float, y: float} ~~~"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:41
msgid ""
"We can use this simple definition to allocate points in many different ways. "
"For example, in this code, each of these three local variables contains a "
"point, but allocated in a different place:"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:48
#, no-wrap
msgid ""
"~~~\n"
"# struct Point {x: float, y: float}\n"
"let on_the_stack :  Point =  Point {x: 3.0, y: 4.0};\n"
"let managed_box  : @Point = @Point {x: 5.0, y: 1.0};\n"
"let owned_box    : ~Point = ~Point {x: 7.0, y: 9.0};\n"
"~~~\n"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:60
msgid ""
"Suppose we wanted to write a procedure that computed the distance between "
"any two points, no matter where they were stored. For example, we might like "
"to compute the distance between `on_the_stack` and `managed_box`, or between "
"`managed_box` and `owned_box`. One option is to define a function that takes "
"two arguments of type `Point`that is, it takes the points by value. But if "
"we define it this way, calling the function will cause the points to be "
"copied. For points, this is probably not so bad, but often copies are "
"expensive. Worse, if the data type contains mutable fields, copying can "
"change the semantics of your program in unexpected ways. So we'd like to "
"define a function that takes the points by pointer. We can use borrowed "
"pointers to do this:"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:70
#, no-wrap
msgid ""
"~~~\n"
"# struct Point {x: float, y: float}\n"
"# fn sqrt(f: float) -> float { 0f }\n"
"fn compute_distance(p1: &Point, p2: &Point) -> float {\n"
"    let x_d = p1.x - p2.x;\n"
"    let y_d = p1.y - p2.y;\n"
"    sqrt(x_d * x_d + y_d * y_d)\n"
"}\n"
"~~~\n"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:82
#, no-wrap
msgid ""
"~~~\n"
"# struct Point {x: float, y: float}\n"
"# let on_the_stack :  Point =  Point{x: 3.0, y: 4.0};\n"
"# let managed_box  : @Point = @Point{x: 5.0, y: 1.0};\n"
"# let owned_box    : ~Point = ~Point{x: 7.0, y: 9.0};\n"
"# fn compute_distance(p1: &Point, p2: &Point) -> float { 0f }\n"
"compute_distance(&on_the_stack, managed_box);\n"
"compute_distance(managed_box, owned_box);\n"
"~~~\n"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:89
msgid ""
"Here, the `&` operator takes the address of the variable `on_the_stack`; "
"this is because `on_the_stack` has the type `Point` (that is, a struct "
"value) and we have to take its address to get a 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."
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:95
msgid ""
"In contrast, we can pass the boxes `managed_box` and `owned_box` to "
"`compute_distance` directly. The compiler automatically converts a box like "
"`@Point` or `~Point` to a borrowed pointer like `&Point`. This is another "
"form of borrowing: in this case, the caller lends the contents of the "
"managed or owned box to the callee."
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:105
msgid ""
"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 "
"variable have been lent out, you cannot send that variable to another task. "
"In addition, the compiler will reject any code that might cause the borrowed "
"value to be freed or overwrite its component fields with values of different "
"types (I'll get into what kinds of actions those are shortly). This rule "
"should make intuitive sense: you must wait for a borrower to return the "
"value that you lent it (that is, wait for the borrowed pointer to go out of "
"scope)  before you can make full use of it again."
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:107
msgid "# Other uses for the & operator"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:109
msgid "In the previous example, the value `on_the_stack` was defined like so:"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:114
msgid ""
"~~~ # struct Point {x: float, y: float} let on_the_stack: Point = Point {x: "
"3.0, y: 4.0}; ~~~"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:119
msgid ""
"This declaration means that code can only pass `Point` by value to other "
"functions. As a consequence, we had to explicitly take the address of "
"`on_the_stack` to get a borrowed pointer. Sometimes however it is more "
"convenient to move the & operator into the definition of `on_the_stack`:"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:124
msgid ""
"~~~ # struct Point {x: float, y: float} let on_the_stack2: &Point = &Point "
"{x: 3.0, y: 4.0}; ~~~"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:128
msgid ""
"Applying `&` to an rvalue (non-assignable location) is just a convenient "
"shorthand for creating a temporary and taking its address. A more verbose "
"way to write the same code is:"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:134
msgid ""
"~~~ # struct Point {x: float, y: float} let tmp = Point {x: 3.0, y: 4.0}; "
"let on_the_stack2 : &Point = &tmp; ~~~"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:136
msgid "# Taking the address of fields"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:141
msgid ""
"As in C, the `&` operator is not limited to taking the address of local "
"variables. It can also take the address of fields or individual array "
"elements. For example, consider this type definition for `rectangle`:"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:147
msgid ""
"~~~ struct Point {x: float, y: float} // as before struct Size {w: float, h: "
"float} // as before struct Rectangle {origin: Point, size: Size} ~~~"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:149
msgid "Now, as before, we can define rectangles in a few different ways:"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:161
#, no-wrap
msgid ""
"~~~\n"
"# struct Point {x: float, y: float}\n"
"# struct Size {w: float, h: float} // as before\n"
"# struct Rectangle {origin: Point, size: Size}\n"
"let rect_stack   = &Rectangle {origin: Point {x: 1f, y: 2f},\n"
"                               size: Size {w: 3f, h: 4f}};\n"
"let rect_managed = @Rectangle {origin: Point {x: 3f, y: 4f},\n"
"                               size: Size {w: 3f, h: 4f}};\n"
"let rect_owned   = ~Rectangle {origin: Point {x: 5f, y: 6f},\n"
"                               size: Size {w: 3f, h: 4f}};\n"
"~~~\n"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:164
msgid ""
"In each case, we can extract out individual subcomponents with the `&` "
"operator. For example, I could write:"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:175
msgid ""
"~~~ # struct Point {x: float, y: float} // as before # struct Size {w: "
"float, h: float} // as before # struct Rectangle {origin: Point, size: Size} "
"# let rect_stack = &Rectangle {origin: Point {x: 1f, y: 2f}, size: Size {w: "
"3f, h: 4f}}; # let rect_managed = @Rectangle {origin: Point {x: 3f, y: 4f}, "
"size: Size {w: 3f, h: 4f}}; # let rect_owned = ~Rectangle {origin: Point {x: "
"5f, y: 6f}, size: Size {w: 3f, h: 4f}}; # fn compute_distance(p1: &Point, "
"p2: &Point) -> float { 0f } compute_distance(&rect_stack.origin, "
"&rect_managed.origin); ~~~"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:178
msgid ""
"which would borrow the field `origin` from the rectangle on the stack as "
"well as from the managed box, and then compute the distance between them."
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:180
msgid "# Borrowing managed boxes and rooting"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:186
msgid ""
"Weve seen a few examples so far of borrowing heap boxes, both managed and "
"owned. Up till this point, weve glossed over issues of safety. As stated in "
"the introduction, at runtime a borrowed pointer is simply a pointer, nothing "
"more. Therefore, avoiding C's problems with dangling pointers requires a "
"compile-time safety check."
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:197
msgid ""
"The basis for the check is the notion of _lifetimes_. A lifetime is a static "
"approximation of the span of execution during which the pointer is valid: it "
"always corresponds to some expression or block within the program. Code "
"inside that expression can use the pointer without restrictions. But if the "
"pointer escapes from that expression (for example, if the expression "
"contains an assignment expression that assigns the pointer to a mutable "
"field of a data structure with a broader scope than the pointer itself), the "
"compiler reports an error. We'll be discussing lifetimes more in the "
"examples to come, and a more thorough introduction is also available."
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:202
msgid ""
"When the `&` operator creates a borrowed pointer, the compiler must ensure "
"that the pointer remains valid for its entire lifetime. Sometimes this is "
"relatively easy, such as when taking the address of a local variable or a "
"field that is stored on the stack:"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:211
#, no-wrap
msgid ""
"~~~\n"
"struct X { f: int }\n"
"fn example1() {\n"
"    let mut x = X { f: 3 };\n"
"    let y = &mut x.f;  // -+ L\n"
"    ...                //  |\n"
"}                      // -+\n"
"~~~\n"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:216
msgid ""
"Here, the lifetime of the borrowed pointer `y` is simply L, the remainder of "
"the function body. The compiler need not do any other work to prove that "
"code will not free `x.f`. This is true even if the code mutates `x`."
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:218
msgid "The situation gets more complex when borrowing data inside heap boxes:"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:227
#, no-wrap
msgid ""
"~~~\n"
"# struct X { f: int }\n"
"fn example2() {\n"
"    let mut x = @X { f: 3 };\n"
"    let y = &x.f;      // -+ L\n"
"    ...                //  |\n"
"}                      // -+\n"
"~~~\n"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:238
msgid ""
"In this example, the value `x` is a heap box, and `y` is therefore a pointer "
"into that heap box. Again the lifetime of `y` is L, the remainder of the "
"function body. But there is a crucial difference: suppose `x` were to be "
"reassigned during the lifetime L? If the compiler isn't careful, the managed "
"box could become *unrooted*, and would therefore be subject to garbage "
"collection. A heap box that is unrooted is one such that no pointer values "
"in the heap point to it. It would violate memory safety for the box that was "
"originally assigned to `x` to be garbage-collected, since a non-heap pointer "
"*`y`* still points into it."
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:241
msgid ""
"> ***Note:*** Our current implementation implements the garbage collector > "
"using reference counting and cycle detection."
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:247
msgid ""
"For this reason, whenever an `&` expression borrows the interior of a "
"managed box stored in a mutable location, the compiler inserts a temporary "
"that ensures that the managed box remains live for the entire lifetime. So, "
"the above example would be compiled as if it were written"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:257
#, no-wrap
msgid ""
"~~~\n"
"# struct X { f: int }\n"
"fn example2() {\n"
"    let mut x = @X {f: 3};\n"
"    let x1 = x;\n"
"    let y = &x1.f;     // -+ L\n"
"    ...                //  |\n"
"}                      // -+\n"
"~~~\n"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:260
msgid ""
"Now if `x` is reassigned, the pointer `y` will still remain valid. This "
"process is called *rooting*."
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:262
msgid "# Borrowing owned boxes"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:268
msgid ""
"The previous example demonstrated *rooting*, the process by which the "
"compiler ensures that managed boxes remain live for the duration of a "
"borrow. Unfortunately, rooting does not work for borrows of owned boxes, "
"because it is not possible to have two references to a owned box."
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:274
msgid ""
"For owned boxes, therefore, the compiler will only allow a borrow *if the "
"compiler can guarantee that the owned box will not be reassigned or moved "
"for the lifetime of the pointer*. This does not necessarily mean that the "
"owned box is stored in immutable memory. For example, the following function "
"is legal:"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:289
#, no-wrap
msgid ""
"~~~\n"
"# fn some_condition() -> bool { true }\n"
"# struct Foo { f: int }\n"
"fn example3() -> int {\n"
"    let mut x = ~Foo {f: 3};\n"
"    if some_condition() {\n"
"        let y = &x.f;      // -+ L\n"
"        return *y;         //  |\n"
"    }                      // -+\n"
"    x = ~Foo {f: 4};\n"
"    ...\n"
"# return 0;\n"
"}\n"
"~~~\n"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:295
msgid ""
"Here, as before, the interior of the variable `x` is being borrowed and `x` "
"is declared as mutable. However, the compiler can prove that `x` is not "
"assigned anywhere in the lifetime L of the variable `y`. Therefore, it "
"accepts the function, even though `x` is mutable and in fact is mutated "
"later in the function."
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:301
msgid ""
"It may not be clear why we are so concerned about mutating a borrowed "
"variable. The reason is that the runtime system frees any owned box _as soon "
"as its owning reference changes or goes out of scope_. Therefore, a program "
"like this is illegal (and would be rejected by the compiler):"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:310
#, no-wrap
msgid ""
"~~~ {.xfail-test}\n"
"fn example3() -> int {\n"
"    let mut x = ~X {f: 3};\n"
"    let y = &x.f;\n"
"    x = ~X {f: 4};  // Error reported here.\n"
"    *y\n"
"}\n"
"~~~\n"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:313
msgid ""
"To make this clearer, consider this diagram showing the state of memory "
"immediately before the re-assignment of `x`:"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:316 doc/tutorial-borrowed-ptr.md:330
#, no-wrap
msgid ""
"~~~ {.notrust}\n"
"    Stack               Exchange Heap\n"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:325
#, no-wrap
msgid ""
"  x +----------+\n"
"    | ~{f:int} | ----+\n"
"  y +----------+     |\n"
"    | &int     | ----+\n"
"    +----------+     |    +---------+\n"
"                     +--> |  f: 3   |\n"
"                          +---------+\n"
"~~~\n"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:327
msgid "Once the reassignment occurs, the memory will look like this:"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:339
#, no-wrap
msgid ""
"  x +----------+          +---------+\n"
"    | ~{f:int} | -------> |  f: 4   |\n"
"  y +----------+          +---------+\n"
"    | &int     | ----+\n"
"    +----------+     |    +---------+\n"
"                     +--> | (freed) |\n"
"                          +---------+\n"
"~~~\n"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:342
msgid ""
"Here you can see that the variable `y` still points at the old box, which "
"has been freed."
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:348
msgid ""
"In fact, the compiler can apply the same kind of reasoning to any memory "
"that is _(uniquely) owned by the stack frame_. So we could modify the "
"previous example to introduce additional owned pointers and structs, and the "
"compiler will still be able to detect possible mutations:"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:353
#, no-wrap
msgid ""
"~~~ {.xfail-test}\n"
"fn example3() -> int {\n"
"    struct R { g: int }\n"
"    struct S { f: ~R }\n"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:361
#, no-wrap
msgid ""
"    let mut x = ~S {f: ~R {g: 3}};\n"
"    let y = &x.f.g;\n"
"    x = ~S {f: ~R {g: 4}};  // Error reported here.\n"
"    x.f = ~R {g: 5};        // Error reported here.\n"
"    *y\n"
"}\n"
"~~~\n"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:365
msgid ""
"In this case, two errors are reported, one when the variable `x` is modified "
"and another when `x.f` is modified. Either modification would invalidate the "
"pointer `y`."
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:367
msgid "# Borrowing and enums"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:373
msgid ""
"The previous example showed that the type system forbids any borrowing of "
"owned 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`."
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:376
msgid ""
"As an example, lets look at the following `shape` type that can represent "
"both rectangles and circles:"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:385
#, no-wrap
msgid ""
"~~~\n"
"struct Point {x: float, y: float}; // as before\n"
"struct Size {w: float, h: float}; // as before\n"
"enum Shape {\n"
"    Circle(Point, float),   // origin, radius\n"
"    Rectangle(Point, Size)  // upper-left, dimensions\n"
"}\n"
"~~~\n"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:389
msgid ""
"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."
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:405
#, no-wrap
msgid ""
"~~~\n"
"# struct Point {x: float, y: float}; // as before\n"
"# struct Size {w: float, h: float}; // as before\n"
"# enum Shape {\n"
"#     Circle(Point, float),   // origin, radius\n"
"#     Rectangle(Point, Size)  // upper-left, dimensions\n"
"# }\n"
"# static tau: float = 6.28f;\n"
"fn compute_area(shape: &Shape) -> float {\n"
"    match *shape {\n"
"        Circle(_, radius) => 0.5 * tau * radius * radius,\n"
"        Rectangle(_, ref size) => size.w * size.h\n"
"    }\n"
"}\n"
"~~~\n"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:410
msgid ""
"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)."
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:412
msgid "[tau]: http://www.math.utah.edu/~palais/pi.html"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:418
msgid ""
"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_."
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:421
msgid ""
"To make this more clear, let's look at a diagram of memory layout in the "
"case where `shape` points at a rectangle:"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:424 doc/tutorial-borrowed-ptr.md:449
#, no-wrap
msgid ""
"~~~ {.notrust}\n"
"Stack             Memory\n"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:433
#, no-wrap
msgid ""
"+-------+         +---------------+\n"
"| shape | ------> | rectangle(    |\n"
"+-------+         |   {x: float,  |\n"
"| size  | -+      |    y: float}, |\n"
"+-------+  +----> |   {w: float,  |\n"
"                  |    h: float}) |\n"
"                  +---------------+\n"
"~~~\n"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:440
msgid ""
"Here you can see that rectangular shapes are composed of five words of "
"memory. The first is a tag indicating which variant this enum is "
"(`rectangle`, in this case). The next two words are the `x` and `y` fields "
"for the point and the remaining two are the `w` and `h` fields for the size. "
"The binding `size` is then a pointer into the inside of the shape."
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:446
msgid ""
"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:"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:458
#, no-wrap
msgid ""
"+-------+         +---------------+\n"
"| shape | ------> | circle(       |\n"
"+-------+         |   {x: float,  |\n"
"| size  | -+      |    y: float}, |\n"
"+-------+  +----> |   float)      |\n"
"                  |               |\n"
"                  +---------------+\n"
"~~~\n"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:463
msgid ""
"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."
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:475
msgid ""
"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 owned 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 `&mut Shape`, then the "
"ref binding would be ill-typed.  Just as with owned 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."
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:477
msgid "# Returning borrowed pointers"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:483
msgid ""
"So far, all of the examples we have 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."
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:485
msgid "For example, we could write a subroutine like this:"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:490
msgid ""
"~~~ struct Point {x: float, y: float} fn get_x<'r>(p: &'r Point) -> &'r "
"float { &p.x } ~~~"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:498
msgid ""
"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."
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:504
msgid ""
"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."
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:510
msgid ""
"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."
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:518
msgid ""
"Named lifetimes that appear in function signatures are conceptually the same "
"as the other lifetimes we have seen before, but they are a bit abstract: "
"they dont refer to a specific expression within `get_x()`, but rather to "
"some expression within the *caller of `get_x()`*.  The 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."
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:523
msgid ""
"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 field of a struct "
"is valid as long as the struct is valid. Therefore, the compiler accepts the "
"function `get_x()`."
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:526
msgid ""
"To emphasize this point, lets look at a variation on the example, this time "
"one that does not compile:"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:533
#, no-wrap
msgid ""
"~~~ {.xfail-test}\n"
"struct Point {x: float, y: float}\n"
"fn get_x_sh(p: @Point) -> &float {\n"
"    &p.x // Error reported here\n"
"}\n"
"~~~\n"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:541
msgid ""
"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."
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:552
msgid ""
"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."
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:559
msgid ""
"In general, if you borrow a managed (or owned) box to create a borrowed "
"pointer, the pointer will only be valid within the function and cannot be "
"returned. This is why the typical way to return borrowed pointers is to take "
"borrowed pointers as input (the only other case in which it can be legal to "
"return a borrowed pointer is if the pointer points at a static constant)."
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:561
msgid "# Named lifetimes"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:565
msgid ""
"Let's look at named lifetimes in more detail. Named lifetimes allow for "
"grouping of parameters by lifetime. For example, consider this function:"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:579
#, no-wrap
msgid ""
"~~~\n"
"# struct Point {x: float, y: float}; // as before\n"
"# struct Size {w: float, h: float}; // as before\n"
"# enum Shape {\n"
"#     Circle(Point, float),   // origin, radius\n"
"#     Rectangle(Point, Size)  // upper-left, dimensions\n"
"# }\n"
"# fn compute_area(shape: &Shape) -> float { 0f }\n"
"fn select<'r, T>(shape: &'r Shape, threshold: float,\n"
"                 a: &'r T, b: &'r T) -> &'r T {\n"
"    if compute_area(shape) > threshold {a} else {b}\n"
"}\n"
"~~~\n"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:585
msgid ""
"This function takes three borrowed pointers and assigns each the same "
"lifetime `r`.  In practice, this means that, in the caller, the lifetime `r` "
"will be the *intersection of the lifetime of the three region parameters*. "
"This may be overly conservative, as in this example:"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:607
#, no-wrap
msgid ""
"~~~\n"
"# struct Point {x: float, y: float}; // as before\n"
"# struct Size {w: float, h: float}; // as before\n"
"# enum Shape {\n"
"#     Circle(Point, float),   // origin, radius\n"
"#     Rectangle(Point, Size)  // upper-left, dimensions\n"
"# }\n"
"# fn compute_area(shape: &Shape) -> float { 0f }\n"
"# fn select<'r, T>(shape: &Shape, threshold: float,\n"
"#                  a: &'r T, b: &'r T) -> &'r T {\n"
"#     if compute_area(shape) > threshold {a} else {b}\n"
"# }\n"
"                                                     // -+ r\n"
"fn select_based_on_unit_circle<'r, T>(               //  |-+ B\n"
"    threshold: float, a: &'r T, b: &'r T) -> &'r T { //  | |\n"
"                                                     //  | |\n"
"    let shape = Circle(Point {x: 0., y: 0.}, 1.);    //  | |\n"
"    select(&shape, threshold, a, b)                  //  | |\n"
"}                                                    //  |-+\n"
"                                                     // -+\n"
"~~~\n"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:617
msgid ""
"In this call to `select()`, the lifetime of the first parameter shape is B, "
"the function body. Both of the second two parameters `a` and `b` share the "
"same lifetime, `r`, which is a lifetime parameter of "
"`select_based_on_unit_circle()`. The caller will infer the intersection of "
"these two lifetimes as the lifetime of the returned value, and hence the "
"return value of `select()` will be assigned a lifetime of B. This will in "
"turn lead to a compilation error, because `select_based_on_unit_circle()` is "
"supposed to return a value with the lifetime `r`."
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:622
msgid ""
"To address this, we can modify the definition of `select()` to distinguish "
"the lifetime of the first parameter from the lifetime of the latter two. "
"After all, the first parameter is not being returned. Here is how the new "
"`select()` might look:"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:636
#, no-wrap
msgid ""
"~~~\n"
"# struct Point {x: float, y: float}; // as before\n"
"# struct Size {w: float, h: float}; // as before\n"
"# enum Shape {\n"
"#     Circle(Point, float),   // origin, radius\n"
"#     Rectangle(Point, Size)  // upper-left, dimensions\n"
"# }\n"
"# fn compute_area(shape: &Shape) -> float { 0f }\n"
"fn select<'r, 'tmp, T>(shape: &'tmp Shape, threshold: float,\n"
"                       a: &'r T, b: &'r T) -> &'r T {\n"
"    if compute_area(shape) > threshold {a} else {b}\n"
"}\n"
"~~~\n"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:641
msgid ""
"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:"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:655
#, no-wrap
msgid ""
"~~~\n"
"# struct Point {x: float, y: float}; // as before\n"
"# struct Size {w: float, h: float}; // as before\n"
"# enum Shape {\n"
"#     Circle(Point, float),   // origin, radius\n"
"#     Rectangle(Point, Size)  // upper-left, dimensions\n"
"# }\n"
"# fn compute_area(shape: &Shape) -> float { 0f }\n"
"fn select<'r, T>(shape: &Shape, threshold: float,\n"
"                 a: &'r T, b: &'r T) -> &'r T {\n"
"    if compute_area(shape) > threshold {a} else {b}\n"
"}\n"
"~~~\n"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:657
msgid "This is equivalent to the previous definition."
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:659
msgid "# Conclusion"
msgstr ""

#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:663
msgid ""
"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 "
"document on borrowed pointers, which will explain the full notation and give "
"more examples."
msgstr ""