one-indexed-vec 0.2.0

A one-based (1-indexed) wrapper around Vec<T>: element at position N is accessed via vec[N].
Documentation
//! Classical sequences with 1-based indexing.
//!
//! Sequence generators are associated functions on `Vec1`, callable as
//! `Vec1::fibonacci(10)` etc. Series sums (pure scalar functions) remain
//! free functions.

use crate::Vec1;

impl Vec1<f64> {
    /// Arithmetic sequence: `a_n = a_1 + (n-1) * d`.
    ///
    /// ```rust
    /// use one_indexed_vec::Vec1;
    /// let s = Vec1::arithmetic(5, 2.0, 3.0);
    /// assert_eq!(s[1], 2.0);
    /// assert_eq!(s[5], 14.0);
    /// ```
    pub fn arithmetic(n: usize, a1: f64, d: f64) -> Self {
        let mut out = Self::with_capacity(n);
        for i in 1..=n {
            out.push(a1 + (i - 1) as f64 * d);
        }
        out
    }

    /// Geometric sequence: `g_n = a_1 * r^(n-1)`.
    ///
    /// ```rust
    /// use one_indexed_vec::Vec1;
    /// let s = Vec1::geometric(5, 2.0, 3.0);
    /// assert_eq!(s[1], 2.0);
    /// assert_eq!(s[3], 18.0);
    /// ```
    pub fn geometric(n: usize, a1: f64, r: f64) -> Self {
        let mut out = Self::with_capacity(n);
        for i in 1..=n {
            out.push(a1 * libm::pow(r, (i - 1) as f64));
        }
        out
    }

    /// Linearly spaced values from `start` to `end` (inclusive), `n` points.
    ///
    /// Matches the semantics of `numpy.linspace` and MATLAB's `linspace`:
    /// the first point is exactly `start`, the last is exactly `end`, and
    /// the spacing is uniform.
    ///
    /// ```rust
    /// use one_indexed_vec::Vec1;
    /// let v = Vec1::linspace(0.0, 1.0, 5);
    /// assert_eq!(v.as_slice(), &[0.0, 0.25, 0.5, 0.75, 1.0]);
    /// ```
    pub fn linspace(start: f64, end: f64, n: usize) -> Self {
        if n == 0 {
            return Self::new();
        }
        if n == 1 {
            let mut v = Self::with_capacity(1);
            v.push(start);
            return v;
        }
        let step = (end - start) / (n - 1) as f64;
        let mut out = Self::with_capacity(n);
        for i in 0..n {
            out.push(start + i as f64 * step);
        }
        out
    }
}

impl Vec1<u64> {
    /// Fibonacci sequence: `F_1 = 1, F_2 = 1, F_n = F_{n-1} + F_{n-2}`.
    ///
    /// ```rust
    /// use one_indexed_vec::Vec1;
    /// let f = Vec1::fibonacci(10);
    /// assert_eq!(f[1], 1);
    /// assert_eq!(f[10], 55);
    /// ```
    pub fn fibonacci(n: usize) -> Self {
        let mut out = Self::with_capacity(n);
        if n >= 1 {
            out.push(1);
        }
        if n >= 2 {
            out.push(1);
        }
        for i in 3..=n {
            let next = out[i - 1] + out[i - 2];
            out.push(next);
        }
        out
    }
}

// ============================================================================
// Series sums (pure scalar functions)
// ============================================================================

/// Arithmetic series sum: `S_n = n/2 * (a_1 + a_n)`.
///
/// ```rust
/// use one_indexed_vec::math::sequences::arithmetic_sum;
/// assert!((arithmetic_sum(10, 1.0, 10.0) - 55.0).abs() < 1e-10);
/// ```
pub fn arithmetic_sum(n: usize, a1: f64, an: f64) -> f64 {
    n as f64 * (a1 + an) / 2.0
}

/// Geometric series sum: `S_n = a_1 * (1 - r^n) / (1 - r)`.
///
/// ```rust
/// use one_indexed_vec::math::sequences::geometric_sum;
/// assert!((geometric_sum(5, 1.0, 2.0) - 31.0).abs() < 1e-10);
/// ```
pub fn geometric_sum(n: usize, a1: f64, r: f64) -> f64 {
    if (r - 1.0).abs() < 1e-15 {
        a1 * n as f64
    } else {
        a1 * (1.0 - libm::pow(r, n as f64)) / (1.0 - r)
    }
}

// ============================================================================
// Tests
// ============================================================================

#[cfg(test)]
mod tests {
    use super::*;

    // ----- arithmetic -----

    #[test]
    fn arithmetic_basic() {
        let s = Vec1::arithmetic(5, 2.0, 3.0);
        assert!((s[1] - 2.0).abs() < 1e-10);
        assert!((s[3] - 8.0).abs() < 1e-10);
        assert!((s[5] - 14.0).abs() < 1e-10);
    }

    #[test]
    fn arithmetic_empty() {
        let s = Vec1::arithmetic(0, 2.0, 3.0);
        assert!(s.is_empty());
    }

    #[test]
    fn arithmetic_single() {
        let s = Vec1::arithmetic(1, 7.0, 3.0);
        assert_eq!(s.len(), 1);
        assert!((s[1] - 7.0).abs() < 1e-10);
    }

    // ----- geometric -----

    #[test]
    fn geometric_basic() {
        let s = Vec1::geometric(5, 2.0, 3.0);
        assert!((s[1] - 2.0).abs() < 1e-10);
        assert!((s[3] - 18.0).abs() < 1e-10);
        assert!((s[5] - 162.0).abs() < 1e-10);
    }

    #[test]
    fn geometric_empty() {
        let s = Vec1::geometric(0, 2.0, 3.0);
        assert!(s.is_empty());
    }

    // ----- linspace -----

    #[test]
    fn linspace_basic() {
        let v = Vec1::linspace(0.0, 1.0, 5);
        assert_eq!(v.len(), 5);
        assert!((v[1] - 0.0).abs() < 1e-10);
        assert!((v[2] - 0.25).abs() < 1e-10);
        assert!((v[3] - 0.5).abs() < 1e-10);
        assert!((v[4] - 0.75).abs() < 1e-10);
        assert!((v[5] - 1.0).abs() < 1e-10);
    }

    #[test]
    fn linspace_single() {
        let v = Vec1::linspace(3.0, 3.0, 1);
        assert_eq!(v.len(), 1);
        assert!((v[1] - 3.0).abs() < 1e-10);
    }

    #[test]
    fn linspace_empty() {
        let v = Vec1::<f64>::linspace(0.0, 1.0, 0);
        assert!(v.is_empty());
    }

    #[test]
    fn linspace_descending() {
        let v = Vec1::linspace(1.0, 0.0, 3);
        assert!((v[1] - 1.0).abs() < 1e-10);
        assert!((v[2] - 0.5).abs() < 1e-10);
        assert!((v[3] - 0.0).abs() < 1e-10);
    }

    #[test]
    fn linspace_endpoints_exact() {
        // The endpoints must be *exactly* start and end, not just close.
        let v = Vec1::linspace(0.1, 0.9, 9);
        assert_eq!(v[1], 0.1);
        assert_eq!(v[9], 0.9);
    }

    // ----- fibonacci -----

    #[test]
    fn fibonacci_basic() {
        let f = Vec1::fibonacci(10);
        assert_eq!(f[1], 1);
        assert_eq!(f[2], 1);
        assert_eq!(f[5], 5);
        assert_eq!(f[10], 55);
    }

    #[test]
    fn fibonacci_empty() {
        let f = Vec1::fibonacci(0);
        assert!(f.is_empty());
    }

    #[test]
    fn fibonacci_single() {
        let f = Vec1::fibonacci(1);
        assert_eq!(f.len(), 1);
        assert_eq!(f[1], 1);
    }

    #[test]
    fn fibonacci_two() {
        let f = Vec1::fibonacci(2);
        assert_eq!(f.len(), 2);
        assert_eq!(f[1], 1);
        assert_eq!(f[2], 1);
    }

    // ----- series sums -----

    #[test]
    fn sums() {
        assert!((arithmetic_sum(10, 1.0, 10.0) - 55.0).abs() < 1e-10);
        assert!((geometric_sum(5, 1.0, 2.0) - 31.0).abs() < 1e-10);
    }

    #[test]
    fn geometric_sum_r_equals_1() {
        assert!((geometric_sum(5, 2.0, 1.0) - 10.0).abs() < 1e-10);
    }
}