Add mapv_into and modify docs

Author: bluss

src/impl_methods.rs

@@ -1095,8 +1095,9 @@ impl<A, S, D> ArrayBase<S, D> where S: Data<Elem=A>, D: Dimension
         init
     }
 
-    /// Create a new array with the results of applying `f` on a reference
-    /// to each element.
+    /// Call `f` by reference on each element and create a new array
+    /// with the results.
+    ///
     /// Elements are visited in arbitrary order.
     ///
     /// Return an array with the same shape as *self*.
@@ -1130,8 +1131,9 @@ impl<A, S, D> ArrayBase<S, D> where S: Data<Elem=A>, D: Dimension
         }
     }
 
-    /// Create a new array with the results of applying `f` on the value of
-    /// each element.
+    /// Call `f` by value on each element and create a new array
+    /// with the new values.
+    ///
     /// Elements are visited in arbitrary order.
     ///
     /// Return an array with the same shape as *self*.
@@ -1141,7 +1143,7 @@ impl<A, S, D> ArrayBase<S, D> where S: Data<Elem=A>, D: Dimension
     ///
     /// let a = arr2(&[[ 0., 1.],
     ///                [-1., 2.]]);
-    /// assert!(
+    /// assert_eq!(
     ///     a.mapv(f32::abs) == arr2(&[[0., 1.],
     ///                                [1., 2.]])
     /// );
@@ -1153,8 +1155,21 @@ impl<A, S, D> ArrayBase<S, D> where S: Data<Elem=A>, D: Dimension
         self.map(move |x| f(x.clone()))
     }
 
-    /// Modify the array in place by calling `f` with a mutable reference
-    /// to each element.
+    /// Call `f` by value on each element, update the array with new values
+    /// and return it.
+    ///
+    /// Elements are visited in arbitrary order.
+    pub fn mapv_into<F>(mut self, f: F) -> Self
+        where S: DataMut,
+              F: FnMut(A) -> A,
+              A: Clone,
+    {
+        self.applyv(f);
+        self
+    }
+
+    /// Modify in place by calling `f` by mutable reference on each element.
+    ///
     /// Elements are visited in arbitrary order.
     pub fn apply<F>(&mut self, f: F)
         where S: DataMut,
@@ -1163,8 +1178,9 @@ impl<A, S, D> ArrayBase<S, D> where S: Data<Elem=A>, D: Dimension
         self.unordered_foreach_mut(f);
     }
 
-    /// Modify the array in place by calling a function `f` that maps
-    /// each element by value (from `A` to `A`).
+    /// Modify in place by calling `f` by value on each element. The
+    /// array is updated with the new values.
+    ///
     /// Elements are visited in arbitrary order.
     ///
     /// ```
@@ -1173,6 +1189,10 @@ impl<A, S, D> ArrayBase<S, D> where S: Data<Elem=A>, D: Dimension
     /// let mut a = arr2(&[[ 0., 1.],
     ///                    [-1., 2.]]);
     /// a.applyv(f32::exp);
+    /// assert!(
+    ///     a.allclose(&arr2(&[[1.00000, 2.71828],
+    ///                        [0.36788, 7.38906]]), 1e-5)
+    /// );
     /// ```
     pub fn applyv<F>(&mut self, mut f: F)
         where S: DataMut,