[RFC PATCH v1 1/2] rust: add NonEmptySlice

[Francis Laniel]

Add NonEmptySlice<T>, a [T] wrapper that is guaranteed to contain at
least one element.
This lets methods such as last_mut() return a plain reference instead
of an Option, so callers that have already checked for emptiness no
longer need unwrap() or unwrap_unchecked().

Suggested-by: Gary Guo <gary@xxxxxxxxxxx>
Signed-off-by: Francis Laniel <laniel_francis@xxxxxxx>
---
 rust/kernel/lib.rs   |  1 +
 rust/kernel/slice.rs | 76 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 77 insertions(+)
 create mode 100644 rust/kernel/slice.rs

diff --git a/rust/kernel/lib.rs b/rust/kernel/lib.rs
index 7225abc64084..8cc01aceb3b2 100644
--- a/rust/kernel/lib.rs
+++ b/rust/kernel/lib.rs
@@ -130,6 +130,7 @@
 #[cfg(CONFIG_RUST_SERIAL_DEV_BUS_ABSTRACTIONS)]
 pub mod serdev;
 pub mod sizes;
+pub mod slice;
 #[cfg(CONFIG_SOC_BUS)]
 pub mod soc;
 #[doc(hidden)]
diff --git a/rust/kernel/slice.rs b/rust/kernel/slice.rs
new file mode 100644
index 000000000000..7e467cb952c3
--- /dev/null
+++ b/rust/kernel/slice.rs
@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Slice abstractions to ease development.
+
+use core::ops::{Deref, DerefMut};
+
+/// A slice that is guaranteed to contain at least one element.
+///
+/// # Invariants
+///
+/// `self.0` is not empty.
+#[repr(transparent)]
+pub struct NonEmptySlice<T>([T]);
+
+impl<T> NonEmptySlice<T> {
+    /// Returns `None` if `s` is empty.
+    pub fn new(s: &mut [T]) -> Option<&Self> {
+        if s.is_empty() {
+            return None;
+        }
+        // SAFETY: `Self` is `repr(transparent)` over `[T]`, so the cast keeps the slice length.
+        // INVARIANT: `s` is not empty, checked above.
+        Some(unsafe { &*(core::ptr::from_mut(s) as *const Self) })
+    }
+
+    /// Returns `None` if `s` is empty.
+    pub fn new_mut(s: &mut [T]) -> Option<&mut Self> {
+        if s.is_empty() {
+            return None;
+        }
+        // SAFETY: `Self` is `repr(transparent)` over `[T]`, so the cast keeps the slice length.
+        // INVARIANT: `s` is not empty, checked above.
+        Some(unsafe { &mut *(core::ptr::from_mut(s) as *mut Self) })
+    }
+
+    /// Returns a reference to the first element.
+    pub fn first(&mut self) -> &T {
+        // SAFETY: By the type invariant, `len >= 1`, so `0` is in bounds.
+        unsafe { self.0.get_unchecked(0) }
+    }
+
+    /// Returns a mutable reference to the first element.
+    pub fn first_mut(&mut self) -> &mut T {
+        // SAFETY: By the type invariant, `len >= 1`, so `0` is in bounds.
+        unsafe { self.0.get_unchecked_mut(0) }
+    }
+
+    /// Returns a reference to the last element.
+    pub fn last(&mut self) -> &T {
+        let last = self.0.len() - 1;
+        // SAFETY: By the type invariant, `len >= 1`, so `last` is in bounds.
+        unsafe { self.0.get_unchecked(last) }
+    }
+
+    /// Returns a mutable reference to the last element.
+    pub fn last_mut(&mut self) -> &mut T {
+        let last = self.0.len() - 1;
+        // SAFETY: By the type invariant, `len >= 1`, so `last` is in bounds.
+        unsafe { self.0.get_unchecked_mut(last) }
+    }
+}
+
+impl<T> Deref for NonEmptySlice<T> {
+    type Target = [T];
+
+    fn deref(&self) -> &[T] {
+        &self.0
+    }
+}
+
+impl<T> DerefMut for NonEmptySlice<T> {
+    // Mutating elements through `&mut [T]` can't change the length, so the invariant holds.
+    fn deref_mut(&mut self) -> &mut [T] {
+        &mut self.0
+    }
+}
-- 
2.47.3