one_indexed_vec/lib.rs
1//! # one-indexed-vec
2//!
3//! Scientific computing library with 1-based indexing.
4//!
5//! Built on the [`Vec1`] type — a `Vec`-like container whose first element
6//! lives at index `1`, matching mathematical notation and the conventions
7//! of Fortran, MATLAB, and Julia.
8//!
9//! ## Modules
10//!
11//! | Module | Feature | Description |
12//! |--------|---------|-------------|
13//! | [`vec1_core`] | always | The 1-based container and [`Index1`] |
14//! | [`math`] | `math` | Sequences, series, Fourier analysis, orthogonal polynomials |
15//! | [`numerical`] | `numerical` | Basic numeric ops, integration, ODEs, root finding |
16//! | [`linear`] | `linear` | Matrices, decompositions, eigenvalues |
17//! | [`signal`] | `signal` | Filters, window functions, correlation |
18//! | [`stats`] | `stats` | Descriptive statistics, regression, distributions |
19//! | [`physics`] | `physics` | Quantum mechanics, thermodynamics, optics |
20//! | [`chemistry`] | `chemistry` | Atomic data, kinetics, thermodynamics |
21//!
22//! ## Quick start
23//!
24//! ```rust
25//! use one_indexed_vec::{Vec1, vec1};
26//!
27//! let v = vec1![1.0, 2.0, 3.0, 4.0, 5.0];
28//! assert_eq!(v[1], 1.0);
29//! assert_eq!(v.sum(), 15.0);
30//! assert_eq!(v.mean(), 3.0);
31//! ```
32//!
33//! ## Migration from 0.1.x
34//!
35//! In `0.1.x` the container was called `VecIndexFromOne<T>`. As of `0.2.0`,
36//! the canonical name is [`Vec1`]. The old name is retained as a deprecated
37//! type alias for backward compatibility.
38//!
39//! ```rust
40//! #![allow(deprecated)]
41//! use one_indexed_vec::VecIndexFromOne;
42//!
43//! let v = VecIndexFromOne::from(vec![1, 2, 3]);
44//! assert_eq!(v[1], 1);
45//! ```
46//!
47//! Numeric algorithms that previously lived under `one_indexed_vec::ops`
48//! are now available as methods on [`Vec1`], grouped under the disciplinary
49//! modules. The [`ops`] module is kept as an empty deprecated placeholder.
50
51#![cfg_attr(not(feature = "std"), no_std)]
52#![warn(missing_docs)]
53#![warn(rust_2018_idioms)]
54
55/* #[cfg(feature = "std")]
56extern crate std; */
57
58#[cfg(not(feature = "std"))]
59extern crate alloc;
60
61// ============================================================================
62// Modules
63// ============================================================================
64
65/// Core container: [`Vec1<T>`], the 1-based [`Index1`], and fundamental
66/// numeric operations (`sum`, `mean`, `dot_product`, ...).
67pub mod vec1_core;
68
69/// Mathematical formulas and algorithms: sequences, series, Fourier
70/// analysis, orthogonal polynomials, FFT, combinatorics.
71#[cfg(feature = "math")]
72pub mod math;
73
74/// Numerical algorithms: integration, ODEs, root finding, optimization,
75/// window operations, finite differences, sliding statistics.
76#[cfg(feature = "numerical")]
77pub mod numerical;
78
79/// Linear algebra: matrices, LU/QR/Cholesky decompositions, eigenvalues,
80/// Gaussian elimination.
81#[cfg(feature = "linear")]
82pub mod linear;
83
84/// Signal processing: FIR/IIR filters, window functions, convolution,
85/// correlation.
86#[cfg(feature = "signal")]
87pub mod signal;
88
89/// Statistics: descriptive statistics, correlation, regression,
90/// probability distributions.
91#[cfg(feature = "stats")]
92pub mod stats;
93
94/// Physics: quantum mechanics, thermodynamics, optics.
95#[cfg(feature = "physics")]
96pub mod physics;
97
98/// Chemistry: atomic data, reaction kinetics, thermodynamics.
99#[cfg(feature = "chemistry")]
100pub mod chemistry;
101
102// ============================================================================
103// Canonical names
104// ============================================================================
105
106pub use vec1_core::Vec1;
107pub use vec1_core::index1::Index1;
108
109// `vec1!` is automatically exported at the crate root by `#[macro_export]`.
110
111// ============================================================================
112// Deprecated re-exports (0.1.x → 0.2.0)
113// ============================================================================
114
115/// Deprecated alias for [`Vec1`].
116///
117/// The container was renamed in `0.2.0`. Update your code to use [`Vec1`].
118/// The alias will be removed in `1.0`.
119#[deprecated(
120 since = "0.2.0",
121 note = "use `Vec1` instead; `VecIndexFromOne` will be removed in 1.0"
122)]
123pub type VecIndexFromOne<T> = Vec1<T>;
124
125/// Deprecated re-export of numeric algorithms.
126///
127/// In `0.1.x`, all numeric algorithms lived under `one_indexed_vec::ops`.
128/// They have been reorganized as methods on [`Vec1`] under the disciplinary
129/// modules:
130///
131/// | Old location | New location |
132/// |--------------|--------------|
133/// | `ops::prefix_sum` | [`Vec1::prefix_sum`] |
134/// | `ops::moving_average` | [`Vec1::moving_average`] |
135/// | `ops::sliding_window_max` | [`Vec1::sliding_window_max`] |
136/// | `ops::mean` | [`Vec1::mean`] |
137/// | `ops::convolve` | [`Vec1::convolve`] |
138///
139/// This module is intentionally empty. It is kept only so that
140/// `use one_indexed_vec::ops::*;` continues to compile without error.
141/// New code should import [`Vec1`] directly — all methods are available on
142/// the container.
143#[deprecated(since = "0.2.0", note = "methods moved to `Vec1`; import `Vec1` instead of `ops`")]
144pub mod ops {
145 // Intentionally empty.
146 //
147 // The numeric algorithms previously re-exported here are now methods
148 // on `Vec1`. Because methods defined in `impl` blocks are not items
149 // that can be re-exported, there is nothing left to `pub use`.
150 //
151 // Code that previously wrote:
152 //
153 // use one_indexed_vec::ops::*;
154 //
155 // should now write:
156 //
157 // use one_indexed_vec::Vec1;
158 //
159 // and call methods directly, e.g. `v.mean()`, `v.moving_average(3)`.
160}
161
162// ============================================================================
163// Crate-level tests
164// ============================================================================
165
166#[cfg(test)]
167mod tests {
168 use super::*;
169
170 #[test]
171 fn canonical_name_available() {
172 let v = Vec1::from(vec![1, 2, 3]);
173 assert_eq!(v[1], 1);
174 assert_eq!(v[3], 3);
175 }
176
177 #[test]
178 #[allow(deprecated)]
179 fn deprecated_alias_works() {
180 let v = VecIndexFromOne::from(vec![1, 2, 3]);
181 assert_eq!(v[1], 1);
182 }
183
184 #[test]
185 fn vec1_macro_available_at_root() {
186 let v = crate::vec1![1, 2, 3];
187 assert_eq!(v.len(), 3);
188 }
189}