From 42326ec2a48a6a70d737b27cb7930810360a1df6 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Sat, 16 Jul 2016 18:00:05 +0200 Subject: [PATCH 01/14] Add examples for VecDeque --- src/libcollections/vec_deque.rs | 72 ++++++++++++++++++++++++++++++++- 1 file changed, 71 insertions(+), 1 deletion(-) diff --git a/src/libcollections/vec_deque.rs b/src/libcollections/vec_deque.rs index 84a0bbbd24983..9e4428ec57d50 100644 --- a/src/libcollections/vec_deque.rs +++ b/src/libcollections/vec_deque.rs @@ -365,12 +365,28 @@ impl VecDeque { impl VecDeque { /// Creates an empty `VecDeque`. + /// + /// # Examples + /// + /// ``` + /// use std::collections::VecDeque; + /// + /// let vector: VecDeque = VecDeque::new(); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn new() -> VecDeque { VecDeque::with_capacity(INITIAL_CAPACITY) } /// Creates an empty `VecDeque` with space for at least `n` elements. + /// + /// # Examples + /// + /// ``` + /// use std::collections::VecDeque; + /// + /// let vector: VecDeque = VecDeque::with_capacity(10); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn with_capacity(n: usize) -> VecDeque { // +1 since the ringbuffer always leaves one space empty @@ -696,6 +712,25 @@ impl VecDeque { /// Returns a pair of slices which contain, in order, the contents of the /// `VecDeque`. + /// + /// # Examples + /// + /// ``` + /// use std::collections::VecDeque; + /// + /// let mut vector: VecDeque = VecDeque::new(); + /// + /// vector.push_back(0); + /// vector.push_back(1); + /// vector.push_back(2); + /// + /// assert_eq!(vector.as_slices(), (&[0u32, 1, 2] as &[u32], &[] as &[u32])); + /// + /// vector.push_front(10); + /// vector.push_front(9); + /// + /// assert_eq!(vector.as_slices(), (&[9u32, 10] as &[u32], &[0u32, 1, 2] as &[u32])); + /// ``` #[inline] #[stable(feature = "deque_extras_15", since = "1.5.0")] pub fn as_slices(&self) -> (&[T], &[T]) { @@ -715,6 +750,24 @@ impl VecDeque { /// Returns a pair of slices which contain, in order, the contents of the /// `VecDeque`. + /// + /// # Examples + /// + /// ``` + /// use std::collections::VecDeque; + /// + /// let mut vector: VecDeque = VecDeque::new(); + /// + /// vector.push_back(0); + /// vector.push_back(1); + /// + /// vector.push_front(10); + /// vector.push_front(9); + /// + /// vector.as_mut_slices().0[0] = 42; + /// vector.as_mut_slices().1[0] = 24; + /// assert_eq!(vector.as_slices(), (&[42u32, 10] as &[u32], &[24u32, 1] as &[u32])); + /// ``` #[inline] #[stable(feature = "deque_extras_15", since = "1.5.0")] pub fn as_mut_slices(&mut self) -> (&mut [T], &mut [T]) { @@ -789,7 +842,7 @@ impl VecDeque { /// /// ``` /// use std::collections::VecDeque; - + /// /// let mut v: VecDeque<_> = vec![1, 2, 3].into_iter().collect(); /// assert_eq!(vec![3].into_iter().collect::>(), v.drain(2..).collect()); /// assert_eq!(vec![1, 2].into_iter().collect::>(), v); @@ -875,6 +928,22 @@ impl VecDeque { /// Returns `true` if the `VecDeque` contains an element equal to the /// given value. + /// + /// # Examples + /// + /// ``` + /// #![feature(vec_deque_contains)] + /// + /// use std::collections::VecDeque; + /// + /// let mut vector: VecDeque = VecDeque::new(); + /// + /// vector.push_back(0); + /// vector.push_back(1); + /// + /// assert_eq!(vector.contains(&1), true); + /// assert_eq!(vector.contains(&10), false); + /// ``` #[unstable(feature = "vec_deque_contains", reason = "recently added", issue = "32630")] pub fn contains(&self, x: &T) -> bool @@ -1404,6 +1473,7 @@ impl VecDeque { /// Returns `None` if `index` is out of bounds. /// /// # Examples + /// /// ``` /// use std::collections::VecDeque; /// From 0c9a6f65d0163c4b24b4e8ebb6474282f912f6f8 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Sat, 16 Jul 2016 17:27:55 +0200 Subject: [PATCH 02/14] Add examples for LinkedList --- src/libcollections/linked_list.rs | 74 +++++++++++++++++++++++++++---- 1 file changed, 65 insertions(+), 9 deletions(-) diff --git a/src/libcollections/linked_list.rs b/src/libcollections/linked_list.rs index dbede94f0bf1b..3d5c3125fae24 100644 --- a/src/libcollections/linked_list.rs +++ b/src/libcollections/linked_list.rs @@ -172,6 +172,14 @@ impl Default for LinkedList { impl LinkedList { /// Creates an empty `LinkedList`. + /// + /// # Examples + /// + /// ``` + /// use std::collections::LinkedList; + /// + /// let list: LinkedList = LinkedList::new(); + /// ``` #[inline] #[stable(feature = "rust1", since = "1.0.0")] pub fn new() -> Self { @@ -226,6 +234,24 @@ impl LinkedList { } /// Provides a forward iterator. + /// + /// # Examples + /// + /// ``` + /// use std::collections::LinkedList; + /// + /// let mut list: LinkedList = LinkedList::new(); + /// + /// list.push_back(0); + /// list.push_back(1); + /// list.push_back(2); + /// + /// let mut iter = list.iter(); + /// assert_eq!(iter.next(), Some(&0)); + /// assert_eq!(iter.next(), Some(&1)); + /// assert_eq!(iter.next(), Some(&2)); + /// assert_eq!(iter.next(), None); + /// ``` #[inline] #[stable(feature = "rust1", since = "1.0.0")] pub fn iter(&self) -> Iter { @@ -238,6 +264,28 @@ impl LinkedList { } /// Provides a forward iterator with mutable references. + /// + /// # Examples + /// + /// ``` + /// use std::collections::LinkedList; + /// + /// let mut list: LinkedList = LinkedList::new(); + /// + /// list.push_back(0); + /// list.push_back(1); + /// list.push_back(2); + /// + /// for element in list.iter_mut() { + /// *element += 10; + /// } + /// + /// let mut iter = list.iter(); + /// assert_eq!(iter.next(), Some(&10)); + /// assert_eq!(iter.next(), Some(&11)); + /// assert_eq!(iter.next(), Some(&12)); + /// assert_eq!(iter.next(), None); + /// ``` #[inline] #[stable(feature = "rust1", since = "1.0.0")] pub fn iter_mut(&mut self) -> IterMut { @@ -289,7 +337,6 @@ impl LinkedList { /// /// dl.push_back(3); /// assert_eq!(dl.len(), 3); - /// /// ``` #[inline] #[stable(feature = "rust1", since = "1.0.0")] @@ -316,7 +363,6 @@ impl LinkedList { /// dl.clear(); /// assert_eq!(dl.len(), 0); /// assert_eq!(dl.front(), None); - /// /// ``` #[inline] #[stable(feature = "rust1", since = "1.0.0")] @@ -326,6 +372,23 @@ impl LinkedList { /// Returns `true` if the `LinkedList` contains an element equal to the /// given value. + /// + /// # Examples + /// + /// ``` + /// #![feature(linked_list_contains)] + /// + /// use std::collections::LinkedList; + /// + /// let mut list: LinkedList = LinkedList::new(); + /// + /// list.push_back(0); + /// list.push_back(1); + /// list.push_back(2); + /// + /// assert_eq!(list.contains(&0), true); + /// assert_eq!(list.contains(&10), false); + /// ``` #[unstable(feature = "linked_list_contains", reason = "recently added", issue = "32630")] pub fn contains(&self, x: &T) -> bool @@ -347,7 +410,6 @@ impl LinkedList { /// /// dl.push_front(1); /// assert_eq!(dl.front(), Some(&1)); - /// /// ``` #[inline] #[stable(feature = "rust1", since = "1.0.0")] @@ -374,7 +436,6 @@ impl LinkedList { /// Some(x) => *x = 5, /// } /// assert_eq!(dl.front(), Some(&5)); - /// /// ``` #[inline] #[stable(feature = "rust1", since = "1.0.0")] @@ -395,7 +456,6 @@ impl LinkedList { /// /// dl.push_back(1); /// assert_eq!(dl.back(), Some(&1)); - /// /// ``` #[inline] #[stable(feature = "rust1", since = "1.0.0")] @@ -422,7 +482,6 @@ impl LinkedList { /// Some(x) => *x = 5, /// } /// assert_eq!(dl.back(), Some(&5)); - /// /// ``` #[inline] #[stable(feature = "rust1", since = "1.0.0")] @@ -446,7 +505,6 @@ impl LinkedList { /// /// dl.push_front(1); /// assert_eq!(dl.front().unwrap(), &1); - /// /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn push_front(&mut self, elt: T) { @@ -471,9 +529,7 @@ impl LinkedList { /// assert_eq!(d.pop_front(), Some(3)); /// assert_eq!(d.pop_front(), Some(1)); /// assert_eq!(d.pop_front(), None); - /// /// ``` - /// #[stable(feature = "rust1", since = "1.0.0")] pub fn pop_front(&mut self) -> Option { self.pop_front_node().map(Node::into_element) From 3b5d71e0cfb2d81f588a0b8929e796f3b68488e0 Mon Sep 17 00:00:00 2001 From: "Novotnik, Petr" Date: Sun, 17 Jul 2016 12:06:10 +0200 Subject: [PATCH 03/14] Make .enumerate() example self-explanatory --- src/doc/book/loops.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/doc/book/loops.md b/src/doc/book/loops.md index e681d1bee0618..e4cb861d3b0f5 100644 --- a/src/doc/book/loops.md +++ b/src/doc/book/loops.md @@ -105,19 +105,19 @@ When you need to keep track of how many times you already looped, you can use th #### On ranges: ```rust -for (i, j) in (5..10).enumerate() { - println!("i = {} and j = {}", i, j); +for (index, value) in (5..10).enumerate() { + println!("index = {} and value = {}", index, value); } ``` Outputs: ```text -i = 0 and j = 5 -i = 1 and j = 6 -i = 2 and j = 7 -i = 3 and j = 8 -i = 4 and j = 9 +index = 0 and value = 5 +index = 1 and value = 6 +index = 2 and value = 7 +index = 3 and value = 8 +index = 4 and value = 9 ``` Don't forget to add the parentheses around the range. From 6a09df9079279297c5f68c0a1214a17e8193cd6a Mon Sep 17 00:00:00 2001 From: Jack O'Connor Date: Sun, 17 Jul 2016 11:31:44 -0400 Subject: [PATCH 04/14] implement AddAssign for String --- src/libcollections/string.rs | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/src/libcollections/string.rs b/src/libcollections/string.rs index eedf4c2c11f34..688f057604251 100644 --- a/src/libcollections/string.rs +++ b/src/libcollections/string.rs @@ -59,7 +59,7 @@ use core::fmt; use core::hash; use core::iter::FromIterator; use core::mem; -use core::ops::{self, Add, Index, IndexMut}; +use core::ops::{self, Add, AddAssign, Index, IndexMut}; use core::ptr; use core::str::pattern::Pattern; use rustc_unicode::char::{decode_utf16, REPLACEMENT_CHARACTER}; @@ -1559,6 +1559,14 @@ impl<'a> Add<&'a str> for String { } } +#[stable(feature = "rust1", since = "1.11.0")] +impl<'a> AddAssign<&'a str> for String { + #[inline] + fn add_assign(&mut self, other: &str) { + self.push_str(other); + } +} + #[stable(feature = "rust1", since = "1.0.0")] impl ops::Index> for String { type Output = str; From ce442b4f5195ff6af27ae3335c7bb372015c1407 Mon Sep 17 00:00:00 2001 From: ggomez Date: Wed, 20 Jul 2016 15:02:33 +0200 Subject: [PATCH 05/14] Add debug for hash_map::{Entry, VacantEntry, OccupiedEntry} --- src/libstd/collections/hash/map.rs | 33 ++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/src/libstd/collections/hash/map.rs b/src/libstd/collections/hash/map.rs index 60d7e01d98814..a03249e006356 100644 --- a/src/libstd/collections/hash/map.rs +++ b/src/libstd/collections/hash/map.rs @@ -1351,6 +1351,20 @@ pub enum Entry<'a, K: 'a, V: 'a> { ), } +#[stable(feature= "debug_hash_map", since = "1.12.0")] +impl<'a, K: 'a + Debug, V: 'a + Debug> Debug for Entry<'a, K, V> { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + match *self { + Vacant(ref v) => f.debug_tuple("Entry") + .field(v) + .finish(), + Occupied(ref o) => f.debug_tuple("Entry") + .field(o) + .finish(), + } + } +} + /// A view into a single occupied location in a HashMap. #[stable(feature = "rust1", since = "1.0.0")] pub struct OccupiedEntry<'a, K: 'a, V: 'a> { @@ -1358,6 +1372,16 @@ pub struct OccupiedEntry<'a, K: 'a, V: 'a> { elem: FullBucket>, } +#[stable(feature= "debug_hash_map", since = "1.12.0")] +impl<'a, K: 'a + Debug, V: 'a + Debug> Debug for OccupiedEntry<'a, K, V> { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + f.debug_struct("OccupiedEntry") + .field("key", self.key()) + .field("value", self.get()) + .finish() + } +} + /// A view into a single empty location in a HashMap. #[stable(feature = "rust1", since = "1.0.0")] pub struct VacantEntry<'a, K: 'a, V: 'a> { @@ -1366,6 +1390,15 @@ pub struct VacantEntry<'a, K: 'a, V: 'a> { elem: VacantEntryState>, } +#[stable(feature= "debug_hash_map", since = "1.12.0")] +impl<'a, K: 'a + Debug, V: 'a> Debug for VacantEntry<'a, K, V> { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + f.debug_tuple("VacantEntry") + .field(self.key()) + .finish() + } +} + /// Possible states of a VacantEntry. enum VacantEntryState { /// The index is occupied, but the key to insert has precedence, From d820fcba122771742f8bdeed4c8619292f3450f6 Mon Sep 17 00:00:00 2001 From: Mark Buer Date: Mon, 18 Jul 2016 17:54:15 +0930 Subject: [PATCH 06/14] Remove rustdoc reference to `walk_dir` --- src/libstd/fs.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/libstd/fs.rs b/src/libstd/fs.rs index 83439b3f13215..c28f70b8692ad 100644 --- a/src/libstd/fs.rs +++ b/src/libstd/fs.rs @@ -791,8 +791,8 @@ impl Iterator for ReadDir { impl DirEntry { /// Returns the full path to the file that this entry represents. /// - /// The full path is created by joining the original path to `read_dir` or - /// `walk_dir` with the filename of this entry. + /// The full path is created by joining the original path to `read_dir` + /// with the filename of this entry. /// /// # Examples /// From cac58ab5b7501a7ea3146a4521d8f34389bc3f73 Mon Sep 17 00:00:00 2001 From: Jack O'Connor Date: Mon, 18 Jul 2016 14:00:35 -0400 Subject: [PATCH 07/14] update the since field to 1.12.0 for String AddAssign --- src/libcollections/string.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libcollections/string.rs b/src/libcollections/string.rs index 688f057604251..3920b57962c87 100644 --- a/src/libcollections/string.rs +++ b/src/libcollections/string.rs @@ -1559,7 +1559,7 @@ impl<'a> Add<&'a str> for String { } } -#[stable(feature = "rust1", since = "1.11.0")] +#[stable(feature = "rust1", since = "1.12.0")] impl<'a> AddAssign<&'a str> for String { #[inline] fn add_assign(&mut self, other: &str) { From 9b8130666de569d6d27332d42df43859a57b3e72 Mon Sep 17 00:00:00 2001 From: Jack O'Connor Date: Mon, 18 Jul 2016 14:27:17 -0400 Subject: [PATCH 08/14] use a new feature name for String AddAssign --- src/libcollections/string.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libcollections/string.rs b/src/libcollections/string.rs index 3920b57962c87..71c6a6c892eab 100644 --- a/src/libcollections/string.rs +++ b/src/libcollections/string.rs @@ -1559,7 +1559,7 @@ impl<'a> Add<&'a str> for String { } } -#[stable(feature = "rust1", since = "1.12.0")] +#[stable(feature = "stringaddassign", since = "1.12.0")] impl<'a> AddAssign<&'a str> for String { #[inline] fn add_assign(&mut self, other: &str) { From f77bcc86b1624644c4e897b9fb1f094d8ea81f15 Mon Sep 17 00:00:00 2001 From: Alex Crichton Date: Mon, 18 Jul 2016 16:25:11 -0700 Subject: [PATCH 09/14] rustc: Remove soft-float from MIPS targets Right now two MIPS targets in the compiler, `mips-unknown-linux-{gnu,musl}` both generate object files using the soft-float ABI through LLVM by default. This is also expressed as the `-C soft-float` codegen option and otherwise isn't used for any other target in the compiler. This option was added quite some time ago (back in #9617), and nowadays it's more appropriate to be done through a codegen option. This is motivated by #34743 which necessitated an upgrade in the CMake installation on our bots which necessitated an upgrade in the Ubuntu version which invalidated the MIPS compilers we were using. The new MIPS compilers (coming from Debian I believe) all have hard float enabled by default and soft float support not built in. This meant that we couldn't upgrade the bots until #34841 landed because otherwise we would fail to compile C code as the `-msoft-float` option wouldn't work. Unfortunately, though, this means that once we upgrade the bots the C code we're compiling will be compiled for hard float and the Rust code will be compiled for soft float, a bad mismatch! This PR remedies the situation such that Rust will compile with hard float as well. If this lands it will likely produce broken nightlies for a day or two while we get around to upgrading the bots because the current C toolchain only produces soft-float binaries, and now rust will be hard-float. Hopefully, though, the upgrade can go smoothly! --- src/librustc_back/target/mips_unknown_linux_gnu.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/librustc_back/target/mips_unknown_linux_gnu.rs b/src/librustc_back/target/mips_unknown_linux_gnu.rs index 794e4d4996c94..ceb17e53a5552 100644 --- a/src/librustc_back/target/mips_unknown_linux_gnu.rs +++ b/src/librustc_back/target/mips_unknown_linux_gnu.rs @@ -22,7 +22,7 @@ pub fn target() -> Target { target_vendor: "unknown".to_string(), options: TargetOptions { cpu: "mips32r2".to_string(), - features: "+mips32r2,+soft-float".to_string(), + features: "+mips32r2".to_string(), max_atomic_width: 32, ..super::linux_base::opts() }, From 4a2116b97af2e935b359558c046034f4c3cb80a8 Mon Sep 17 00:00:00 2001 From: ggomez Date: Tue, 19 Jul 2016 15:03:32 +0200 Subject: [PATCH 10/14] [CSS] Fix unwanted top margin for toggle wrapper --- src/librustdoc/html/static/rustdoc.css | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/librustdoc/html/static/rustdoc.css b/src/librustdoc/html/static/rustdoc.css index 303cc671f4a23..de0457592fc88 100644 --- a/src/librustdoc/html/static/rustdoc.css +++ b/src/librustdoc/html/static/rustdoc.css @@ -636,8 +636,11 @@ span.since { margin-right: 5px; } -.enum > .toggle-wrapper > .collapse-toggle, .struct > .toggle-wrapper > .collapse-toggle { +.toggle-wrapper > .collapse-toggle { left: 0; +} + +.variant + .toggle-wrapper > a { margin-top: 5px; } From a005b2cd2ac679da7393e537aa05e2b7d32d36d5 Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Mon, 18 Jul 2016 22:29:05 -0400 Subject: [PATCH 11/14] Rewrite/expand doc examples for `Vec::set_len`. --- src/libcollections/vec.rs | 32 ++++++++++++++++++++++++++++++-- 1 file changed, 30 insertions(+), 2 deletions(-) diff --git a/src/libcollections/vec.rs b/src/libcollections/vec.rs index da56b21cf0c05..9badf8cf18305 100644 --- a/src/libcollections/vec.rs +++ b/src/libcollections/vec.rs @@ -532,9 +532,37 @@ impl Vec { /// # Examples /// /// ``` - /// let mut v = vec![1, 2, 3, 4]; + /// use std::ptr; + /// + /// let mut vec = vec!['r', 'u', 's', 't']; + /// + /// unsafe { + /// ptr::drop_in_place(&mut vec[3]); + /// vec.set_len(3); + /// } + /// assert_eq!(vec, ['r', 'u', 's']); + /// ``` + /// + /// In this example, there is a memory leak since the memory locations + /// owned by the vector were not freed prior to the `set_len` call: + /// + /// ``` + /// let mut vec = vec!['r', 'u', 's', 't']; + /// + /// unsafe { + /// vec.set_len(0); + /// } + /// ``` + /// + /// In this example, the vector gets expanded from zero to four items + /// without any memory allocations occurring, resulting in vector + /// values of unallocated memory: + /// + /// ``` + /// let mut vec: Vec = Vec::new(); + /// /// unsafe { - /// v.set_len(1); + /// vec.set_len(4); /// } /// ``` #[inline] From 00e3149dede9fbc464e0f654e7093626d7a8ca27 Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Tue, 19 Jul 2016 20:38:35 -0400 Subject: [PATCH 12/14] Add doc examples for `Vec::{as_slice,as_mut_slice}`. --- src/libcollections/vec.rs | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/src/libcollections/vec.rs b/src/libcollections/vec.rs index 518b94b5031b4..4cc5b11dc3434 100644 --- a/src/libcollections/vec.rs +++ b/src/libcollections/vec.rs @@ -541,6 +541,14 @@ impl Vec { /// Extracts a slice containing the entire vector. /// /// Equivalent to `&s[..]`. + /// + /// # Examples + /// + /// ``` + /// use std::io::{self, Write}; + /// let buffer = vec![1, 2, 3, 5, 8]; + /// io::sink().write(buffer.as_slice()).unwrap(); + /// ``` #[inline] #[stable(feature = "vec_as_slice", since = "1.7.0")] pub fn as_slice(&self) -> &[T] { @@ -550,6 +558,14 @@ impl Vec { /// Extracts a mutable slice of the entire vector. /// /// Equivalent to `&mut s[..]`. + /// + /// # Examples + /// + /// ``` + /// use std::io::{self, Read}; + /// let mut buffer = vec![0; 3]; + /// io::repeat(0b101).read_exact(buffer.as_mut_slice()).unwrap(); + /// ``` #[inline] #[stable(feature = "vec_as_slice", since = "1.7.0")] pub fn as_mut_slice(&mut self) -> &mut [T] { From 9b5db220c899fdd3656c8e28fc747808b8cab7c7 Mon Sep 17 00:00:00 2001 From: ggomez Date: Tue, 19 Jul 2016 14:40:42 +0200 Subject: [PATCH 13/14] Add doc for btree_map types --- src/libcollections/btree/map.rs | 191 +++++++++++++++++++++++++++++++- 1 file changed, 189 insertions(+), 2 deletions(-) diff --git a/src/libcollections/btree/map.rs b/src/libcollections/btree/map.rs index ef94aae78f416..c3a7d4023754a 100644 --- a/src/libcollections/btree/map.rs +++ b/src/libcollections/btree/map.rs @@ -313,6 +313,10 @@ pub struct RangeMut<'a, K: 'a, V: 'a> { } /// A view into a single entry in a map, which may either be vacant or occupied. +/// This enum is constructed from the [`entry`] method on [`BTreeMap`]. +/// +/// [`BTreeMap`]: struct.BTreeMap.html +/// [`entry`]: struct.BTreeMap.html#method.entry #[stable(feature = "rust1", since = "1.0.0")] pub enum Entry<'a, K: 'a, V: 'a> { /// A vacant Entry @@ -340,7 +344,9 @@ impl<'a, K: 'a + Debug + Ord, V: 'a + Debug> Debug for Entry<'a, K, V> { } } -/// A vacant Entry. +/// A vacant Entry. It is part of the [`Entry`] enum. +/// +/// [`Entry`]: enum.Entry.html #[stable(feature = "rust1", since = "1.0.0")] pub struct VacantEntry<'a, K: 'a, V: 'a> { key: K, @@ -360,7 +366,9 @@ impl<'a, K: 'a + Debug + Ord, V: 'a> Debug for VacantEntry<'a, K, V> { } } -/// An occupied Entry. +/// An occupied Entry. It is part of the [`Entry`] enum. +/// +/// [`Entry`]: enum.Entry.html #[stable(feature = "rust1", since = "1.0.0")] pub struct OccupiedEntry<'a, K: 'a, V: 'a> { handle: Handle, K, V, marker::LeafOrInternal>, marker::KV>, @@ -1890,6 +1898,17 @@ impl BTreeMap { impl<'a, K: Ord, V> Entry<'a, K, V> { /// Ensures a value is in the entry by inserting the default if empty, and returns /// a mutable reference to the value in the entry. + /// + /// # Examples + /// + /// ``` + /// use std::collections::BTreeMap; + /// + /// let mut map: BTreeMap<&str, usize> = BTreeMap::new(); + /// map.entry("poneyland").or_insert(12); + /// + /// assert_eq!(map["poneyland"], 12); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn or_insert(self, default: V) -> &'a mut V { match self { @@ -1900,6 +1919,19 @@ impl<'a, K: Ord, V> Entry<'a, K, V> { /// Ensures a value is in the entry by inserting the result of the default function if empty, /// and returns a mutable reference to the value in the entry. + /// + /// # Examples + /// + /// ``` + /// use std::collections::BTreeMap; + /// + /// let mut map: BTreeMap<&str, String> = BTreeMap::new(); + /// let s = "hoho".to_owned(); + /// + /// map.entry("poneyland").or_insert_with(|| s); + /// + /// assert_eq!(map["poneyland"], "hoho".to_owned()); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn or_insert_with V>(self, default: F) -> &'a mut V { match self { @@ -1909,6 +1941,15 @@ impl<'a, K: Ord, V> Entry<'a, K, V> { } /// Returns a reference to this entry's key. + /// + /// # Examples + /// + /// ``` + /// use std::collections::BTreeMap; + /// + /// let mut map: BTreeMap<&str, usize> = BTreeMap::new(); + /// assert_eq!(map.entry("poneyland").key(), &"poneyland"); + /// ``` #[stable(feature = "map_entry_keys", since = "1.10.0")] pub fn key(&self) -> &K { match *self { @@ -1921,12 +1962,36 @@ impl<'a, K: Ord, V> Entry<'a, K, V> { impl<'a, K: Ord, V> VacantEntry<'a, K, V> { /// Gets a reference to the key that would be used when inserting a value /// through the VacantEntry. + /// + /// # Examples + /// + /// ``` + /// use std::collections::BTreeMap; + /// + /// let mut map: BTreeMap<&str, usize> = BTreeMap::new(); + /// assert_eq!(map.entry("poneyland").key(), &"poneyland"); + /// ``` #[stable(feature = "map_entry_keys", since = "1.10.0")] pub fn key(&self) -> &K { &self.key } /// Take ownership of the key. + /// + /// # Examples + /// + /// ``` + /// #![feature(map_entry_recover_keys)] + /// + /// use std::collections::BTreeMap; + /// use std::collections::btree_map::Entry; + /// + /// let mut map: BTreeMap<&str, usize> = BTreeMap::new(); + /// + /// if let Entry::Vacant(v) = map.entry("poneyland") { + /// v.into_key(); + /// } + /// ``` #[unstable(feature = "map_entry_recover_keys", issue = "34285")] pub fn into_key(self) -> K { self.key @@ -1934,6 +1999,21 @@ impl<'a, K: Ord, V> VacantEntry<'a, K, V> { /// Sets the value of the entry with the VacantEntry's key, /// and returns a mutable reference to it. + /// + /// # Examples + /// + /// ``` + /// use std::collections::BTreeMap; + /// + /// let mut count: BTreeMap<&str, usize> = BTreeMap::new(); + /// + /// // count the number of occurrences of letters in the vec + /// for x in vec!["a","b","a","c","a","b"] { + /// *count.entry(x).or_insert(0) += 1; + /// } + /// + /// assert_eq!(count["a"], 3); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn insert(self, value: V) -> &'a mut V { *self.length += 1; @@ -1979,30 +2059,106 @@ impl<'a, K: Ord, V> VacantEntry<'a, K, V> { impl<'a, K: Ord, V> OccupiedEntry<'a, K, V> { /// Gets a reference to the key in the entry. + /// + /// # Examples + /// + /// ``` + /// use std::collections::BTreeMap; + /// + /// let mut map: BTreeMap<&str, usize> = BTreeMap::new(); + /// map.entry("poneyland").or_insert(12); + /// assert_eq!(map.entry("poneyland").key(), &"poneyland"); + /// ``` #[stable(feature = "map_entry_keys", since = "1.10.0")] pub fn key(&self) -> &K { self.handle.reborrow().into_kv().0 } /// Take ownership of the key and value from the map. + /// + /// # Examples + /// + /// ``` + /// #![feature(map_entry_recover_keys)] + /// + /// use std::collections::BTreeMap; + /// use std::collections::btree_map::Entry; + /// + /// let mut map: BTreeMap<&str, usize> = BTreeMap::new(); + /// map.entry("poneyland").or_insert(12); + /// + /// if let Entry::Occupied(o) = map.entry("poneyland") { + /// // We delete the entry from the map. + /// o.remove_pair(); + /// } + /// + /// // If now try to get the value, it will panic: + /// // println!("{}", map["poneyland"]); + /// ``` #[unstable(feature = "map_entry_recover_keys", issue = "34285")] pub fn remove_pair(self) -> (K, V) { self.remove_kv() } /// Gets a reference to the value in the entry. + /// + /// # Examples + /// + /// ``` + /// use std::collections::BTreeMap; + /// use std::collections::btree_map::Entry; + /// + /// let mut map: BTreeMap<&str, usize> = BTreeMap::new(); + /// map.entry("poneyland").or_insert(12); + /// + /// if let Entry::Occupied(o) = map.entry("poneyland") { + /// assert_eq!(o.get(), &12); + /// } + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn get(&self) -> &V { self.handle.reborrow().into_kv().1 } /// Gets a mutable reference to the value in the entry. + /// + /// # Examples + /// + /// ``` + /// use std::collections::BTreeMap; + /// use std::collections::btree_map::Entry; + /// + /// let mut map: BTreeMap<&str, usize> = BTreeMap::new(); + /// map.entry("poneyland").or_insert(12); + /// + /// assert_eq!(map["poneyland"], 12); + /// if let Entry::Occupied(mut o) = map.entry("poneyland") { + /// *o.get_mut() += 10; + /// } + /// assert_eq!(map["poneyland"], 22); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn get_mut(&mut self) -> &mut V { self.handle.kv_mut().1 } /// Converts the entry into a mutable reference to its value. + /// + /// # Examples + /// + /// ``` + /// use std::collections::BTreeMap; + /// use std::collections::btree_map::Entry; + /// + /// let mut map: BTreeMap<&str, usize> = BTreeMap::new(); + /// map.entry("poneyland").or_insert(12); + /// + /// assert_eq!(map["poneyland"], 12); + /// if let Entry::Occupied(o) = map.entry("poneyland") { + /// *o.into_mut() += 10; + /// } + /// assert_eq!(map["poneyland"], 22); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn into_mut(self) -> &'a mut V { self.handle.into_kv_mut().1 @@ -2010,12 +2166,43 @@ impl<'a, K: Ord, V> OccupiedEntry<'a, K, V> { /// Sets the value of the entry with the OccupiedEntry's key, /// and returns the entry's old value. + /// + /// # Examples + /// + /// ``` + /// use std::collections::BTreeMap; + /// use std::collections::btree_map::Entry; + /// + /// let mut map: BTreeMap<&str, usize> = BTreeMap::new(); + /// map.entry("poneyland").or_insert(12); + /// + /// if let Entry::Occupied(mut o) = map.entry("poneyland") { + /// assert_eq!(o.insert(15), 12); + /// } + /// assert_eq!(map["poneyland"], 15); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn insert(&mut self, value: V) -> V { mem::replace(self.get_mut(), value) } /// Takes the value of the entry out of the map, and returns it. + /// + /// # Examples + /// + /// ``` + /// use std::collections::BTreeMap; + /// use std::collections::btree_map::Entry; + /// + /// let mut map: BTreeMap<&str, usize> = BTreeMap::new(); + /// map.entry("poneyland").or_insert(12); + /// + /// if let Entry::Occupied(o) = map.entry("poneyland") { + /// assert_eq!(o.remove(), 12); + /// } + /// // If we try to get "poneyland"'s value, it'll panic: + /// // println!("{}", map["poneyland"]); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn remove(self) -> V { self.remove_kv().1 From fbfee42a2f65b7a3d4acd0d9d029bb75208ac800 Mon Sep 17 00:00:00 2001 From: Sean McArthur Date: Thu, 14 Jul 2016 12:17:39 -0700 Subject: [PATCH 14/14] core: impl From for Option --- src/libcore/option.rs | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/src/libcore/option.rs b/src/libcore/option.rs index 045c1f9feafc6..fe508adb71380 100644 --- a/src/libcore/option.rs +++ b/src/libcore/option.rs @@ -142,6 +142,7 @@ use self::Option::*; use clone::Clone; +use convert::From; use default::Default; use iter::ExactSizeIterator; use iter::{Iterator, DoubleEndedIterator, FromIterator, IntoIterator}; @@ -754,6 +755,13 @@ impl<'a, T> IntoIterator for &'a mut Option { } } +#[stable(since = "1.12.0", feature = "option_from")] +impl From for Option { + fn from(val: T) -> Option { + Some(val) + } +} + ///////////////////////////////////////////////////////////////////////////// // The Option Iterators /////////////////////////////////////////////////////////////////////////////