diff --git a/src/geomspace.rs b/src/geomspace.rs index c3b5a4095..285e761a3 100644 --- a/src/geomspace.rs +++ b/src/geomspace.rs @@ -66,14 +66,17 @@ impl ExactSizeIterator for Geomspace where Geomspace: 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(a: F, b: F, n: usize) -> Option> where diff --git a/src/impl_constructors.rs b/src/impl_constructors.rs index 03458ed00..300ae91c1 100644 --- a/src/impl_constructors.rs +++ b/src/impl_constructors.rs @@ -67,10 +67,16 @@ impl ArrayBase 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 ArrayBase 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 ArrayBase 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 ArrayBase 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; diff --git a/src/linspace.rs b/src/linspace.rs index 2654d406d..f70303dca 100644 --- a/src/linspace.rs +++ b/src/linspace.rs @@ -63,11 +63,12 @@ impl ExactSizeIterator for Linspace /// 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(a: F, b: F, n: usize) -> Linspace where F: Float @@ -86,13 +87,15 @@ pub fn linspace(a: F, b: F, n: usize) -> Linspace } } -/// 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(a: F, b: F, step: F) -> Linspace where F: Float @@ -102,7 +105,11 @@ pub fn range(a: F, b: F, step: F) -> Linspace 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, } } diff --git a/src/logspace.rs b/src/logspace.rs index a86ea0545..6723e4be3 100644 --- a/src/logspace.rs +++ b/src/logspace.rs @@ -65,13 +65,16 @@ where impl ExactSizeIterator for Logspace where Logspace: 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(base: F, a: F, b: F, n: usize) -> Logspace where