feat(byte_array): add ByteSpan::to_byte_array

When slicing bytespans (to-be-implemented), the end-offset is trimmed by shifting the word to the
right.
The left offset, however, will be trimmed lazily only if the `ByteSpan` is casted into a `ByteArray`.

Note: Lazily removing the end-offset will require saving an additional field, `end_offset` in
`ByteSpan`, due to how strings are represented inside felt252 (the first byte is the msb of the
word). In other words, we cannot just reduce the remainder_len, because then it'd be impossible to
know how much to trim off from the remainder word at `to_byte_array`.

Author: Gilad Chase

corelib/src/byte_array.cairo

@@ -43,6 +43,7 @@
 //! ```
 
 use crate::array::{ArrayTrait, Span, SpanTrait};
+use crate::bytes_31::split_bytes31;
 #[allow(unused_imports)]
 use crate::bytes_31::{
     BYTES_IN_BYTES31, Bytes31Trait, POW_2_128, POW_2_8, U128IntoBytes31, U8IntoBytes31,
@@ -655,6 +656,48 @@ pub impl ByteSpanImpl of ByteSpanTrait {
     fn is_empty(self: ByteSpan) -> bool {
         self.remainder_len == 0 && self.data.len() == 0
     }
+
+    /// Converts a `ByteSpan` into a `ByteArray`.
+    /// The cast includes trimming the start_offset of the first word of the span (which is created
+    /// when slicing).
+    ///
+    /// Note: creating `ByteArray.data` from `Span` requires allocating a new memory
+    /// segment for the returned array, and *O*(*n*) operations to populate the array with the
+    /// content of the span (see also `SpanIntoArray`).
+    fn to_byte_array(mut self: ByteSpan) -> ByteArray {
+        let remainder_len = upcast(self.remainder_len);
+        let Some(first_word) = self.data.pop_front() else {
+            // Slice is included entirely in the remainder word.
+            let len_without_offset: usize = remainder_len - upcast(self.first_char_start_offset);
+            let (start_offset_trimmed, _) = split_bytes31(
+                self.remainder_word, remainder_len, len_without_offset,
+            );
+            return ByteArray {
+                data: array![],
+                pending_word: start_offset_trimmed,
+                pending_word_len: upcast(len_without_offset),
+            };
+        };
+
+        let mut ba = Default::default();
+        let n_bytes_to_append = BYTES_IN_BYTES31 - upcast(self.first_char_start_offset);
+        let (first_word_no_offset, _) = split_bytes31(
+            (*first_word).into(), BYTES_IN_BYTES31, n_bytes_to_append,
+        );
+        ba.append_word(first_word_no_offset, n_bytes_to_append);
+
+        // Append the rest of the span, which is now aligned since the first word was popped.
+        ba.append_aligned_byte_span(self);
+        ba
+    }
+}
+
+impl ByteSpanDefault of Default<ByteSpan> {
+    fn default() -> ByteSpan {
+        ByteSpan {
+            data: [].span(), first_char_start_offset: 0, remainder_word: 0, remainder_len: 0,
+        }
+    }
 }
 
 /// Trait for types that can be converted into a `ByteSpan`.

corelib/src/test/byte_array_test.cairo

@@ -547,9 +547,34 @@ fn test_span_copy() {
 
     let other_span = span;
     assert_eq!(other_span.len(), 2);
+    assert_eq!(ba, span.to_byte_array());
+
     let span_again = span.span();
-    assert_eq!(span_again.len(), span.len());
+    assert_eq!(ba, span_again.to_byte_array());
+    assert_eq!(ba, span.to_byte_array());
+
     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`.
+    assert_eq!(ba, even_more_span_again.to_byte_array());
+    assert_eq!(ba, other_span.to_byte_array());
+    assert_eq!(ba, span.to_byte_array());
+}
+
+#[test]
+fn test_span_to_bytearray() {
+    let empty_ba: ByteArray = "";
+    assert_eq!(empty_ba.span().to_byte_array(), empty_ba);
+
+    // Only remainder.
+    let small_ba: ByteArray = "hello";
+    assert_eq!(small_ba.span().to_byte_array(), small_ba);
+
+    // Data word and remainder.
+    let large_ba: ByteArray = "0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVW"; // 40 bytes
+    assert_eq!(large_ba.span().to_byte_array(), large_ba);
+
+    // Two data words and remainder.
+    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.
 }