diff --git a/RELEASES.md b/RELEASES.md index 8b4786666..b94ef88f0 100644 --- a/RELEASES.md +++ b/RELEASES.md @@ -1,3 +1,125 @@ +Version 0.17.0 (2025-10-13) +=========================== +Version 0.17.0 introduces a new **array reference type** — the preferred way to write functions and extension traits in `ndarray`. +This release is fully backwards-compatible but represents a major usability improvement. +The first section of this changelog explains the change in detail. + +It also includes numerous new methods, math functions, and internal improvements — all credited below. + +A New Way to Write Functions +------------- + +### TL;DR +`ndarray` 0.17.0 adds new reference types for writing functions and traits that work seamlessly with owned arrays and views. + +When writing functions that accept array arguments: +- **Use `&ArrayRef`** to read elements from any array. +- **Use `&mut ArrayRef`** to modify elements. +- **Use `&T where T: AsRef>`** to inspect shape/stride only. +- **Use `&mut T where T: AsMut>`** to modify shape/stride only. + +All existing function signatures continue to work; these new types are fully opt-in. + +### Background +ndarray has multiple ways to write functions that take arrays (a problem captured well in issue [#1059](https://github.com/rust-ndarray/ndarray/issues/1059)). +For example: +```rust +fn sum(a: ArrayView1) -> f64; +fn sum(a: &ArrayView1) -> f64; +fn sum(a: &Array1) -> f64; +``` +All of these work, but having several equivalent forms causes confusion. +The most general solution, writing generically over storage types: +```rust +fn sum(a: &ArrayBase) -> f64 +where S: Data; +``` +is powerful but verbose and often hard to read. +Version 0.17.0 introduces a new, simpler pattern that expresses the same flexibility more clearly. + +### Solution +Three new reference types make it easier to write functions that accept any kind of array while clearly expressing what kind of access (data or layout) they need. + +#### Reading / Writing Elements: `ArrayRef` +`ArrayRef` is the `Deref` target of `ArrayBase`. +It behaves like `&[T]` for `Vec`, giving access to elements and layout. +Mutability is expressed through the reference itself (`&` vs `&mut`), not through a trait bound or the type itself. +It is used as follows: +```rust +fn sum(a: &ArrayRef1) -> f64; +fn cumsum_mut(a: &mut ArrayRef1); +``` +(ArrayRef1 is available from the prelude.) + +#### Reading / Writing Shape: `LayoutRef` +LayoutRef lets functions view or modify shape/stride information without touching data. +This replaces verbose signatures like: +```rust +fn alter_view(a: &mut ArrayBase) +where S: Data; +``` +Use AsRef / AsMut for best compatibility: +```rust +fn alter_shape(a: &mut T) +where T: AsMut>; +``` +(Accepting a `LayoutRef` directly can cause unnecessary copies; see [#1440](https://github.com/rust-ndarray/ndarray/pull/1440).) + +#### Reading / Writing Unsafe Elements: `RawRef` +`RawRef` augments `RawArrayView` and `RawArrayViewMut` for power users needing unsafe element access (e.g. uninitialized buffers). +Like `LayoutRef`, it is best used via `AsRef` / `AsMut`. + +Added +----- +- A new "array reference" type by [@akern40](https://github.com/akern40) [#1440](https://github.com/rust-ndarray/ndarray/pull/1440) +- A `diff` method for calculating the difference between elements by [@johann-cm](https://github.com/johann-cm) [#1437](https://github.com/rust-ndarray/ndarray/pull/1437) +- A `partition` method for partially sorting an array by [@NewBornRustacean](https://github.com/NewBornRustacean) [#1498](https://github.com/rust-ndarray/ndarray/pull/1498) +- A `meshgrid` method for building regular grids of values by [@akern40](https://github.com/akern40) [#1477](https://github.com/rust-ndarray/ndarray/pull/1477) +- A `cumprod` method for cumulative products by [@NewBornRustacean](https://github.com/NewBornRustacean) [#1491](https://github.com/rust-ndarray/ndarray/pull/1491) +- More element-wise math functions for floats by [@Waterdragen](https://github.com/Waterdragen) [#1507](https://github.com/rust-ndarray/ndarray/pull/1507) + - Additions include `exp_m1`, `ln_1p`, `asin`, `acos`, `atan`, `sinh`, `cosh`, `tanh`, `asinh`, `acosh`, `atanh`, and `hypot` +- Dot product support for dynamic arrays by [@NewBornRustacean](https://github.com/NewBornRustacean) [#1483](https://github.com/rust-ndarray/ndarray/pull/1483) and [@akern40](https://github.com/akern40) [#1494](https://github.com/rust-ndarray/ndarray/pull/1494) +- An `axis_windows_with_stride` method for strided windows by [@goertzenator](https://github.com/goertzenator) [#1460](https://github.com/rust-ndarray/ndarray/pull/1460) +- In-place methods for permuting (`permute_axes`) and reversing (`reverse_axes`) axes by [@NewBornRustacean](https://github.com/NewBornRustacean) [#1505](https://github.com/rust-ndarray/ndarray/pull/1505) +- Adds `into_*_iter` functions as lifetime-preserving versions of into-iterator functionality by [@akern40](https://github.com/akern40) [#1510](https://github.com/rust-ndarray/ndarray/pull/1510) + +Changed +------- +- `remove_index` can now be called on views, in addition to owned arrays by [@akern40](https://github.com/akern40) + +Removed +------- +- Removed the `serde-1`, `test`, and `docs` feature flags; by [@akern40](https://github.com/akern40) [#1479](https://github.com/rust-ndarray/ndarray/pull/1479) + - Use `approx,serde,rayon` instead of `docs`. + - Use `serde` instead of `serde-1` + + +Fixed +----- +- `last_mut()` now guarantees that the underlying data is uniquely held by [@bluss](https://github.com/bluss) [#1429](https://github.com/rust-ndarray/ndarray/pull/1429) +- `ArrayView` is now covariant over lifetime by [@akern40](https://github.com/akern40) [#1480](https://github.com/rust-ndarray/ndarray/pull/1480), so that the following code now compiles +```rust +fn fn_cov<'a>(x: ArrayView1<'static, f64>) -> ArrayView1<'a, f64> { + x +} +``` + +Documentation +----- +- Filled missing documentation and adds warn(missing_docs) by [@akern40](https://github.com/akern40) +- Fixed a typo in the documentation of `select` by [@Drazhar](https://github.com/Drazhar) +- Fixed a typo in the documentation of `into_raw_vec_and_offset` by [@benliepert](https://github.com/benliepert) +- Documented `Array::zeros` with how to control the return type by [@akern40](https://github.com/akern40) + +Other +----- +- Expanded the gitignore file for IDEs by [@XXMA16](https://github.com/XXMA16) and [@akern40](https://github.com/akern40) +- Stabilized the MSRV to 1.64 by [@akern40](https://github.com/akern40) +- Switched to nextest for testing by [@akern40](https://github.com/akern40) +- Added Miri to CI by [@akern40](https://github.com/akern40) +- Smoothed out tests that can be run with `no_std` by [@akern40](https://github.com/akern40) +- Updated to Edition 2021 by [@akern40](https://github.com/akern40) + Version 0.16.1 (2024-08-14) ===========================