Rollup of 25 pull requests

src/doc/index.md

@@ -6,55 +6,72 @@ nav {
 }
 </style>
 
-This page is an overview of the documentation included with your Rust install.
-Other unofficial documentation may exist elsewhere; for example, the [Rust
-Learning] project collects documentation from the community, and [Docs.rs]
-builds documentation for individual Rust packages.
+Welcome to an overview of the documentation provided by the Rust project.
+All of these projects are managed by the Docs Team; there are other
+unofficial documentation resources as well!
 
-# API Documentation
+Many of these resources take the form of "books"; we collectively call these
+"The Rust Bookshelf." Some are large, some are small.
 
-Rust provides a standard library with a number of features; [we host its
-documentation here][api].
+## Learn Rust
 
-# Extended Error Documentation
+If you'd like to learn Rust, this is the spot for you! All of these resources
+assume that you have programmed before, but not in any specific language:
+
+### The Rust Programming Language
+
+Affectionately nicknamed "the book," [The Rust Programming
+Language](book/index.html) will give you an overview of the language from
+first principles. You'll build a few projects along the way, and by the end,
+you'll have a solid grasp of the language.
+
+### Rust By Example
+
+If reading multiple hundreds of pages about a language isn't your style, then
+[Rust By Example](rust-by-example/index.html) has you covered. While the book talks about code with
+a lot of words, RBE shows off a bunch of code, and keeps the talking to a
+minimum. It also includes exercises!
+
+## Use Rust
+
+Once you've gotten familliar with the language, these resources can help you
+when you're actually using it day-to-day.
+
+### The Standard Library
+
+Rust's standard library has [extensive API documentation](std/index.html),
+with explanations of how to use various things, as well as example code for
+accomplishing various tasks.
+
+### The Cargo Book
+
+[The Cargo Book](cargo/index.html) is a guide to Cargo, Rust's build tool and dependency manager.
+
+### The Rustdoc Book
+
+[The Rustdoc Book](rustdoc/index.html) describes our documentation tool, `rustdoc`.
+
+### Extended Error Listing
 
 Many of Rust's errors come with error codes, and you can request extended
-diagnostics from the compiler on those errors. We also [have the text of those
-extended errors on the web][err], if you prefer to read them that way.
-
-# The Rust Bookshelf
-
-Rust provides a number of book-length sets of documentation, collectively
-nicknamed 'The Rust Bookshelf.'
-
-* [The Rust Programming Language][book] teaches you how to program in Rust.
-* [Rust By Example][rbe] teaches you how to program in Rust using editable examples.
-* [The Cargo Book][cargo-book] is a guide to Cargo, Rust's build tool and dependency manager.
-* [The Unstable Book][unstable-book] has documentation for unstable features.
-* [The Rustonomicon][nomicon] is your guidebook to the dark arts of unsafe Rust.
-* [The Reference][ref] is not a formal spec, but is more detailed and comprehensive than the book.
-* [The Rustdoc Book][rustdoc-book] describes our documentation tool, `rustdoc`.
-
-Initially, documentation lands in the Unstable Book, and then, as part of the
-stabilization process, is moved into the Book, Nomicon, or Reference.
-
-Another few words about the reference: it is guaranteed to be accurate, but not
-complete. We have a policy that features must have documentation to be stabilized,
-but we did not always have this policy, and so there are some stable things that
-are not yet in the reference. We're working on back-filling things that landed
-before this policy was put into place. That work is being tracked
-[here][refchecklist].
-
-[Rust Learning]: https://github.com/ctjhoa/rust-learning
-[Docs.rs]: https://docs.rs/
-[api]: std/index.html
-[ref]: reference/index.html
-[refchecklist]: https://github.com/rust-lang-nursery/reference/issues/9
-[err]: error-index.html
-[book]: book/index.html
-[rbe]: rust-by-example/index.html
-[nomicon]: nomicon/index.html
-[unstable-book]: unstable-book/index.html
-[rustdoc-book]: rustdoc/index.html
-[cargo-book]: cargo/index.html
+diagnostics from the compiler on those errors. You can also [read them
+here](error-index.html), if you prefer to read them that way.
+
+## Master Rust
+
+Once you're quite familiar with the language, you may find these advanced
+resources useful.
+
+### The Reference
+
+[The Reference](reference/index.html) is not a formal spec, but is more detailed and
+comprehensive than the book.
+
+### The Rustonomicon
+
+[The Rustonomicon](nomicon/index.html) is your guidebook to the dark arts of unsafe
+Rust. It's also sometimes called "the 'nomicon."
+
+### The Unstable Book
 
+[The Unstable Book](unstable-book/index.html) has documentation for unstable features.

src/liballoc/borrow.rs

@@ -59,6 +59,7 @@ pub trait ToOwned {
     /// let vv: Vec<i32> = v.to_owned();
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
+    #[must_use = "cloning is often expensive and is not expected to have side effects"]
     fn to_owned(&self) -> Self::Owned;
 
     /// Uses borrowed data to replace owned data, usually by cloning.

src/liballoc/lib.rs

@@ -99,7 +99,6 @@
 #![feature(fundamental)]
 #![feature(generic_param_attrs)]
 #![cfg_attr(stage0, feature(i128_type))]
-#![feature(iter_rfold)]
 #![feature(lang_items)]
 #![feature(needs_allocator)]
 #![feature(nonzero)]

src/liballoc/string.rs

@@ -1517,7 +1517,7 @@ impl String {
         }
     }
 
-    /// Creates a splicing iterator that removes the specified range in the string,
+    /// Removes the specified range in the string,
     /// and replaces it with the given string.
     /// The given string doesn't need to be the same length as the range.
     ///
@@ -1537,21 +1537,20 @@ impl String {
     /// Basic usage:
     ///
     /// ```
-    /// #![feature(splice)]
     /// let mut s = String::from("α is alpha, β is beta");
     /// let beta_offset = s.find('β').unwrap_or(s.len());
     ///
     /// // Replace the range up until the β from the string
-    /// s.splice(..beta_offset, "Α is capital alpha; ");
+    /// s.replace_range(..beta_offset, "Α is capital alpha; ");
     /// assert_eq!(s, "Α is capital alpha; β is beta");
     /// ```
-    #[unstable(feature = "splice", reason = "recently added", issue = "44643")]
-    pub fn splice<R>(&mut self, range: R, replace_with: &str)
+    #[stable(feature = "splice", since = "1.27.0")]
+    pub fn replace_range<R>(&mut self, range: R, replace_with: &str)
         where R: RangeBounds<usize>
     {
         // Memory safety
         //
-        // The String version of Splice does not have the memory safety issues
+        // Replace_range does not have the memory safety issues of a vector Splice.
         // of the vector version. The data is just plain bytes.
 
         match range.start() {

src/liballoc/tests/string.rs

@@ -443,53 +443,53 @@ fn test_drain() {
 }
 
 #[test]
-fn test_splice() {
+fn test_replace_range() {
     let mut s = "Hello, world!".to_owned();
-    s.splice(7..12, "世界");
+    s.replace_range(7..12, "世界");
     assert_eq!(s, "Hello, 世界!");
 }
 
 #[test]
 #[should_panic]
-fn test_splice_char_boundary() {
+fn test_replace_range_char_boundary() {
     let mut s = "Hello, 世界!".to_owned();
-    s.splice(..8, "");
+    s.replace_range(..8, "");
 }
 
 #[test]
-fn test_splice_inclusive_range() {
+fn test_replace_range_inclusive_range() {
     let mut v = String::from("12345");
-    v.splice(2..=3, "789");
+    v.replace_range(2..=3, "789");
     assert_eq!(v, "127895");
-    v.splice(1..=2, "A");
+    v.replace_range(1..=2, "A");
     assert_eq!(v, "1A895");
 }
 
 #[test]
 #[should_panic]
-fn test_splice_out_of_bounds() {
+fn test_replace_range_out_of_bounds() {
     let mut s = String::from("12345");
-    s.splice(5..6, "789");
+    s.replace_range(5..6, "789");
 }
 
 #[test]
 #[should_panic]
-fn test_splice_inclusive_out_of_bounds() {
+fn test_replace_range_inclusive_out_of_bounds() {
     let mut s = String::from("12345");
-    s.splice(5..=5, "789");
+    s.replace_range(5..=5, "789");
 }
 
 #[test]
-fn test_splice_empty() {
+fn test_replace_range_empty() {
     let mut s = String::from("12345");
-    s.splice(1..2, "");
+    s.replace_range(1..2, "");
     assert_eq!(s, "1345");
 }
 
 #[test]
-fn test_splice_unbounded() {
+fn test_replace_range_unbounded() {
     let mut s = String::from("12345");
-    s.splice(.., "");
+    s.replace_range(.., "");
     assert_eq!(s, "");
 }
 

src/liballoc/vec.rs

@@ -1283,6 +1283,49 @@ impl<T> Vec<T> {
         }
         other
     }
+
+    /// Resizes the `Vec` in-place so that `len` is equal to `new_len`.
+    ///
+    /// If `new_len` is greater than `len`, the `Vec` is extended by the
+    /// difference, with each additional slot filled with the result of
+    /// calling the closure `f`. The return values from `f` will end up
+    /// in the `Vec` in the order they have been generated.
+    ///
+    /// If `new_len` is less than `len`, the `Vec` is simply truncated.
+    ///
+    /// This method uses a closure to create new values on every push. If
+    /// you'd rather [`Clone`] a given value, use [`resize`]. If you want
+    /// to use the [`Default`] trait to generate values, you can pass
+    /// [`Default::default()`] as the second argument..
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(vec_resize_with)]
+    ///
+    /// let mut vec = vec![1, 2, 3];
+    /// vec.resize_with(5, Default::default);
+    /// assert_eq!(vec, [1, 2, 3, 0, 0]);
+    ///
+    /// let mut vec = vec![];
+    /// let mut p = 1;
+    /// vec.resize_with(4, || { p *= 2; p });
+    /// assert_eq!(vec, [2, 4, 8, 16]);
+    /// ```
+    ///
+    /// [`resize`]: #method.resize
+    /// [`Clone`]: ../../std/clone/trait.Clone.html
+    #[unstable(feature = "vec_resize_with", issue = "41758")]
+    pub fn resize_with<F>(&mut self, new_len: usize, f: F)
+        where F: FnMut() -> T
+    {
+        let len = self.len();
+        if new_len > len {
+            self.extend_with(new_len - len, ExtendFunc(f));
+        } else {
+            self.truncate(new_len);
+        }
+    }
 }
 
 impl<T: Clone> Vec<T> {
@@ -1293,8 +1336,8 @@ impl<T: Clone> Vec<T> {
     /// If `new_len` is less than `len`, the `Vec` is simply truncated.
     ///
     /// This method requires [`Clone`] to be able clone the passed value. If
-    /// you'd rather create a value with [`Default`] instead, see
-    /// [`resize_default`].
+    /// you need more flexibility (or want to rely on [`Default`] instead of
+    /// [`Clone`]), use [`resize_with`].
     ///
     /// # Examples
     ///
@@ -1310,7 +1353,7 @@ impl<T: Clone> Vec<T> {
     ///
     /// [`Clone`]: ../../std/clone/trait.Clone.html
     /// [`Default`]: ../../std/default/trait.Default.html
-    /// [`resize_default`]: #method.resize_default
+    /// [`resize_with`]: #method.resize_with
     #[stable(feature = "vec_resize", since = "1.5.0")]
     pub fn resize(&mut self, new_len: usize, value: T) {
         let len = self.len();
@@ -1389,24 +1432,31 @@ impl<T: Default> Vec<T> {
 
 // This code generalises `extend_with_{element,default}`.
 trait ExtendWith<T> {
-    fn next(&self) -> T;
+    fn next(&mut self) -> T;
     fn last(self) -> T;
 }
 
 struct ExtendElement<T>(T);
 impl<T: Clone> ExtendWith<T> for ExtendElement<T> {
-    fn next(&self) -> T { self.0.clone() }
+    fn next(&mut self) -> T { self.0.clone() }
     fn last(self) -> T { self.0 }
 }
 
 struct ExtendDefault;
 impl<T: Default> ExtendWith<T> for ExtendDefault {
-    fn next(&self) -> T { Default::default() }
+    fn next(&mut self) -> T { Default::default() }
     fn last(self) -> T { Default::default() }
 }
+
+struct ExtendFunc<F>(F);
+impl<T, F: FnMut() -> T> ExtendWith<T> for ExtendFunc<F> {
+    fn next(&mut self) -> T { (self.0)() }
+    fn last(mut self) -> T { (self.0)() }
+}
+
 impl<T> Vec<T> {
     /// Extend the vector by `n` values, using the given generator.
-    fn extend_with<E: ExtendWith<T>>(&mut self, n: usize, value: E) {
+    fn extend_with<E: ExtendWith<T>>(&mut self, n: usize, mut value: E) {
         self.reserve(n);
 
         unsafe {

src/libcore/clone.rs

@@ -105,6 +105,7 @@ pub trait Clone : Sized {
     /// assert_eq!("Hello", hello.clone());
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
+    #[must_use = "cloning is often expensive and is not expected to have side effects"]
     fn clone(&self) -> Self;
 
     /// Performs copy-assignment from `source`.