---

yaml
---
r: 208361
b: refs/heads/snap-stage3
c: e780fb2
h: refs/heads/master
i:
  208359: 03291f2
v: v3

Author: steveklabnik

[refs]

@@ -1,7 +1,7 @@
 ---
 refs/heads/master: 38a97becdf3e6a6157f6f7ec2d98ade8d8edc193
 refs/heads/snap-stage1: e33de59e47c5076a89eadeb38f4934f58a3618a6
-refs/heads/snap-stage3: 3ca008dcf12283247122f25928630f2a484ff768
+refs/heads/snap-stage3: e780fb270c5296a87ff9dc1442fc141f69e77fcd
 refs/heads/try: 7b4ef47b7805a402d756fb8157101f64880a522f
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/dist-snap: ba4081a5a8573875fed17545846f6f6902c8ba8d

branches/snap-stage3/src/doc/trpl/SUMMARY.md

@@ -15,6 +15,7 @@
     * [Concurrency](concurrency.md)
     * [Error Handling](error-handling.md)
     * [FFI](ffi.md)
+    * [Borrow and AsRef](borrow-and-asref.md)
 * [Syntax and Semantics](syntax-and-semantics.md)
     * [Variable Bindings](variable-bindings.md)
     * [Functions](functions.md)

branches/snap-stage3/src/doc/trpl/borrow-and-asref.md

@@ -0,0 +1,93 @@
+% Borrow and AsRef
+
+The [`Borrow`][borrow] and [`AsRef`][asref] traits are very similar, but
+different. Here’s a quick refresher on what these two traits mean.
+
+[borrow]: ../std/borrow/trait.Borrow.html
+[asref]: ../std/convert/trait.AsRef.html
+
+# Borrow
+
+The `Borrow` trait is used when you’re writing a datastructure, and you want to
+use either an owned or borrowed type as synonymous for some purpose.
+
+For example, [`HashMap`][hashmap] has a [`get` method][get] which uses `Borrow`:
+
+```rust,ignore
+fn get<Q: ?Sized>(&self, k: &Q) -> Option<&V>
+    where K: Borrow<Q>,
+          Q: Hash + Eq
+```
+
+[hashmap]: ../std/collections/struct.HashMap.html
+[get]: ../std/collections/struct.HashMap.html#method.get
+
+This signature is pretty complicated. The `K` parameter is what we’re interested
+in here. It refers to a parameter of the `HashMap` itself:
+
+```rust,ignore
+struct HashMap<K, V, S = RandomState> {
+```
+
+The `K` parameter is the type of _key_ the `HashMap` uses. So, looking at
+the signature of `get()` again, we can use `get()` when the key implements
+`Borrow<Q>`. That way, we can make a `HashMap` which uses `String` keys,
+but use `&str`s when we’re searching:
+
+```rust
+use std::collections::HashMap;
+
+let mut map = HashMap::new();
+map.insert("Foo".to_string(), 42);
+
+assert_eq!(map.get("Foo"), Some(&42));
+```
+
+This is because the standard library has `impl Borrow<str> for String`.
+
+For most types, when you want to take an owned or borrowed type, a `&T` is
+enough. But one area where `Borrow` is effective is when there’s more than one
+kind of borrowed value. Slices are an area where this is especially true: you
+can have both an `&[T]` or a `&mut [T]`. If we wanted to accept both of these
+types, `Borrow` is up for it:
+
+```
+use std::borrow::Borrow;
+use std::fmt::Display;
+
+fn foo<T: Borrow<i32> + Display>(a: T) {
+    println!("a is borrowed: {}", a);
+}
+
+let mut i = 5;
+
+foo(&i);
+foo(&mut i);
+```
+
+This will print out `a is borrowed: 5` twice.
+
+# AsRef
+
+The `AsRef` trait is a conversion trait. It’s used for converting some value to
+a reference in generic code. Like this:
+
+```rust
+let s = "Hello".to_string();
+
+fn foo<T: AsRef<str>>(s: T) {
+    let slice = s.as_ref();
+}
+```
+
+# Which should I use?
+
+We can see how they’re kind of the same: they both deal with owned and borrowed
+versions of some type. However, they’re a bit different.
+
+Choose `Borrow` when you want to abstract over different kinds of borrowing, or
+when you’re building a datastructure that treats owned and borrowed values in
+equivalent ways, such as hashing and comparison.
+
+Choose `AsRef` when you want to convert something to a reference directly, and
+you’re writing generic code.

branches/snap-stage3/src/libcollections/borrow.rs

@@ -37,6 +37,11 @@ use self::Cow::*;
 /// trait: if `T: Borrow<U>`, then `&U` can be borrowed from `&T`.  A given
 /// type can be borrowed as multiple different types. In particular, `Vec<T>:
 /// Borrow<Vec<T>>` and `Vec<T>: Borrow<[T]>`.
+///
+/// `Borrow` is very similar to, but different than, `AsRef`. See
+/// [the book][book] for more.
+///
+/// [book]: ../../book/borrow-and-asref.html
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait Borrow<Borrowed: ?Sized> {
     /// Immutably borrows from an owned value.

branches/snap-stage3/src/libcore/convert.rs

@@ -24,6 +24,11 @@ use marker::Sized;
 
 /// A cheap, reference-to-reference conversion.
 ///
+/// `AsRef` is very similar to, but different than, `Borrow`. See
+/// [the book][book] for more.
+///
+/// [book]: ../../book/borrow-and-asref.html
+///
 /// # Examples
 ///
 /// Both `String` and `&str` implement `AsRef<str>`:

branches/snap-stage3/src/libcore/slice.rs

@@ -140,7 +140,7 @@ impl<T> SliceExt for [T] {
             assume(!p.is_null());
             if mem::size_of::<T>() == 0 {
                 Iter {ptr: p,
-                      end: ((p as usize).wrapping_add(self.len())) as *const T,
+                      end: (p as usize + self.len()) as *const T,
                       _marker: marker::PhantomData}
             } else {
                 Iter {ptr: p,
@@ -277,7 +277,7 @@ impl<T> SliceExt for [T] {
             assume(!p.is_null());
             if mem::size_of::<T>() == 0 {
                 IterMut {ptr: p,
-                         end: ((p as usize).wrapping_add(self.len())) as *mut T,
+                         end: (p as usize + self.len()) as *mut T,
                          _marker: marker::PhantomData}
             } else {
                 IterMut {ptr: p,
@@ -632,17 +632,35 @@ fn size_from_ptr<T>(_: *const T) -> usize {
 
 
 // Use macros to be generic over const/mut
-macro_rules! slice_offset {
+//
+// They require non-negative `$by` because otherwise the expression
+// `(ptr as usize + $by)` would interpret `-1` as `usize::MAX` (and
+// thus trigger a panic when overflow checks are on).
+
+// Use this to do `$ptr + $by`, where `$by` is non-negative.
+macro_rules! slice_add_offset {
     ($ptr:expr, $by:expr) => {{
         let ptr = $ptr;
         if size_from_ptr(ptr) == 0 {
-            transmute((ptr as isize).wrapping_add($by))
+            transmute(ptr as usize + $by)
         } else {
             ptr.offset($by)
         }
     }};
 }
 
+// Use this to do `$ptr - $by`, where `$by` is non-negative.
+macro_rules! slice_sub_offset {
+    ($ptr:expr, $by:expr) => {{
+        let ptr = $ptr;
+        if size_from_ptr(ptr) == 0 {
+            transmute(ptr as usize - $by)
+        } else {
+            ptr.offset(-$by)
+        }
+    }};
+}
+
 macro_rules! slice_ref {
     ($ptr:expr) => {{
         let ptr = $ptr;
@@ -665,24 +683,22 @@ macro_rules! iterator {
             #[inline]
             fn next(&mut self) -> Option<$elem> {
                 // could be implemented with slices, but this avoids bounds checks
-                if self.ptr == self.end {
-                    None
-                } else {
-                    unsafe {
-                        if mem::size_of::<T>() != 0 {
-                            ::intrinsics::assume(!self.ptr.is_null());
-                            ::intrinsics::assume(!self.end.is_null());
-                        }
+                unsafe {
+                    ::intrinsics::assume(!self.ptr.is_null());
+                    ::intrinsics::assume(!self.end.is_null());
+                    if self.ptr == self.end {
+                        None
+                    } else {
                         let old = self.ptr;
-                        self.ptr = slice_offset!(self.ptr, 1);
+                        self.ptr = slice_add_offset!(self.ptr, 1);
                         Some(slice_ref!(old))
                     }
                 }
             }
 
             #[inline]
             fn size_hint(&self) -> (usize, Option<usize>) {
-                let diff = (self.end as usize).wrapping_sub(self.ptr as usize);
+                let diff = (self.end as usize) - (self.ptr as usize);
                 let size = mem::size_of::<T>();
                 let exact = diff / (if size == 0 {1} else {size});
                 (exact, Some(exact))
@@ -710,15 +726,13 @@ macro_rules! iterator {
             #[inline]
             fn next_back(&mut self) -> Option<$elem> {
                 // could be implemented with slices, but this avoids bounds checks
-                if self.end == self.ptr {
-                    None
-                } else {
-                    unsafe {
-                        self.end = slice_offset!(self.end, -1);
-                        if mem::size_of::<T>() != 0 {
-                            ::intrinsics::assume(!self.ptr.is_null());
-                            ::intrinsics::assume(!self.end.is_null());
-                        }
+                unsafe {
+                    ::intrinsics::assume(!self.ptr.is_null());
+                    ::intrinsics::assume(!self.end.is_null());
+                    if self.end == self.ptr {
+                        None
+                    } else {
+                        self.end = slice_sub_offset!(self.end, 1);
                         Some(slice_ref!(self.end))
                     }
                 }
@@ -728,29 +742,29 @@ macro_rules! iterator {
 }
 
 macro_rules! make_slice {
-    ($start: expr, $end: expr) => {{
-        let start = $start;
-        let diff = ($end as usize).wrapping_sub(start as usize);
-        if size_from_ptr(start) == 0 {
-            // use a non-null pointer value
-            unsafe { from_raw_parts(1 as *const _, diff) }
+    ($t: ty => $result: ty: $start: expr, $end: expr) => {{
+        let diff = $end as usize - $start as usize;
+        let len = if mem::size_of::<T>() == 0 {
+            diff
         } else {
-            let len = diff / size_from_ptr(start);
-            unsafe { from_raw_parts(start, len) }
+            diff / mem::size_of::<$t>()
+        };
+        unsafe {
+            from_raw_parts($start, len)
         }
     }}
 }
 
 macro_rules! make_mut_slice {
-    ($start: expr, $end: expr) => {{
-        let start = $start;
-        let diff = ($end as usize).wrapping_sub(start as usize);
-        if size_from_ptr(start) == 0 {
-            // use a non-null pointer value
-            unsafe { from_raw_parts_mut(1 as *mut _, diff) }
+    ($t: ty => $result: ty: $start: expr, $end: expr) => {{
+        let diff = $end as usize - $start as usize;
+        let len = if mem::size_of::<T>() == 0 {
+            diff
         } else {
-            let len = diff / size_from_ptr(start);
-            unsafe { from_raw_parts_mut(start, len) }
+            diff / mem::size_of::<$t>()
+        };
+        unsafe {
+            from_raw_parts_mut($start, len)
         }
     }}
 }
@@ -773,14 +787,14 @@ impl<'a, T> Iter<'a, T> {
     /// iterator can continue to be used while this exists.
     #[unstable(feature = "core")]
     pub fn as_slice(&self) -> &'a [T] {
-        make_slice!(self.ptr, self.end)
+        make_slice!(T => &'a [T]: self.ptr, self.end)
     }
 
     // Helper function for Iter::nth
     fn iter_nth(&mut self, n: usize) -> Option<&'a T> {
         match self.as_slice().get(n) {
             Some(elem_ref) => unsafe {
-                self.ptr = slice_offset!(self.ptr, (n as isize).wrapping_add(1));
+                self.ptr = slice_add_offset!(elem_ref as *const _, 1);
                 Some(slice_ref!(elem_ref))
             },
             None => {
@@ -813,7 +827,12 @@ impl<'a, T> RandomAccessIterator for Iter<'a, T> {
     fn idx(&mut self, index: usize) -> Option<&'a T> {
         unsafe {
             if index < self.indexable() {
-                Some(slice_ref!(self.ptr.offset(index as isize)))
+                if mem::size_of::<T>() == 0 {
+                    // Use a non-null pointer value
+                    Some(&mut *(1 as *mut _))
+                } else {
+                    Some(transmute(self.ptr.offset(index as isize)))
+                }
             } else {
                 None
             }
@@ -841,14 +860,14 @@ impl<'a, T> IterMut<'a, T> {
     /// restricted lifetimes that do not consume the iterator.
     #[unstable(feature = "core")]
     pub fn into_slice(self) -> &'a mut [T] {
-        make_mut_slice!(self.ptr, self.end)
+        make_mut_slice!(T => &'a mut [T]: self.ptr, self.end)
     }
 
     // Helper function for IterMut::nth
     fn iter_nth(&mut self, n: usize) -> Option<&'a mut T> {
-        match make_mut_slice!(self.ptr, self.end).get_mut(n) {
+        match make_mut_slice!(T => &'a mut [T]: self.ptr, self.end).get_mut(n) {
             Some(elem_ref) => unsafe {
-                self.ptr = slice_offset!(self.ptr, (n as isize).wrapping_add(1));
+                self.ptr = slice_add_offset!(elem_ref as *mut _, 1);
                 Some(slice_ref!(elem_ref))
             },
             None => {

branches/snap-stage3/src/rust-installer

@@ -1 +1 @@
-Subproject commit e54d4823d26cdb3f98e5a1b17e1c257cd329aa61
+Subproject commit ebc6b04c29591108d3f28e724b4b9b74cd1232e6