feat(ops): add get, SliceIndex and impl for ByteSpan

Implementation notes for ByteSpan:

1. When a slice ends before a word boundary (it's last word isn't a full 31 bytes long)
, it's last word is copied into the remainder word.
Rationale: this is consistent with `ByteArray`'s `pending word`, and allows slices of full bytes31
that include an end_suffix to be shifted-right without allocating a new array.

2. When slices include a start-offset, the offset is applied lazily only upon `into`ing into a
   `ByteArray`, otherwise it's only recorded in the `first_char_start_offset` field.

Author: Gilad Chase

corelib/src/byte_array.cairo

@@ -55,6 +55,7 @@ use crate::cmp::min;
 use crate::integer::{U32TryIntoNonZero, u128_safe_divmod};
 #[feature("bounded-int-utils")]
 use crate::internal::bounded_int::{self, BoundedInt, downcast, upcast};
+use crate::num::traits::CheckedSub;
 #[allow(unused_imports)]
 use crate::serde::Serde;
 use crate::traits::{Into, TryInto};
@@ -837,6 +838,16 @@ pub impl ByteSpanImpl of ByteSpanTrait {
         ba.append_from_parts(self.data, self.remainder_word, upcast(self.remainder_len));
         ba
     }
+
+    /// Gets the element(s) at the given index.
+    /// Accepts ranges (returns Option<ByteSpan>), and (to-be-implemented) single indices (returns
+    /// Option<u8>).
+    #[feature("corelib-get-trait")]
+    fn get<I, impl TGet: crate::ops::Get<ByteSpan, I>, +Drop<I>>(
+        self: @ByteSpan, index: I,
+    ) -> Option<TGet::Output> {
+        TGet::get(self, index)
+    }
 }
 
 impl ByteSpanDefault of Default<ByteSpan> {
@@ -847,6 +858,59 @@ impl ByteSpanDefault of Default<ByteSpan> {
     }
 }
 
+
+impl ByteSpanGetRange of crate::ops::Get<ByteSpan, crate::ops::Range<usize>> {
+    type Output = ByteSpan;
+
+    /// Returns a slice for the given range `[start, end)`.
+    /// If span is consumed by the slice: returns the default object.
+    /// If out of bounds: returns `None`.
+    fn get(self: @ByteSpan, index: crate::ops::Range<usize>) -> Option<ByteSpan> {
+        let range = index;
+        let len = (range.end).checked_sub(range.start)?;
+        if len == 0 {
+            return Some(Default::default());
+        }
+        if range.end > self.len() {
+            return None;
+        }
+
+        let abs_start = range.start + upcast(*self.first_char_start_offset);
+        let (start_word, start_offset) = DivRem::div_rem(abs_start, BYTES_IN_BYTES31_NONZERO);
+        let (end_word, end_offset) = DivRem::div_rem(abs_start + len, BYTES_IN_BYTES31_NONZERO);
+        let data_len = self.data.len();
+
+        let remainder_with_end_offset_trimmed = if end_word < data_len {
+            let word = (*self.data[end_word]).into();
+            shift_right(word, BYTES_IN_BYTES31, BYTES_IN_BYTES31 - end_offset)
+        } else {
+            let remainder_len = upcast(*self.remainder_len);
+            shift_right(*self.remainder_word, remainder_len, remainder_len - end_offset)
+        };
+
+        Some(
+            ByteSpan {
+                data: self.data.slice(start_word, min(end_word, data_len) - start_word),
+                first_char_start_offset: downcast(start_offset).unwrap(),
+                remainder_word: remainder_with_end_offset_trimmed,
+                remainder_len: downcast(end_offset).unwrap(),
+            },
+        )
+    }
+}
+
+impl ByteSpanGetRangeInclusive of crate::ops::Get<ByteSpan, crate::ops::RangeInclusive<usize>> {
+    type Output = ByteSpan;
+
+    /// Returns a slice for the given range `[start, end]`.
+    /// If span is consumed by the slice: returns the default object.
+    /// If out of bounds: returns `None`.
+    fn get(self: @ByteSpan, index: crate::ops::RangeInclusive<usize>) -> Option<ByteSpan> {
+        let end_exclusive = crate::num::traits::CheckedAdd::checked_add(index.end, 1)?;
+        ByteSpanTrait::get(self, index.start..end_exclusive)
+    }
+}
+
 /// Trait for types that can be converted into a `ByteSpan`.
 #[unstable(feature: "byte-span")]
 pub trait ToByteSpanTrait<C> {
@@ -874,6 +938,21 @@ impl ByteSpanToByteSpan of ToByteSpanTrait<ByteSpan> {
     }
 }
 
+/// Shifts a word right by `n_bytes`.
+/// The input `bytes31` and the output `bytes31`s are represented using `felt252`s to improve
+/// performance.
+///
+/// Note: this function assumes that:
+/// 1. `word` is validly convertible to a `bytes31` which has no more than `word_len` bytes of data.
+/// 2. `n_bytes <= word_len`.
+/// 3. `word_len <= BYTES_IN_BYTES31`.
+/// If these assumptions are not met, it can corrupt the result. Thus, this should be a
+/// private function. We could add masking/assertions but it would be more expensive.
+fn shift_right(word: felt252, word_len: usize, n_bytes: usize) -> felt252 {
+    let (_shifted_out, after_shift_right) = split_bytes31(word, word_len, n_bytes);
+    after_shift_right
+}
+
 mod helpers {
     use core::num::traits::Bounded;
     use crate::bytes_31::BYTES_IN_BYTES31;

corelib/src/ops.cairo

@@ -73,3 +73,8 @@ pub use range::{
 // `RangeOp` and `RangeInclusiveOp` are used internally by the compiler.
 #[allow(unused_imports)]
 use range::{RangeInclusiveOp, RangeOp};
+
+#[unstable(feature: "corelib-get-trait")]
+pub mod get;
+#[feature("corelib-get-trait")]
+pub use get::Get;

corelib/src/ops/get.cairo

@@ -0,0 +1,42 @@
+/// A trait for fallible indexing operations with different index types.
+///
+/// Unlike [`IndexView`] and [`Index`] which panic on out-of-bounds access, `Get`
+/// returns an `Option`, providing safe indexing operations. This trait enables containers
+/// to support multiple index types (e.g., `Range<usize>`, `RangeInclusive<usize>`,
+/// or `usize`) through a unified interface.
+///
+/// [`IndexView`]: crate::ops::IndexView
+/// [`Index`]: crate::ops::Index
+///
+/// # Examples
+///
+/// The following example shows how `ByteSpan` implements `Get` for both `Range<usize>`
+/// and `RangeInclusive<usize>`, enabling safe slicing operations that return `None` when
+/// out of bounds.
+///
+/// ```
+/// use core::byte_array::{ByteSpan, ByteSpanTrait};
+///
+/// let ba: ByteArray = "hello";
+/// let span = ba.span();
+///
+/// // Using Range<usize>.
+/// let slice = span.get(1..4).unwrap();
+/// assert_eq!(slice.to_byte_array(), "ell");
+///
+/// // Using RangeInclusive<usize>.
+/// let slice = span.get(1..=3).unwrap();
+/// assert_eq!(slice.to_byte_array(), "ell");
+///
+/// // Out of bounds returns None.
+/// assert!(span.get(10..20).is_none());
+/// ```
+// TODO(giladchase): add examples for `usize` once supported.
+#[unstable(feature: "corelib-get-trait")]
+pub trait Get<C, I> {
+    /// The returned type after indexing.
+    type Output;
+
+    /// Returns the output at this index, if in bounds.
+    fn get(self: @C, index: I) -> Option<Self::Output>;
+}

corelib/src/ops/index.cairo

@@ -6,6 +6,9 @@
 //! * [`IndexView`] - For snapshot-based access
 //! * [`Index`] - For reference-based access
 //!
+//! For safe indexing operations that return `Option`, see the unstable [`Get`] trait
+//! in the [`get`] module.
+//!
 //! # When to use which trait
 //!
 //! - Use [`IndexView`] when the collection can be accessed in a read-only context and is not
@@ -17,6 +20,8 @@
 //! Only one of these traits should be implemented for any given type, not both.
 //!
 //! [`Felt252Dict`]: core::dict::Felt252Dict
+//! [`Get`]: crate::ops::get::Get
+//! [`get`]: crate::ops::get
 
 #[feature("deprecated-index-traits")]
 use crate::traits::{Index as DeprecatedIndex, IndexView as DeprecatedIndexView};

corelib/src/test/byte_array_test.cairo

@@ -1,5 +1,6 @@
 #[feature("byte-span")]
-use crate::byte_array::{ByteSpanTrait, ToByteSpanTrait};
+use crate::byte_array::{ByteSpan, ByteSpanTrait, ToByteSpanTrait};
+use crate::num::traits::Bounded;
 use crate::test::test_utils::{assert_eq, assert_ne};
 
 #[test]
@@ -508,39 +509,58 @@ fn test_from_collect() {
     assert_eq!(ba, "hello");
 }
 
-// TODO(giladchase): add dedicated is_empty test once we have `slice`.
 #[test]
 fn test_span_len() {
-    // Test simple happy flow --- value is included in the last word.
     // TODO(giladchase): add short string test here once supported cast into span.
     let ba: ByteArray = "A";
-    let span = ba.span();
-    assert_eq!(span.len(), 1);
-    assert!(!span.is_empty());
+    assert_eq!(ba.span().len(), 1);
+    assert!(!ba.span().is_empty());
+
+    let ba_31: ByteArray = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcde";
+    assert_eq!(ba_31.span().len(), 31);
+    assert!(!ba_31.span().is_empty());
 
-    // Test empty.
     let empty_ba: ByteArray = "";
-    let empty_span = empty_ba.span();
-    assert_eq!(empty_span.len(), 0);
-    assert!(empty_span.is_empty());
+    assert_eq!(empty_ba.span().len(), 0);
+    assert!(empty_ba.span().is_empty());
 
-    // TODO(giladchase): Add start-offset using slice once supported.
     // First word in the array, second in last word.
     let two_byte31: ByteArray = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefg";
-    let mut single_span = two_byte31.span();
-    assert_eq!(single_span.len(), 33, "len error with start offset");
-    assert!(!single_span.is_empty());
+    let single_span = two_byte31.span().get(1..=32);
+    assert_eq!(single_span.map(|s| s.len()), Some(32), "len error with start offset");
+    assert_eq!(single_span.map(|s| s.is_empty()), Some(false));
 
-    // TODO(giladchase): Add start-offset using slice once supported.
-    // First word in the array, second in the array, third in last word.
+    // First word in the array, second in the array, third in remainder.
     let three_bytes31: ByteArray =
         "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789#$"; // 64 chars.
-    let mut three_span = three_bytes31.span();
-    assert_eq!(three_span.len(), 64, "len error with size-3 bytearray");
-    assert!(!three_span.is_empty());
+    let three_span = three_bytes31.span().get(1..64);
+    assert_eq!(three_span.map(|s| s.len()), Some(63), "len error with size-3 bytearray");
+    assert_eq!(three_span.map(|s| s.is_empty()), Some(false));
     // TODO(giladchase): use `ByteSpan::PartialEq` to check that a consuming slice == Default.
 }
 
+#[test]
+fn test_span_slice_is_empty() {
+    let ba: ByteArray = "hello";
+    let span = ba.span();
+    let is_empty = |span: ByteSpan| span.is_empty();
+
+    let empty = span.get(2..2);
+    assert_eq!(empty.map(|s| s.len()), Some(0));
+    assert_eq!(empty.map(is_empty), Some(true));
+    assert_eq!(empty.map(|s| s.to_byte_array()), Some(""));
+
+    let ba_31: ByteArray = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcde";
+    assert_eq!(ba_31.span().get(30..30).map(is_empty), Some(true));
+    assert_eq!(ba_31.span().get(31..31).map(is_empty), Some(true));
+    assert_eq!(ba_31.span().get(15..30).map(is_empty), Some(false));
+
+    let ba_30: ByteArray = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcd";
+    assert_eq!(ba_30.span().get(29..29).map(is_empty), Some(true));
+    assert_eq!(ba_30.span().get(30..30).map(is_empty), Some(true));
+    assert_eq!(ba_30.span().get(15..29).map(is_empty), Some(false));
+}
+
 #[test]
 fn test_span_copy() {
     let ba: ByteArray = "12";
@@ -561,6 +581,85 @@ fn test_span_copy() {
     assert_eq!(ba, span.to_byte_array());
 }
 
+#[test]
+fn test_span_slice_empty() {
+    let ba: ByteArray = "hello";
+    let span = ba.span();
+
+    let empty = span.get(2..2).unwrap();
+    assert_eq!(empty.len(), 0);
+    assert!(empty.is_empty());
+    assert_eq!(empty.to_byte_array(), "");
+}
+
+// TODO(giladchase): replace assert+is_none with assert_eq when we have PartialEq.
+#[test]
+fn test_span_slice_out_of_bounds() {
+    let ba: ByteArray = "hello";
+    let span = ba.span();
+
+    assert!(span.get(3..=7).is_none(), "end out of bounds");
+    assert!(span.get(6..=6).is_none(), "start out of bounds (inclusive)");
+
+    assert!(
+        span.get(2..4).unwrap().get((Bounded::<usize>::MAX - 1)..Bounded::<usize>::MAX).is_none(),
+        "start offset overflow",
+    );
+    assert!(
+        span.get(2..=3).unwrap().get((Bounded::<usize>::MAX - 1)..Bounded::<usize>::MAX).is_none(),
+        "start offset overflow (first get inclusive)",
+    );
+    assert!(
+        span.get(2..4).unwrap().get((Bounded::<usize>::MAX - 1)..=Bounded::<usize>::MAX).is_none(),
+        "start offset overflow (second get inclusive)",
+    );
+    assert!(
+        span.get(2..=3).unwrap().get((Bounded::<usize>::MAX - 1)..=Bounded::<usize>::MAX).is_none(),
+        "start offset overflow (both gets inclusive)",
+    );
+    assert!(span.get(Bounded::<usize>::MAX..0).is_none(), "backwards range");
+
+    let empty_string: ByteArray = "";
+    assert!(empty_string.span().get(0..2).is_none(), "empty slice is sliceable");
+}
+
+#[test]
+fn test_span_slice_under_31_bytes() {
+    // Word entirely in remainder word.
+    let ba: ByteArray = "abcde";
+    let span = ba.span();
+    let tba = |ba: ByteSpan| ba.to_byte_array();
+
+    assert_eq!(span.get(0..=2).map(tba), Some("abc"));
+    assert_eq!(span.get(2..4).map(tba), Some("cd"));
+    assert_eq!(span.get(4..=4).map(tba), Some("e"));
+}
+#[test]
+fn test_span_slice_exactly_31_bytes() {
+    // 1 full data word, empty last_word.
+    let ba_31: ByteArray = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcde";
+    let span = ba_31.span();
+
+    assert_eq!(span.len(), 31);
+    assert_eq!(span.get(0..31).unwrap().to_byte_array(), ba_31);
+    assert_eq!(span.get(10..=19).unwrap().to_byte_array(), "KLMNOPQRST");
+}
+
+#[test]
+fn test_span_slice_positions() {
+    // Two full bytes31 + remainder with 2 bytes.
+    let ba_64: ByteArray = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789#$";
+    let span = ba_64.span();
+    let tba = |ba: ByteSpan| ba.to_byte_array();
+
+    assert_eq!(span.get(10..=39).map(tba), Some("KLMNOPQRSTUVWXYZabcdefghijklmn"));
+    assert_eq!(
+        span.get(5..64).map(tba),
+        Some("FGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789#$"),
+    );
+    assert_eq!(span.get(29..49).map(tba), Some("defghijklmnopqrstuvw"));
+}
+
 #[test]
 fn test_span_to_bytearray() {
     let empty_ba: ByteArray = "";
@@ -578,5 +677,18 @@ fn test_span_to_bytearray() {
     let even_larger_ba: ByteArray =
         "abcdeFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789#$"; // 64 bytes
     assert_eq!(even_larger_ba.span().to_byte_array(), even_larger_ba);
-    // TODO(giladchase): test with slice.
+}
+
+#[test]
+fn test_span_multiple_start_offset_slicing() {
+    let ba_6: ByteArray = "abcdef";
+    let span = ba_6.span();
+
+    let slice1_inc = span.get(1..=5).unwrap();
+    let slice2_inc = slice1_inc.get(1..=4).unwrap();
+    let slice3_inc = slice2_inc.get(1..=3).unwrap();
+
+    assert_eq!(slice1_inc.to_byte_array(), "bcdef");
+    assert_eq!(slice2_inc.to_byte_array(), "cdef");
+    assert_eq!(slice3_inc.to_byte_array(), "def");
 }