diff --git a/src/doc/book/guessing-game.md b/src/doc/book/guessing-game.md index b9b6e9a4c9568..e071bfdf8bce1 100644 --- a/src/doc/book/guessing-game.md +++ b/src/doc/book/guessing-game.md @@ -295,7 +295,7 @@ Rust warns us that we haven’t used the `Result` value. This warning comes from a special annotation that `io::Result` has. Rust is trying to tell you that you haven’t handled a possible error. The right way to suppress the error is to actually write error handling. Luckily, if we want to crash if there’s -a problem, we can use these two little methods. If we can recover from the +a problem, we can use `expect()`. If we can recover from the error somehow, we’d do something else, but we’ll save that for a future project. diff --git a/src/doc/book/inline-assembly.md b/src/doc/book/inline-assembly.md index 7659c4ff88dae..a5a2d7ce74e7d 100644 --- a/src/doc/book/inline-assembly.md +++ b/src/doc/book/inline-assembly.md @@ -2,8 +2,7 @@ For extremely low-level manipulations and performance reasons, one might wish to control the CPU directly. Rust supports using inline -assembly to do this via the `asm!` macro. The syntax roughly matches -that of GCC & Clang: +assembly to do this via the `asm!` macro. ```ignore asm!(assembly template diff --git a/src/doc/book/testing.md b/src/doc/book/testing.md index d57664bf07e4d..59d07e4f81c6e 100644 --- a/src/doc/book/testing.md +++ b/src/doc/book/testing.md @@ -515,7 +515,3 @@ you add more examples. We haven’t covered all of the details with writing documentation tests. For more, please see the [Documentation chapter](documentation.html). - -One final note: documentation tests *cannot* be run on binary crates. -To see more on file arrangement see the [Crates and -Modules](crates-and-modules.html) section. diff --git a/src/doc/reference.md b/src/doc/reference.md index 8e655ee22e302..4c5fd31b96ed1 100644 --- a/src/doc/reference.md +++ b/src/doc/reference.md @@ -3328,6 +3328,10 @@ The primitive types are the following: * The boolean type `bool` with values `true` and `false`. * The machine types (integer and floating-point). * The machine-dependent integer types. +* Arrays +* Tuples +* Slices +* Function pointers #### Machine types diff --git a/src/liballoc/arc.rs b/src/liballoc/arc.rs index 74325afaebd48..b5d7279edb006 100644 --- a/src/liballoc/arc.rs +++ b/src/liballoc/arc.rs @@ -201,11 +201,12 @@ impl Arc { Arc { _ptr: unsafe { Shared::new(Box::into_raw(x)) } } } - /// Unwraps the contained value if the `Arc` has only one strong reference. - /// This will succeed even if there are outstanding weak references. + /// Unwraps the contained value if the `Arc` has exactly one strong reference. /// /// Otherwise, an `Err` is returned with the same `Arc`. /// + /// This will succeed even if there are outstanding weak references. + /// /// # Examples /// /// ``` diff --git a/src/liballoc/rc.rs b/src/liballoc/rc.rs index 162312e2457da..dc283f5acdff8 100644 --- a/src/liballoc/rc.rs +++ b/src/liballoc/rc.rs @@ -224,11 +224,12 @@ impl Rc { } } - /// Unwraps the contained value if the `Rc` has only one strong reference. - /// This will succeed even if there are outstanding weak references. + /// Unwraps the contained value if the `Rc` has exactly one strong reference. /// /// Otherwise, an `Err` is returned with the same `Rc`. /// + /// This will succeed even if there are outstanding weak references. + /// /// # Examples /// /// ``` diff --git a/src/libcollections/binary_heap.rs b/src/libcollections/binary_heap.rs index bd329949618e5..29258180c67ba 100644 --- a/src/libcollections/binary_heap.rs +++ b/src/libcollections/binary_heap.rs @@ -167,6 +167,49 @@ use vec::{self, Vec}; /// item's ordering relative to any other item, as determined by the `Ord` /// trait, changes while it is in the heap. This is normally only possible /// through `Cell`, `RefCell`, global state, I/O, or unsafe code. +/// +/// # Examples +/// +/// ``` +/// use std::collections::BinaryHeap; +/// +/// // type inference lets us omit an explicit type signature (which +/// // would be `BinaryHeap` in this example). +/// let mut heap = BinaryHeap::new(); +/// +/// // We can use peek to look at the next item in the heap. In this case, +/// // there's no items in there yet so we get None. +/// assert_eq!(heap.peek(), None); +/// +/// // Let's add some scores... +/// heap.push(1); +/// heap.push(5); +/// heap.push(2); +/// +/// // Now peek shows the most important item in the heap. +/// assert_eq!(heap.peek(), Some(&5)); +/// +/// // We can check the length of a heap. +/// assert_eq!(heap.len(), 3); +/// +/// // We can iterate over the items in the heap, although they are returned in +/// // a random order. +/// for x in heap.iter() { +/// println!("{}", x); +/// } +/// +/// // If we instead pop these scores, they should come back in order. +/// assert_eq!(heap.pop(), Some(5)); +/// assert_eq!(heap.pop(), Some(2)); +/// assert_eq!(heap.pop(), Some(1)); +/// assert_eq!(heap.pop(), None); +/// +/// // We can clear the heap of any remaining items. +/// heap.clear(); +/// +/// // The heap should now be empty. +/// assert!(heap.is_empty()) +/// ``` #[stable(feature = "rust1", since = "1.0.0")] pub struct BinaryHeap { data: Vec, @@ -203,6 +246,8 @@ impl BinaryHeap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BinaryHeap; /// let mut heap = BinaryHeap::new(); @@ -220,6 +265,8 @@ impl BinaryHeap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BinaryHeap; /// let mut heap = BinaryHeap::with_capacity(10); @@ -235,6 +282,8 @@ impl BinaryHeap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BinaryHeap; /// let heap = BinaryHeap::from(vec![1, 2, 3, 4]); @@ -253,6 +302,8 @@ impl BinaryHeap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BinaryHeap; /// let mut heap = BinaryHeap::new(); @@ -273,6 +324,8 @@ impl BinaryHeap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BinaryHeap; /// let mut heap = BinaryHeap::with_capacity(100); @@ -297,6 +350,8 @@ impl BinaryHeap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BinaryHeap; /// let mut heap = BinaryHeap::new(); @@ -318,6 +373,8 @@ impl BinaryHeap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BinaryHeap; /// let mut heap = BinaryHeap::new(); @@ -331,6 +388,19 @@ impl BinaryHeap { } /// Discards as much additional capacity as possible. + /// + /// # Examples + /// + /// Basic usage: + /// + /// ``` + /// use std::collections::BinaryHeap; + /// let mut heap: BinaryHeap = BinaryHeap::with_capacity(100); + /// + /// assert!(heap.capacity() >= 100); + /// heap.shrink_to_fit(); + /// assert!(heap.capacity() == 0); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn shrink_to_fit(&mut self) { self.data.shrink_to_fit(); @@ -341,6 +411,8 @@ impl BinaryHeap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BinaryHeap; /// let mut heap = BinaryHeap::from(vec![1, 3]); @@ -364,6 +436,8 @@ impl BinaryHeap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BinaryHeap; /// let mut heap = BinaryHeap::new(); @@ -386,6 +460,8 @@ impl BinaryHeap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// #![feature(binary_heap_extras)] /// @@ -424,6 +500,8 @@ impl BinaryHeap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// #![feature(binary_heap_extras)] /// @@ -454,6 +532,8 @@ impl BinaryHeap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BinaryHeap; /// let heap = BinaryHeap::from(vec![1, 2, 3, 4, 5, 6, 7]); @@ -474,6 +554,8 @@ impl BinaryHeap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BinaryHeap; /// @@ -571,12 +653,40 @@ impl BinaryHeap { } /// Returns the length of the binary heap. + /// + /// # Examples + /// + /// Basic usage: + /// + /// ``` + /// use std::collections::BinaryHeap; + /// let mut heap = BinaryHeap::from(vec![1, 3]); + /// + /// assert_eq!(heap.len(), 2); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn len(&self) -> usize { self.data.len() } /// Checks if the binary heap is empty. + /// + /// # Examples + /// + /// Basic usage: + /// + /// ``` + /// use std::collections::BinaryHeap; + /// let mut heap = BinaryHeap::new(); + /// + /// assert!(heap.is_empty()); + /// + /// heap.push(3); + /// heap.push(5); + /// heap.push(1); + /// + /// assert!(!heap.is_empty()); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn is_empty(&self) -> bool { self.len() == 0 @@ -585,6 +695,23 @@ impl BinaryHeap { /// Clears the binary heap, returning an iterator over the removed elements. /// /// The elements are removed in arbitrary order. + /// + /// # Examples + /// + /// Basic usage: + /// + /// ``` + /// use std::collections::BinaryHeap; + /// let mut heap = BinaryHeap::from(vec![1, 3]); + /// + /// assert!(!heap.is_empty()); + /// + /// for x in heap.drain() { + /// println!("{}", x); + /// } + /// + /// assert!(heap.is_empty()); + /// ``` #[inline] #[stable(feature = "drain", since = "1.6.0")] pub fn drain(&mut self) -> Drain { @@ -592,6 +719,21 @@ impl BinaryHeap { } /// Drops all items from the binary heap. + /// + /// # Examples + /// + /// Basic usage: + /// + /// ``` + /// use std::collections::BinaryHeap; + /// let mut heap = BinaryHeap::from(vec![1, 3]); + /// + /// assert!(!heap.is_empty()); + /// + /// heap.clear(); + /// + /// assert!(heap.is_empty()); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn clear(&mut self) { self.drain(); @@ -809,6 +951,8 @@ impl IntoIterator for BinaryHeap { /// /// # Examples /// + /// Basic usage: + /// /// ``` /// use std::collections::BinaryHeap; /// let heap = BinaryHeap::from(vec![1, 2, 3, 4]); diff --git a/src/libcollections/btree/set.rs b/src/libcollections/btree/set.rs index 1cd50c2dcbe9e..dc653b446da45 100644 --- a/src/libcollections/btree/set.rs +++ b/src/libcollections/btree/set.rs @@ -38,6 +38,36 @@ use Bound; /// [`Ord`]: ../../core/cmp/trait.Ord.html /// [`Cell`]: ../../std/cell/struct.Cell.html /// [`RefCell`]: ../../std/cell/struct.RefCell.html +/// +/// # Examples +/// +/// ``` +/// use std::collections::BTreeSet; +/// +/// // Type inference lets us omit an explicit type signature (which +/// // would be `BTreeSet<&str>` in this example). +/// let mut books = BTreeSet::new(); +/// +/// // Add some books. +/// books.insert("A Dance With Dragons"); +/// books.insert("To Kill a Mockingbird"); +/// books.insert("The Odyssey"); +/// books.insert("The Great Gatsby"); +/// +/// // Check for a specific one. +/// if !books.contains("The Winds of Winter") { +/// println!("We have {} books, but The Winds of Winter ain't one.", +/// books.len()); +/// } +/// +/// // Remove a book. +/// books.remove("The Odyssey"); +/// +/// // Iterate over everything. +/// for book in &books { +/// println!("{}", book); +/// } +/// ``` #[derive(Clone, Hash, PartialEq, Eq, Ord, PartialOrd)] #[stable(feature = "rust1", since = "1.0.0")] pub struct BTreeSet { diff --git a/src/libcore/hash/sip.rs b/src/libcore/hash/sip.rs index 722d77a8a11ef..342071f1b51b7 100644 --- a/src/libcore/hash/sip.rs +++ b/src/libcore/hash/sip.rs @@ -19,15 +19,17 @@ use super::Hasher; /// /// See: http://131002.net/siphash/ /// -/// Consider this as a main "general-purpose" hash for all hashtables: it -/// runs at good speed (competitive with spooky and city) and permits -/// strong _keyed_ hashing. Key your hashtables from a strong RNG, -/// such as `rand::Rng`. +/// This is currently the default hashing function used by standard library +/// (eg. `collections::HashMap` uses it by default). /// -/// Although the SipHash algorithm is considered to be cryptographically -/// strong, this implementation has not been reviewed for such purposes. -/// As such, all cryptographic uses of this implementation are strongly -/// discouraged. +/// SipHash is a general-purpose hashing function: it runs at a good +/// speed (competitive with Spooky and City) and permits strong _keyed_ +/// hashing. This lets you key your hashtables from a strong RNG, such as +/// [`rand::os::OsRng`](https://doc.rust-lang.org/rand/rand/os/struct.OsRng.html). +/// +/// Although the SipHash algorithm is considered to be generally strong, +/// it is not intended for cryptographic purposes. As such, all +/// cryptographic uses of this implementation are _strongly discouraged_. #[stable(feature = "rust1", since = "1.0.0")] pub struct SipHasher { k0: u64, diff --git a/src/librustc_typeck/check/method/suggest.rs b/src/librustc_typeck/check/method/suggest.rs index 7dc9d46c303f0..cdf7e1bd33aa9 100644 --- a/src/librustc_typeck/check/method/suggest.rs +++ b/src/librustc_typeck/check/method/suggest.rs @@ -141,7 +141,8 @@ pub fn report_error<'a, 'tcx>(fcx: &FnCtxt<'a, 'tcx>, if !static_sources.is_empty() { err.fileline_note( span, - "found defined static methods, maybe a `self` is missing?"); + "found the following associated functions; to be used as \ + methods, functions must have a `self` parameter"); report_candidates(fcx, &mut err, span, item_name, static_sources); } diff --git a/src/test/compile-fail/issue-7575.rs b/src/test/compile-fail/issue-7575.rs index 6c7196527efdb..3cb30981b673c 100644 --- a/src/test/compile-fail/issue-7575.rs +++ b/src/test/compile-fail/issue-7575.rs @@ -9,6 +9,7 @@ // except according to those terms. // Test the mechanism for warning about possible missing `self` declarations. +// ignore-tidy-linelength trait CtxtFn { fn f8(self, usize) -> usize; @@ -72,15 +73,15 @@ impl ManyImplTrait for Myisize {} fn no_param_bound(u: usize, m: Myisize) -> usize { u.f8(42) + u.f9(342) + m.fff(42) //~^ ERROR no method named `f9` found for type `usize` in the current scope - //~^^ NOTE found defined static methods, maybe a `self` is missing? + //~^^ NOTE found the following associated functions; to be used as methods, functions must have a `self` parameter //~^^^ ERROR no method named `fff` found for type `Myisize` in the current scope - //~^^^^ NOTE found defined static methods, maybe a `self` is missing? + //~^^^^ NOTE found the following associated functions; to be used as methods, functions must have a `self` parameter } fn param_bound(t: T) -> bool { t.is_str() //~^ ERROR no method named `is_str` found for type `T` in the current scope - //~^^ NOTE found defined static methods, maybe a `self` is missing? + //~^^ NOTE found the following associated functions; to be used as methods, functions must have a `self` parameter } fn main() {