From c004bebc9ef12b5d6c24d0d482344ad485f2050b Mon Sep 17 00:00:00 2001
From: Jonas Hietala <tradet.h@gmail.com>
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<T> Vec<T> {
/// ```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<T> {
@@ -189,10 +189,10 @@ impl<T> Vec<T> {
/// # 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<T>, Vec<T>) {
@@ -218,9 +218,9 @@ impl<T: Clone> Vec<T> {
/// # 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<T> {
@@ -276,9 +276,9 @@ impl<T: Clone> Vec<T> {
/// # 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<T: Clone> Vec<T> {
/// # 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<T: Clone> Vec<T> {
/// # 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<T: Clone> Vec<T> {
/// # 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<T>, Vec<T>) {
let mut lefts = Vec::new();
@@ -522,7 +522,7 @@ impl<T> Vec<T> {
///
/// ```rust
/// # use std::vec::Vec;
- /// let mut vec: Vec<int> = vec!(1i);
+ /// let mut vec: Vec<int> = vec![1i];
/// vec.reserve_additional(10);
/// assert!(vec.capacity() >= 11);
/// ```
@@ -547,7 +547,7 @@ impl<T> Vec<T> {
/// # 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<T> Vec<T> {
/// # 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<T> Vec<T> {
/// # 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<T> {
@@ -646,9 +646,9 @@ impl<T> Vec<T> {
/// # 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<T> Vec<T> {
/// # 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<T> {
@@ -700,9 +700,9 @@ impl<T> Vec<T> {
/// # 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<T> Vec<T> {
/// ```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<T> Vec<T> {
/// # 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<T> Vec<T> {
/// ```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<T> Vec<T> {
/// # 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<T> Vec<T> {
/// # 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<T> Vec<T> {
/// # 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<T> Vec<T> {
/// # 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<T> Vec<T> {
/// # 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<T> Vec<T> {
/// # 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<T> Vec<T> {
/// # 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<T> Vec<T> {
/// # 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<T> Vec<T> {
/// # 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<T> Vec<T> {
///
/// # 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<T> Vec<T> {
/// # 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<T> Vec<T> {
/// # 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<T> {
@@ -1023,11 +1023,11 @@ impl<T> Vec<T> {
/// # 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<T> Vec<T> {
/// # 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<T> {
let len = self.len();
@@ -1096,9 +1096,9 @@ impl<T> Vec<T> {
/// # 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<T>) {
@@ -1115,7 +1115,7 @@ impl<T> Vec<T> {
/// # 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<T> Vec<T> {
/// # 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<T> Vec<T> {
/// # 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<T> Vec<T> {
/// # 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<T> Vec<T> {
/// # 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<T> Vec<T> {
/// # 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<T> Vec<T> {
/// # 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<T> Vec<T> {
/// # 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<T> Vec<T> {
/// # 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<T:Ord> Vec<T> {
/// # 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<T:PartialEq> Vec<T> {
/// # Example
///
/// ```rust
- /// let vec = vec!(1i, 2, 3);
+ /// let vec = vec![1i, 2, 3];
/// assert!(vec.contains(&1));
/// ```
#[inline]
@@ -1377,9 +1377,9 @@ impl<T:PartialEq> Vec<T> {
/// # 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<T> Vector<T> for Vec<T> {
/// ```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 <tradet.h@gmail.com>
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<T> Vec<T> {
/// 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<T> Vec<T> {
/// # 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<T> Vec<T> {
/// # 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<T> Vec<T> {
///
/// 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<T> Vec<T> {
///
/// 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 <tradet.h@gmail.com>
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<T> Vec<T> {
/// - 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<T> {
Vec { len: length, cap: capacity, ptr: ptr }
@@ -1312,13 +1343,13 @@ impl<T> Vec<T> {
/// # 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<T> Vec<T> {
/// 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 <tradet.h@gmail.com>
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<T> Vec<T> {
///
/// # Example
///
- /// ```rust
- /// # use std::vec::Vec;
+ /// ```
/// let mut vec: Vec<int> = Vec::new();
/// ```
#[inline]
@@ -141,8 +139,7 @@ impl<T> Vec<T> {
///
/// # Example
///
- /// ```rust
- /// # use std::vec::Vec;
+ /// ```
/// let mut vec: Vec<int> = Vec::with_capacity(10);
///
/// // The vector contains no items, even though it has capacity for more
@@ -177,8 +174,7 @@ impl<T> Vec<T> {
///
/// # 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<T> Vec<T> {
///
/// # 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<T: Clone> Vec<T> {
///
/// # 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<T: Clone> Vec<T> {
///
/// # Example
///
- /// ```rust
- /// # use std::vec::Vec;
+ /// ```
/// let slice = [1i, 2, 3];
/// let vec = Vec::from_slice(slice);
/// ```
@@ -309,8 +304,7 @@ impl<T: Clone> Vec<T> {
/// 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<T: Clone> Vec<T> {
///
/// # 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<T: Clone> Vec<T> {
///
/// # Example
///
- /// ```rust
+ /// ```
/// let mut vec = vec!["hello"];
/// vec.grow(2, &("world"));
/// assert_eq!(vec, vec!["hello", "world", "world"]);
@@ -389,7 +383,7 @@ impl<T: Clone> Vec<T> {
///
/// # 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<T: Clone> Vec<T> {
///
/// # 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<T> Vec<T> {
///
/// # Example
///
- /// ```rust
- /// # use std::vec::Vec;
+ /// ```
/// let vec: Vec<int> = Vec::with_capacity(10);
/// assert_eq!(vec.capacity(), 10);
/// ```
@@ -580,8 +573,7 @@ impl<T> Vec<T> {
///
/// # Example
///
- /// ```rust
- /// # use std::vec::Vec;
+ /// ```
/// let mut vec: Vec<int> = vec![1i];
/// vec.reserve_additional(10);
/// assert!(vec.capacity() >= 11);
@@ -606,7 +598,7 @@ impl<T> Vec<T> {
///
/// # Example
///
- /// ```rust
+ /// ```
/// let mut vec = vec![1i, 2, 3];
/// vec.reserve(10);
/// assert!(vec.capacity() >= 10);
@@ -624,8 +616,7 @@ impl<T> Vec<T> {
///
/// # Example
///
- /// ```rust
- /// # use std::vec::Vec;
+ /// ```
/// let mut vec: Vec<int> = Vec::with_capacity(10);
/// vec.reserve_exact(11);
/// assert_eq!(vec.capacity(), 11);
@@ -648,7 +639,7 @@ impl<T> Vec<T> {
///
/// # Example
///
- /// ```rust
+ /// ```
/// let mut vec = vec![1i, 2, 3];
/// vec.shrink_to_fit();
/// ```
@@ -680,7 +671,7 @@ impl<T> Vec<T> {
///
/// # 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<T> Vec<T> {
///
/// # Example
///
- /// ```rust
+ /// ```
/// let mut vec = vec![1i, 2];
/// vec.push(3);
/// assert_eq!(vec, vec![1, 2, 3]);
@@ -741,7 +732,7 @@ impl<T> Vec<T> {
///
/// # 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<T> Vec<T> {
///
/// # Example
///
- /// ```rust
+ /// ```
/// let mut vec = vec![1i, 2, 3, 4];
/// vec.truncate(2);
/// assert_eq!(vec, vec![1, 2]);
@@ -780,7 +771,7 @@ impl<T> Vec<T> {
///
/// # Example
///
- /// ```rust
+ /// ```
/// fn foo(slice: &mut [int]) {}
///
/// let mut vec = vec![1i, 2];
@@ -802,7 +793,7 @@ impl<T> Vec<T> {
///
/// # 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<T> Vec<T> {
///
/// # Example
///
- /// ```rust
+ /// ```
/// #![allow(deprecated)]
///
/// let vec = vec![1i, 2, 3];
@@ -868,7 +859,7 @@ impl<T> Vec<T> {
///
/// # 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<T> Vec<T> {
///
/// # Example
///
- /// ```rust
+ /// ```
/// let vec = vec![1i, 2, 3];
/// for num in vec.iter() {
/// println!("{}", *num);
@@ -900,7 +891,7 @@ impl<T> Vec<T> {
///
/// # Example
///
- /// ```rust
+ /// ```
/// let mut vec = vec![1i, 2, 3];
/// for num in vec.mut_iter() {
/// *num = 0;
@@ -918,7 +909,7 @@ impl<T> Vec<T> {
///
/// # 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<T> Vec<T> {
///
/// # Example
///
- /// ```rust
+ /// ```
/// let vec = vec![1i, 2, 3, 4];
/// assert!(vec.slice(0, 2) == [1, 2]);
/// ```
@@ -958,7 +949,7 @@ impl<T> Vec<T> {
///
/// # Example
///
- /// ```rust
+ /// ```
/// let vec = vec![1i, 2, 3];
/// assert!(vec.tail() == [2, 3]);
/// ```
@@ -975,7 +966,7 @@ impl<T> Vec<T> {
///
/// # Example
///
- /// ```rust
+ /// ```
/// let vec = vec![1i, 2, 3, 4];
/// assert!(vec.tailn(2) == [3, 4]);
/// ```
@@ -989,7 +980,7 @@ impl<T> Vec<T> {
///
/// # Example
///
- /// ```rust
+ /// ```
/// let vec = vec![1i, 2, 3];
/// assert!(vec.last() == Some(&3));
/// ```
@@ -1003,7 +994,7 @@ impl<T> Vec<T> {
///
/// # 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<T> Vec<T> {
/// 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<T> Vec<T> {
///
/// # 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<T> Vec<T> {
///
/// # 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<T> Vec<T> {
///
/// # 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<T> Vec<T> {
///
/// # 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<T> Vec<T> {
///
/// # 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<T> Vec<T> {
///
/// # Example
///
- /// ```rust
+ /// ```
/// let mut vec = vec![1i, 2, 3, 4];
/// assert!(vec.mut_slice(0, 2) == [1, 2]);
/// ```
@@ -1201,7 +1192,7 @@ impl<T> Vec<T> {
///
/// # Example
///
- /// ```rust
+ /// ```
/// let mut vec = vec![1i, 2, 3, 4];
/// assert!(vec.mut_slice_from(2) == [3, 4]);
/// ```
@@ -1218,7 +1209,7 @@ impl<T> Vec<T> {
///
/// # Example
///
- /// ```rust
+ /// ```
/// let mut vec = vec![1i, 2, 3, 4];
/// assert!(vec.mut_slice_to(2) == [1, 2]);
/// ```
@@ -1239,7 +1230,7 @@ impl<T> Vec<T> {
///
/// # 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<T> Vec<T> {
///
/// # Example
///
- /// ```rust
+ /// ```
/// let mut v = vec![1i, 2, 3];
/// v.reverse();
/// assert_eq!(v, vec![3i, 2, 1]);
@@ -1288,7 +1279,7 @@ impl<T> Vec<T> {
///
/// # Example
///
- /// ```rust
+ /// ```
/// let vec = vec![1i, 2, 3];
/// assert!(vec.slice_from(1) == [2, 3]);
/// ```
@@ -1305,7 +1296,7 @@ impl<T> Vec<T> {
///
/// # Example
///
- /// ```rust
+ /// ```
/// let vec = vec![1i, 2, 3, 4];
/// assert!(vec.slice_to(2) == [1, 2]);
/// ```
@@ -1390,7 +1381,7 @@ impl<T> Vec<T> {
///
/// # 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<T> Vec<T> {
///
/// # 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<T:Ord> Vec<T> {
///
/// # Example
///
- /// ```rust
+ /// ```
/// let mut vec = vec![3i, 1, 2];
/// vec.sort();
/// assert_eq!(vec, vec![1, 2, 3]);
@@ -1464,7 +1455,7 @@ impl<T:PartialEq> Vec<T> {
///
/// # Example
///
- /// ```rust
+ /// ```
/// let vec = vec![1i, 2, 3];
/// assert!(vec.contains(&1));
/// ```
@@ -1479,7 +1470,7 @@ impl<T:PartialEq> Vec<T> {
///
/// # 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<T> Vector<T> for Vec<T> {
///
/// # Example
///
- /// ```rust
+ /// ```
/// fn foo(slice: &[int]) {}
///
/// let vec = vec![1i, 2];