Merge pull request #42 from okaneco/prep_new_release

Bump version to `0.2.4`, update docs

Author: okaneco

CHANGELOG.md

@@ -1,5 +1,14 @@
 # `safe_unaligned_simd` changelog
 
+## Version 0.2.4 - 2026-02
+
+Added support for *n*-element structure loads and stores on `aarch64` NEON (i.e., into `int16x8x3_t`).  
+This provides wrappers for `vldNq` and `vstNq` intrinsics which deinterleave into N registers on load and interleave into memory on store.
+
+### Notable PRs
+
+[`#41`][41] - Add wrappers for NEON interleaved load/store  
+
 ## Version 0.2.3 - 2025-09
 
 Added support for AVX-512 intrinsics on `x86`/`x86_64`.  
@@ -67,6 +76,7 @@ The functions are located within an architecture's `cell` module.
 
 Initial release
 
+[41]: https://github.com/okaneco/safe_unaligned_simd/pull/41
 [30]: https://github.com/okaneco/safe_unaligned_simd/pull/30
 [29]: https://github.com/okaneco/safe_unaligned_simd/pull/29
 [28]: https://github.com/okaneco/safe_unaligned_simd/pull/28

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "safe_unaligned_simd"
-version = "0.2.3"
+version = "0.2.4"
 edition = "2024"
 rust-version = "1.88"
 license = "MIT OR Apache-2.0"

README.md

@@ -77,12 +77,15 @@ pub fn v128_store<T: Is16BytesUnaligned>(t: &mut T, v: v128);
 
 ## A note on creating mutable array references from slices
 
+**_tl;dr:_ Use [`as_mut_array`][as_mut_array] to avoid this bug, stable since `1.93`.**
+
 Beware of accidentally creating mutable references to temporary arrays.
 
 Rust will implicitly clone an array from a slice and return a mutable reference to that clone if not wrapped properly in parentheses.
 
 ```rust
 // Valid mutable array reference creation
+let out_data: &mut [u8; 4] = chunk[..4].as_mut_array().unwrap(); // since 1.93
 let out_data: &mut [u8; 4] = (&mut chunk[..4]).try_into().unwrap();
 let out_data = TryInto::<&mut [u8; 4]>::try_into(&mut chunk[..4]).unwrap();
 
@@ -93,10 +96,9 @@ let out_data = TryInto::<&mut [u8; 4]>::try_into(&mut chunk[..4]).unwrap();
 let out_data = &mut chunk[..4].try_into().unwrap();
 ```
 
-A better solution is to use [`as_mut_array`][as_mut_array] to sidestep this entirely.<br>
-As of the time of this writing (`rustc 1.91`), `as_mut_array` is unstable but in the process of being stabilized.
+The now-stable [`as_mut_array`][as_mut_array] sidesteps this issue entirely.<br>
 
-[as_mut_array]: https://doc.rust-lang.org/stable/std/primitive.slice.html#method.as_mut_array
+[as_mut_array]: https://doc.rust-lang.org/1.93.0/std/primitive.slice.html#method.as_mut_array
 
 ## License
 This crate is licensed under either

src/aarch64.rs

@@ -334,137 +334,68 @@ vld_n_replicate_k! {
 
     /// Load `u8` data to two registers, with de-interleaving.
     fn vld2q_u8(_: &[u8; 16][..2] as [u8; 32]) -> uint8x16x2_t;
-    /// Load `i8` data to two registers, with de-interleaving
+    /// Load `i8` data to two registers, with de-interleaving.
     fn vld2q_s8(_: &[i8; 16][..2] as [i8; 32]) -> int8x16x2_t;
-    /// Load `u16` data to two registers, with de-interleaving
+    /// Load `u16` data to two registers, with de-interleaving.
     fn vld2q_u16(_: &[u16; 8][..2] as [u16; 16]) -> uint16x8x2_t;
-    /// Load `i16` data to two registers, with de-interleaving
+    /// Load `i16` data to two registers, with de-interleaving.
     fn vld2q_s16(_: &[i16; 8][..2] as [i16; 16]) -> int16x8x2_t;
-    /// Load `u32` data to two registers, with de-interleaving
+    /// Load `u32` data to two registers, with de-interleaving.
     fn vld2q_u32(_: &[u32; 4][..2] as [u32; 8]) -> uint32x4x2_t;
-    /// Load `i32` data to two registers, with de-interleaving
+    /// Load `i32` data to two registers, with de-interleaving.
     fn vld2q_s32(_: &[i32; 4][..2] as [i32; 8]) -> int32x4x2_t;
-    /// Load `f32` data to two registers, with de-interleaving
+    /// Load `f32` data to two registers, with de-interleaving.
     fn vld2q_f32(_: &[f32; 4][..2] as [f32; 8]) -> float32x4x2_t;
-    /// Load `u64` data to two registers, with de-interleaving
+    /// Load `u64` data to two registers, with de-interleaving.
     fn vld2q_u64(_: &[u64; 2][..2] as [u64; 4]) -> uint64x2x2_t;
-    /// Load `i64` data to two registers, with de-interleaving
+    /// Load `i64` data to two registers, with de-interleaving.
     fn vld2q_s64(_: &[i64; 2][..2] as [i64; 4]) -> int64x2x2_t;
-    /// Load `f64` data to two registers, with de-interleaving
+    /// Load `f64` data to two registers, with de-interleaving.
     fn vld2q_f64(_: &[f64; 2][..2] as [f64; 4]) -> float64x2x2_t;
 
-    /// Load `u8` data to three registers, with de-interleaving
+    /// Load `u8` data to three registers, with de-interleaving.
     fn vld3q_u8(_: &[u8; 16][..3] as [u8; 48]) -> uint8x16x3_t;
-    /// Load `i8` data to three registers, with de-interleaving
+    /// Load `i8` data to three registers, with de-interleaving.
     fn vld3q_s8(_: &[i8; 16][..3] as [i8; 48]) -> int8x16x3_t;
-    /// Load `u16` data to three registers, with de-interleaving
+    /// Load `u16` data to three registers, with de-interleaving.
     fn vld3q_u16(_: &[u16; 8][..3] as [u16; 24]) -> uint16x8x3_t;
-    /// Load `i16` data to three registers, with de-interleaving
+    /// Load `i16` data to three registers, with de-interleaving.
     fn vld3q_s16(_: &[i16; 8][..3] as [i16; 24]) -> int16x8x3_t;
-    /// Load `u32` data to three registers, with de-interleaving
+    /// Load `u32` data to three registers, with de-interleaving.
     fn vld3q_u32(_: &[u32; 4][..3] as [u32; 12]) -> uint32x4x3_t;
-    /// Load `i32` data to three registers, with de-interleaving
+    /// Load `i32` data to three registers, with de-interleaving.
     fn vld3q_s32(_: &[i32; 4][..3] as [i32; 12]) -> int32x4x3_t;
-    /// Load `f32` data to three registers, with de-interleaving
+    /// Load `f32` data to three registers, with de-interleaving.
     fn vld3q_f32(_: &[f32; 4][..3] as [f32; 12]) -> float32x4x3_t;
-    /// Load `u64` data to three registers, with de-interleaving
+    /// Load `u64` data to three registers, with de-interleaving.
     fn vld3q_u64(_: &[u64; 2][..3] as [u64; 6]) -> uint64x2x3_t;
-    /// Load `i64` data to three registers, with de-interleaving
+    /// Load `i64` data to three registers, with de-interleaving.
     fn vld3q_s64(_: &[i64; 2][..3] as [i64; 6]) -> int64x2x3_t;
-    /// Load `f64` data to three registers, with de-interleaving
+    /// Load `f64` data to three registers, with de-interleaving.
     fn vld3q_f64(_: &[f64; 2][..3] as [f64; 6]) -> float64x2x3_t;
 
-    /// Load `u8` data to four registers, with de-interleaving
+    /// Load `u8` data to four registers, with de-interleaving.
     fn vld4q_u8(_: &[u8; 16][..4] as [u8; 64]) -> uint8x16x4_t;
-    /// Load `i8` data to four registers, with de-interleaving
+    /// Load `i8` data to four registers, with de-interleaving.
     fn vld4q_s8(_: &[i8; 16][..4] as [i8; 64]) -> int8x16x4_t;
-    /// Load `u16` data to four registers, with de-interleaving
+    /// Load `u16` data to four registers, with de-interleaving.
     fn vld4q_u16(_: &[u16; 8][..4] as [u16; 32]) -> uint16x8x4_t;
-    /// Load `i16` data to four registers, with de-interleaving
+    /// Load `i16` data to four registers, with de-interleaving.
     fn vld4q_s16(_: &[i16; 8][..4] as [i16; 32]) -> int16x8x4_t;
-    /// Load `u32` data to four registers, with de-interleaving
+    /// Load `u32` data to four registers, with de-interleaving.
     fn vld4q_u32(_: &[u32; 4][..4] as [u32; 16]) -> uint32x4x4_t;
-    /// Load `i32` data to four registers, with de-interleaving
+    /// Load `i32` data to four registers, with de-interleaving.
     fn vld4q_s32(_: &[i32; 4][..4] as [i32; 16]) -> int32x4x4_t;
-    /// Load `f32` data to four registers, with de-interleaving
+    /// Load `f32` data to four registers, with de-interleaving.
     fn vld4q_f32(_: &[f32; 4][..4] as [f32; 16]) -> float32x4x4_t;
-    /// Load `u64` data to four registers, with de-interleaving
+    /// Load `u64` data to four registers, with de-interleaving.
     fn vld4q_u64(_: &[u64; 2][..4] as [u64; 8]) -> uint64x2x4_t;
-    /// Load `i64` data to four registers, with de-interleaving
+    /// Load `i64` data to four registers, with de-interleaving.
     fn vld4q_s64(_: &[i64; 2][..4] as [i64; 8]) -> int64x2x4_t;
-    /// Load `f64` data to four registers, with de-interleaving
+    /// Load `f64` data to four registers, with de-interleaving.
     fn vld4q_f64(_: &[f64; 2][..4] as [f64; 8]) -> float64x2x4_t;
 }
 
-vld_n_replicate_k! {
-    unsafe: store;
-    // Stores full registers, so 16 bytes per register
-    size: assert_size_16bytes;
-
-    /// Store `u8` data from two registers, with interleaving
-    fn vst2q_u8(_: &[u8; 16][..2] as [u8; 32]) -> uint8x16x2_t;
-    /// Store `i8` data from two registers, with interleaving
-    fn vst2q_s8(_: &[i8; 16][..2] as [i8; 32]) -> int8x16x2_t;
-    /// Store `u16` data from two registers, with interleaving
-    fn vst2q_u16(_: &[u16; 8][..2] as [u16; 16]) -> uint16x8x2_t;
-    /// Store `i16` data from two registers, with interleaving
-    fn vst2q_s16(_: &[i16; 8][..2] as [i16; 16]) -> int16x8x2_t;
-    /// Store `u32` data from two registers, with interleaving
-    fn vst2q_u32(_: &[u32; 4][..2] as [u32; 8]) -> uint32x4x2_t;
-    /// Store `i32` data from two registers, with interleaving
-    fn vst2q_s32(_: &[i32; 4][..2] as [i32; 8]) -> int32x4x2_t;
-    /// Store `f32` data from two registers, with interleaving
-    fn vst2q_f32(_: &[f32; 4][..2] as [f32; 8]) -> float32x4x2_t;
-    /// Store `u64` data from two registers, with interleaving
-    fn vst2q_u64(_: &[u64; 2][..2] as [u64; 4]) -> uint64x2x2_t;
-    /// Store `i64` data from two registers, with interleaving
-    fn vst2q_s64(_: &[i64; 2][..2] as [i64; 4]) -> int64x2x2_t;
-    /// Store `f64` data from two registers, with interleaving
-    fn vst2q_f64(_: &[f64; 2][..2] as [f64; 4]) -> float64x2x2_t;
-
-    /// Store `u8` data from three registers, with interleaving
-    fn vst3q_u8(_: &[u8; 16][..3] as [u8; 48]) -> uint8x16x3_t;
-    /// Store `i8` data from three registers, with interleaving
-    fn vst3q_s8(_: &[i8; 16][..3] as [i8; 48]) -> int8x16x3_t;
-    /// Store `u16` data from three registers, with interleaving
-    fn vst3q_u16(_: &[u16; 8][..3] as [u16; 24]) -> uint16x8x3_t;
-    /// Store `i16` data from three registers, with interleaving
-    fn vst3q_s16(_: &[i16; 8][..3] as [i16; 24]) -> int16x8x3_t;
-    /// Store `u32` data from three registers, with interleaving
-    fn vst3q_u32(_: &[u32; 4][..3] as [u32; 12]) -> uint32x4x3_t;
-    /// Store `i32` data from three registers, with interleaving
-    fn vst3q_s32(_: &[i32; 4][..3] as [i32; 12]) -> int32x4x3_t;
-    /// Store `f32` data from three registers, with interleaving
-    fn vst3q_f32(_: &[f32; 4][..3] as [f32; 12]) -> float32x4x3_t;
-    /// Store `u64` data from three registers, with interleaving
-    fn vst3q_u64(_: &[u64; 2][..3] as [u64; 6]) -> uint64x2x3_t;
-    /// Store `i64` data from three registers, with interleaving
-    fn vst3q_s64(_: &[i64; 2][..3] as [i64; 6]) -> int64x2x3_t;
-    /// Store `f64` data from three registers, with interleaving
-    fn vst3q_f64(_: &[f64; 2][..3] as [f64; 6]) -> float64x2x3_t;
-
-    /// Store `u8` data from four registers, with interleaving
-    fn vst4q_u8(_: &[u8; 16][..4] as [u8; 64]) -> uint8x16x4_t;
-    /// Store `i8` data from four registers, with interleaving
-    fn vst4q_s8(_: &[i8; 16][..4] as [i8; 64]) -> int8x16x4_t;
-    /// Store `u16` data from four registers, with interleaving
-    fn vst4q_u16(_: &[u16; 8][..4] as [u16; 32]) -> uint16x8x4_t;
-    /// Store `i16` data from four registers, with interleaving
-    fn vst4q_s16(_: &[i16; 8][..4] as [i16; 32]) -> int16x8x4_t;
-    /// Store `u32` data from four registers, with interleaving
-    fn vst4q_u32(_: &[u32; 4][..4] as [u32; 16]) -> uint32x4x4_t;
-    /// Store `i32` data from four registers, with interleaving
-    fn vst4q_s32(_: &[i32; 4][..4] as [i32; 16]) -> int32x4x4_t;
-    /// Store `f32` data from four registers, with interleaving
-    fn vst4q_f32(_: &[f32; 4][..4] as [f32; 16]) -> float32x4x4_t;
-    /// Store `u64` data from four registers, with interleaving
-    fn vst4q_u64(_: &[u64; 2][..4] as [u64; 8]) -> uint64x2x4_t;
-    /// Store `i64` data from four registers, with interleaving
-    fn vst4q_s64(_: &[i64; 2][..4] as [i64; 8]) -> int64x2x4_t;
-    /// Store `f64` data from four registers, with interleaving
-    fn vst4q_f64(_: &[f64; 2][..4] as [f64; 8]) -> float64x2x4_t;
-}
-
 vld_n_replicate_k! {
     unsafe: store;
     // Stores full registers, so 8 bytes per register
@@ -645,6 +576,75 @@ vld_n_replicate_k! {
     fn vst1q_f64_x4(_: &[f64; 2][..4] as [[f64; 2]; 4]) -> float64x2x4_t;
 }
 
+vld_n_replicate_k! {
+    unsafe: store;
+    // Stores full registers, so 16 bytes per register
+    size: assert_size_16bytes;
+
+    /// Store `u8` data from two registers, with interleaving.
+    fn vst2q_u8(_: &[u8; 16][..2] as [u8; 32]) -> uint8x16x2_t;
+    /// Store `i8` data from two registers, with interleaving.
+    fn vst2q_s8(_: &[i8; 16][..2] as [i8; 32]) -> int8x16x2_t;
+    /// Store `u16` data from two registers, with interleaving.
+    fn vst2q_u16(_: &[u16; 8][..2] as [u16; 16]) -> uint16x8x2_t;
+    /// Store `i16` data from two registers, with interleaving.
+    fn vst2q_s16(_: &[i16; 8][..2] as [i16; 16]) -> int16x8x2_t;
+    /// Store `u32` data from two registers, with interleaving.
+    fn vst2q_u32(_: &[u32; 4][..2] as [u32; 8]) -> uint32x4x2_t;
+    /// Store `i32` data from two registers, with interleaving.
+    fn vst2q_s32(_: &[i32; 4][..2] as [i32; 8]) -> int32x4x2_t;
+    /// Store `f32` data from two registers, with interleaving.
+    fn vst2q_f32(_: &[f32; 4][..2] as [f32; 8]) -> float32x4x2_t;
+    /// Store `u64` data from two registers, with interleaving.
+    fn vst2q_u64(_: &[u64; 2][..2] as [u64; 4]) -> uint64x2x2_t;
+    /// Store `i64` data from two registers, with interleaving.
+    fn vst2q_s64(_: &[i64; 2][..2] as [i64; 4]) -> int64x2x2_t;
+    /// Store `f64` data from two registers, with interleaving.
+    fn vst2q_f64(_: &[f64; 2][..2] as [f64; 4]) -> float64x2x2_t;
+
+    /// Store `u8` data from three registers, with interleaving.
+    fn vst3q_u8(_: &[u8; 16][..3] as [u8; 48]) -> uint8x16x3_t;
+    /// Store `i8` data from three registers, with interleaving.
+    fn vst3q_s8(_: &[i8; 16][..3] as [i8; 48]) -> int8x16x3_t;
+    /// Store `u16` data from three registers, with interleaving.
+    fn vst3q_u16(_: &[u16; 8][..3] as [u16; 24]) -> uint16x8x3_t;
+    /// Store `i16` data from three registers, with interleaving.
+    fn vst3q_s16(_: &[i16; 8][..3] as [i16; 24]) -> int16x8x3_t;
+    /// Store `u32` data from three registers, with interleaving.
+    fn vst3q_u32(_: &[u32; 4][..3] as [u32; 12]) -> uint32x4x3_t;
+    /// Store `i32` data from three registers, with interleaving.
+    fn vst3q_s32(_: &[i32; 4][..3] as [i32; 12]) -> int32x4x3_t;
+    /// Store `f32` data from three registers, with interleaving.
+    fn vst3q_f32(_: &[f32; 4][..3] as [f32; 12]) -> float32x4x3_t;
+    /// Store `u64` data from three registers, with interleaving.
+    fn vst3q_u64(_: &[u64; 2][..3] as [u64; 6]) -> uint64x2x3_t;
+    /// Store `i64` data from three registers, with interleaving.
+    fn vst3q_s64(_: &[i64; 2][..3] as [i64; 6]) -> int64x2x3_t;
+    /// Store `f64` data from three registers, with interleaving.
+    fn vst3q_f64(_: &[f64; 2][..3] as [f64; 6]) -> float64x2x3_t;
+
+    /// Store `u8` data from four registers, with interleaving.
+    fn vst4q_u8(_: &[u8; 16][..4] as [u8; 64]) -> uint8x16x4_t;
+    /// Store `i8` data from four registers, with interleaving.
+    fn vst4q_s8(_: &[i8; 16][..4] as [i8; 64]) -> int8x16x4_t;
+    /// Store `u16` data from four registers, with interleaving.
+    fn vst4q_u16(_: &[u16; 8][..4] as [u16; 32]) -> uint16x8x4_t;
+    /// Store `i16` data from four registers, with interleaving.
+    fn vst4q_s16(_: &[i16; 8][..4] as [i16; 32]) -> int16x8x4_t;
+    /// Store `u32` data from four registers, with interleaving.
+    fn vst4q_u32(_: &[u32; 4][..4] as [u32; 16]) -> uint32x4x4_t;
+    /// Store `i32` data from four registers, with interleaving.
+    fn vst4q_s32(_: &[i32; 4][..4] as [i32; 16]) -> int32x4x4_t;
+    /// Store `f32` data from four registers, with interleaving.
+    fn vst4q_f32(_: &[f32; 4][..4] as [f32; 16]) -> float32x4x4_t;
+    /// Store `u64` data from four registers, with interleaving.
+    fn vst4q_u64(_: &[u64; 2][..4] as [u64; 8]) -> uint64x2x4_t;
+    /// Store `i64` data from four registers, with interleaving.
+    fn vst4q_s64(_: &[i64; 2][..4] as [i64; 8]) -> int64x2x4_t;
+    /// Store `f64` data from four registers, with interleaving.
+    fn vst4q_f64(_: &[f64; 2][..4] as [f64; 8]) -> float64x2x4_t;
+}
+
 vld_n_replicate_k! {
     unsafe: load;
     size: various_sizes;

src/lib.rs

@@ -44,13 +44,16 @@
 //!
 //! ## A note on creating mutable array references from slices
 //!
+//! **_tl;dr:_ Use [`as_mut_array`][as_mut_array] to avoid this bug, stable since `1.93`.**
+//!
 //! Beware of accidentally creating mutable references to temporary arrays.
 //!
 //! Rust will implicitly clone an array from a slice and return a mutable reference to that clone if not wrapped properly in parentheses.
 //!
-//! ```rust,no_run
+//! ```rust,ignore
 //! # let mut chunk = [0u8; 8];
 //! // Valid mutable array reference creation
+//! let out_data: &mut [u8; 4] = chunk[..4].as_mut_array().unwrap(); // since 1.93
 //! let out_data: &mut [u8; 4] = (&mut chunk[..4]).try_into().unwrap();
 //! let out_data = TryInto::<&mut [u8; 4]>::try_into(&mut chunk[..4]).unwrap();
 //!
@@ -62,10 +65,9 @@
 //! # *out_data = [1u8; 4];
 //! ```
 //!
-//! A better solution is to use [`as_mut_array`][as_mut_array] to sidestep this entirely.<br>
-//! As of the time of this writing (`rustc 1.91`), `as_mut_array` is unstable but in the process of being stabilized.
+//! The now-stable [`as_mut_array`][as_mut_array] sidesteps this issue entirely.<br>
 //!
-//! [as_mut_array]: https://doc.rust-lang.org/stable/std/primitive.slice.html#method.as_mut_array
+//! [as_mut_array]: https://doc.rust-lang.org/1.93.0/std/primitive.slice.html#method.as_mut_array
 #![forbid(missing_docs, non_ascii_idents)]
 #![cfg_attr(not(test), no_std)]