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

Note: unlike `pending_word` in `ByteArray`, the remainder word can contains 31 bytes (rather than
30) for forward-compatibility with short-string spans, which can be 31 bytes and must be held in the
remainder word.

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, SpanTrait};
 #[allow(unused_imports)]
 use crate::bytes_31::{
     BYTES_IN_BYTES31, Bytes31Trait, POW_2_128, POW_2_8, U128IntoBytes31, U8IntoBytes31,
@@ -52,6 +52,8 @@ use crate::clone::Clone;
 use crate::cmp::min;
 #[allow(unused_imports)]
 use crate::integer::{U32TryIntoNonZero, u128_safe_divmod};
+#[feature("bounded-int-utils")]
+use crate::internal::bounded_int::{BoundedInt, downcast, upcast};
 #[allow(unused_imports)]
 use crate::serde::Serde;
 use crate::traits::{Into, TryInto};
@@ -586,3 +588,84 @@ 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 ByteSpan {
+    /// A span representing the array of all `bytes31` words in the byte-span, excluding the last
+    /// bytes_31 word that is stored in [Self::last_word].
+    /// Invariant: every byte stored in `data` is part of the span except for the bytes appearing
+    /// before `first_char_start_offset` in the first word.
+    data: Span<bytes31>,
+    /// The offset of the first character in the first entry of [Self::data], for use in span
+    /// slices.
+    first_char_start_offset: BoundedInt<0, 30>,
+    /// Contains the final bytes of the span when the end is either not in memory or isn't aligned
+    /// to a word boundary.
+    /// It is represented as a `felt252` to improve performance of building the byte array, but
+    /// represents a `bytes31`.
+    /// The first byte is the most significant byte among the `pending_word_len` bytes in the word.
+    remainder_word: felt252,
+    /// The number of bytes in [Self::remainder_word].
+    remainder_len: BoundedInt<0, 31>,
+}
+
+#[generate_trait]
+pub impl ByteArraySpanImpl of ByteSpanTrait {
+    /// Returns the length of the `ByteSpan`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let ba: ByteArray = "byte array";
+    /// let span = ba.span();
+    /// let len = span.len();
+    /// assert!(len == 10);
+    /// ```
+    #[must_use]
+    fn len(self: @ByteSpan) -> usize {
+        let data_bytes = self.data.len() * BYTES_IN_BYTES31;
+        data_bytes - upcast(self.first_char_start_offset) + upcast(self.remainder_len)
+    }
+
+    /// Returns `true` if the `ByteSpan` has a length of 0.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let ba: ByteArray = "";
+    /// let span = ba.span();
+    /// assert!(span.is_empty());
+    ///
+    /// let ba2: ByteArray = "not empty";
+    /// let span2 = ba2.span();
+    /// assert!(!span2.is_empty());
+    /// ```
+    fn is_empty(self: @ByteSpan) -> bool {
+        self.len() == 0
+    }
+}
+
+pub trait ToByteSpanTrait<C> {
+    #[must_use]
+    fn span(self: @C) -> ByteSpan;
+}
+
+impl ByteArrayToByteSpan of ToByteSpanTrait<ByteArray> {
+    fn span(self: @ByteArray) -> ByteSpan {
+        ByteSpan {
+            data: self.data.span(),
+            first_char_start_offset: 0,
+            remainder_word: *self.pending_word,
+            remainder_len: downcast(self.pending_word_len).expect('In [0,30] by assumption'),
+        }
+    }
+}
+
+impl ByteSpanToByteSpan of ToByteSpanTrait<ByteSpan> {
+    fn span(self: @ByteSpan) -> ByteSpan {
+        *self
+    }
+}

corelib/src/test/byte_array_test.cairo

@@ -1,3 +1,4 @@
+use crate::byte_array::{ByteSpanTrait, ToByteSpanTrait};
 use crate::test::test_utils::{assert_eq, assert_ne};
 
 #[test]
@@ -505,3 +506,49 @@ fn test_from_collect() {
     let ba: ByteArray = array!['h', 'e', 'l', 'l', 'o'].into_iter().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);
+    assert!(!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());
+
+    // 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());
+
+    // TODO(giladchase): Add start-offset using slice once supported.
+    // First word in the array, second in the array, third in last word.
+    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());
+}
+
+#[test]
+fn test_span_copy() {
+    let ba: ByteArray = "12";
+    let span = ba.span();
+    assert_eq!(span.len(), 2);
+
+    let other_span = span;
+    assert_eq!(other_span.len(), 2);
+    let span_again = span.span();
+    assert_eq!(span_again.len(), span.len());
+    let even_more_span_again = other_span.span();
+    assert_eq!(even_more_span_again.len(), other_span.len());
+    // TODO(giladchase): verify span content once we add `into` or `PartialEq`.
+}