Improve docs of linspace, range, logspace, geomspace

This includes a few corrections and clarifications:

* The old docs used interval notation in some cases, which was
  confusing in the case that `start > end`.

* `linspace` now has a note describing the difference in behavior from
  `std::ops::RangeInclusive` for the case that `start > end`.

* Panics in conversions from `usize` to `A` are now mentioned.

* The docs now say that the element type must implement `Float`
  instead of saying that it must be `f32` or `f64`.

Author: jturner314

src/geomspace.rs

@@ -66,14 +66,17 @@ impl<F> ExactSizeIterator for Geomspace<F> where Geomspace<F>: Iterator {}
 
 /// An iterator of a sequence of geometrically spaced values.
 ///
-/// The `Geomspace` has `n` elements, where the first element is `a` and the
-/// last element is `b`.
+/// The `Geomspace` has `n` geometrically spaced elements from `start` to `end`
+/// (inclusive).
 ///
-/// Iterator element type is `F`, where `F` must be either `f32` or `f64`.
+/// The iterator element type is `F`, where `F` must implement `Float`, e.g.
+/// `f32` or `f64`.
 ///
 /// Returns `None` if `start` and `end` have different signs or if either one
 /// is zero. Conceptually, this means that in order to obtain a `Some` result,
 /// `end / start` must be positive.
+///
+/// **Panics** if converting `n - 1` to type `F` fails.
 #[inline]
 pub fn geomspace<F>(a: F, b: F, n: usize) -> Option<Geomspace<F>>
 where

src/impl_constructors.rs

@@ -67,10 +67,16 @@ impl<S, A> ArrayBase<S, Ix1>
         Self::from_vec(iterable.into_iter().collect())
     }
 
-    /// Create a one-dimensional array from the inclusive interval
-    /// `[start, end]` with `n` elements. `A` must be a floating point type.
+    /// Create a one-dimensional array with `n` evenly spaced elements from
+    /// `start` to `end` (inclusive). `A` must be a floating point type.
     ///
-    /// **Panics** if `n` is greater than `isize::MAX`.
+    /// Note that if `start > end`, the first element will still be `start`,
+    /// and the following elements will be decreasing. This is different from
+    /// the behavior of `std::ops::RangeInclusive`, which interprets `start >
+    /// end` to mean that the range is empty.
+    ///
+    /// **Panics** if `n` is greater than `isize::MAX` or if converting `n - 1`
+    /// to type `A` fails.
     ///
     /// ```rust
     /// use ndarray::{Array, arr1};
@@ -84,9 +90,8 @@ impl<S, A> ArrayBase<S, Ix1>
         Self::from_vec(to_vec(linspace::linspace(start, end, n)))
     }
 
-    /// Create a one-dimensional array from the half-open interval
-    /// `[start, end)` with elements spaced by `step`. `A` must be a floating
-    /// point type.
+    /// Create a one-dimensional array with elements from `start` to `end`
+    /// (exclusive), incrementing by `step`. `A` must be a floating point type.
     ///
     /// **Panics** if the length is greater than `isize::MAX`.
     ///
@@ -102,13 +107,14 @@ impl<S, A> ArrayBase<S, Ix1>
         Self::from_vec(to_vec(linspace::range(start, end, step)))
     }
 
-    /// Create a one-dimensional array with `n` elements logarithmically spaced,
-    /// with the starting value being `base.powf(start)` and the final one being
-    /// `base.powf(end)`. `A` must be a floating point type.
+    /// Create a one-dimensional array with `n` logarithmically spaced
+    /// elements, with the starting value being `base.powf(start)` and the
+    /// final one being `base.powf(end)`. `A` must be a floating point type.
     ///
     /// If `base` is negative, all values will be negative.
     ///
-    /// **Panics** if the length is greater than `isize::MAX`.
+    /// **Panics** if `n` is greater than `isize::MAX` or if converting `n - 1`
+    /// to type `A` fails.
     ///
     /// ```rust
     /// use approx::assert_abs_diff_eq;
@@ -129,15 +135,15 @@ impl<S, A> ArrayBase<S, Ix1>
         Self::from_vec(to_vec(logspace::logspace(base, start, end, n)))
     }
 
-    /// Create a one-dimensional array from the inclusive interval `[start,
-    /// end]` with `n` elements geometrically spaced. `A` must be a floating
-    /// point type.
+    /// Create a one-dimensional array with `n` geometrically spaced elements
+    /// from `start` to `end` (inclusive). `A` must be a floating point type.
     ///
     /// Returns `None` if `start` and `end` have different signs or if either
     /// one is zero. Conceptually, this means that in order to obtain a `Some`
     /// result, `end / start` must be positive.
     ///
-    /// **Panics** if `n` is greater than `isize::MAX`.
+    /// **Panics** if `n` is greater than `isize::MAX` or if converting `n - 1`
+    /// to type `A` fails.
     ///
     /// ```rust
     /// use approx::assert_abs_diff_eq;

src/linspace.rs

@@ -63,11 +63,12 @@ impl<F> ExactSizeIterator for Linspace<F>
 
 /// Return an iterator of evenly spaced floats.
 ///
-/// The `Linspace` has `n` elements, where the first
-/// element is `a` and the last element is `b`.
+/// The `Linspace` has `n` elements from `a` to `b` (inclusive).
 ///
-/// Iterator element type is `F`, where `F` must be
-/// either `f32` or `f64`.
+/// The iterator element type is `F`, where `F` must implement `Float`, e.g.
+/// `f32` or `f64`.
+///
+/// **Panics** if converting `n - 1` to type `F` fails.
 #[inline]
 pub fn linspace<F>(a: F, b: F, n: usize) -> Linspace<F>
     where F: Float
@@ -86,13 +87,15 @@ pub fn linspace<F>(a: F, b: F, n: usize) -> Linspace<F>
     }
 }
 
-/// Return an iterator of floats spaced by `step`, from
-/// the half-open interval [a, b).
-/// Numerical reasons can result in `b` being included
-/// in the result.
+/// Return an iterator of floats from `start` to `end` (exclusive),
+/// incrementing by `step`.
+///
+/// Numerical reasons can result in `b` being included in the result.
+///
+/// The iterator element type is `F`, where `F` must implement `Float`, e.g.
+/// `f32` or `f64`.
 ///
-/// Iterator element type is `F`, where `F` must be
-/// either `f32` or `f64`.
+/// **Panics** if converting `((b - a) / step).ceil()` to type `F` fails.
 #[inline]
 pub fn range<F>(a: F, b: F, step: F) -> Linspace<F>
     where F: Float
@@ -102,7 +105,11 @@ pub fn range<F>(a: F, b: F, step: F) -> Linspace<F>
     Linspace {
         start: a,
         step: step,
-        len: steps.to_usize().unwrap(),
+        len: steps.to_usize().expect(
+            "Converting the length to `usize` must not fail. The most likely \
+             cause of this failure is if the sign of `end - start` is \
+             different from the sign of `step`.",
+        ),
         index: 0,
     }
 }

src/logspace.rs

@@ -65,13 +65,16 @@ where
 
 impl<F> ExactSizeIterator for Logspace<F> where Logspace<F>: Iterator {}
 
-/// An iterator of a sequence of logarithmically spaced number.
+/// An iterator of a sequence of logarithmically spaced numbers.
 ///
 /// The `Logspace` has `n` elements, where the first element is `base.powf(a)`
 /// and the last element is `base.powf(b)`.  If `base` is negative, this
 /// iterator will return all negative values.
 ///
-/// Iterator element type is `F`, where `F` must be either `f32` or `f64`.
+/// The iterator element type is `F`, where `F` must implement `Float`, e.g.
+/// `f32` or `f64`.
+///
+/// **Panics** if converting `n - 1` to type `F` fails.
 #[inline]
 pub fn logspace<F>(base: F, a: F, b: F, n: usize) -> Logspace<F>
 where