Address bluss's comments and add iteration section

Author: jturner314

src/doc/ndarray_for_numpy_users/mod.rs

@@ -1,7 +1,29 @@
 //! `ndarray` for NumPy users.
 //!
-//! `ndarray`'s array type ([`ArrayBase`](../../struct.ArrayBase.html)), is
-//! very similar to NumPy's array type (`numpy.ndarray`):
+//! This is an introductory guide to `ndarray` for people with experience using
+//! NumPy, although it may also be useful to others. For a more general
+//! introduction to `ndarray`'s array type `ArrayBase`, see the [`ArrayBase`
+//! docs][ArrayBase].
+//!
+//! # Contents
+//!
+//! * [Similarities](#similarities)
+//! * [Some key differences](#some-key-differences)
+//! * [Other Rust array/matrix crates](#other-rust-arraymatrix-crates)
+//! * [Rough `ndarray`–NumPy equivalents](#rough-ndarraynumpy-equivalents)
+//!
+//!   * [Array creation](#array-creation)
+//!   * [Indexing and slicing](#indexing-and-slicing)
+//!   * [Shape and strides](#shape-and-strides)
+//!   * [Mathematics](#mathematics)
+//!   * [Array manipulation](#array-manipulation)
+//!   * [Iteration](#iteration)
+//!   * [Convenience methods for 2-D arrays](#convenience-methods-for-2-d-arrays)
+//!
+//! # Similarities
+//!
+//! `ndarray`'s array type ([`ArrayBase`][ArrayBase]), is very similar to
+//! NumPy's array type (`numpy.ndarray`):
 //!
 //! * Arrays have a single element type.
 //! * Arrays can have arbitrarily many dimensions.
@@ -47,14 +69,12 @@
 //! </td>
 //! <td>
 //!
-//! In `ndarray`, all arrays are instances of
-//! [`ArrayBase`](../../struct.ArrayBase.html), but `ArrayBase` is generic over
-//! the ownership of the data. [`Array`](../../type.Array.html) owns its data;
-//! [`ArrayView`](../../type.ArrayView.html) is a view;
-//! [`ArrayViewMut`](../../type.ArrayViewMut.html) is a mutable view; and
-//! [`ArcArray`](../../type.ArcArray.html) has a reference-counted pointer to
-//! its data (with copy-on-write mutation). Arrays and views follow Rust's
-//! aliasing rules.
+//! In `ndarray`, all arrays are instances of [`ArrayBase`][ArrayBase], but
+//! `ArrayBase` is generic over the ownership of the data. [`Array`][Array]
+//! owns its data; [`ArrayView`][ArrayView] is a view;
+//! [`ArrayViewMut`][ArrayViewMut] is a mutable view; and
+//! [`ArcArray`][ArcArray] has a reference-counted pointer to its data (with
+//! copy-on-write mutation). Arrays and views follow Rust's aliasing rules.
 //!
 //! </td>
 //! </tr>
@@ -68,9 +88,9 @@
 //! <td>
 //!
 //! In `ndarray`, you can create fixed-dimension arrays, such as
-//! [`Array2`](../../type.Array2.html). This takes advantage of the type system
-//! to help you write correct code and also avoids small heap allocations for
-//! the shape and strides.
+//! [`Array2`][Array2]. This takes advantage of the type system to help you
+//! write correct code and also avoids small heap allocations for the shape and
+//! strides.
 //!
 //! </td>
 //! </tr>
@@ -164,13 +184,14 @@
 //! `np.array([[1.,2.,3.], [4.,5.,6.]])` | [`array![[1.,2.,3.], [4.,5.,6.]]`][array!] or [`arr2(&[[1.,2.,3.], [4.,5.,6.]])`][arr2()] | 2×3 floating-point array literal
 //! `np.arange(0., 10., 0.5)` or `np.r_[:10.:0.5]` | [`Array::range(0., 10., 0.5)`][::range()] | create a 1-D array with values `0.`, `0.5`, …, `9.5`
 //! `np.linspace(0., 10., 11)` or `np.r_[:10.:11j]` | [`Array::linspace(0., 10., 11)`][::linspace()] | create a 1-D array with 11 elements with values `0.`, …, `10.`
+//! `np.ones((3, 4, 5))` | [`Array::ones((3, 4, 5))`][::ones()] | create a 3×4×5 array filled with ones (inferring the element type)
 //! `np.zeros((3, 4, 5))` | [`Array::zeros((3, 4, 5))`][::zeros()] | create a 3×4×5 array filled with zeros (inferring the element type)
 //! `np.zeros((3, 4, 5), order='F')` | [`Array::zeros((3, 4, 5).f())`][::zeros()] | create a 3×4×5 array with Fortran (column-major) memory layout filled with zeros (inferring the element type)
+//! `np.zeros_like(a, order='C')` | [`Array::zeros(a.raw_dim())`][::zeros()] | create an array of zeros of the shape shape as `a`, with row-major memory layout (unlike NumPy, this infers the element type from context instead of duplicating `a`'s element type)
 //! `np.full((3, 4), 7.)` | [`Array::from_elem((3, 4), 7.)`][::from_elem()] | create a 3×4 array filled with the value `7.`
 //! `np.eye(3)` | [`Array::eye(3)`][::eye()] | create a 3×3 identity matrix (inferring the element type)
 //! `np.array([1, 2, 3, 4]).reshape((2, 2))` | [`Array::from_shape_vec((2, 2), vec![1, 2, 3, 4])?`][::from_shape_vec()] | create a 2×2 array from the elements in the list/`Vec`
 //! `np.array([1, 2, 3, 4]).reshape((2, 2), order='F')` | [`Array::from_shape_vec((2, 2).f(), vec![1, 2, 3, 4])?`][::from_shape_vec()] | create a 2×2 array from the elements in the list/`Vec` using Fortran (column-major) order
-//! `np.empty((3, 4))` | [`unsafe { Array::uninitialized((3, 4)) }`][::uninitialized()] | create a 3×4 uninitialized array (inferring the element type)
 //! `np.random` | See the [`ndarray-rand`](https://crates.io/crates/ndarray-rand) crate. | create arrays of random numbers
 //!
 //! ## Indexing and slicing
@@ -190,22 +211,30 @@
 //!
 //! NumPy | `ndarray` | Notes
 //! ------|-----------|------
-//! `a[-1]` | [`a[a.len()-1]`][.index()] | access the last element in 1-D array `a`
-//! `a[1,4]` | [`a[(1,4)]`][.index()] | access the element in row 1, column 4
-//! `a[1]` or `a[1,:,:]` | [`a.slice(s![1, .., ..])`][.slice()] or [`a.subview(Axis(0), 1)`][.subview()] | get a 2-D subview of a 3-D array at index 1 of axis 0
-//! `a[0:5]` or `a[:5]` or `a[0:5,:]` | [`a.slice(s![0..5, ..])`][.slice()] or [`a.slice(s![..5, ..])`][.slice()] or [`a.slice_axis(Axis(0), (0..5).into())`][.slice_axis()] | get the first 5 rows of a 2-D array
-//! `a[-5:]` or `a[-5:,:]` | [`a.slice(s![-5.., ..])`][.slice()] or [`a.slice_axis(Axis(0), (-5..).into())`][.slice_axis()] | get the last 5 rows of a 2-D array
-//! `a[:3,4:9]` | [`a.slice(s![..3, 4..9])`][.slice()] | columns 4, 5, 6, 7, and 8 of the first 3 rows
-//! `a[1:4:2,::-1]` | [`a.slice(s![1..4;2, ..;-1])`][.slice()] | rows 1 and 3 with the columns in reverse order
+//! `a[-1]` | [`a[a.len() - 1]`][.index()] | access the last element in 1-D array `a`
+//! `a[1, 4]` | [`a[[1, 4]]`][.index()] | access the element in row 1, column 4
+//! `a[1]` or `a[1, :, :]` | [`a.slice(s![1, .., ..])`][.slice()] or [`a.subview(Axis(0), 1)`][.subview()] | get a 2-D subview of a 3-D array at index 1 of axis 0
+//! `a[0:5]` or `a[:5]` or `a[0:5, :]` | [`a.slice(s![0..5, ..])`][.slice()] or [`a.slice(s![..5, ..])`][.slice()] or [`a.slice_axis(Axis(0), Slice::from(0..5))`][.slice_axis()] | get the first 5 rows of a 2-D array
+//! `a[-5:]` or `a[-5:, :]` | [`a.slice(s![-5.., ..])`][.slice()] or [`a.slice_axis(Axis(0), Slice::from(-5..))`][.slice_axis()] | get the last 5 rows of a 2-D array
+//! `a[:3, 4:9]` | [`a.slice(s![..3, 4..9])`][.slice()] | columns 4, 5, 6, 7, and 8 of the first 3 rows
+//! `a[1:4:2, ::-1]` | [`a.slice(s![1..4;2, ..;-1])`][.slice()] | rows 1 and 3 with the columns in reverse order
 //!
 //! ## Shape and strides
 //!
+//! Note that [`a.shape()`][.shape()], [`a.dim()`][.dim()], and
+//! [`a.raw_dim()`][.raw_dim()] all return the shape of the array, but as
+//! different types. `a.shape()` returns the shape as `&[Ix]`, (where
+//! [`Ix`][Ix] is `usize`) which is useful for general operations on the shape.
+//! `a.dim()` returns the shape as `D::Pattern`, which is useful for
+//! pattern-matching shapes. `a.raw_dim()` returns the shape as `D`, which is
+//! useful for creating other arrays of the same shape.
+//!
 //! NumPy | `ndarray` | Notes
 //! ------|-----------|------
 //! `np.ndim(a)` or `a.ndim` | [`a.ndim()`][.ndim()] | get the number of dimensions of array `a`
 //! `np.size(a)` or `a.size` | [`a.len()`][.len()] | get the number of elements in array `a`
 //! `np.shape(a)` or `a.shape` | [`a.shape()`][.shape()] or [`a.dim()`][.dim()] | get the shape of array `a`
-//! `a.shape[axis]` | [`a.len_of(Axis(axis))`][.len_of()] or `a.shape()[axis]` | get the length of an axis
+//! `a.shape[axis]` | [`a.len_of(Axis(axis))`][.len_of()] | get the length of an axis
 //! `a.strides` | [`a.strides()`][.strides()] | get the strides of array `a`
 //! `np.size(a) == 0` or `a.size == 0` | [`a.is_empty()`][.is_empty()] | check if the array has zero elements
 //!
@@ -242,7 +271,7 @@
 //!
 //! </td><td>
 //!
-//! transpose of array `a`
+//! transpose of array `a` (view for `.t()` or by-move for `.reversed_axes()`)
 //!
 //! </td></tr>
 //!
@@ -467,11 +496,33 @@
 //! `a[:] = b` | [`a.assign(&b)`][.assign()] | copy the data from array `b` into array `a`
 //! `np.concatenate((a,b), axis=1)` | [`stack![Axis(1), a, b]`][stack!] or [`stack(Axis(1), &[a.view(), b.view()])`][stack()] | concatenate arrays `a` and `b` along axis 1
 //! `a[:,np.newaxis]` or `np.expand_dims(a, axis=1)` | [`a.insert_axis(Axis(1))`][.insert_axis()] | create an array from `a`, inserting a new axis 1
-//! `a.transpose()` or `a.T` | [`a.t()`][.t()] or [`a.reversed_axes()`][.reversed_axes()] | transpose of array `a`
+//! `a.transpose()` or `a.T` | [`a.t()`][.t()] or [`a.reversed_axes()`][.reversed_axes()] | transpose of array `a` (view for `.t()` or by-move for `.reversed_axes()`)
 //! `np.diag(a)` | [`a.diag()`][.diag()] | view the diagonal of `a`
-//! `a.flat` | [`a.iter()`][.iter()] | iterator over the array elements in logical order
 //! `a.flatten()` | [`Array::from_iter(a.iter())`][::from_iter()] | create a 1-D array by flattening `a`
 //!
+//! ## Iteration
+//!
+//! `ndarray` has lots of interesting iterators/producers that implement the
+//! [`NdProducer`][NdProducer] trait, which is a generalization of `Iterator`
+//! to multiple dimensions. This makes it possible to correctly and efficiently
+//! zip together slices/subviews of arrays in multiple dimensions with
+//! [`Zip`][Zip] or [`azip!()`][azip!]. The purpose of this is similar to
+//! [`np.nditer`](https://docs.scipy.org/doc/numpy/reference/generated/numpy.nditer.html),
+//! but [`Zip`][Zip] is implemented and used somewhat differently.
+//!
+//! This table lists some of the iterators/producers which have a direct
+//! equivalent in NumPy. For a more complete introduction to producers and
+//! iterators, see [*Loops, Producers, and
+//! Iterators*](../../struct.ArrayBase.html#loops-producers-and-iterators).
+//! Note that there are also variants of these iterators (with a `_mut` suffix)
+//! that yield `ArrayViewMut` instead of `ArrayView`.
+//!
+//! NumPy | `ndarray` | Notes
+//! ------|-----------|------
+//! `a.flat` | [`a.iter()`][.iter()] | iterator over the array elements in logical order
+//! `np.ndenumerate(a)` | [`a.indexed_iter()`][.indexed_iter()] | flat iterator yielding the index along with each element reference
+//! `iter(a)` | [`a.outer_iter()`][.outer_iter()] or [`a.axis_iter(Axis(0))`][.axis_iter()] | iterator over the first (outermost) axis, yielding each subview
+//!
 //! ## Convenience methods for 2-D arrays
 //!
 //! NumPy | `ndarray` | Notes
@@ -483,9 +534,17 @@
 //! `a.shape[0] == a.shape[1]` | [`a.is_square()`][.is_square()] | check if the array is square
 //!
 //! [.all_close()]: ../../struct.ArrayBase.html#method.all_close
-//! [array!]: ../../macro.array.html
+//! [ArcArray]: ../../type.ArcArray.html
 //! [arr2()]: ../../fn.arr2.html
+//! [array!]: ../../macro.array.html
+//! [Array]: ../../type.Array.html
+//! [Array2]: ../../type.Array2.html
+//! [ArrayBase]: ../../struct.ArrayBase.html
+//! [ArrayView]: ../../type.ArrayView.html
+//! [ArrayViewMut]: ../../type.ArrayViewMut.html
 //! [.assign()]: ../../struct.ArrayBase.html#method.assign
+//! [.axis_iter()]: ../../struct.ArrayBase.html#method.axis_iter
+//! [azip!]: ../../macro.azip.html
 //! [.cols()]: ../../struct.ArrayBase.html#method.cols
 //! [.column()]: ../../struct.ArrayBase.html#method.column
 //! [.column_mut()]: ../../struct.ArrayBase.html#method.column_mut
@@ -503,10 +562,12 @@
 //! [::from_shape_vec_unchecked()]: ../../struct.ArrayBase.html#method.from_shape_vec_unchecked
 //! [::from_vec()]: ../../struct.ArrayBase.html#method.from_vec
 //! [.index()]: ../../struct.ArrayBase.html#impl-Index<I>
+//! [.indexed_iter()]: ../../struct.ArrayBase.html#method.indexed_iter
 //! [.insert_axis()]: ../../struct.ArrayBase.html#method.insert_axis
 //! [.is_empty()]: ../../struct.ArrayBase.html#method.is_empty
 //! [.is_square()]: ../../struct.ArrayBase.html#method.is_square
 //! [.iter()]: ../../struct.ArrayBase.html#method.iter
+//! [Ix]: ../../type.Ix.html
 //! [.len()]: ../../struct.ArrayBase.html#method.len
 //! [.len_of()]: ../../struct.ArrayBase.html#method.len_of
 //! [::linspace()]: ../../struct.ArrayBase.html#method.linspace
@@ -519,7 +580,11 @@
 //! [matrix-* dot]: ../../struct.ArrayBase.html#method.dot-1
 //! [.mean_axis()]: ../../struct.ArrayBase.html#method.mean_axis
 //! [.ndim()]: ../../struct.ArrayBase.html#method.ndim
+//! [NdProducer]: ../../trait.NdProducer.html
+//! [::ones()]: ../../struct.ArrayBase.html#method.ones
+//! [.outer_iter()]: ../../struct.ArrayBase.html#method.outer_iter
 //! [::range()]: ../../struct.ArrayBase.html#method.range
+//! [.raw_dim()]: ../../struct.ArrayBase.html#method.raw_dim
 //! [.reversed_axes()]: ../../struct.ArrayBase.html#method.reversed_axes
 //! [.row()]: ../../struct.ArrayBase.html#method.row
 //! [.row_mut()]: ../../struct.ArrayBase.html#method.row_mut
@@ -542,3 +607,4 @@
 //! [vec-* dot]: ../../struct.ArrayBase.html#method.dot
 //! [.visit()]: ../../struct.ArrayBase.html#method.visit
 //! [::zeros()]: ../../struct.ArrayBase.html#method.zeros
+//! [Zip]: ../../struct.Zip.html