---

yaml
---
r: 31119
b: refs/heads/incoming
c: a46db48
h: refs/heads/master
i:
  31117: 4066a4e
  31115: e89bb31
  31111: 1f5ec07
  31103: 659523d
v: v3

Author: catamorphism

[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: c765c59ab19f7dcb2f9c5e90d5ea4e724df33904
+refs/heads/incoming: a46db484abcdd517c0116301c77364e8e1c373af
 refs/heads/dist-snap: 2f32a1581f522e524009138b33b1c7049ced668d
 refs/tags/release-0.2: c870d2dffb391e14efb05aa27898f1f6333a9596
 refs/tags/release-0.3: b5f0d0f648d9a6153664837026ba1be43d3e2503

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

@@ -2,40 +2,40 @@
 
 # Introduction
 
-Borrowed pointers are one of the more flexible and powerful tools
-available in Rust. A borrowed pointer can be used to point anywhere:
-into the managed and exchange heaps, into the stack, and even into the
-interior of another data structure. With regard to flexibility, it is
-comparable to a C pointer or C++ reference. However, unlike C and C++,
-the Rust compiler includes special checks that ensure that borrowed
-pointers are being used safely. Another advantage of borrowed pointers
-is that they are invisible to the garbage collector, so working with
-borrowed pointers helps keep things efficient.
-
-Despite the fact that they are completely safe, at runtime, a borrowed
-pointer is “just a pointer”. They introduce zero overhead. All safety
-checks are done at compilation time.
+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.
+
+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.
 
 Although borrowed pointers have rather elaborate theoretical
 underpinnings (region pointers), the core concepts will be familiar to
-anyone who worked with C or C++. Therefore, the best way to explain
+anyone who has worked with C or C++. Therefore, the best way to explain
 how they are used—and their limitations—is probably just to work
 through several examples.
 
 # By example
 
-Borrowed pointers are called borrowed because they are only valid for
-a limit duration. Borrowed pointers never claim any kind of ownership
-over the data that they point at: instead, they are used for cases
-where you like to make use of data for a short time.
+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.
 
 As an example, consider a simple struct type `Point`:
 
 ~~~
 struct Point {x: float, y: float}
 ~~~
 
-We can use this simple definition to allocate points in many ways. For
+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:
 
@@ -46,17 +46,17 @@ let shared_box   : @Point = @Point {x: 5.0, y: 1.0};
 let unique_box   : ~Point = ~Point {x: 7.0, y: 9.0};
 ~~~
 
-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
-`shared_box`, or between `shared_box` and `unique_box`. One option is
-to define a function that takes two arguments of type point—that is,
-it takes the points by value. But this will cause the points to be
-copied when we call the function. For points, this is probably not so
-bad, but often copies are expensive or, worse, if there are mutable
-fields, they can change the semantics of your program. So we’d like to
-define a function that takes the points by pointer. We can use
-borrowed pointers to do this:
+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 `shared_box`, or between
+`shared_box` and `unique_box`. One option is to define a function that takes
+two arguments of type `Point`—that is, it takes the points by value. But 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:
 
 ~~~
 # struct Point {x: float, y: float}
@@ -80,28 +80,28 @@ compute_distance(&on_the_stack, shared_box);
 compute_distance(shared_box, unique_box);
 ~~~
 
-Here the `&` operator is used to take the address of the variable
+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 are created an alias: that is, another
-route to the same data.
-
-In the case of the boxes `shared_box` and `unique_box`, however, no
-explicit action is necessary. The compiler will automatically convert
-a box like `@Point` or `~Point` to a borrowed pointer like
-`&Point`. This is another form of borrowing; in this case, the
-contents of the shared/unique box is being lent out.
-
-Whenever a value is borrowed, there are some limitations on what you
-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, nor
-will you be permitted to take actions that might cause the borrowed
-value to be freed or to change its type (I’ll get into what kinds of
-actions those are shortly). This rule should make intuitive sense: you
-must wait for a borrowed value to be returned (that is, for the
-borrowed pointer to go out of scope) before you can make full use of
-it again.
+`on_the_stack`, because we have created an alias: that is, another
+name for the same data.
+
+In contrast, we can pass the boxes `shared_box` and `unique_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 shared or
+unique box to the callee.
+
+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.
 
 # Other uses for the & operator
 

branches/incoming/src/libcore/str.rs

@@ -1361,7 +1361,7 @@ pub pure fn is_whitespace(s: &str) -> bool {
  *
  * Alphanumeric characters are determined by `char::is_alphanumeric`
  */
-pure fn is_alphanumeric(s: &str) -> bool {
+fn is_alphanumeric(s: &str) -> bool {
     return all(s, char::is_alphanumeric);
 }
 
@@ -2030,22 +2030,22 @@ pub mod raw {
 }
 
 pub trait UniqueStr {
-    pure fn trim() -> self;
-    pure fn trim_left() -> self;
-    pure fn trim_right() -> self;
+    fn trim() -> self;
+    fn trim_left() -> self;
+    fn trim_right() -> self;
 }
 
 /// Extension methods for strings
 impl ~str: UniqueStr {
     /// Returns a string with leading and trailing whitespace removed
     #[inline]
-    pure fn trim() -> ~str { trim(self) }
+    fn trim() -> ~str { trim(self) }
     /// Returns a string with leading whitespace removed
     #[inline]
-    pure fn trim_left() -> ~str { trim_left(self) }
+    fn trim_left() -> ~str { trim_left(self) }
     /// Returns a string with trailing whitespace removed
     #[inline]
-    pure fn trim_right() -> ~str { trim_right(self) }
+    fn trim_right() -> ~str { trim_right(self) }
 }
 
 #[cfg(notest)]
@@ -2062,33 +2062,33 @@ pub mod traits {
 pub mod traits {}
 
 pub trait StrSlice {
-    pure fn all(it: fn(char) -> bool) -> bool;
-    pure fn any(it: fn(char) -> bool) -> bool;
-    pure fn contains(needle: &a/str) -> bool;
-    pure fn contains_char(needle: char) -> bool;
-    pure fn each(it: fn(u8) -> bool);
-    pure fn eachi(it: fn(uint, u8) -> bool);
-    pure fn each_char(it: fn(char) -> bool);
-    pure fn each_chari(it: fn(uint, char) -> bool);
-    pure fn ends_with(needle: &str) -> bool;
-    pure fn is_empty() -> bool;
-    pure fn is_not_empty() -> bool;
-    pure fn is_whitespace() -> bool;
-    pure fn is_alphanumeric() -> bool;
+    fn all(it: fn(char) -> bool) -> bool;
+    fn any(it: fn(char) -> bool) -> bool;
+    fn contains(needle: &a/str) -> bool;
+    fn contains_char(needle: char) -> bool;
+    fn each(it: fn(u8) -> bool);
+    fn eachi(it: fn(uint, u8) -> bool);
+    fn each_char(it: fn(char) -> bool);
+    fn each_chari(it: fn(uint, char) -> bool);
+    fn ends_with(needle: &str) -> bool;
+    fn is_empty() -> bool;
+    fn is_not_empty() -> bool;
+    fn is_whitespace() -> bool;
+    fn is_alphanumeric() -> bool;
     pure fn len() -> uint;
     pure fn slice(begin: uint, end: uint) -> ~str;
-    pure fn split(sepfn: fn(char) -> bool) -> ~[~str];
-    pure fn split_char(sep: char) -> ~[~str];
-    pure fn split_str(sep: &a/str) -> ~[~str];
-    pure fn starts_with(needle: &a/str) -> bool;
-    pure fn substr(begin: uint, n: uint) -> ~str;
+    fn split(sepfn: fn(char) -> bool) -> ~[~str];
+    fn split_char(sep: char) -> ~[~str];
+    fn split_str(sep: &a/str) -> ~[~str];
+    fn starts_with(needle: &a/str) -> bool;
+    fn substr(begin: uint, n: uint) -> ~str;
     pure fn to_lower() -> ~str;
     pure fn to_upper() -> ~str;
-    pure fn escape_default() -> ~str;
-    pure fn escape_unicode() -> ~str;
-    pure fn trim() -> ~str;
-    pure fn trim_left() -> ~str;
-    pure fn trim_right() -> ~str;
+    fn escape_default() -> ~str;
+    fn escape_unicode() -> ~str;
+    fn trim() -> ~str;
+    fn trim_left() -> ~str;
+    fn trim_right() -> ~str;
     pure fn to_unique() -> ~str;
     pure fn char_at(i: uint) -> char;
 }
@@ -2100,56 +2100,54 @@ impl &str: StrSlice {
      * contains no characters
      */
     #[inline]
-    pure fn all(it: fn(char) -> bool) -> bool { all(self, it) }
+    fn all(it: fn(char) -> bool) -> bool { all(self, it) }
     /**
      * Return true if a predicate matches any character (and false if it
      * matches none or there are no characters)
      */
     #[inline]
-    pure fn any(it: fn(char) -> bool) -> bool { any(self, it) }
+    fn any(it: fn(char) -> bool) -> bool { any(self, it) }
     /// Returns true if one string contains another
     #[inline]
-    pure fn contains(needle: &a/str) -> bool { contains(self, needle) }
+    fn contains(needle: &a/str) -> bool { contains(self, needle) }
     /// Returns true if a string contains a char
     #[inline]
-    pure fn contains_char(needle: char) -> bool {
-        contains_char(self, needle)
-    }
+    fn contains_char(needle: char) -> bool { contains_char(self, needle) }
     /// Iterate over the bytes in a string
     #[inline]
-    pure fn each(it: fn(u8) -> bool) { each(self, it) }
+    fn each(it: fn(u8) -> bool) { each(self, it) }
     /// Iterate over the bytes in a string, with indices
     #[inline]
-    pure fn eachi(it: fn(uint, u8) -> bool) { eachi(self, it) }
+    fn eachi(it: fn(uint, u8) -> bool) { eachi(self, it) }
     /// Iterate over the chars in a string
     #[inline]
-    pure fn each_char(it: fn(char) -> bool) { each_char(self, it) }
+    fn each_char(it: fn(char) -> bool) { each_char(self, it) }
     /// Iterate over the chars in a string, with indices
     #[inline]
-    pure fn each_chari(it: fn(uint, char) -> bool) { each_chari(self, it) }
+    fn each_chari(it: fn(uint, char) -> bool) { each_chari(self, it) }
     /// Returns true if one string ends with another
     #[inline]
-    pure fn ends_with(needle: &str) -> bool { ends_with(self, needle) }
+    fn ends_with(needle: &str) -> bool { ends_with(self, needle) }
     /// Returns true if the string has length 0
     #[inline]
-    pure fn is_empty() -> bool { is_empty(self) }
+    fn is_empty() -> bool { is_empty(self) }
     /// Returns true if the string has length greater than 0
     #[inline]
-    pure fn is_not_empty() -> bool { is_not_empty(self) }
+    fn is_not_empty() -> bool { is_not_empty(self) }
     /**
      * Returns true if the string contains only whitespace
      *
      * Whitespace characters are determined by `char::is_whitespace`
      */
     #[inline]
-    pure fn is_whitespace() -> bool { is_whitespace(self) }
+    fn is_whitespace() -> bool { is_whitespace(self) }
     /**
      * Returns true if the string contains only alphanumerics
      *
      * Alphanumeric characters are determined by `char::is_alphanumeric`
      */
     #[inline]
-    pure fn is_alphanumeric() -> bool { is_alphanumeric(self) }
+    fn is_alphanumeric() -> bool { is_alphanumeric(self) }
     #[inline]
     /// Returns the size in bytes not counting the null terminator
     pure fn len() -> uint { len(self) }
@@ -2164,29 +2162,29 @@ impl &str: StrSlice {
     pure fn slice(begin: uint, end: uint) -> ~str { slice(self, begin, end) }
     /// Splits a string into substrings using a character function
     #[inline]
-    pure fn split(sepfn: fn(char) -> bool) -> ~[~str] { split(self, sepfn) }
+    fn split(sepfn: fn(char) -> bool) -> ~[~str] { split(self, sepfn) }
     /**
      * Splits a string into substrings at each occurrence of a given character
      */
     #[inline]
-    pure fn split_char(sep: char) -> ~[~str] { split_char(self, sep) }
+    fn split_char(sep: char) -> ~[~str] { split_char(self, sep) }
     /**
      * Splits a string into a vector of the substrings separated by a given
      * string
      */
     #[inline]
-    pure fn split_str(sep: &a/str) -> ~[~str] { split_str(self, sep) }
+    fn split_str(sep: &a/str) -> ~[~str] { split_str(self, sep) }
     /// Returns true if one string starts with another
     #[inline]
-    pure fn starts_with(needle: &a/str) -> bool { starts_with(self, needle) }
+    fn starts_with(needle: &a/str) -> bool { starts_with(self, needle) }
     /**
      * Take a substring of another.
      *
      * Returns a string containing `n` characters starting at byte offset
      * `begin`.
      */
     #[inline]
-    pure fn substr(begin: uint, n: uint) -> ~str { substr(self, begin, n) }
+    fn substr(begin: uint, n: uint) -> ~str { substr(self, begin, n) }
     /// Convert a string to lowercase
     #[inline]
     pure fn to_lower() -> ~str { to_lower(self) }
@@ -2195,20 +2193,20 @@ impl &str: StrSlice {
     pure fn to_upper() -> ~str { to_upper(self) }
     /// Escape each char in `s` with char::escape_default.
     #[inline]
-    pure fn escape_default() -> ~str { escape_default(self) }
+    fn escape_default() -> ~str { escape_default(self) }
     /// Escape each char in `s` with char::escape_unicode.
     #[inline]
-    pure fn escape_unicode() -> ~str { escape_unicode(self) }
+    fn escape_unicode() -> ~str { escape_unicode(self) }
 
     /// Returns a string with leading and trailing whitespace removed
     #[inline]
-    pure fn trim() -> ~str { trim(self) }
+    fn trim() -> ~str { trim(self) }
     /// Returns a string with leading whitespace removed
     #[inline]
-    pure fn trim_left() -> ~str { trim_left(self) }
+    fn trim_left() -> ~str { trim_left(self) }
     /// Returns a string with trailing whitespace removed
     #[inline]
-    pure fn trim_right() -> ~str { trim_right(self) }
+    fn trim_right() -> ~str { trim_right(self) }
 
     #[inline]
     pure fn to_unique() -> ~str { self.slice(0, self.len()) }