feat(byte_array): add ByteArray::span and Span::len

Author: Gilad Chase

corelib/src/byte_array.cairo

@@ -42,7 +42,7 @@
 //! assert!(first_byte == 0x41);
 //! ```
 
-use crate::array::{ArrayTrait, SpanTrait};
+use crate::array::{ArrayTrait, Span as ArraySpan, SpanTrait as ArraySpanTrait};
 #[allow(unused_imports)]
 use crate::bytes_31::{
     BYTES_IN_BYTES31, Bytes31Trait, POW_2_128, POW_2_8, U128IntoBytes31, U8IntoBytes31,
@@ -585,3 +585,49 @@ impl ByteArrayFromIterator of crate::iter::FromIterator<ByteArray, u8> {
         ba
     }
 }
+
+/// A view into a contiguous collection of a string type.
+/// Currently implemented only for `ByteArray`, but will soon be implemented for other string types.
+/// `Span` implements the `Copy` and the `Drop` traits.
+#[derive(Copy, Drop)]
+pub struct Span {
+    pub(crate) raw_data: ArraySpan<bytes31>,
+    /// The offset of the first character in the first entry of [Self::raw_data], for use in span
+    /// slices.
+    /// Value should be in the range [0, 30].
+    pub(crate) first_char_start_offset: usize,
+    /// The last word in the span will always be located in this field, to account for bytearrays
+    /// which don't include the pending bytes31 word in the array itself.
+    pub(crate) last_word: felt252,
+    /// The offset of the last character in the last entry of span, located in [Self::last_word].
+    /// Value should be in the range [0, 30].
+    pub(crate) last_char_end_offset: usize,
+}
+
+#[generate_trait]
+pub impl ByteArraySpanImpl of SpanTrait {
+    fn len(self: @Span) -> usize {
+        let raw_data_bytes = self.raw_data.len() * BYTES_IN_BYTES31;
+        raw_data_bytes - *self.first_char_start_offset + *self.last_char_end_offset
+    }
+
+    fn is_empty(self: @Span) -> bool {
+        self.len() == 0
+    }
+}
+
+pub trait ToSpanTrait<C> {
+    #[must_use]
+    fn span(self: @C) -> Span;
+}
+
+impl ByteArrayToSpan of ToSpanTrait<ByteArray> {
+    fn span(self: @ByteArray) -> Span {
+        Span {
+            raw_data: self.data.span(),
+            first_char_start_offset: 0,
+            last_word: *self.pending_word,
+            last_char_end_offset: *self.pending_word_len,
+        }
+    }
+}

corelib/src/test/byte_array_test.cairo

@@ -1,3 +1,6 @@
+pub use crate::byte_array::{
+    Span as ByteArraySpan, SpanTrait as ByteArraySpanTrait, ToSpanTrait as ByteArrayToSpanTrait,
+};
 use crate::test::test_utils::{assert_eq, assert_ne};
 
 #[test]
@@ -463,6 +466,50 @@ fn test_from_collect() {
     assert_eq!(ba, "hello");
 }
 
+#[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, 'wrong span len');
+    assert!(!span.is_empty());
+
+    // Test empty.
+    let empty_ba: ByteArray = "";
+    let empty_span = empty_ba.span();
+    assert_eq(@empty_span.len(), @0, 'empty span len != 0');
+    assert!(empty_span.is_empty());
+
+    // First word in the array + start offset, second in last word.
+    let two_byte31: ByteArray = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefg";
+    let mut single_span = two_byte31.span();
+    // TODO(giladchase): use slice once supported.
+    single_span.first_char_start_offset = 1;
+
+    assert_eq(@single_span.len(), @32, 'len error with start offset');
+    assert!(!single_span.is_empty());
+
+    // First word in the array + start offset, second in the array, third in last word.
+    let three_bytes31: ByteArray =
+        "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789#$"; // 64 chars.
+    let mut three_span = three_bytes31.span();
+    three_span.first_char_start_offset = 1;
+    assert_eq(@three_span.len(), @63, 'len error with size-3 bytearray');
+    assert!(!three_span.is_empty());
+}
+
+#[test]
+fn test_span_copy() {
+    let ba: ByteArray = "12";
+    let span = ba.span();
+    assert_eq(@span.len(), @2, 'wrong span len');
+
+    let other_span = span;
+    assert_eq(@other_span.len(), @2, 'span len is equal to Copy');
+    assert_eq(@other_span.len(), @span.len(), 'original span still usable');
+}
+
 // ========= Test helper functions =========
 
 fn compare_spans<T, +crate::fmt::Debug<T>, +PartialEq<T>, +Copy<T>, +Drop<T>>(