From c004bebc9ef12b5d6c24d0d482344ad485f2050b Mon Sep 17 00:00:00 2001 From: Jonas Hietala Date: Tue, 22 Jul 2014 10:33:26 +0200 Subject: [PATCH 1/4] doc: Use vec![] instead of vec!() in Vec. --- src/libcollections/vec.rs | 154 +++++++++++++++++++------------------- 1 file changed, 77 insertions(+), 77 deletions(-) diff --git a/src/libcollections/vec.rs b/src/libcollections/vec.rs index 751775888b759..f75865c218d10 100644 --- a/src/libcollections/vec.rs +++ b/src/libcollections/vec.rs @@ -151,7 +151,7 @@ impl Vec { /// ```rust /// # use std::vec::Vec; /// let vec = Vec::from_fn(3, |idx| idx * 2); - /// assert_eq!(vec, vec!(0, 2, 4)); + /// assert_eq!(vec, vec![0, 2, 4]); /// ``` #[inline] pub fn from_fn(length: uint, op: |uint| -> T) -> Vec { @@ -189,10 +189,10 @@ impl Vec { /// # Example /// /// ```rust - /// let vec = vec!(1i, 2i, 3i, 4i); + /// let vec = vec![1i, 2i, 3i, 4i]; /// let (even, odd) = vec.partition(|&n| n % 2 == 0); - /// assert_eq!(even, vec!(2, 4)); - /// assert_eq!(odd, vec!(1, 3)); + /// assert_eq!(even, vec![2, 4]); + /// assert_eq!(odd, vec![1, 3]); /// ``` #[inline] pub fn partition(self, f: |&T| -> bool) -> (Vec, Vec) { @@ -218,9 +218,9 @@ impl Vec { /// # Example /// /// ```rust - /// let vec = vec!(1i, 2i); + /// let vec = vec![1i, 2i]; /// let vec = vec.append([3i, 4i]); - /// assert_eq!(vec, vec!(1, 2, 3, 4)); + /// assert_eq!(vec, vec![1, 2, 3, 4]); /// ``` #[inline] pub fn append(mut self, second: &[T]) -> Vec { @@ -276,9 +276,9 @@ impl Vec { /// # Example /// /// ```rust - /// let mut vec = vec!(1i); + /// let mut vec = vec![1i]; /// vec.push_all([2i, 3, 4]); - /// assert_eq!(vec, vec!(1, 2, 3, 4)); + /// assert_eq!(vec, vec![1, 2, 3, 4]); /// ``` #[inline] pub fn push_all(&mut self, other: &[T]) { @@ -306,9 +306,9 @@ impl Vec { /// # Example /// /// ```rust - /// let mut vec = vec!("hello"); + /// let mut vec = vec!["hello"]; /// vec.grow(2, &("world")); - /// assert_eq!(vec, vec!("hello", "world", "world")); + /// assert_eq!(vec, vec!["hello", "world", "world"]); /// ``` pub fn grow(&mut self, n: uint, value: &T) { self.reserve_additional(n); @@ -330,10 +330,10 @@ impl Vec { /// # Example /// /// ```rust - /// let mut vec = vec!("a", "b", "c"); + /// let mut vec = vec!["a", "b", "c"]; /// vec.grow_set(1, &("fill"), "d"); /// vec.grow_set(4, &("fill"), "e"); - /// assert_eq!(vec, vec!("a", "d", "c", "fill", "e")); + /// assert_eq!(vec, vec!["a", "d", "c", "fill", "e"]); /// ``` pub fn grow_set(&mut self, index: uint, initval: &T, value: T) { let l = self.len(); @@ -352,10 +352,10 @@ impl Vec { /// # Example /// /// ```rust - /// let vec = vec!(1i, 2, 3, 4); + /// let vec = vec![1i, 2, 3, 4]; /// let (even, odd) = vec.partitioned(|&n| n % 2 == 0); - /// assert_eq!(even, vec!(2i, 4)); - /// assert_eq!(odd, vec!(1i, 3)); + /// assert_eq!(even, vec![2i, 4]); + /// assert_eq!(odd, vec![1i, 3]); /// ``` pub fn partitioned(&self, f: |&T| -> bool) -> (Vec, Vec) { let mut lefts = Vec::new(); @@ -522,7 +522,7 @@ impl Vec { /// /// ```rust /// # use std::vec::Vec; - /// let mut vec: Vec = vec!(1i); + /// let mut vec: Vec = vec![1i]; /// vec.reserve_additional(10); /// assert!(vec.capacity() >= 11); /// ``` @@ -547,7 +547,7 @@ impl Vec { /// # Example /// /// ```rust - /// let mut vec = vec!(1i, 2, 3); + /// let mut vec = vec![1i, 2, 3]; /// vec.reserve(10); /// assert!(vec.capacity() >= 10); /// ``` @@ -589,7 +589,7 @@ impl Vec { /// # Example /// /// ```rust - /// let mut vec = vec!(1i, 2, 3); + /// let mut vec = vec![1i, 2, 3]; /// vec.shrink_to_fit(); /// ``` pub fn shrink_to_fit(&mut self) { @@ -621,9 +621,9 @@ impl Vec { /// # Example /// /// ```rust - /// let mut vec = vec!(1i, 2, 3); + /// let mut vec = vec![1i, 2, 3]; /// assert_eq!(vec.pop(), Some(3)); - /// assert_eq!(vec, vec!(1, 2)); + /// assert_eq!(vec, vec![1, 2]); /// ``` #[inline] pub fn pop(&mut self) -> Option { @@ -646,9 +646,9 @@ impl Vec { /// # Example /// /// ```rust - /// let mut vec = vec!(1i, 2); + /// let mut vec = vec![1i, 2]; /// vec.push(3); - /// assert_eq!(vec, vec!(1, 2, 3)); + /// assert_eq!(vec, vec![1, 2, 3]); /// ``` #[inline] pub fn push(&mut self, value: T) { @@ -682,9 +682,9 @@ impl Vec { /// # Example /// /// ```rust - /// let vec = vec!(1i, 2); + /// let vec = vec![1i, 2]; /// let vec = vec.append_one(3); - /// assert_eq!(vec, vec!(1, 2, 3)); + /// assert_eq!(vec, vec![1, 2, 3]); /// ``` #[inline] pub fn append_one(mut self, x: T) -> Vec { @@ -700,9 +700,9 @@ impl Vec { /// # Example /// /// ```rust - /// let mut vec = vec!(1i, 2, 3, 4); + /// let mut vec = vec![1i, 2, 3, 4]; /// vec.truncate(2); - /// assert_eq!(vec, vec!(1, 2)); + /// assert_eq!(vec, vec![1, 2]); /// ``` pub fn truncate(&mut self, len: uint) { unsafe { @@ -723,7 +723,7 @@ impl Vec { /// ```rust /// fn foo(slice: &mut [int]) {} /// - /// let mut vec = vec!(1i, 2); + /// let mut vec = vec![1i, 2]; /// foo(vec.as_mut_slice()); /// ``` #[inline] @@ -743,7 +743,7 @@ impl Vec { /// # Example /// /// ```rust - /// let v = vec!("a".to_string(), "b".to_string()); + /// let v = vec!["a".to_string(), "b".to_string()]; /// for s in v.move_iter() { /// // s has type String, not &String /// println!("{}", s); @@ -782,7 +782,7 @@ impl Vec { /// ```rust /// #![allow(deprecated)] /// - /// let vec = vec!(1i, 2, 3); + /// let vec = vec![1i, 2, 3]; /// assert!(vec.get(1) == &2); /// ``` #[deprecated="prefer using indexing, e.g., vec[0]"] @@ -800,9 +800,9 @@ impl Vec { /// # Example /// /// ```rust - /// let mut vec = vec!(1i, 2, 3); + /// let mut vec = vec![1i, 2, 3]; /// *vec.get_mut(1) = 4; - /// assert_eq!(vec, vec!(1i, 4, 3)); + /// assert_eq!(vec, vec![1i, 4, 3]); /// ``` #[inline] pub fn get_mut<'a>(&'a mut self, index: uint) -> &'a mut T { @@ -815,7 +815,7 @@ impl Vec { /// # Example /// /// ```rust - /// let vec = vec!(1i, 2, 3); + /// let vec = vec![1i, 2, 3]; /// for num in vec.iter() { /// println!("{}", *num); /// } @@ -832,7 +832,7 @@ impl Vec { /// # Example /// /// ```rust - /// let mut vec = vec!(1i, 2, 3); + /// let mut vec = vec![1i, 2, 3]; /// for num in vec.mut_iter() { /// *num = 0; /// } @@ -850,13 +850,13 @@ impl Vec { /// # Example /// /// ```rust - /// let mut v = vec!(5i, 4, 1, 3, 2); + /// let mut v = vec![5i, 4, 1, 3, 2]; /// v.sort_by(|a, b| a.cmp(b)); - /// assert_eq!(v, vec!(1i, 2, 3, 4, 5)); + /// assert_eq!(v, vec![1i, 2, 3, 4, 5]); /// /// // reverse sorting /// v.sort_by(|a, b| b.cmp(a)); - /// assert_eq!(v, vec!(5i, 4, 3, 2, 1)); + /// assert_eq!(v, vec![5i, 4, 3, 2, 1]); /// ``` #[inline] pub fn sort_by(&mut self, compare: |&T, &T| -> Ordering) { @@ -873,7 +873,7 @@ impl Vec { /// # Example /// /// ```rust - /// let vec = vec!(1i, 2, 3, 4); + /// let vec = vec![1i, 2, 3, 4]; /// assert!(vec.slice(0, 2) == [1, 2]); /// ``` #[inline] @@ -890,7 +890,7 @@ impl Vec { /// # Example /// /// ```rust - /// let vec = vec!(1i, 2, 3); + /// let vec = vec![1i, 2, 3]; /// assert!(vec.tail() == [2, 3]); /// ``` #[inline] @@ -907,7 +907,7 @@ impl Vec { /// # Example /// /// ```rust - /// let vec = vec!(1i, 2, 3, 4); + /// let vec = vec![1i, 2, 3, 4]; /// assert!(vec.tailn(2) == [3, 4]); /// ``` #[inline] @@ -921,7 +921,7 @@ impl Vec { /// # Example /// /// ```rust - /// let vec = vec!(1i, 2, 3); + /// let vec = vec![1i, 2, 3]; /// assert!(vec.last() == Some(&3)); /// ``` #[inline] @@ -935,9 +935,9 @@ impl Vec { /// # Example /// /// ```rust - /// let mut vec = vec!(1i, 2, 3); + /// let mut vec = vec![1i, 2, 3]; /// *vec.mut_last().unwrap() = 4; - /// assert_eq!(vec, vec!(1i, 2, 4)); + /// assert_eq!(vec, vec![1i, 2, 4]); /// ``` #[inline] pub fn mut_last<'a>(&'a mut self) -> Option<&'a mut T> { @@ -951,14 +951,14 @@ impl Vec { /// /// # Example /// ```rust - /// let mut v = vec!("foo".to_string(), "bar".to_string(), - /// "baz".to_string(), "qux".to_string()); + /// let mut v = vec!["foo".to_string(), "bar".to_string(), + /// "baz".to_string(), "qux".to_string()]; /// /// assert_eq!(v.swap_remove(1), Some("bar".to_string())); - /// assert_eq!(v, vec!("foo".to_string(), "qux".to_string(), "baz".to_string())); + /// assert_eq!(v, vec!["foo".to_string(), "qux".to_string(), "baz".to_string()]); /// /// assert_eq!(v.swap_remove(0), Some("foo".to_string())); - /// assert_eq!(v, vec!("baz".to_string(), "qux".to_string())); + /// assert_eq!(v, vec!["baz".to_string(), "qux".to_string()]); /// /// assert_eq!(v.swap_remove(2), None); /// ``` @@ -983,9 +983,9 @@ impl Vec { /// # Example /// /// ```rust - /// let mut vec = vec!(1i, 2, 3); + /// let mut vec = vec![1i, 2, 3]; /// vec.unshift(4); - /// assert_eq!(vec, vec!(4, 1, 2, 3)); + /// assert_eq!(vec, vec![4, 1, 2, 3]); /// ``` #[inline] pub fn unshift(&mut self, element: T) { @@ -1003,9 +1003,9 @@ impl Vec { /// # Example /// /// ```rust - /// let mut vec = vec!(1i, 2, 3); + /// let mut vec = vec![1i, 2, 3]; /// assert!(vec.shift() == Some(1)); - /// assert_eq!(vec, vec!(2, 3)); + /// assert_eq!(vec, vec![2, 3]); /// ``` #[inline] pub fn shift(&mut self) -> Option { @@ -1023,11 +1023,11 @@ impl Vec { /// # Example /// /// ```rust - /// let mut vec = vec!(1i, 2, 3); + /// let mut vec = vec![1i, 2, 3]; /// vec.insert(1, 4); - /// assert_eq!(vec, vec!(1, 4, 2, 3)); + /// assert_eq!(vec, vec![1, 4, 2, 3]); /// vec.insert(4, 5); - /// assert_eq!(vec, vec!(1, 4, 2, 3, 5)); + /// assert_eq!(vec, vec![1, 4, 2, 3, 5]); /// ``` pub fn insert(&mut self, index: uint, element: T) { let len = self.len(); @@ -1057,13 +1057,13 @@ impl Vec { /// # Example /// /// ```rust - /// let mut v = vec!(1i, 2, 3); + /// let mut v = vec![1i, 2, 3]; /// assert_eq!(v.remove(1), Some(2)); - /// assert_eq!(v, vec!(1, 3)); + /// assert_eq!(v, vec![1, 3]); /// /// assert_eq!(v.remove(4), None); /// // v is unchanged: - /// assert_eq!(v, vec!(1, 3)); + /// assert_eq!(v, vec![1, 3]); /// ``` pub fn remove(&mut self, index: uint) -> Option { let len = self.len(); @@ -1096,9 +1096,9 @@ impl Vec { /// # Example /// /// ```rust - /// let mut vec = vec!(box 1i); - /// vec.push_all_move(vec!(box 2, box 3, box 4)); - /// assert_eq!(vec, vec!(box 1, box 2, box 3, box 4)); + /// let mut vec = vec![box 1i]; + /// vec.push_all_move(vec![box 2, box 3, box 4]); + /// assert_eq!(vec, vec![box 1, box 2, box 3, box 4]); /// ``` #[inline] pub fn push_all_move(&mut self, other: Vec) { @@ -1115,7 +1115,7 @@ impl Vec { /// # Example /// /// ```rust - /// let mut vec = vec!(1i, 2, 3, 4); + /// let mut vec = vec![1i, 2, 3, 4]; /// assert!(vec.mut_slice(0, 2) == [1, 2]); /// ``` #[inline] @@ -1133,7 +1133,7 @@ impl Vec { /// # Example /// /// ```rust - /// let mut vec = vec!(1i, 2, 3, 4); + /// let mut vec = vec![1i, 2, 3, 4]; /// assert!(vec.mut_slice_from(2) == [3, 4]); /// ``` #[inline] @@ -1150,7 +1150,7 @@ impl Vec { /// # Example /// /// ```rust - /// let mut vec = vec!(1i, 2, 3, 4); + /// let mut vec = vec![1i, 2, 3, 4]; /// assert!(vec.mut_slice_to(2) == [1, 2]); /// ``` #[inline] @@ -1171,7 +1171,7 @@ impl Vec { /// # Example /// /// ```rust - /// let mut vec = vec!(1i, 2, 3, 4, 5, 6); + /// let mut vec = vec![1i, 2, 3, 4, 5, 6]; /// /// // scoped to restrict the lifetime of the borrows /// { @@ -1202,9 +1202,9 @@ impl Vec { /// # Example /// /// ```rust - /// let mut v = vec!(1i, 2, 3); + /// let mut v = vec![1i, 2, 3]; /// v.reverse(); - /// assert_eq!(v, vec!(3i, 2, 1)); + /// assert_eq!(v, vec![3i, 2, 1]); /// ``` #[inline] pub fn reverse(&mut self) { @@ -1220,7 +1220,7 @@ impl Vec { /// # Example /// /// ```rust - /// let vec = vec!(1i, 2, 3); + /// let vec = vec![1i, 2, 3]; /// assert!(vec.slice_from(1) == [2, 3]); /// ``` #[inline] @@ -1237,7 +1237,7 @@ impl Vec { /// # Example /// /// ```rust - /// let vec = vec!(1i, 2, 3); + /// let vec = vec![1i, 2, 3]; /// assert!(vec.slice_to(2) == [1, 2]); /// ``` #[inline] @@ -1288,9 +1288,9 @@ impl Vec { /// # Example /// /// ```rust - /// let mut vec = vec!(1i, 2, 3, 4); + /// let mut vec = vec![1i, 2, 3, 4]; /// vec.retain(|x| x%2 == 0); - /// assert_eq!(vec, vec!(2, 4)); + /// assert_eq!(vec, vec![2, 4]); /// ``` pub fn retain(&mut self, f: |&T| -> bool) { let len = self.len(); @@ -1319,9 +1319,9 @@ impl Vec { /// # Example /// /// ```rust - /// let mut vec = vec!(0u, 1); + /// let mut vec = vec![0u, 1]; /// vec.grow_fn(3, |i| i); - /// assert_eq!(vec, vec!(0, 1, 0, 1, 2)); + /// assert_eq!(vec, vec![0, 1, 0, 1, 2]); /// ``` pub fn grow_fn(&mut self, n: uint, f: |uint| -> T) { self.reserve_additional(n); @@ -1340,9 +1340,9 @@ impl Vec { /// # Example /// /// ```rust - /// let mut vec = vec!(3i, 1, 2); + /// let mut vec = vec![3i, 1, 2]; /// vec.sort(); - /// assert_eq!(vec, vec!(1, 2, 3)); + /// assert_eq!(vec, vec![1, 2, 3]); /// ``` pub fn sort(&mut self) { self.as_mut_slice().sort() @@ -1362,7 +1362,7 @@ impl Vec { /// # Example /// /// ```rust - /// let vec = vec!(1i, 2, 3); + /// let vec = vec![1i, 2, 3]; /// assert!(vec.contains(&1)); /// ``` #[inline] @@ -1377,9 +1377,9 @@ impl Vec { /// # Example /// /// ```rust - /// let mut vec = vec!(1i, 2, 2, 3, 2); + /// let mut vec = vec![1i, 2, 2, 3, 2]; /// vec.dedup(); - /// assert_eq!(vec, vec!(1i, 2, 3, 2)); + /// assert_eq!(vec, vec![1i, 2, 3, 2]); /// ``` pub fn dedup(&mut self) { unsafe { @@ -1474,7 +1474,7 @@ impl Vector for Vec { /// ```rust /// fn foo(slice: &[int]) {} /// - /// let vec = vec!(1i, 2); + /// let vec = vec![1i, 2]; /// foo(vec.as_slice()); /// ``` #[inline] From 4357da356071e34278c5ef29aa1480360d0659b5 Mon Sep 17 00:00:00 2001 From: Jonas Hietala Date: Tue, 22 Jul 2014 11:07:49 +0200 Subject: [PATCH 2/4] doc: Fill vec documentation with examples. Add more useful functions to main example. --- src/libcollections/vec.rs | 73 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 72 insertions(+), 1 deletion(-) diff --git a/src/libcollections/vec.rs b/src/libcollections/vec.rs index f75865c218d10..707732557f48a 100644 --- a/src/libcollections/vec.rs +++ b/src/libcollections/vec.rs @@ -46,6 +46,16 @@ pub static PTR_MARKER: u8 = 0; /// /// assert_eq!(vec.pop(), Some(2)); /// assert_eq!(vec.len(), 1); +/// +/// *vec.get_mut(0) = 7i; +/// assert_eq!(vec[0], 7); +/// +/// vec.push_all([1, 2, 3]); +/// +/// for x in vec.iter() { +/// println!("{}", x); +/// } +/// assert_eq!(vec, vec![7i, 1, 2, 3]); /// ``` /// /// The `vec!` macro is provided to make initialization more convenient: @@ -56,6 +66,25 @@ pub static PTR_MARKER: u8 = 0; /// assert_eq!(vec, vec![1, 2, 3, 4]); /// ``` /// +/// Use a `Vec` as an efficient stack: +/// +/// ``` +/// let mut stack = Vec::new(); +/// +/// stack.push(1i); +/// stack.push(2i); +/// stack.push(3i); +/// +/// loop { +/// let top = match stack.pop() { +/// None => break, // empty +/// Some(x) => x, +/// }; +/// // Prints 3, 2, 1 +/// println!("{}", top); +/// } +/// ``` +/// /// # Capacity and reallocation /// /// The capacity of a vector is the amount of space allocated for any future @@ -766,6 +795,15 @@ impl Vec { /// This will explicitly set the size of the vector, without actually /// modifying its buffers, so it is up to the caller to ensure that the /// vector is actually the specified size. + /// + /// # Example + /// + /// ``` + /// let mut v = vec![1u, 2, 3, 4]; + /// unsafe { + /// v.set_len(1); + /// } + /// ``` #[inline] pub unsafe fn set_len(&mut self, len: uint) { self.len = len; @@ -1237,7 +1275,7 @@ impl Vec { /// # Example /// /// ```rust - /// let vec = vec![1i, 2, 3]; + /// let vec = vec![1i, 2, 3, 4]; /// assert!(vec.slice_to(2) == [1, 2]); /// ``` #[inline] @@ -1250,6 +1288,13 @@ impl Vec { /// # Failure /// /// Fails if the vector is empty + /// + /// # Example + /// + /// ``` + /// let vec = vec![1i, 2, 3]; + /// assert!(vec.init() == [1, 2]); + /// ``` #[inline] pub fn init<'a>(&'a self) -> &'a [T] { self.slice(0, self.len() - 1) @@ -1263,6 +1308,19 @@ impl Vec { /// /// Modifying the vector may cause its buffer to be reallocated, which /// would also make any pointers to it invalid. + /// + /// # Example + /// + /// ``` + /// use std::vec::raw; + /// + /// let v = vec![1i, 2, 3]; + /// let p = v.as_ptr(); + /// unsafe { + /// let b = raw::from_buf(p, 3u); + /// assert_eq!(b, vec![1i, 2, 3]); + /// } + /// ``` #[inline] pub fn as_ptr(&self) -> *const T { self.ptr as *const T @@ -1275,6 +1333,19 @@ impl Vec { /// /// Modifying the vector may cause its buffer to be reallocated, which /// would also make any pointers to it invalid. + /// + /// # Example + /// + /// ``` + /// use std::ptr; + /// + /// let mut v = vec![1i, 2, 3]; + /// let p = v.as_mut_ptr(); + /// unsafe { + /// ptr::write(p, 9i); + /// } + /// assert_eq!(v, vec![9i, 2, 3]); + /// ``` #[inline] pub fn as_mut_ptr(&mut self) -> *mut T { self.ptr From eafcf6ba417973c0d8658b9cfe8c21d809aaa381 Mon Sep 17 00:00:00 2001 From: Jonas Hietala Date: Tue, 22 Jul 2014 13:40:38 +0200 Subject: [PATCH 3/4] doc: Vec::from_raw_parts. Also more explicit raw pointer handling in unsafe examples. --- src/libcollections/vec.rs | 42 ++++++++++++++++++++++++++++++++++----- 1 file changed, 37 insertions(+), 5 deletions(-) diff --git a/src/libcollections/vec.rs b/src/libcollections/vec.rs index 707732557f48a..99eba0da19d1d 100644 --- a/src/libcollections/vec.rs +++ b/src/libcollections/vec.rs @@ -204,6 +204,37 @@ impl Vec { /// - there must be `length` valid instances of type `T` at the /// beginning of that allocation /// - `ptr` must be allocated by the default `Vec` allocator + /// + /// # Example + /// + /// ``` + /// use std::ptr; + /// use std::mem; + /// + /// fn main() { + /// let mut v = vec![1i, 2, 3]; + /// + /// // Pull out the various important pieces of information about `v` + /// let p = v.as_mut_ptr(); + /// let len = v.len(); + /// let cap = v.capacity(); + /// + /// unsafe { + /// // Cast `v` into the void: no destructor run, so we are in + /// // complete control of the allocation to which `p` points. + /// mem::forget(v); + /// + /// // Overwrite memory with 4, 5, 6 + /// for i in range(0, len as int) { + /// ptr::write(p.offset(i), 4 + i); + /// } + /// + /// // Put everything back together into a Vec + /// let rebuilt = Vec::from_raw_parts(len, cap, p); + /// assert_eq!(rebuilt, vec![4i, 5i, 6i]); + /// } + /// } + /// ``` pub unsafe fn from_raw_parts(length: uint, capacity: uint, ptr: *mut T) -> Vec { Vec { len: length, cap: capacity, ptr: ptr } @@ -1312,13 +1343,13 @@ impl Vec { /// # Example /// /// ``` - /// use std::vec::raw; - /// /// let v = vec![1i, 2, 3]; /// let p = v.as_ptr(); /// unsafe { - /// let b = raw::from_buf(p, 3u); - /// assert_eq!(b, vec![1i, 2, 3]); + /// // Examine each element manually + /// assert_eq!(*p, 1i); + /// assert_eq!(*p.offset(1), 2i); + /// assert_eq!(*p.offset(2), 3i); /// } /// ``` #[inline] @@ -1343,8 +1374,9 @@ impl Vec { /// let p = v.as_mut_ptr(); /// unsafe { /// ptr::write(p, 9i); + /// ptr::write(p.offset(2), 5i); /// } - /// assert_eq!(v, vec![9i, 2, 3]); + /// assert_eq!(v, vec![9i, 2, 5]); /// ``` #[inline] pub fn as_mut_ptr(&mut self) -> *mut T { From 8d54ec8f4bdd88fe35911aa236ed67deef6bd521 Mon Sep 17 00:00:00 2001 From: Jonas Hietala Date: Tue, 22 Jul 2014 14:02:55 +0200 Subject: [PATCH 4/4] doc: Normalize example style Remove unnecessary `use std::vec::Vec`. Use ``` code blocks with rust as default instead of spelling it out. --- src/libcollections/vec.rs | 115 ++++++++++++++++++-------------------- 1 file changed, 53 insertions(+), 62 deletions(-) diff --git a/src/libcollections/vec.rs b/src/libcollections/vec.rs index 99eba0da19d1d..0002867495c78 100644 --- a/src/libcollections/vec.rs +++ b/src/libcollections/vec.rs @@ -35,8 +35,7 @@ pub static PTR_MARKER: u8 = 0; /// /// # Examples /// -/// ```rust -/// # use std::vec::Vec; +/// ``` /// let mut vec = Vec::new(); /// vec.push(1i); /// vec.push(2i); @@ -60,7 +59,7 @@ pub static PTR_MARKER: u8 = 0; /// /// The `vec!` macro is provided to make initialization more convenient: /// -/// ```rust +/// ``` /// let mut vec = vec![1i, 2i, 3i]; /// vec.push(4); /// assert_eq!(vec, vec![1, 2, 3, 4]); @@ -115,8 +114,7 @@ impl Vec { /// /// # Example /// - /// ```rust - /// # use std::vec::Vec; + /// ``` /// let mut vec: Vec = Vec::new(); /// ``` #[inline] @@ -141,8 +139,7 @@ impl Vec { /// /// # Example /// - /// ```rust - /// # use std::vec::Vec; + /// ``` /// let mut vec: Vec = Vec::with_capacity(10); /// /// // The vector contains no items, even though it has capacity for more @@ -177,8 +174,7 @@ impl Vec { /// /// # Example /// - /// ```rust - /// # use std::vec::Vec; + /// ``` /// let vec = Vec::from_fn(3, |idx| idx * 2); /// assert_eq!(vec, vec![0, 2, 4]); /// ``` @@ -248,7 +244,7 @@ impl Vec { /// /// # Example /// - /// ```rust + /// ``` /// let vec = vec![1i, 2i, 3i, 4i]; /// let (even, odd) = vec.partition(|&n| n % 2 == 0); /// assert_eq!(even, vec![2, 4]); @@ -277,7 +273,7 @@ impl Vec { /// /// # Example /// - /// ```rust + /// ``` /// let vec = vec![1i, 2i]; /// let vec = vec.append([3i, 4i]); /// assert_eq!(vec, vec![1, 2, 3, 4]); @@ -292,8 +288,7 @@ impl Vec { /// /// # Example /// - /// ```rust - /// # use std::vec::Vec; + /// ``` /// let slice = [1i, 2, 3]; /// let vec = Vec::from_slice(slice); /// ``` @@ -309,8 +304,7 @@ impl Vec { /// Creates a `Vec` with `length` copies of `value`. /// /// # Example - /// ```rust - /// # use std::vec::Vec; + /// ``` /// let vec = Vec::from_elem(3, "hi"); /// println!("{}", vec); // prints [hi, hi, hi] /// ``` @@ -335,7 +329,7 @@ impl Vec { /// /// # Example /// - /// ```rust + /// ``` /// let mut vec = vec![1i]; /// vec.push_all([2i, 3, 4]); /// assert_eq!(vec, vec![1, 2, 3, 4]); @@ -365,7 +359,7 @@ impl Vec { /// /// # Example /// - /// ```rust + /// ``` /// let mut vec = vec!["hello"]; /// vec.grow(2, &("world")); /// assert_eq!(vec, vec!["hello", "world", "world"]); @@ -389,7 +383,7 @@ impl Vec { /// /// # Example /// - /// ```rust + /// ``` /// let mut vec = vec!["a", "b", "c"]; /// vec.grow_set(1, &("fill"), "d"); /// vec.grow_set(4, &("fill"), "e"); @@ -411,7 +405,7 @@ impl Vec { /// /// # Example /// - /// ```rust + /// ``` /// let vec = vec![1i, 2, 3, 4]; /// let (even, odd) = vec.partitioned(|&n| n % 2 == 0); /// assert_eq!(even, vec![2i, 4]); @@ -561,8 +555,7 @@ impl Vec { /// /// # Example /// - /// ```rust - /// # use std::vec::Vec; + /// ``` /// let vec: Vec = Vec::with_capacity(10); /// assert_eq!(vec.capacity(), 10); /// ``` @@ -580,8 +573,7 @@ impl Vec { /// /// # Example /// - /// ```rust - /// # use std::vec::Vec; + /// ``` /// let mut vec: Vec = vec![1i]; /// vec.reserve_additional(10); /// assert!(vec.capacity() >= 11); @@ -606,7 +598,7 @@ impl Vec { /// /// # Example /// - /// ```rust + /// ``` /// let mut vec = vec![1i, 2, 3]; /// vec.reserve(10); /// assert!(vec.capacity() >= 10); @@ -624,8 +616,7 @@ impl Vec { /// /// # Example /// - /// ```rust - /// # use std::vec::Vec; + /// ``` /// let mut vec: Vec = Vec::with_capacity(10); /// vec.reserve_exact(11); /// assert_eq!(vec.capacity(), 11); @@ -648,7 +639,7 @@ impl Vec { /// /// # Example /// - /// ```rust + /// ``` /// let mut vec = vec![1i, 2, 3]; /// vec.shrink_to_fit(); /// ``` @@ -680,7 +671,7 @@ impl Vec { /// /// # Example /// - /// ```rust + /// ``` /// let mut vec = vec![1i, 2, 3]; /// assert_eq!(vec.pop(), Some(3)); /// assert_eq!(vec, vec![1, 2]); @@ -705,7 +696,7 @@ impl Vec { /// /// # Example /// - /// ```rust + /// ``` /// let mut vec = vec![1i, 2]; /// vec.push(3); /// assert_eq!(vec, vec![1, 2, 3]); @@ -741,7 +732,7 @@ impl Vec { /// /// # Example /// - /// ```rust + /// ``` /// let vec = vec![1i, 2]; /// let vec = vec.append_one(3); /// assert_eq!(vec, vec![1, 2, 3]); @@ -759,7 +750,7 @@ impl Vec { /// /// # Example /// - /// ```rust + /// ``` /// let mut vec = vec![1i, 2, 3, 4]; /// vec.truncate(2); /// assert_eq!(vec, vec![1, 2]); @@ -780,7 +771,7 @@ impl Vec { /// /// # Example /// - /// ```rust + /// ``` /// fn foo(slice: &mut [int]) {} /// /// let mut vec = vec![1i, 2]; @@ -802,7 +793,7 @@ impl Vec { /// /// # Example /// - /// ```rust + /// ``` /// let v = vec!["a".to_string(), "b".to_string()]; /// for s in v.move_iter() { /// // s has type String, not &String @@ -848,7 +839,7 @@ impl Vec { /// /// # Example /// - /// ```rust + /// ``` /// #![allow(deprecated)] /// /// let vec = vec![1i, 2, 3]; @@ -868,7 +859,7 @@ impl Vec { /// /// # Example /// - /// ```rust + /// ``` /// let mut vec = vec![1i, 2, 3]; /// *vec.get_mut(1) = 4; /// assert_eq!(vec, vec![1i, 4, 3]); @@ -883,7 +874,7 @@ impl Vec { /// /// # Example /// - /// ```rust + /// ``` /// let vec = vec![1i, 2, 3]; /// for num in vec.iter() { /// println!("{}", *num); @@ -900,7 +891,7 @@ impl Vec { /// /// # Example /// - /// ```rust + /// ``` /// let mut vec = vec![1i, 2, 3]; /// for num in vec.mut_iter() { /// *num = 0; @@ -918,7 +909,7 @@ impl Vec { /// /// # Example /// - /// ```rust + /// ``` /// let mut v = vec![5i, 4, 1, 3, 2]; /// v.sort_by(|a, b| a.cmp(b)); /// assert_eq!(v, vec![1i, 2, 3, 4, 5]); @@ -941,7 +932,7 @@ impl Vec { /// /// # Example /// - /// ```rust + /// ``` /// let vec = vec![1i, 2, 3, 4]; /// assert!(vec.slice(0, 2) == [1, 2]); /// ``` @@ -958,7 +949,7 @@ impl Vec { /// /// # Example /// - /// ```rust + /// ``` /// let vec = vec![1i, 2, 3]; /// assert!(vec.tail() == [2, 3]); /// ``` @@ -975,7 +966,7 @@ impl Vec { /// /// # Example /// - /// ```rust + /// ``` /// let vec = vec![1i, 2, 3, 4]; /// assert!(vec.tailn(2) == [3, 4]); /// ``` @@ -989,7 +980,7 @@ impl Vec { /// /// # Example /// - /// ```rust + /// ``` /// let vec = vec![1i, 2, 3]; /// assert!(vec.last() == Some(&3)); /// ``` @@ -1003,7 +994,7 @@ impl Vec { /// /// # Example /// - /// ```rust + /// ``` /// let mut vec = vec![1i, 2, 3]; /// *vec.mut_last().unwrap() = 4; /// assert_eq!(vec, vec![1i, 2, 4]); @@ -1019,7 +1010,7 @@ impl Vec { /// Returns `None` if `index` is out of bounds. /// /// # Example - /// ```rust + /// ``` /// let mut v = vec!["foo".to_string(), "bar".to_string(), /// "baz".to_string(), "qux".to_string()]; /// @@ -1051,7 +1042,7 @@ impl Vec { /// /// # Example /// - /// ```rust + /// ``` /// let mut vec = vec![1i, 2, 3]; /// vec.unshift(4); /// assert_eq!(vec, vec![4, 1, 2, 3]); @@ -1071,7 +1062,7 @@ impl Vec { /// /// # Example /// - /// ```rust + /// ``` /// let mut vec = vec![1i, 2, 3]; /// assert!(vec.shift() == Some(1)); /// assert_eq!(vec, vec![2, 3]); @@ -1091,7 +1082,7 @@ impl Vec { /// /// # Example /// - /// ```rust + /// ``` /// let mut vec = vec![1i, 2, 3]; /// vec.insert(1, 4); /// assert_eq!(vec, vec![1, 4, 2, 3]); @@ -1125,7 +1116,7 @@ impl Vec { /// /// # Example /// - /// ```rust + /// ``` /// let mut v = vec![1i, 2, 3]; /// assert_eq!(v.remove(1), Some(2)); /// assert_eq!(v, vec![1, 3]); @@ -1164,7 +1155,7 @@ impl Vec { /// /// # Example /// - /// ```rust + /// ``` /// let mut vec = vec![box 1i]; /// vec.push_all_move(vec![box 2, box 3, box 4]); /// assert_eq!(vec, vec![box 1, box 2, box 3, box 4]); @@ -1183,7 +1174,7 @@ impl Vec { /// /// # Example /// - /// ```rust + /// ``` /// let mut vec = vec![1i, 2, 3, 4]; /// assert!(vec.mut_slice(0, 2) == [1, 2]); /// ``` @@ -1201,7 +1192,7 @@ impl Vec { /// /// # Example /// - /// ```rust + /// ``` /// let mut vec = vec![1i, 2, 3, 4]; /// assert!(vec.mut_slice_from(2) == [3, 4]); /// ``` @@ -1218,7 +1209,7 @@ impl Vec { /// /// # Example /// - /// ```rust + /// ``` /// let mut vec = vec![1i, 2, 3, 4]; /// assert!(vec.mut_slice_to(2) == [1, 2]); /// ``` @@ -1239,7 +1230,7 @@ impl Vec { /// /// # Example /// - /// ```rust + /// ``` /// let mut vec = vec![1i, 2, 3, 4, 5, 6]; /// /// // scoped to restrict the lifetime of the borrows @@ -1270,7 +1261,7 @@ impl Vec { /// /// # Example /// - /// ```rust + /// ``` /// let mut v = vec![1i, 2, 3]; /// v.reverse(); /// assert_eq!(v, vec![3i, 2, 1]); @@ -1288,7 +1279,7 @@ impl Vec { /// /// # Example /// - /// ```rust + /// ``` /// let vec = vec![1i, 2, 3]; /// assert!(vec.slice_from(1) == [2, 3]); /// ``` @@ -1305,7 +1296,7 @@ impl Vec { /// /// # Example /// - /// ```rust + /// ``` /// let vec = vec![1i, 2, 3, 4]; /// assert!(vec.slice_to(2) == [1, 2]); /// ``` @@ -1390,7 +1381,7 @@ impl Vec { /// /// # Example /// - /// ```rust + /// ``` /// let mut vec = vec![1i, 2, 3, 4]; /// vec.retain(|x| x%2 == 0); /// assert_eq!(vec, vec![2, 4]); @@ -1421,7 +1412,7 @@ impl Vec { /// /// # Example /// - /// ```rust + /// ``` /// let mut vec = vec![0u, 1]; /// vec.grow_fn(3, |i| i); /// assert_eq!(vec, vec![0, 1, 0, 1, 2]); @@ -1442,7 +1433,7 @@ impl Vec { /// /// # Example /// - /// ```rust + /// ``` /// let mut vec = vec![3i, 1, 2]; /// vec.sort(); /// assert_eq!(vec, vec![1, 2, 3]); @@ -1464,7 +1455,7 @@ impl Vec { /// /// # Example /// - /// ```rust + /// ``` /// let vec = vec![1i, 2, 3]; /// assert!(vec.contains(&1)); /// ``` @@ -1479,7 +1470,7 @@ impl Vec { /// /// # Example /// - /// ```rust + /// ``` /// let mut vec = vec![1i, 2, 2, 3, 2]; /// vec.dedup(); /// assert_eq!(vec, vec![1i, 2, 3, 2]); @@ -1574,7 +1565,7 @@ impl Vector for Vec { /// /// # Example /// - /// ```rust + /// ``` /// fn foo(slice: &[int]) {} /// /// let vec = vec![1i, 2];