From e5756a2ad018b907b1d59fc00718c5182d1f277d Mon Sep 17 00:00:00 2001 From: TAdev0 Date: Tue, 29 Oct 2024 15:30:23 +0100 Subject: [PATCH 01/31] Array module --- corelib/src/array.cairo | 365 +++++++++++++++++++++++++++++++++------- 1 file changed, 308 insertions(+), 57 deletions(-) diff --git a/corelib/src/array.cairo b/corelib/src/array.cairo index 29d08de5af3..88be5abe047 100644 --- a/corelib/src/array.cairo +++ b/corelib/src/array.cairo @@ -39,17 +39,32 @@ extern fn array_len(arr: @Array) -> usize nopanic; /// Basic trait for the `Array` type. #[generate_trait] pub impl ArrayImpl of ArrayTrait { - /// Creates a new array. + /// Returns a new empty array. + /// + /// # Examples + /// + /// ``` + /// let first_arr: Array = ArrayTrait::new(); + /// let second_arr = ArrayTrait::::new(); + /// ``` + /// + /// It is generally more straightforward to use the `array!` macro to create a new array, + /// calling the `new` function under the hood: + /// + /// ``` + /// let arr: Array = array![]; + /// ``` #[inline] fn new() -> Array nopanic { array_new() } - /// Adds a value T to the end of the array + + /// Adds a value of type `T` to the end of the array. /// - /// Example: + /// # Examples /// /// ``` - /// let mut arr = array![]; + /// let mut arr: Array = array![]; /// arr.append(1); /// arr.append(2); /// ``` @@ -57,12 +72,14 @@ pub impl ArrayImpl of ArrayTrait { fn append(ref self: Array, value: T) nopanic { array_append(ref self, value) } + /// Adds a span to the end of the array. + /// Requires that the values of the span implement `Clone` and `Drop` traits. /// - /// Example: + /// # Examples /// /// ``` - /// let mut arr = array![]; + /// let mut arr: Array = array![]; /// arr.append_span(array![3, 4, 5].span()); /// ``` fn append_span<+Clone, +Drop>(ref self: Array, mut span: Span) { @@ -74,10 +91,11 @@ pub impl ArrayImpl of ArrayTrait { Option::None => {} }; } + /// Pops a value from the front of the array. - /// Return `Option::Some` if the array is not empty, `Option::None` otherwise. + /// Returns `Option::Some(value)` if the array is not empty, `Option::None` otherwise. /// - /// Example: + /// # Examples /// /// ``` /// let mut arr = array![2, 3, 4]; @@ -93,15 +111,19 @@ pub impl ArrayImpl of ArrayTrait { Option::None => Option::None, } } + /// Pops a value from the front of the array. - /// Return `Option::Some` containing the remaining array and the value removed if the array is + /// Returns an option containing the remaining array and the value removed if the array is /// not empty, otherwise `Option::None` and drops the array. /// - /// Example: + /// # Examples /// /// ``` /// let arr = array![2, 3, 4]; /// assert!(arr.pop_front_consume() == Option::Some((array![3, 4], 2))); + /// + /// let arr: Array = array![]; + /// assert!(arr.pop_front_consume() == Option::None); /// ``` #[inline] fn pop_front_consume(self: Array) -> Option<(Array, T)> nopanic { @@ -110,33 +132,37 @@ pub impl ArrayImpl of ArrayTrait { Option::None => Option::None, } } - /// Returns 'Option::Some' of the value at the given 'index', + + /// Returns an option containing a box of a snapshot of the value at the given 'index' /// if the array contains this index, 'Option::None' otherwise. /// - /// Example: + /// # Examples /// /// ``` /// let arr = array![2, 3, 4]; - /// assert!(arr.get(1) == Option::Some(@3)); + /// assert!(arr.get(1).unwrap().unbox() == @3); /// ``` #[inline] fn get(self: @Array, index: usize) -> Option> { array_get(self, index) } - /// Returns a snapshot of the value at the given 'index'. + + /// Returns a snapshot of the value at the given 'index' if the array contains this index, + /// panics with an 'Index out of bounds' error otherwise. /// - /// Example: + /// # Examples /// /// ``` /// let arr = array![2, 3, 4]; - /// assert!(arr.at(1) == @4); + /// assert!(arr.at(1) == @3); /// ``` fn at(self: @Array, index: usize) -> @T { array_at(self, index).unbox() } - /// Returns the length of the array. + + /// Returns the length of the array as a `usize` value. /// - /// Example: + /// # Examples /// /// ``` /// let arr = array![2, 3, 4]; @@ -147,9 +173,10 @@ pub impl ArrayImpl of ArrayTrait { fn len(self: @Array) -> usize { array_len(self) } - /// Returns whether the array is empty. + + /// Returns whether the array is empty or not. /// - /// Example: + /// # Examples /// /// ``` /// let mut arr = array![]; @@ -166,7 +193,15 @@ pub impl ArrayImpl of ArrayTrait { Option::None => true, } } + /// Returns a span of the array. + /// + /// # Examples + /// + /// ``` + /// let arr: Array = array![1, 2, 3]; + /// let span: Span = arr.span(); + /// ``` #[inline] #[must_use] fn span(snapshot: @Array) -> Span { @@ -174,24 +209,63 @@ pub impl ArrayImpl of ArrayTrait { } } +/// `Default` trait implementation to create a new empty array. impl ArrayDefault of Default> { + /// Returns a new empty array. + /// + /// # Examples + /// + /// ``` + /// let arr: Array = Default::default(); + /// ``` #[inline] fn default() -> Array { ArrayTrait::new() } } +/// `IndexView` trait implementation to access an item contained in type `Array` with an index of type `usize`. impl ArrayIndex of IndexView, usize, @T> { + /// Returns a snapshot of the element at the given index. + /// `IndexView` needs to be explicitly imported with `use core::ops::IndexView;` + /// + /// # Examples + /// + /// ``` + /// let arr: @Array = @array![1, 2, 3]; + /// let element: @u8 = arr.index(0); + /// ``` fn index(self: @Array, index: usize) -> @T { array_at(self, index).unbox() } } +/// `Serde` trait implementation to serialize and deserialize an `Array`. impl ArraySerde, +Drop> of Serde> { + /// Serializes an `Array` into an `Array`. + /// + /// # Examples + /// + /// ``` + /// let arr: Array = array![1, 2, 3]; + /// let mut output: Array = array![]; + /// arr.serialize(ref output); + /// ``` fn serialize(self: @Array, ref output: Array) { self.len().serialize(ref output); serialize_array_helper(self.span(), ref output); } + + /// Deserializes a `Span` into an `Array` and returns an option to an `Array`. + /// + /// # Examples + /// + /// ``` + /// let mut span: Span = array![2, 0, 1].span(); + /// let arr: Array = Serde::deserialize(ref span).unwrap(); + /// assert!(*arr.at(0) == 0); + /// assert!(*arr.at(1) == 1); + /// ``` fn deserialize(ref serialized: Span) -> Option> { let length = *serialized.pop_front()?; let mut arr = array![]; @@ -220,21 +294,40 @@ fn deserialize_array_helper, +Drop>( } /// A span is a view into a continuous collection of the same type - such as `Array`. +/// It is a structure with a single field that holds a snapshot of an array. +/// `Span` implements the `Copy` and the `Drop` traits. pub struct Span { - /// The snapshot of the array. pub(crate) snapshot: @Array } impl SpanCopy of Copy>; impl SpanDrop of Drop>; +/// `Into` trait implementation to convert an array into a span. impl ArrayIntoSpan> of Into, Span> { + /// Takes an array and returns a span of that array. + /// + /// # Examples + /// + /// ``` + /// let arr: Array = array![1, 2, 3]; + /// let span: Span = arr.into(); + /// ``` fn into(self: Array) -> Span { self.span() } } +/// `Into` trait implementation to convert a span into an array. impl SpanIntoArray, +Clone> of Into, Array> { + /// Takes a span and returns an array. + /// + /// # Examples + /// + /// ``` + /// let span: Span = array![1, 2, 3].span(); + /// let arr: Array = span.into(); + /// ``` fn into(self: Span) -> Array { let mut arr = array![]; arr.append_span(self); @@ -242,18 +335,47 @@ impl SpanIntoArray, +Clone> of Into, Array> { } } +/// `Into` trait implementation to convert a span into a snapshot of an array. impl SpanIntoArraySnap of Into, @Array> { + /// Takes a span and returns a snapshot of an array. + /// + /// # Examples + /// + /// ``` + /// let span: Span = array![1, 2, 3].span(); + /// let arr: @Array = span.into(); + /// ``` fn into(self: Span) -> @Array { self.snapshot } } +/// `Serde` trait implementation to serialize and deserialize a `Span`. impl SpanFelt252Serde of Serde> { + /// Serializes a `Span` into an `Array`. + /// + /// # Examples + /// + /// ``` + /// let span: Span = array![1, 2, 3].span(); + /// let mut output: Array = array![]; + /// arr.serialize(ref output); + /// ``` fn serialize(self: @Span, ref output: Array) { (*self).len().serialize(ref output); serialize_array_helper(*self, ref output) } + /// Deserializes a `Span` into an `Span` and returns an option to a `Span`. + /// + /// # Examples + /// + /// ``` + /// let mut span: Span = array![2, 0, 1].span(); + /// let result: Span = Serde::deserialize(ref span).unwrap(); + /// assert!(*result.at(0) == 0); + /// assert!(*result.at(1) == 1); + /// ``` fn deserialize(ref serialized: Span) -> Option> { let length: u32 = (*serialized.pop_front()?).try_into()?; let res = serialized.slice(0, length); @@ -262,12 +384,32 @@ impl SpanFelt252Serde of Serde> { } } +/// `Serde` trait implementation to serialize and deserialize a `Span`. impl SpanSerde, +Drop, -TypeEqual> of Serde> { + /// Serializes a `Span` into an `Array`. + /// + /// # Examples + /// + /// ``` + /// let span: Span = array![1, 2, 3].span(); + /// let mut output: Array = array![]; + /// arr.serialize(ref output); + /// ``` fn serialize(self: @Span, ref output: Array) { (*self).len().serialize(ref output); serialize_array_helper(*self, ref output) } + /// Deserializes a `Span` into an `Span` and returns an option to a `Span`. + /// + /// # Examples + /// + /// ``` + /// let mut span: Span = array![2, 0, 1].span(); + /// let result: Span = Serde::deserialize(ref span).unwrap(); + /// assert!(*result.at(0) == 0); + /// assert!(*result.at(1) == 1); + /// ``` fn deserialize(ref serialized: Span) -> Option> { let length = *serialized.pop_front()?; let mut arr = array_new(); @@ -279,9 +421,10 @@ impl SpanSerde, +Drop, -TypeEqual> of Serde> #[generate_trait] pub impl SpanImpl of SpanTrait { /// Pops a value from the front of the span. - /// Return `Option::Some` if the span is not empty, `Option::None` otherwise. + /// Returns `Option::Some(@value)` if the array is not empty, `Option::None` otherwise. /// - /// Example: + /// # Examples + /// /// ``` /// let mut span = array![1, 2, 3].span(); /// assert!(span.pop_front() == Option::Some(@1)); @@ -296,13 +439,14 @@ pub impl SpanImpl of SpanTrait { Option::None => Option::None, } } + /// Pops a value from the back of the span. - /// Return `Option::Some` if the span is not empty, `Option::None` otherwise. + /// Returns `Option::Some(@value)` if the array is not empty, `Option::None` otherwise. /// - /// Example: + /// # Examples /// ``` /// let mut span = array![1, 2, 3].span(); - /// assert!(span.pop_back() == Option::Some(@7)); + /// assert!(span.pop_back() == Option::Some(@3)); /// ``` #[inline] fn pop_back(ref self: Span) -> Option<@T> { @@ -314,56 +458,72 @@ pub impl SpanImpl of SpanTrait { Option::None => Option::None, } } + /// Pops multiple values from the front of the span. - /// Returns 'Option::Some' of the elements removed if the - /// action completed successfully, 'Option::None' otherwise. + /// Returns an option containing a snapshot of a box that contains the values as a fixed-size array + /// if the action completed successfully, 'Option::None' otherwise. /// - /// Example: + /// # Examples + /// /// ``` /// let mut span = array![1, 2, 3].span(); - /// assert!(span.multi_pop_front::<2>() == Option::Some(@[1, 2])); + /// let result = *(span.multi_pop_front::<2>().unwrap()); + /// let unbox_result = result.unbox(); + /// assert!(unbox_result == [1, 2]); /// ``` fn multi_pop_front(ref self: Span) -> Option<@Box<[T; SIZE]>> { array_snapshot_multi_pop_front(ref self.snapshot) } + /// Pops multiple values from the back of the span. - /// Returns 'Option::Some' of the elements removed if the - /// action completed successfully, 'Option::None' otherwise. + /// Returns an option containing a snapshot of a box that contains the values as a fixed-size array + /// if the action completed successfully, 'Option::None' otherwise. /// - /// Example: + /// # Examples + /// /// ``` /// let mut span = array![1, 2, 3].span(); - /// assert!(span.multi_pop_back::<2>() == Option::Some(@[2, 3])); + /// let result = *(span.multi_pop_back::<2>().unwrap()); + /// let unbox_result = result.unbox(); + /// assert!(unbox_result == [2, 3]);; /// ``` fn multi_pop_back(ref self: Span) -> Option<@Box<[T; SIZE]>> { array_snapshot_multi_pop_back(ref self.snapshot) } - /// Returns 'Option::Some' of the value at the given 'index', + + /// Returns an option containing a box of a snapshot of the value at the given 'index' + /// if the span contains this index, 'Option::None' otherwise. + /// + /// # Examples /// - /// Example: /// ``` - /// let span = array![1, 2, 3].span(); - /// assert!(span.get(1) == Option::Some(@2)); + /// let span = array![2, 3, 4]; + /// assert!(span.get(1).unwrap().unbox() == @3); /// ``` #[inline] fn get(self: Span, index: usize) -> Option> { array_get(self.snapshot, index) } - /// Returns a snapshot of the value at the given 'index'. + + /// Returns a snapshot of the value at the given 'index' if the span contains this index, + /// panics with an 'Index out of bounds' error otherwise. + /// + /// # Examples /// - /// Example: /// ``` - /// let span = array![1, 2, 3].span(); - /// assert!(span.at(1) == @2); + /// let span = array![2, 3, 4].span(); + /// assert!(span.at(1) == @3); /// ``` #[inline] fn at(self: Span, index: usize) -> @T { array_at(self.snapshot, index).unbox() } + /// Returns a span containing values from the 'start' index, with /// amount equal to 'length'. /// - /// Example: + /// # Examples + /// /// ``` /// let span = array![1, 2, 3].span(); /// assert!(span.slice(1, 2) == array![2, 3].span()); @@ -372,11 +532,13 @@ pub impl SpanImpl of SpanTrait { fn slice(self: Span, start: usize, length: usize) -> Span { Span { snapshot: array_slice(self.snapshot, start, length).expect('Index out of bounds') } } - /// Returns the length of the span. + + /// Returns the length of the span as a `usize` value. + /// + /// # Examples /// - /// Example: /// ``` - /// let span = array![1, 2, 3].span(); + /// let span = array![2, 3, 4].span(); /// assert!(span.len() == 3); /// ``` #[inline] @@ -384,10 +546,14 @@ pub impl SpanImpl of SpanTrait { fn len(self: Span) -> usize { array_len(self.snapshot) } - /// Returns whether the span is empty. + + /// Returns whether the span is empty or not. + /// + /// # Examples /// - /// Example: /// ``` + /// let span: Span = array![].span(); + /// assert!(span.is_empty()); /// let span = array![1, 2, 3].span(); /// assert!(!span.is_empty()); /// ``` @@ -402,81 +568,134 @@ pub impl SpanImpl of SpanTrait { } } -/// Implementation of the `SpanIndex` trait for spans. +/// `IndexView` trait implementation to access an item contained in type `Span` with an index of type `usize`. pub impl SpanIndex of IndexView, usize, @T> { + /// Returns a snapshot of the element at the given index. + /// `IndexView` needs to be explicitly imported with `use core::ops::IndexView;` + /// + /// # Examples + /// + /// ``` + /// let span: @Span = @array![1, 2, 3].span(); + /// let element: @u8 = span.index(0); + /// ``` #[inline] fn index(self: @Span, index: usize) -> @T { array_at(*self.snapshot, index).unbox() } } -/// A Trait that, given a data structure, returns a span of the data. +/// `ToSpanTrait` is a trait that, given a data structure, returns a span of the data. pub trait ToSpanTrait { /// Returns a span pointing to the data in the input. #[must_use] fn span(self: @C) -> Span; } +/// `ToSpanTrait` implementation for `Array`. impl ArrayToSpan of ToSpanTrait, T> { + /// Returns a `Span` corresponding to a view into an `Array`. #[inline] fn span(self: @Array) -> Span { ArrayTrait::span(self) } } +/// `Into` trait implementation to convert a data structure into a span. +/// The data structure needs to implement the `ToSpanTrait` trait. impl SnapIntoSpanWhereToSpanTrait> of Into<@C, Span> { + /// Returns a `Span` corresponding to a view into the given data structure. fn into(self: @C) -> Span { self.span() } } -/// Returns a span from a box of struct of members of the same type. -/// The additional `+Copy<@T>` arg is to prevent later stages from propagating the `S` type Sierra -/// level, where it is deduced by the `T` type. extern fn span_from_tuple>( struct_like: Box<@T> ) -> @Array nopanic; +/// `ToSpanTrait` implementation for a box containing a snapshot of a fixed-size array. impl FixedSizeArrayBoxToSpan of ToSpanTrait, T> { + /// Returns a `Span` corresponding to a view into the given fixed-size array. + /// + /// # Examples + /// + /// ``` + /// let boxed_arr: Box<@[u32; 3]> = BoxTrait::new(@[1, 2, 3]); + /// let span: Span = (@boxed_arr).span(); + /// ``` fn span(self: @Box<@[T; SIZE]>) -> Span { Span { snapshot: span_from_tuple(*self) } } } +/// `ToSpanTrait` implementation for a snapshot of a fixed-size array. impl FixedSizeArrayToSpan< T, const SIZE: usize, -TypeEqual<[T; SIZE], [T; 0]> > of ToSpanTrait<[T; SIZE], T> { + /// Returns a `Span` corresponding to a view into the given fixed-size array. + /// + /// # Examples + /// + /// ``` + /// let arr: [u32; 3] = [1, 2, 3]; + /// let span: Span = (@arr).span(); + /// ``` #[inline] fn span(self: @[T; SIZE]) -> Span { BoxTrait::new(self).span() } } +/// `ToSpanTrait` implementation for a snapshot of an empty fixed-size array. impl EmptyFixedSizeArrayImpl> of ToSpanTrait<[T; 0], T> { + /// Returns a `Span` corresponding to a view into the given empty fixed-size array. + /// + /// # Examples + /// + /// ``` + /// let arr: [u32; 0] = []; + /// let span: Span = (@arr).span(); + /// ``` #[inline] fn span(self: @[T; 0]) -> Span { array![].span() } } -/// Returns a box of struct of members of the same type from a span. -/// The additional `+Copy<@T>` arg is to prevent later stages from propagating the `S` type Sierra -/// level, where it is deduced by the `T` type. extern fn tuple_from_span>( span: @Array ) -> Option<@Box> nopanic; -/// Implements `TryInto` for only copyable types +/// `TryInto` implementation from a span to fixed-size array. impl SpanTryIntoFixedSizedArray< T, const SIZE: usize, -TypeEqual<[T; SIZE], [T; 0]> > of TryInto, @Box<[T; SIZE]>> { + /// Returns an option to a snapshot of a box that contains a fixed-size array. + /// + /// # Examples + /// + /// ``` + /// let span = array![1, 2, 3].span(); + /// let result: Option<@Box<[felt252; 3]>> = span.try_into(); + /// ``` #[inline] fn try_into(self: Span) -> Option<@Box<[T; SIZE]>> { tuple_from_span(self.snapshot) } } +/// `TryInto` implementation from a span to an empty fixed-size array. impl SpanTryIntoEmptyFixedSizedArray> of TryInto, @Box<[T; 0]>> { + /// Returns an option to a snapshot of a box that contains an empty fixed-size array if the span is empty, + /// and `Option::None` otherwise. + /// + /// # Examples + /// + /// ``` + /// let span = array![].span(); + /// let result: Option<@Box<[felt252; 0]>> = span.try_into(); + /// ``` #[inline] fn try_into(self: Span) -> Option<@Box<[T; 0]>> { if self.is_empty() { @@ -488,7 +707,16 @@ impl SpanTryIntoEmptyFixedSizedArray> of TryInto, @Box<[T; 0 } // TODO(spapini): Remove TDrop. It is necessary to get rid of response in case of panic. +/// `Clone` implementation for `Array`. impl ArrayTCloneImpl, +Drop> of Clone> { + /// Returns a clone of `self`. + /// + /// # Examples + /// + /// ``` + /// let arr = array![1, 2, 3]; + /// let arr_clone = arr.clone(); + /// ``` fn clone(self: @Array) -> Array { let mut response = array_new(); let mut span = self.span(); @@ -502,13 +730,33 @@ impl ArrayTCloneImpl, +Drop> of Clone> { } } +/// `PartialEq` implementation for `Array`. impl ArrayPartialEq> of PartialEq> { + /// Returns `true` if the two arrays contain the same elements, false otherwise. + /// + /// # Examples + /// + /// ``` + /// let arr_1 = array![1, 2, 3]; + /// let arr_2 = array![1, 2, 3]; + /// assert!(PartialEq::eq(@arr_1, @arr_2) == true); + /// ``` fn eq(lhs: @Array, rhs: @Array) -> bool { lhs.span() == rhs.span() } } +/// `PartialEq` implementation for `Span`. impl SpanPartialEq> of PartialEq> { + /// Returns `true` if the two spans contain the same elements, false otherwise. + /// + /// # Examples + /// + /// ``` + /// let span_1 = array![1, 2, 3].span(); + /// let span_2 = array![1, 2, 3].span(); + /// assert!(PartialEq::eq(@span_1, @span_2) == true); + /// ``` fn eq(lhs: @Span, rhs: @Span) -> bool { if (*lhs).len() != (*rhs).len() { return false; @@ -583,6 +831,9 @@ trait FixedSizedArrayInfo { /// The size of the array. const SIZE: usize; } + +/// `FixedSizedArrayInfo` implementation for a fixed-size array of size `SIZE`, +/// containing elements of type `T`. impl FixedSizedArrayInfoImpl of FixedSizedArrayInfo<[T; SIZE]> { type Element = T; const SIZE: usize = SIZE; From 8290598e4dd28fa74c216c6520e03ace49dbcf0d Mon Sep 17 00:00:00 2001 From: TAdev0 Date: Tue, 29 Oct 2024 15:38:06 +0100 Subject: [PATCH 02/31] few additions --- corelib/src/array.cairo | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/corelib/src/array.cairo b/corelib/src/array.cairo index 88be5abe047..0a1ebd66aea 100644 --- a/corelib/src/array.cairo +++ b/corelib/src/array.cairo @@ -12,6 +12,7 @@ use crate::iter::Iterator; use crate::RangeCheck; /// A collection of elements of the same type continuous in memory. +/// `Array` derives `Drop` trait. #[derive(Drop)] pub extern type Array; @@ -300,7 +301,9 @@ pub struct Span { pub(crate) snapshot: @Array } +/// `Copy` trait implementation for `Span`. impl SpanCopy of Copy>; +/// `Drop` trait implementation for `Span`. impl SpanDrop of Drop>; /// `Into` trait implementation to convert an array into a span. @@ -781,9 +784,12 @@ pub struct SpanIter { span: Span, } +/// `Drop` trait implementation for `SpanIter` struct. impl SpanIterDrop of Drop>; +/// `Copy` trait implementation for `SpanIter` struct. impl SpanIterCopy of Copy>; +/// `Iterator` trait implementation for `SpanIter` struct. impl SpanIterator of Iterator> { type Item = @T; fn next(ref self: SpanIter) -> Option<@T> { @@ -791,6 +797,7 @@ impl SpanIterator of Iterator> { } } +/// `IntoIterator` trait implementation for `Span`. impl SpanIntoIterator of crate::iter::IntoIterator> { type IntoIter = SpanIter; fn into_iter(self: Span) -> SpanIter { @@ -804,12 +811,14 @@ pub struct ArrayIter { array: Array, } +/// `Clone` trait implementation for `ArrayIter` struct. impl ArrayIterClone, +Drop> of crate::clone::Clone> { fn clone(self: @ArrayIter) -> ArrayIter { ArrayIter { array: crate::clone::Clone::clone(self.array), } } } +/// `Iterator` trait implementation for `ArrayIter` struct. impl ArrayIterator of Iterator> { type Item = T; fn next(ref self: ArrayIter) -> Option { @@ -817,6 +826,7 @@ impl ArrayIterator of Iterator> { } } +/// `IntoIterator` trait implementation for `Array`. impl ArrayIntoIterator of crate::iter::IntoIterator> { type IntoIter = ArrayIter; fn into_iter(self: Array) -> ArrayIter { From 19e33223d511523e365a4b5d6eb78b6ac1140b47 Mon Sep 17 00:00:00 2001 From: TAdev0 Date: Tue, 29 Oct 2024 15:43:56 +0100 Subject: [PATCH 03/31] fmt --- corelib/src/array.cairo | 130 ++++++++++-------- .../src/test/language_features/for_test.cairo | 4 +- 2 files changed, 72 insertions(+), 62 deletions(-) diff --git a/corelib/src/array.cairo b/corelib/src/array.cairo index 0a1ebd66aea..26c4cf93c6f 100644 --- a/corelib/src/array.cairo +++ b/corelib/src/array.cairo @@ -41,17 +41,17 @@ extern fn array_len(arr: @Array) -> usize nopanic; #[generate_trait] pub impl ArrayImpl of ArrayTrait { /// Returns a new empty array. - /// + /// /// # Examples - /// + /// /// ``` /// let first_arr: Array = ArrayTrait::new(); /// let second_arr = ArrayTrait::::new(); /// ``` - /// - /// It is generally more straightforward to use the `array!` macro to create a new array, + /// + /// It is generally more straightforward to use the `array!` macro to create a new array, /// calling the `new` function under the hood: - /// + /// /// ``` /// let arr: Array = array![]; /// ``` @@ -73,7 +73,7 @@ pub impl ArrayImpl of ArrayTrait { fn append(ref self: Array, value: T) nopanic { array_append(ref self, value) } - + /// Adds a span to the end of the array. /// Requires that the values of the span implement `Clone` and `Drop` traits. /// @@ -122,7 +122,7 @@ pub impl ArrayImpl of ArrayTrait { /// ``` /// let arr = array![2, 3, 4]; /// assert!(arr.pop_front_consume() == Option::Some((array![3, 4], 2))); - /// + /// /// let arr: Array = array![]; /// assert!(arr.pop_front_consume() == Option::None); /// ``` @@ -196,9 +196,9 @@ pub impl ArrayImpl of ArrayTrait { } /// Returns a span of the array. - /// + /// /// # Examples - /// + /// /// ``` /// let arr: Array = array![1, 2, 3]; /// let span: Span = arr.span(); @@ -213,9 +213,9 @@ pub impl ArrayImpl of ArrayTrait { /// `Default` trait implementation to create a new empty array. impl ArrayDefault of Default> { /// Returns a new empty array. - /// + /// /// # Examples - /// + /// /// ``` /// let arr: Array = Default::default(); /// ``` @@ -225,13 +225,14 @@ impl ArrayDefault of Default> { } } -/// `IndexView` trait implementation to access an item contained in type `Array` with an index of type `usize`. +/// `IndexView` trait implementation to access an item contained in type `Array` with an index of +/// type `usize`. impl ArrayIndex of IndexView, usize, @T> { /// Returns a snapshot of the element at the given index. /// `IndexView` needs to be explicitly imported with `use core::ops::IndexView;` - /// + /// /// # Examples - /// + /// /// ``` /// let arr: @Array = @array![1, 2, 3]; /// let element: @u8 = arr.index(0); @@ -244,9 +245,9 @@ impl ArrayIndex of IndexView, usize, @T> { /// `Serde` trait implementation to serialize and deserialize an `Array`. impl ArraySerde, +Drop> of Serde> { /// Serializes an `Array` into an `Array`. - /// + /// /// # Examples - /// + /// /// ``` /// let arr: Array = array![1, 2, 3]; /// let mut output: Array = array![]; @@ -258,9 +259,9 @@ impl ArraySerde, +Drop> of Serde> { } /// Deserializes a `Span` into an `Array` and returns an option to an `Array`. - /// + /// /// # Examples - /// + /// /// ``` /// let mut span: Span = array![2, 0, 1].span(); /// let arr: Array = Serde::deserialize(ref span).unwrap(); @@ -309,9 +310,9 @@ impl SpanDrop of Drop>; /// `Into` trait implementation to convert an array into a span. impl ArrayIntoSpan> of Into, Span> { /// Takes an array and returns a span of that array. - /// + /// /// # Examples - /// + /// /// ``` /// let arr: Array = array![1, 2, 3]; /// let span: Span = arr.into(); @@ -324,9 +325,9 @@ impl ArrayIntoSpan> of Into, Span> { /// `Into` trait implementation to convert a span into an array. impl SpanIntoArray, +Clone> of Into, Array> { /// Takes a span and returns an array. - /// + /// /// # Examples - /// + /// /// ``` /// let span: Span = array![1, 2, 3].span(); /// let arr: Array = span.into(); @@ -341,9 +342,9 @@ impl SpanIntoArray, +Clone> of Into, Array> { /// `Into` trait implementation to convert a span into a snapshot of an array. impl SpanIntoArraySnap of Into, @Array> { /// Takes a span and returns a snapshot of an array. - /// + /// /// # Examples - /// + /// /// ``` /// let span: Span = array![1, 2, 3].span(); /// let arr: @Array = span.into(); @@ -356,9 +357,9 @@ impl SpanIntoArraySnap of Into, @Array> { /// `Serde` trait implementation to serialize and deserialize a `Span`. impl SpanFelt252Serde of Serde> { /// Serializes a `Span` into an `Array`. - /// + /// /// # Examples - /// + /// /// ``` /// let span: Span = array![1, 2, 3].span(); /// let mut output: Array = array![]; @@ -369,10 +370,11 @@ impl SpanFelt252Serde of Serde> { serialize_array_helper(*self, ref output) } - /// Deserializes a `Span` into an `Span` and returns an option to a `Span`. - /// + /// Deserializes a `Span` into an `Span` and returns an option to a + /// `Span`. + /// /// # Examples - /// + /// /// ``` /// let mut span: Span = array![2, 0, 1].span(); /// let result: Span = Serde::deserialize(ref span).unwrap(); @@ -390,9 +392,9 @@ impl SpanFelt252Serde of Serde> { /// `Serde` trait implementation to serialize and deserialize a `Span`. impl SpanSerde, +Drop, -TypeEqual> of Serde> { /// Serializes a `Span` into an `Array`. - /// + /// /// # Examples - /// + /// /// ``` /// let span: Span = array![1, 2, 3].span(); /// let mut output: Array = array![]; @@ -404,9 +406,9 @@ impl SpanSerde, +Drop, -TypeEqual> of Serde> } /// Deserializes a `Span` into an `Span` and returns an option to a `Span`. - /// + /// /// # Examples - /// + /// /// ``` /// let mut span: Span = array![2, 0, 1].span(); /// let result: Span = Serde::deserialize(ref span).unwrap(); @@ -427,7 +429,7 @@ pub impl SpanImpl of SpanTrait { /// Returns `Option::Some(@value)` if the array is not empty, `Option::None` otherwise. /// /// # Examples - /// + /// /// ``` /// let mut span = array![1, 2, 3].span(); /// assert!(span.pop_front() == Option::Some(@1)); @@ -463,11 +465,11 @@ pub impl SpanImpl of SpanTrait { } /// Pops multiple values from the front of the span. - /// Returns an option containing a snapshot of a box that contains the values as a fixed-size array - /// if the action completed successfully, 'Option::None' otherwise. + /// Returns an option containing a snapshot of a box that contains the values as a fixed-size + /// array if the action completed successfully, 'Option::None' otherwise. /// /// # Examples - /// + /// /// ``` /// let mut span = array![1, 2, 3].span(); /// let result = *(span.multi_pop_front::<2>().unwrap()); @@ -479,11 +481,11 @@ pub impl SpanImpl of SpanTrait { } /// Pops multiple values from the back of the span. - /// Returns an option containing a snapshot of a box that contains the values as a fixed-size array - /// if the action completed successfully, 'Option::None' otherwise. + /// Returns an option containing a snapshot of a box that contains the values as a fixed-size + /// array if the action completed successfully, 'Option::None' otherwise. /// /// # Examples - /// + /// /// ``` /// let mut span = array![1, 2, 3].span(); /// let result = *(span.multi_pop_back::<2>().unwrap()); @@ -526,7 +528,7 @@ pub impl SpanImpl of SpanTrait { /// amount equal to 'length'. /// /// # Examples - /// + /// /// ``` /// let span = array![1, 2, 3].span(); /// assert!(span.slice(1, 2) == array![2, 3].span()); @@ -571,13 +573,14 @@ pub impl SpanImpl of SpanTrait { } } -/// `IndexView` trait implementation to access an item contained in type `Span` with an index of type `usize`. +/// `IndexView` trait implementation to access an item contained in type `Span` with an index of +/// type `usize`. pub impl SpanIndex of IndexView, usize, @T> { /// Returns a snapshot of the element at the given index. /// `IndexView` needs to be explicitly imported with `use core::ops::IndexView;` - /// + /// /// # Examples - /// + /// /// ``` /// let span: @Span = @array![1, 2, 3].span(); /// let element: @u8 = span.index(0); @@ -620,9 +623,9 @@ extern fn span_from_tuple>( /// `ToSpanTrait` implementation for a box containing a snapshot of a fixed-size array. impl FixedSizeArrayBoxToSpan of ToSpanTrait, T> { /// Returns a `Span` corresponding to a view into the given fixed-size array. - /// + /// /// # Examples - /// + /// /// ``` /// let boxed_arr: Box<@[u32; 3]> = BoxTrait::new(@[1, 2, 3]); /// let span: Span = (@boxed_arr).span(); @@ -637,9 +640,9 @@ impl FixedSizeArrayToSpan< T, const SIZE: usize, -TypeEqual<[T; SIZE], [T; 0]> > of ToSpanTrait<[T; SIZE], T> { /// Returns a `Span` corresponding to a view into the given fixed-size array. - /// + /// /// # Examples - /// + /// /// ``` /// let arr: [u32; 3] = [1, 2, 3]; /// let span: Span = (@arr).span(); @@ -653,9 +656,9 @@ impl FixedSizeArrayToSpan< /// `ToSpanTrait` implementation for a snapshot of an empty fixed-size array. impl EmptyFixedSizeArrayImpl> of ToSpanTrait<[T; 0], T> { /// Returns a `Span` corresponding to a view into the given empty fixed-size array. - /// + /// /// # Examples - /// + /// /// ``` /// let arr: [u32; 0] = []; /// let span: Span = (@arr).span(); @@ -675,9 +678,9 @@ impl SpanTryIntoFixedSizedArray< T, const SIZE: usize, -TypeEqual<[T; SIZE], [T; 0]> > of TryInto, @Box<[T; SIZE]>> { /// Returns an option to a snapshot of a box that contains a fixed-size array. - /// + /// /// # Examples - /// + /// /// ``` /// let span = array![1, 2, 3].span(); /// let result: Option<@Box<[felt252; 3]>> = span.try_into(); @@ -690,11 +693,11 @@ impl SpanTryIntoFixedSizedArray< /// `TryInto` implementation from a span to an empty fixed-size array. impl SpanTryIntoEmptyFixedSizedArray> of TryInto, @Box<[T; 0]>> { - /// Returns an option to a snapshot of a box that contains an empty fixed-size array if the span is empty, - /// and `Option::None` otherwise. - /// + /// Returns an option to a snapshot of a box that contains an empty fixed-size array if the span + /// is empty, and `Option::None` otherwise. + /// /// # Examples - /// + /// /// ``` /// let span = array![].span(); /// let result: Option<@Box<[felt252; 0]>> = span.try_into(); @@ -715,7 +718,7 @@ impl ArrayTCloneImpl, +Drop> of Clone> { /// Returns a clone of `self`. /// /// # Examples - /// + /// /// ``` /// let arr = array![1, 2, 3]; /// let arr_clone = arr.clone(); @@ -736,9 +739,9 @@ impl ArrayTCloneImpl, +Drop> of Clone> { /// `PartialEq` implementation for `Array`. impl ArrayPartialEq> of PartialEq> { /// Returns `true` if the two arrays contain the same elements, false otherwise. - /// + /// /// # Examples - /// + /// /// ``` /// let arr_1 = array![1, 2, 3]; /// let arr_2 = array![1, 2, 3]; @@ -752,9 +755,9 @@ impl ArrayPartialEq> of PartialEq> { /// `PartialEq` implementation for `Span`. impl SpanPartialEq> of PartialEq> { /// Returns `true` if the two spans contain the same elements, false otherwise. - /// + /// /// # Examples - /// + /// /// ``` /// let span_1 = array![1, 2, 3].span(); /// let span_2 = array![1, 2, 3].span(); @@ -791,7 +794,9 @@ impl SpanIterCopy of Copy>; /// `Iterator` trait implementation for `SpanIter` struct. impl SpanIterator of Iterator> { + /// Type of the values contained in the span. type Item = @T; + /// Returns an option to a snapshot of a span element if it exist, and `Option::None` otherwise. fn next(ref self: SpanIter) -> Option<@T> { self.span.pop_front() } @@ -813,6 +818,7 @@ pub struct ArrayIter { /// `Clone` trait implementation for `ArrayIter` struct. impl ArrayIterClone, +Drop> of crate::clone::Clone> { + /// Returns a clone of `self`. fn clone(self: @ArrayIter) -> ArrayIter { ArrayIter { array: crate::clone::Clone::clone(self.array), } } @@ -820,7 +826,9 @@ impl ArrayIterClone, +Drop> of crate::clone::Clone /// `Iterator` trait implementation for `ArrayIter` struct. impl ArrayIterator of Iterator> { + /// Type of the values contained in the array. type Item = T; + /// Returns an option to an element of the array if it exist, and `Option::None` otherwise. fn next(ref self: ArrayIter) -> Option { self.array.pop_front() } diff --git a/corelib/src/test/language_features/for_test.cairo b/corelib/src/test/language_features/for_test.cairo index 9c29b2b7e83..95ed51cf912 100644 --- a/corelib/src/test/language_features/for_test.cairo +++ b/corelib/src/test/language_features/for_test.cairo @@ -21,7 +21,9 @@ fn test_for_loop_array_variables() { #[test] fn test_for_loop_array_tuples() { let mut i = 10; - for (x, y) in array![ + for ( + x, y + ) in array![ (10, 10), (11, 11), (12, 12), (13, 13), (14, 14), (15, 15), (16, 16), (17, 17) ] { assert_eq!(x, i); From 7689558593e621c2e2c821c98fea6bacec008f4c Mon Sep 17 00:00:00 2001 From: TAdev0 Date: Tue, 29 Oct 2024 15:48:37 +0100 Subject: [PATCH 04/31] fmt --- corelib/src/test/language_features/for_test.cairo | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/corelib/src/test/language_features/for_test.cairo b/corelib/src/test/language_features/for_test.cairo index 95ed51cf912..9c29b2b7e83 100644 --- a/corelib/src/test/language_features/for_test.cairo +++ b/corelib/src/test/language_features/for_test.cairo @@ -21,9 +21,7 @@ fn test_for_loop_array_variables() { #[test] fn test_for_loop_array_tuples() { let mut i = 10; - for ( - x, y - ) in array![ + for (x, y) in array![ (10, 10), (11, 11), (12, 12), (13, 13), (14, 14), (15, 15), (16, 16), (17, 17) ] { assert_eq!(x, i); From f0d1476a83de15d2615460ddb834a42ad4813f99 Mon Sep 17 00:00:00 2001 From: TAdev0 Date: Tue, 29 Oct 2024 15:50:38 +0100 Subject: [PATCH 05/31] last comment --- corelib/src/array.cairo | 2 ++ 1 file changed, 2 insertions(+) diff --git a/corelib/src/array.cairo b/corelib/src/array.cairo index 26c4cf93c6f..cea00665b55 100644 --- a/corelib/src/array.cairo +++ b/corelib/src/array.cairo @@ -805,6 +805,7 @@ impl SpanIterator of Iterator> { /// `IntoIterator` trait implementation for `Span`. impl SpanIntoIterator of crate::iter::IntoIterator> { type IntoIter = SpanIter; + /// Returns a `SpanIter` given a `Span`. fn into_iter(self: Span) -> SpanIter { SpanIter { span: self } } @@ -837,6 +838,7 @@ impl ArrayIterator of Iterator> { /// `IntoIterator` trait implementation for `Array`. impl ArrayIntoIterator of crate::iter::IntoIterator> { type IntoIter = ArrayIter; + /// Returns an `ArrayIter` given a `Array`. fn into_iter(self: Array) -> ArrayIter { ArrayIter { array: self } } From 1d5cf98146c519da2f50bb6da705dd9c5d7362b1 Mon Sep 17 00:00:00 2001 From: TAdev0 Date: Tue, 29 Oct 2024 16:14:46 +0100 Subject: [PATCH 06/31] fmt --- corelib/Scarb.lock | 2 +- corelib/src/array.cairo | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/corelib/Scarb.lock b/corelib/Scarb.lock index 5f847949a63..1d9308814a8 100644 --- a/corelib/Scarb.lock +++ b/corelib/Scarb.lock @@ -3,4 +3,4 @@ version = 1 [[package]] name = "core" -version = "2.6.3" +version = "2.8.4" diff --git a/corelib/src/array.cairo b/corelib/src/array.cairo index cea00665b55..8bb0dc53582 100644 --- a/corelib/src/array.cairo +++ b/corelib/src/array.cairo @@ -829,7 +829,7 @@ impl ArrayIterClone, +Drop> of crate::clone::Clone impl ArrayIterator of Iterator> { /// Type of the values contained in the array. type Item = T; - /// Returns an option to an element of the array if it exist, and `Option::None` otherwise. + /// Returns an option to an element of the array if it exists, and `Option::None` otherwise. fn next(ref self: ArrayIter) -> Option { self.array.pop_front() } @@ -838,7 +838,7 @@ impl ArrayIterator of Iterator> { /// `IntoIterator` trait implementation for `Array`. impl ArrayIntoIterator of crate::iter::IntoIterator> { type IntoIter = ArrayIter; - /// Returns an `ArrayIter` given a `Array`. + /// Returns an `ArrayIter` given an `Array`. fn into_iter(self: Array) -> ArrayIter { ArrayIter { array: self } } From 1095bd3ebfb901182ca459470535d62596cc0893 Mon Sep 17 00:00:00 2001 From: TAdev0 Date: Tue, 29 Oct 2024 18:57:36 +0100 Subject: [PATCH 07/31] fmt --- corelib/src/array.cairo | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/corelib/src/array.cairo b/corelib/src/array.cairo index 8bb0dc53582..c74f8b90587 100644 --- a/corelib/src/array.cairo +++ b/corelib/src/array.cairo @@ -473,8 +473,8 @@ pub impl SpanImpl of SpanTrait { /// ``` /// let mut span = array![1, 2, 3].span(); /// let result = *(span.multi_pop_front::<2>().unwrap()); - /// let unbox_result = result.unbox(); - /// assert!(unbox_result == [1, 2]); + /// let unboxed_result = result.unbox(); + /// assert!(unboxed_result == [1, 2]); /// ``` fn multi_pop_front(ref self: Span) -> Option<@Box<[T; SIZE]>> { array_snapshot_multi_pop_front(ref self.snapshot) @@ -489,8 +489,8 @@ pub impl SpanImpl of SpanTrait { /// ``` /// let mut span = array![1, 2, 3].span(); /// let result = *(span.multi_pop_back::<2>().unwrap()); - /// let unbox_result = result.unbox(); - /// assert!(unbox_result == [2, 3]);; + /// let unboxed_result = result.unbox(); + /// assert!(unboxed_result == [2, 3]);; /// ``` fn multi_pop_back(ref self: Span) -> Option<@Box<[T; SIZE]>> { array_snapshot_multi_pop_back(ref self.snapshot) From 3c0db71c3758cbd6e4b31d8d73b6204499157400 Mon Sep 17 00:00:00 2001 From: Tristan <122918260+TAdev0@users.noreply.github.com> Date: Wed, 30 Oct 2024 11:15:52 +0100 Subject: [PATCH 08/31] Update corelib/src/array.cairo Co-authored-by: Mathieu <60658558+enitrat@users.noreply.github.com> --- corelib/src/array.cairo | 1 - 1 file changed, 1 deletion(-) diff --git a/corelib/src/array.cairo b/corelib/src/array.cairo index c74f8b90587..1f6f5307816 100644 --- a/corelib/src/array.cairo +++ b/corelib/src/array.cairo @@ -12,7 +12,6 @@ use crate::iter::Iterator; use crate::RangeCheck; /// A collection of elements of the same type continuous in memory. -/// `Array` derives `Drop` trait. #[derive(Drop)] pub extern type Array; From 978fceb5cc2d942ab02726646f9839c40d1c4b2e Mon Sep 17 00:00:00 2001 From: Tristan <122918260+TAdev0@users.noreply.github.com> Date: Wed, 30 Oct 2024 11:42:30 +0100 Subject: [PATCH 09/31] Update corelib/src/array.cairo Co-authored-by: Mathieu <60658558+enitrat@users.noreply.github.com> --- corelib/src/array.cairo | 1 - 1 file changed, 1 deletion(-) diff --git a/corelib/src/array.cairo b/corelib/src/array.cairo index 1f6f5307816..0b080353a67 100644 --- a/corelib/src/array.cairo +++ b/corelib/src/array.cairo @@ -74,7 +74,6 @@ pub impl ArrayImpl of ArrayTrait { } /// Adds a span to the end of the array. - /// Requires that the values of the span implement `Clone` and `Drop` traits. /// /// # Examples /// From 010ca59eff985aaaeb8965bf6605de09b5eb23d4 Mon Sep 17 00:00:00 2001 From: TAdev0 Date: Wed, 30 Oct 2024 11:42:52 +0100 Subject: [PATCH 10/31] update --- corelib/src/array.cairo | 84 ++++++++++++++++++++++++++++++++++++----- 1 file changed, 74 insertions(+), 10 deletions(-) diff --git a/corelib/src/array.cairo b/corelib/src/array.cairo index 1f6f5307816..b61d3d2d875 100644 --- a/corelib/src/array.cairo +++ b/corelib/src/array.cairo @@ -1,3 +1,66 @@ +//! A contiguous collection of elements of the same type in memory, written +//! `Array`. +//! +//! Arrays have *O*(1) indexing, *O*(1) push and *O*(1) pop +//! (from the front). +//! +//! Arrays can only be mutated by appending to the end or popping from the front. +//! +//! # Examples +//! +//! You can explicitly create an [`Array`] with [`ArrayTrait::new`]: +//! +//! ``` +//! let arr: Array = ArrayTrait::new(); +//! ``` +//! +//! ...or by using the `array!` macro: +//! +//! ``` +//! let arr: Array = array![]; +//! +//! let arr: Array = array![1, 2, 3, 4, 5]; +//! ``` +//! +//! You can [`append`] values onto the end of an array: +//! +//! ``` +//! let mut arr = array![1, 2]; +//! arr.append(3); +//! ``` +//! +//! Popping values from the front works like this: +//! +//! ``` +//! let mut arr = array![1, 2]; +//! let one = arr.pop_front(); // Returns Option::Some(1) +//! ``` +//! +//! Arrays support indexing (through the [`IndexView`] trait): +//! +//! ``` +//! let arr = array![1, 2, 3]; +//! let three = arr[2]; // Returns a snapshot (@T) +//! ``` +//! +//! Arrays can be converted to [`Span`]s for read-only access: +//! +//! ``` +//! let arr = array![1, 2, 3]; +//! let span = arr.span(); +//! ``` +//! +//! A span can be manipulated without affecting the original array: +//! +//! ``` +//! let mut arr = array![1, 2, 3]; +//! let mut span = arr.span(); +//! span.pop_back(); +//! assert!(arr == array![1, 2, 3]); +//! ``` +//! +//! [`append`]: ArrayTrait::append + #[feature("deprecated-index-traits")] use crate::traits::IndexView; @@ -39,17 +102,17 @@ extern fn array_len(arr: @Array) -> usize nopanic; /// Basic trait for the `Array` type. #[generate_trait] pub impl ArrayImpl of ArrayTrait { - /// Returns a new empty array. + /// Constructs a new, empty `Array`. /// /// # Examples /// /// ``` - /// let first_arr: Array = ArrayTrait::new(); - /// let second_arr = ArrayTrait::::new(); + /// let arr: Array = ArrayTrait::new(); + /// + /// let arr = ArrayTrait::::new(); /// ``` /// - /// It is generally more straightforward to use the `array!` macro to create a new array, - /// calling the `new` function under the hood: + /// It is also possible to use the `array!` macro to create a new array. /// /// ``` /// let arr: Array = array![]; @@ -64,9 +127,9 @@ pub impl ArrayImpl of ArrayTrait { /// # Examples /// /// ``` - /// let mut arr: Array = array![]; - /// arr.append(1); - /// arr.append(2); + /// let mut arr: Array = array![1, 2]; + /// arr.append(3); + /// assert!(arr == array![1, 2, 3]); /// ``` #[inline] fn append(ref self: Array, value: T) nopanic { @@ -79,8 +142,9 @@ pub impl ArrayImpl of ArrayTrait { /// # Examples /// /// ``` - /// let mut arr: Array = array![]; - /// arr.append_span(array![3, 4, 5].span()); + /// let mut arr: Array = array![]; + /// arr.append_span(array![1, 2, 3].span()); + /// assert!(arr == array![1, 2, 3]); /// ``` fn append_span<+Clone, +Drop>(ref self: Array, mut span: Span) { match span.pop_front() { From 5e6d5b9623c2919317bc6ee59254a39c2527fc20 Mon Sep 17 00:00:00 2001 From: TAdev0 Date: Wed, 30 Oct 2024 12:34:57 +0100 Subject: [PATCH 11/31] address comments --- corelib/src/array.cairo | 93 +++++++++++++++++++++++------------------ 1 file changed, 53 insertions(+), 40 deletions(-) diff --git a/corelib/src/array.cairo b/corelib/src/array.cairo index 4f93d425036..86e2a9a690c 100644 --- a/corelib/src/array.cairo +++ b/corelib/src/array.cairo @@ -108,7 +108,7 @@ pub impl ArrayImpl of ArrayTrait { /// /// ``` /// let arr: Array = ArrayTrait::new(); - /// + /// /// let arr = ArrayTrait::::new(); /// ``` /// @@ -165,7 +165,7 @@ pub impl ArrayImpl of ArrayTrait { /// assert!(arr.pop_front() == Option::Some(2)); /// assert!(arr.pop_front() == Option::Some(3)); /// assert!(arr.pop_front() == Option::Some(4)); - /// assert!(arr.pop_front() == Option::None); + /// assert!(arr.pop_front().is_none()); /// ``` #[inline] fn pop_front(ref self: Array) -> Option nopanic { @@ -185,8 +185,8 @@ pub impl ArrayImpl of ArrayTrait { /// let arr = array![2, 3, 4]; /// assert!(arr.pop_front_consume() == Option::Some((array![3, 4], 2))); /// - /// let arr: Array = array![]; - /// assert!(arr.pop_front_consume() == Option::None); + /// let arr: Array = array![]; + /// assert!(arr.pop_front_consume().is_none()); /// ``` #[inline] fn pop_front_consume(self: Array) -> Option<(Array, T)> nopanic { @@ -196,9 +196,11 @@ pub impl ArrayImpl of ArrayTrait { } } - /// Returns an option containing a box of a snapshot of the value at the given 'index' + /// Returns an option containing a box of a snapshot of the element at the given 'index' /// if the array contains this index, 'Option::None' otherwise. /// + /// Element at index 0 is the front of the array. + /// /// # Examples /// /// ``` @@ -210,14 +212,19 @@ pub impl ArrayImpl of ArrayTrait { array_get(self, index) } - /// Returns a snapshot of the value at the given 'index' if the array contains this index, - /// panics with an 'Index out of bounds' error otherwise. + /// Returns a snapshot of the element at the given index. + /// + /// Element at index 0 is the front of the array. + /// + /// # Panics + /// + /// Panics if the index is out of bounds. /// /// # Examples /// /// ``` - /// let arr = array![2, 3, 4]; - /// assert!(arr.at(1) == @3); + /// let mut arr: Array = array![3,4,5,6]; + /// assert!(arr.at(1) == @4); /// ``` fn at(self: @Array, index: usize) -> @T { array_at(self, index).unbox() @@ -298,6 +305,7 @@ impl ArrayIndex of IndexView, usize, @T> { /// ``` /// let arr: @Array = @array![1, 2, 3]; /// let element: @u8 = arr.index(0); + /// assert!(element == @1) /// ``` fn index(self: @Array, index: usize) -> @T { array_at(self, index).unbox() @@ -314,21 +322,21 @@ impl ArraySerde, +Drop> of Serde> { /// let arr: Array = array![1, 2, 3]; /// let mut output: Array = array![]; /// arr.serialize(ref output); + /// assert!(output == array![3, 1, 2, 3]) /// ``` fn serialize(self: @Array, ref output: Array) { self.len().serialize(ref output); serialize_array_helper(self.span(), ref output); } - /// Deserializes a `Span` into an `Array` and returns an option to an `Array`. + /// Deserializes a `Span` into an `Array` and returns an option of an `Array`. /// /// # Examples /// /// ``` /// let mut span: Span = array![2, 0, 1].span(); /// let arr: Array = Serde::deserialize(ref span).unwrap(); - /// assert!(*arr.at(0) == 0); - /// assert!(*arr.at(1) == 1); + /// assert!(arr == array![0, 1]); /// ``` fn deserialize(ref serialized: Span) -> Option> { let length = *serialized.pop_front()?; @@ -369,7 +377,6 @@ impl SpanCopy of Copy>; /// `Drop` trait implementation for `Span`. impl SpanDrop of Drop>; -/// `Into` trait implementation to convert an array into a span. impl ArrayIntoSpan> of Into, Span> { /// Takes an array and returns a span of that array. /// @@ -384,15 +391,19 @@ impl ArrayIntoSpan> of Into, Span> { } } -/// `Into` trait implementation to convert a span into an array. + impl SpanIntoArray, +Clone> of Into, Array> { - /// Takes a span and returns an array. + /// Turns a span into an array. + /// + /// This needs to allocate a new memory segment for the returned array, and *O*(*n*) operations + /// to populate the array with the content of the span. /// /// # Examples /// /// ``` - /// let span: Span = array![1, 2, 3].span(); - /// let arr: Array = span.into(); + /// let input: Span = array![1, 2, 3].span(); + /// let output: Array = input.into(); + /// assert!(input == output.span()); /// ``` fn into(self: Span) -> Array { let mut arr = array![]; @@ -401,7 +412,6 @@ impl SpanIntoArray, +Clone> of Into, Array> { } } -/// `Into` trait implementation to convert a span into a snapshot of an array. impl SpanIntoArraySnap of Into, @Array> { /// Takes a span and returns a snapshot of an array. /// @@ -426,13 +436,14 @@ impl SpanFelt252Serde of Serde> { /// let span: Span = array![1, 2, 3].span(); /// let mut output: Array = array![]; /// arr.serialize(ref output); + /// assert!(output == array![3, 1, 2, 3].span()); /// ``` fn serialize(self: @Span, ref output: Array) { (*self).len().serialize(ref output); serialize_array_helper(*self, ref output) } - /// Deserializes a `Span` into an `Span` and returns an option to a + /// Deserializes a `Span` into an `Span` and returns an option of a /// `Span`. /// /// # Examples @@ -440,8 +451,7 @@ impl SpanFelt252Serde of Serde> { /// ``` /// let mut span: Span = array![2, 0, 1].span(); /// let result: Span = Serde::deserialize(ref span).unwrap(); - /// assert!(*result.at(0) == 0); - /// assert!(*result.at(1) == 1); + /// assert!(result == array![0, 1]); /// ``` fn deserialize(ref serialized: Span) -> Option> { let length: u32 = (*serialized.pop_front()?).try_into()?; @@ -461,21 +471,21 @@ impl SpanSerde, +Drop, -TypeEqual> of Serde> /// let span: Span = array![1, 2, 3].span(); /// let mut output: Array = array![]; /// arr.serialize(ref output); + /// assert!(output == array![3, 1, 2, 3].span()); /// ``` fn serialize(self: @Span, ref output: Array) { (*self).len().serialize(ref output); serialize_array_helper(*self, ref output) } - /// Deserializes a `Span` into an `Span` and returns an option to a `Span`. + /// Deserializes a `Span` into an `Span` and returns an option of a `Span`. /// /// # Examples /// /// ``` /// let mut span: Span = array![2, 0, 1].span(); /// let result: Span = Serde::deserialize(ref span).unwrap(); - /// assert!(*result.at(0) == 0); - /// assert!(*result.at(1) == 1); + /// assert!(result == array![0, 1].span()); /// ``` fn deserialize(ref serialized: Span) -> Option> { let length = *serialized.pop_front()?; @@ -558,9 +568,11 @@ pub impl SpanImpl of SpanTrait { array_snapshot_multi_pop_back(ref self.snapshot) } - /// Returns an option containing a box of a snapshot of the value at the given 'index' + /// Returns an option containing a box of a snapshot of the element at the given 'index' /// if the span contains this index, 'Option::None' otherwise. /// + /// Element at index 0 is the front of the array. + /// /// # Examples /// /// ``` @@ -572,8 +584,13 @@ pub impl SpanImpl of SpanTrait { array_get(self.snapshot, index) } - /// Returns a snapshot of the value at the given 'index' if the span contains this index, - /// panics with an 'Index out of bounds' error otherwise. + /// Returns a snapshot of the element at the given index. + /// + /// Element at index 0 is the front of the array. + /// + /// # Panics + /// + /// Panics if the index is out of bounds. /// /// # Examples /// @@ -646,6 +663,7 @@ pub impl SpanIndex of IndexView, usize, @T> { /// ``` /// let span: @Span = @array![1, 2, 3].span(); /// let element: @u8 = span.index(0); + /// assert!(element == @1); /// ``` #[inline] fn index(self: @Span, index: usize) -> @T { @@ -669,8 +687,6 @@ impl ArrayToSpan of ToSpanTrait, T> { } } -/// `Into` trait implementation to convert a data structure into a span. -/// The data structure needs to implement the `ToSpanTrait` trait. impl SnapIntoSpanWhereToSpanTrait> of Into<@C, Span> { /// Returns a `Span` corresponding to a view into the given data structure. fn into(self: @C) -> Span { @@ -739,7 +755,7 @@ extern fn tuple_from_span>( impl SpanTryIntoFixedSizedArray< T, const SIZE: usize, -TypeEqual<[T; SIZE], [T; 0]> > of TryInto, @Box<[T; SIZE]>> { - /// Returns an option to a snapshot of a box that contains a fixed-size array. + /// Returns an option of a snapshot of a box that contains a fixed-size array. /// /// # Examples /// @@ -755,7 +771,7 @@ impl SpanTryIntoFixedSizedArray< /// `TryInto` implementation from a span to an empty fixed-size array. impl SpanTryIntoEmptyFixedSizedArray> of TryInto, @Box<[T; 0]>> { - /// Returns an option to a snapshot of a box that contains an empty fixed-size array if the span + /// Returns an option of a snapshot of a box that contains an empty fixed-size array if the span /// is empty, and `Option::None` otherwise. /// /// # Examples @@ -775,7 +791,6 @@ impl SpanTryIntoEmptyFixedSizedArray> of TryInto, @Box<[T; 0 } // TODO(spapini): Remove TDrop. It is necessary to get rid of response in case of panic. -/// `Clone` implementation for `Array`. impl ArrayTCloneImpl, +Drop> of Clone> { /// Returns a clone of `self`. /// @@ -798,7 +813,6 @@ impl ArrayTCloneImpl, +Drop> of Clone> { } } -/// `PartialEq` implementation for `Array`. impl ArrayPartialEq> of PartialEq> { /// Returns `true` if the two arrays contain the same elements, false otherwise. /// @@ -807,14 +821,13 @@ impl ArrayPartialEq> of PartialEq> { /// ``` /// let arr_1 = array![1, 2, 3]; /// let arr_2 = array![1, 2, 3]; - /// assert!(PartialEq::eq(@arr_1, @arr_2) == true); + /// assert!(PartialEq::eq(@arr_1, @arr_2)); /// ``` fn eq(lhs: @Array, rhs: @Array) -> bool { lhs.span() == rhs.span() } } -/// `PartialEq` implementation for `Span`. impl SpanPartialEq> of PartialEq> { /// Returns `true` if the two spans contain the same elements, false otherwise. /// @@ -823,7 +836,7 @@ impl SpanPartialEq> of PartialEq> { /// ``` /// let span_1 = array![1, 2, 3].span(); /// let span_2 = array![1, 2, 3].span(); - /// assert!(PartialEq::eq(@span_1, @span_2) == true); + /// assert!(PartialEq::eq(@span_1, @span_2)); /// ``` fn eq(lhs: @Span, rhs: @Span) -> bool { if (*lhs).len() != (*rhs).len() { @@ -856,9 +869,9 @@ impl SpanIterCopy of Copy>; /// `Iterator` trait implementation for `SpanIter` struct. impl SpanIterator of Iterator> { - /// Type of the values contained in the span. + /// Type of the elements contained in the span. type Item = @T; - /// Returns an option to a snapshot of a span element if it exist, and `Option::None` otherwise. + /// Returns an option of a snapshot of a span element if it exist, and `Option::None` otherwise. fn next(ref self: SpanIter) -> Option<@T> { self.span.pop_front() } @@ -889,9 +902,9 @@ impl ArrayIterClone, +Drop> of crate::clone::Clone /// `Iterator` trait implementation for `ArrayIter` struct. impl ArrayIterator of Iterator> { - /// Type of the values contained in the array. + /// Type of the elements contained in the array. type Item = T; - /// Returns an option to an element of the array if it exists, and `Option::None` otherwise. + /// Returns an option of an element of the array if it exists, and `Option::None` otherwise. fn next(ref self: ArrayIter) -> Option { self.array.pop_front() } From a4281db8d503bd24273d8ed6e47f39b556681f04 Mon Sep 17 00:00:00 2001 From: Tristan <122918260+TAdev0@users.noreply.github.com> Date: Mon, 4 Nov 2024 14:58:19 +0100 Subject: [PATCH 12/31] Update corelib/src/array.cairo Co-authored-by: Mathieu <60658558+enitrat@users.noreply.github.com> --- corelib/src/array.cairo | 1 - 1 file changed, 1 deletion(-) diff --git a/corelib/src/array.cairo b/corelib/src/array.cairo index 86e2a9a690c..391d4cb9af2 100644 --- a/corelib/src/array.cairo +++ b/corelib/src/array.cairo @@ -279,7 +279,6 @@ pub impl ArrayImpl of ArrayTrait { } } -/// `Default` trait implementation to create a new empty array. impl ArrayDefault of Default> { /// Returns a new empty array. /// From b66125206ec57dd4ee5fd7664d387a5175aeb29b Mon Sep 17 00:00:00 2001 From: Tristan <122918260+TAdev0@users.noreply.github.com> Date: Mon, 4 Nov 2024 14:58:39 +0100 Subject: [PATCH 13/31] Update corelib/src/array.cairo Co-authored-by: Mathieu <60658558+enitrat@users.noreply.github.com> --- corelib/src/array.cairo | 5 ----- 1 file changed, 5 deletions(-) diff --git a/corelib/src/array.cairo b/corelib/src/array.cairo index 391d4cb9af2..d11c0293ea0 100644 --- a/corelib/src/array.cairo +++ b/corelib/src/array.cairo @@ -282,11 +282,6 @@ pub impl ArrayImpl of ArrayTrait { impl ArrayDefault of Default> { /// Returns a new empty array. /// - /// # Examples - /// - /// ``` - /// let arr: Array = Default::default(); - /// ``` #[inline] fn default() -> Array { ArrayTrait::new() From 491a36e723fe7827da0818b41bc45c2e04ef0d9f Mon Sep 17 00:00:00 2001 From: Tristan <122918260+TAdev0@users.noreply.github.com> Date: Mon, 4 Nov 2024 14:58:51 +0100 Subject: [PATCH 14/31] Update corelib/src/array.cairo Co-authored-by: Mathieu <60658558+enitrat@users.noreply.github.com> --- corelib/src/array.cairo | 1 - 1 file changed, 1 deletion(-) diff --git a/corelib/src/array.cairo b/corelib/src/array.cairo index d11c0293ea0..4ffff702e8b 100644 --- a/corelib/src/array.cairo +++ b/corelib/src/array.cairo @@ -366,7 +366,6 @@ pub struct Span { pub(crate) snapshot: @Array } -/// `Copy` trait implementation for `Span`. impl SpanCopy of Copy>; /// `Drop` trait implementation for `Span`. impl SpanDrop of Drop>; From 0cb37c05a3725bc9c14d6cc2f96d7208465ef70c Mon Sep 17 00:00:00 2001 From: Tristan <122918260+TAdev0@users.noreply.github.com> Date: Mon, 4 Nov 2024 14:59:00 +0100 Subject: [PATCH 15/31] Update corelib/src/array.cairo Co-authored-by: Mathieu <60658558+enitrat@users.noreply.github.com> --- corelib/src/array.cairo | 1 - 1 file changed, 1 deletion(-) diff --git a/corelib/src/array.cairo b/corelib/src/array.cairo index 4ffff702e8b..8b88f1611a6 100644 --- a/corelib/src/array.cairo +++ b/corelib/src/array.cairo @@ -895,7 +895,6 @@ impl ArrayIterClone, +Drop> of crate::clone::Clone /// `Iterator` trait implementation for `ArrayIter` struct. impl ArrayIterator of Iterator> { - /// Type of the elements contained in the array. type Item = T; /// Returns an option of an element of the array if it exists, and `Option::None` otherwise. fn next(ref self: ArrayIter) -> Option { From 4ab4395cb0a5fc3df50d1411e55b3477febcca85 Mon Sep 17 00:00:00 2001 From: Tristan <122918260+TAdev0@users.noreply.github.com> Date: Mon, 4 Nov 2024 14:59:07 +0100 Subject: [PATCH 16/31] Update corelib/src/array.cairo Co-authored-by: Mathieu <60658558+enitrat@users.noreply.github.com> --- corelib/src/array.cairo | 1 - 1 file changed, 1 deletion(-) diff --git a/corelib/src/array.cairo b/corelib/src/array.cairo index 8b88f1611a6..96c6fe48705 100644 --- a/corelib/src/array.cairo +++ b/corelib/src/array.cairo @@ -896,7 +896,6 @@ impl ArrayIterClone, +Drop> of crate::clone::Clone /// `Iterator` trait implementation for `ArrayIter` struct. impl ArrayIterator of Iterator> { type Item = T; - /// Returns an option of an element of the array if it exists, and `Option::None` otherwise. fn next(ref self: ArrayIter) -> Option { self.array.pop_front() } From d93073dd3f925b5c9186bf88da1473df7c8f8129 Mon Sep 17 00:00:00 2001 From: Tristan <122918260+TAdev0@users.noreply.github.com> Date: Mon, 4 Nov 2024 14:59:13 +0100 Subject: [PATCH 17/31] Update corelib/src/array.cairo Co-authored-by: Mathieu <60658558+enitrat@users.noreply.github.com> --- corelib/src/array.cairo | 1 - 1 file changed, 1 deletion(-) diff --git a/corelib/src/array.cairo b/corelib/src/array.cairo index 96c6fe48705..c13001196ae 100644 --- a/corelib/src/array.cairo +++ b/corelib/src/array.cairo @@ -901,7 +901,6 @@ impl ArrayIterator of Iterator> { } } -/// `IntoIterator` trait implementation for `Array`. impl ArrayIntoIterator of crate::iter::IntoIterator> { type IntoIter = ArrayIter; /// Returns an `ArrayIter` given an `Array`. From 8ca07d1d90359679765151e371a1a20e5c425685 Mon Sep 17 00:00:00 2001 From: Tristan <122918260+TAdev0@users.noreply.github.com> Date: Mon, 4 Nov 2024 14:59:19 +0100 Subject: [PATCH 18/31] Update corelib/src/array.cairo Co-authored-by: Mathieu <60658558+enitrat@users.noreply.github.com> --- corelib/src/array.cairo | 1 - 1 file changed, 1 deletion(-) diff --git a/corelib/src/array.cairo b/corelib/src/array.cairo index c13001196ae..39d57117458 100644 --- a/corelib/src/array.cairo +++ b/corelib/src/array.cairo @@ -903,7 +903,6 @@ impl ArrayIterator of Iterator> { impl ArrayIntoIterator of crate::iter::IntoIterator> { type IntoIter = ArrayIter; - /// Returns an `ArrayIter` given an `Array`. fn into_iter(self: Array) -> ArrayIter { ArrayIter { array: self } } From 7d58c658d342d78db5fb9021329671a70b8893dc Mon Sep 17 00:00:00 2001 From: Tristan <122918260+TAdev0@users.noreply.github.com> Date: Mon, 4 Nov 2024 14:59:32 +0100 Subject: [PATCH 19/31] Update corelib/src/array.cairo Co-authored-by: Mathieu <60658558+enitrat@users.noreply.github.com> --- corelib/src/array.cairo | 2 -- 1 file changed, 2 deletions(-) diff --git a/corelib/src/array.cairo b/corelib/src/array.cairo index 39d57117458..17000483500 100644 --- a/corelib/src/array.cairo +++ b/corelib/src/array.cairo @@ -916,8 +916,6 @@ trait FixedSizedArrayInfo { const SIZE: usize; } -/// `FixedSizedArrayInfo` implementation for a fixed-size array of size `SIZE`, -/// containing elements of type `T`. impl FixedSizedArrayInfoImpl of FixedSizedArrayInfo<[T; SIZE]> { type Element = T; const SIZE: usize = SIZE; From a56c76613721fc18c949ce511d07d80e591601b6 Mon Sep 17 00:00:00 2001 From: TAdev0 Date: Mon, 4 Nov 2024 15:41:57 +0100 Subject: [PATCH 20/31] typo --- crates/cairo-lang-lowering/src/optimizations/cancel_ops.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/cairo-lang-lowering/src/optimizations/cancel_ops.rs b/crates/cairo-lang-lowering/src/optimizations/cancel_ops.rs index 269ba0a7bd0..eb0ae178546 100644 --- a/crates/cairo-lang-lowering/src/optimizations/cancel_ops.rs +++ b/crates/cairo-lang-lowering/src/optimizations/cancel_ops.rs @@ -58,7 +58,7 @@ pub struct CancelOpsContext<'a> { lowered: &'a FlatLowered, /// Maps a variable to the use sites of that variable. - /// Note that a remapping is cosidered as usage here. + /// Note that a remapping is considered as usage here. use_sites: UnorderedHashMap>, /// Maps a variable to the variable that it was renamed to. From 5cfdcdf9356a88728eb3fee131fac1cf3283b122 Mon Sep 17 00:00:00 2001 From: TAdev0 Date: Mon, 4 Nov 2024 18:59:17 +0100 Subject: [PATCH 21/31] address comments --- corelib/src/array.cairo | 70 ++++++++--------------------------------- 1 file changed, 13 insertions(+), 57 deletions(-) diff --git a/corelib/src/array.cairo b/corelib/src/array.cairo index 17000483500..88d79fe030b 100644 --- a/corelib/src/array.cairo +++ b/corelib/src/array.cairo @@ -292,14 +292,18 @@ impl ArrayDefault of Default> { /// type `usize`. impl ArrayIndex of IndexView, usize, @T> { /// Returns a snapshot of the element at the given index. - /// `IndexView` needs to be explicitly imported with `use core::ops::IndexView;` + /// `IndexView` needs to be explicitly imported with `use core::ops::IndexView;` to use the + /// `index` function The explicit import is not required when using the subscripting operator. /// /// # Examples /// /// ``` /// let arr: @Array = @array![1, 2, 3]; /// let element: @u8 = arr.index(0); - /// assert!(element == @1) + /// assert!(element == @1); + /// + /// let element: @u8 = arr[0]; + /// assert!(element == @1); /// ``` fn index(self: @Array, index: usize) -> @T { array_at(self, index).unbox() @@ -367,7 +371,6 @@ pub struct Span { } impl SpanCopy of Copy>; -/// `Drop` trait implementation for `Span`. impl SpanDrop of Drop>; impl ArrayIntoSpan> of Into, Span> { @@ -406,20 +409,11 @@ impl SpanIntoArray, +Clone> of Into, Array> { } impl SpanIntoArraySnap of Into, @Array> { - /// Takes a span and returns a snapshot of an array. - /// - /// # Examples - /// - /// ``` - /// let span: Span = array![1, 2, 3].span(); - /// let arr: @Array = span.into(); - /// ``` fn into(self: Span) -> @Array { self.snapshot } } -/// `Serde` trait implementation to serialize and deserialize a `Span`. impl SpanFelt252Serde of Serde> { /// Serializes a `Span` into an `Array`. /// @@ -454,7 +448,6 @@ impl SpanFelt252Serde of Serde> { } } -/// `Serde` trait implementation to serialize and deserialize a `Span`. impl SpanSerde, +Drop, -TypeEqual> of Serde> { /// Serializes a `Span` into an `Array`. /// @@ -645,8 +638,6 @@ pub impl SpanImpl of SpanTrait { } } -/// `IndexView` trait implementation to access an item contained in type `Span` with an index of -/// type `usize`. pub impl SpanIndex of IndexView, usize, @T> { /// Returns a snapshot of the element at the given index. /// `IndexView` needs to be explicitly imported with `use core::ops::IndexView;` @@ -664,14 +655,13 @@ pub impl SpanIndex of IndexView, usize, @T> { } } -/// `ToSpanTrait` is a trait that, given a data structure, returns a span of the data. +/// `ToSpanTrait` converts a data structure into a span of its data. pub trait ToSpanTrait { /// Returns a span pointing to the data in the input. #[must_use] fn span(self: @C) -> Span; } -/// `ToSpanTrait` implementation for `Array`. impl ArrayToSpan of ToSpanTrait, T> { /// Returns a `Span` corresponding to a view into an `Array`. #[inline] @@ -691,7 +681,6 @@ extern fn span_from_tuple>( struct_like: Box<@T> ) -> @Array nopanic; -/// `ToSpanTrait` implementation for a box containing a snapshot of a fixed-size array. impl FixedSizeArrayBoxToSpan of ToSpanTrait, T> { /// Returns a `Span` corresponding to a view into the given fixed-size array. /// @@ -706,7 +695,6 @@ impl FixedSizeArrayBoxToSpan of ToSpanTrait > of ToSpanTrait<[T; SIZE], T> { @@ -716,7 +704,7 @@ impl FixedSizeArrayToSpan< /// /// ``` /// let arr: [u32; 3] = [1, 2, 3]; - /// let span: Span = (@arr).span(); + /// let span = arr.span() /// ``` #[inline] fn span(self: @[T; SIZE]) -> Span { @@ -732,7 +720,7 @@ impl EmptyFixedSizeArrayImpl> of ToSpanTrait<[T; 0], T> { /// /// ``` /// let arr: [u32; 0] = []; - /// let span: Span = (@arr).span(); + /// let span = arr.span(); /// ``` #[inline] fn span(self: @[T; 0]) -> Span { @@ -785,14 +773,6 @@ impl SpanTryIntoEmptyFixedSizedArray> of TryInto, @Box<[T; 0 // TODO(spapini): Remove TDrop. It is necessary to get rid of response in case of panic. impl ArrayTCloneImpl, +Drop> of Clone> { - /// Returns a clone of `self`. - /// - /// # Examples - /// - /// ``` - /// let arr = array![1, 2, 3]; - /// let arr_clone = arr.clone(); - /// ``` fn clone(self: @Array) -> Array { let mut response = array_new(); let mut span = self.span(); @@ -807,30 +787,12 @@ impl ArrayTCloneImpl, +Drop> of Clone> { } impl ArrayPartialEq> of PartialEq> { - /// Returns `true` if the two arrays contain the same elements, false otherwise. - /// - /// # Examples - /// - /// ``` - /// let arr_1 = array![1, 2, 3]; - /// let arr_2 = array![1, 2, 3]; - /// assert!(PartialEq::eq(@arr_1, @arr_2)); - /// ``` fn eq(lhs: @Array, rhs: @Array) -> bool { lhs.span() == rhs.span() } } impl SpanPartialEq> of PartialEq> { - /// Returns `true` if the two spans contain the same elements, false otherwise. - /// - /// # Examples - /// - /// ``` - /// let span_1 = array![1, 2, 3].span(); - /// let span_2 = array![1, 2, 3].span(); - /// assert!(PartialEq::eq(@span_1, @span_2)); - /// ``` fn eq(lhs: @Span, rhs: @Span) -> bool { if (*lhs).len() != (*rhs).len() { return false; @@ -855,25 +817,22 @@ pub struct SpanIter { span: Span, } -/// `Drop` trait implementation for `SpanIter` struct. impl SpanIterDrop of Drop>; -/// `Copy` trait implementation for `SpanIter` struct. impl SpanIterCopy of Copy>; -/// `Iterator` trait implementation for `SpanIter` struct. impl SpanIterator of Iterator> { - /// Type of the elements contained in the span. + /// The type of the elements being iterated over. type Item = @T; - /// Returns an option of a snapshot of a span element if it exist, and `Option::None` otherwise. + // Advances the iterator and returns the next value. Returns `Option::None` when iteration is + // finished. fn next(ref self: SpanIter) -> Option<@T> { self.span.pop_front() } } -/// `IntoIterator` trait implementation for `Span`. impl SpanIntoIterator of crate::iter::IntoIterator> { type IntoIter = SpanIter; - /// Returns a `SpanIter` given a `Span`. + /// The kind of iterator we are turning this into. fn into_iter(self: Span) -> SpanIter { SpanIter { span: self } } @@ -885,15 +844,12 @@ pub struct ArrayIter { array: Array, } -/// `Clone` trait implementation for `ArrayIter` struct. impl ArrayIterClone, +Drop> of crate::clone::Clone> { - /// Returns a clone of `self`. fn clone(self: @ArrayIter) -> ArrayIter { ArrayIter { array: crate::clone::Clone::clone(self.array), } } } -/// `Iterator` trait implementation for `ArrayIter` struct. impl ArrayIterator of Iterator> { type Item = T; fn next(ref self: ArrayIter) -> Option { From 2463e4a9cd3fd9ecccb9d960e19146a151a91718 Mon Sep 17 00:00:00 2001 From: TAdev0 Date: Mon, 4 Nov 2024 19:00:11 +0100 Subject: [PATCH 22/31] more --- corelib/src/array.cairo | 2 -- 1 file changed, 2 deletions(-) diff --git a/corelib/src/array.cairo b/corelib/src/array.cairo index 88d79fe030b..1086f21d59a 100644 --- a/corelib/src/array.cairo +++ b/corelib/src/array.cairo @@ -732,7 +732,6 @@ extern fn tuple_from_span>( span: @Array ) -> Option<@Box> nopanic; -/// `TryInto` implementation from a span to fixed-size array. impl SpanTryIntoFixedSizedArray< T, const SIZE: usize, -TypeEqual<[T; SIZE], [T; 0]> > of TryInto, @Box<[T; SIZE]>> { @@ -750,7 +749,6 @@ impl SpanTryIntoFixedSizedArray< } } -/// `TryInto` implementation from a span to an empty fixed-size array. impl SpanTryIntoEmptyFixedSizedArray> of TryInto, @Box<[T; 0]>> { /// Returns an option of a snapshot of a box that contains an empty fixed-size array if the span /// is empty, and `Option::None` otherwise. From ad4c1f847c2487646878f3721bfac1e95676b047 Mon Sep 17 00:00:00 2001 From: TAdev0 Date: Fri, 8 Nov 2024 12:53:12 +0100 Subject: [PATCH 23/31] address last comments --- corelib/src/array.cairo | 26 +++++--------------------- 1 file changed, 5 insertions(+), 21 deletions(-) diff --git a/corelib/src/array.cairo b/corelib/src/array.cairo index 1086f21d59a..f5a91012aa7 100644 --- a/corelib/src/array.cairo +++ b/corelib/src/array.cairo @@ -281,27 +281,19 @@ pub impl ArrayImpl of ArrayTrait { impl ArrayDefault of Default> { /// Returns a new empty array. - /// #[inline] fn default() -> Array { ArrayTrait::new() } } -/// `IndexView` trait implementation to access an item contained in type `Array` with an index of -/// type `usize`. impl ArrayIndex of IndexView, usize, @T> { /// Returns a snapshot of the element at the given index. - /// `IndexView` needs to be explicitly imported with `use core::ops::IndexView;` to use the - /// `index` function The explicit import is not required when using the subscripting operator. /// /// # Examples /// /// ``` /// let arr: @Array = @array![1, 2, 3]; - /// let element: @u8 = arr.index(0); - /// assert!(element == @1); - /// /// let element: @u8 = arr[0]; /// assert!(element == @1); /// ``` @@ -310,7 +302,6 @@ impl ArrayIndex of IndexView, usize, @T> { } } -/// `Serde` trait implementation to serialize and deserialize an `Array`. impl ArraySerde, +Drop> of Serde> { /// Serializes an `Array` into an `Array`. /// @@ -374,20 +365,11 @@ impl SpanCopy of Copy>; impl SpanDrop of Drop>; impl ArrayIntoSpan> of Into, Span> { - /// Takes an array and returns a span of that array. - /// - /// # Examples - /// - /// ``` - /// let arr: Array = array![1, 2, 3]; - /// let span: Span = arr.into(); - /// ``` fn into(self: Array) -> Span { self.span() } } - impl SpanIntoArray, +Clone> of Into, Array> { /// Turns a span into an array. /// @@ -640,13 +622,12 @@ pub impl SpanImpl of SpanTrait { pub impl SpanIndex of IndexView, usize, @T> { /// Returns a snapshot of the element at the given index. - /// `IndexView` needs to be explicitly imported with `use core::ops::IndexView;` /// /// # Examples /// /// ``` /// let span: @Span = @array![1, 2, 3].span(); - /// let element: @u8 = span.index(0); + /// let element: @u8 = span[0]; /// assert!(element == @1); /// ``` #[inline] @@ -712,7 +693,6 @@ impl FixedSizeArrayToSpan< } } -/// `ToSpanTrait` implementation for a snapshot of an empty fixed-size array. impl EmptyFixedSizeArrayImpl> of ToSpanTrait<[T; 0], T> { /// Returns a `Span` corresponding to a view into the given empty fixed-size array. /// @@ -849,7 +829,10 @@ impl ArrayIterClone, +Drop> of crate::clone::Clone } impl ArrayIterator of Iterator> { + /// The type of the elements being iterated over. type Item = T; + // Advances the iterator and returns the next value. Returns `Option::None` when iteration is + // finished. fn next(ref self: ArrayIter) -> Option { self.array.pop_front() } @@ -857,6 +840,7 @@ impl ArrayIterator of Iterator> { impl ArrayIntoIterator of crate::iter::IntoIterator> { type IntoIter = ArrayIter; + /// The kind of iterator we are turning this into. fn into_iter(self: Array) -> ArrayIter { ArrayIter { array: self } } From f1d15eb5ab59201713157c766712d3b42a9bc6f5 Mon Sep 17 00:00:00 2001 From: TAdev0 Date: Mon, 11 Nov 2024 13:09:17 +0100 Subject: [PATCH 24/31] address Orizi comments --- corelib/src/array.cairo | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/corelib/src/array.cairo b/corelib/src/array.cairo index 676a564e361..77e81180c6f 100644 --- a/corelib/src/array.cairo +++ b/corelib/src/array.cairo @@ -659,6 +659,7 @@ impl SnapIntoSpanWhereToSpanTrait> of Into<@C, Span> } } +/// Returns a span from a box of a snapshot of a struct of members of the same type. extern fn span_from_tuple>( struct_like: Box<@T>, ) -> @Array nopanic; @@ -709,6 +710,7 @@ impl EmptyFixedSizeArrayImpl> of ToSpanTrait<[T; 0], T> { } } +/// Returns an option to a snapshot of a box of struct of members of the same type from a span. extern fn tuple_from_span>( span: @Array, ) -> Option<@Box> nopanic; @@ -802,8 +804,8 @@ impl SpanIterCopy of Copy>; impl SpanIterator of Iterator> { /// The type of the elements being iterated over. type Item = @T; - // Advances the iterator and returns the next value. Returns `Option::None` when iteration is - // finished. + /// Advances the iterator and returns the next value. Returns `Option::None` when iteration is + /// finished. fn next(ref self: SpanIter) -> Option<@T> { self.span.pop_front() } @@ -811,7 +813,6 @@ impl SpanIterator of Iterator> { impl SpanIntoIterator of crate::iter::IntoIterator> { type IntoIter = SpanIter; - /// The kind of iterator we are turning this into. fn into_iter(self: Span) -> SpanIter { SpanIter { span: self } } @@ -832,8 +833,8 @@ impl ArrayIterClone, +Drop> of crate::clone::Clone impl ArrayIterator of Iterator> { /// The type of the elements being iterated over. type Item = T; - // Advances the iterator and returns the next value. Returns `Option::None` when iteration is - // finished. + /// Advances the iterator and returns the next value. Returns `Option::None` when iteration is + /// finished. fn next(ref self: ArrayIter) -> Option { self.array.pop_front() } @@ -841,7 +842,6 @@ impl ArrayIterator of Iterator> { impl ArrayIntoIterator of crate::iter::IntoIterator> { type IntoIter = ArrayIter; - /// The kind of iterator we are turning this into. fn into_iter(self: Array) -> ArrayIter { ArrayIter { array: self } } From ae73123885ecf3177878c3aaffc198e702f72787 Mon Sep 17 00:00:00 2001 From: TAdev0 Date: Wed, 13 Nov 2024 15:54:44 +0100 Subject: [PATCH 25/31] fmt module --- corelib/src/fmt.cairo | 74 +++++++++++++++++++++++++++++++++++-------- 1 file changed, 61 insertions(+), 13 deletions(-) diff --git a/corelib/src/fmt.cairo b/corelib/src/fmt.cairo index 1377248d0ef..f4aa944eac0 100644 --- a/corelib/src/fmt.cairo +++ b/corelib/src/fmt.cairo @@ -1,3 +1,17 @@ +//! Fmt module that provides functionality for formatting values. +//! +//! The main components of this module are: +//! +//! - `Error`: A type representing formatting errors. +//! - `Formatter`: A struct that holds the configuration and buffer for formatting. +//! - `Display`: A trait for standard formatting using the empty format (`{}`). +//! - `Debug`: A trait for debug formatting using the empty format ("{:?}"). +//! - `LowerHex`: A trait for hex formatting in lower case. +//! +//! The module includes implementations of the `Display`, `Debug` and `LowerHex` traits for various +//! types. + +/// Dedicated type for representing formatting errors. #[derive(Drop)] pub struct Error {} @@ -9,10 +23,18 @@ pub struct Formatter { } /// A trait for standard formatting, using the empty format ("{}"). +/// +/// # Examples +/// +/// ``` +/// let word: ByteArray = "123"; +/// println!("{}", word); +/// ``` pub trait Display { fn fmt(self: @T, ref f: Formatter) -> Result<(), Error>; } +/// `Display` trait implementation for `ByteArray`. impl DisplayByteArray of Display { fn fmt(self: @ByteArray, ref f: Formatter) -> Result<(), Error> { f.buffer.append(self); @@ -20,6 +42,7 @@ impl DisplayByteArray of Display { } } +/// `Display` trait implementation for unsigned integers. impl DisplayInteger< T, +crate::to_byte_array::AppendFormattedToByteArray, +Into, +TryInto>, > of Display { @@ -31,6 +54,7 @@ impl DisplayInteger< } } +/// `Display` trait implementation for signed integers. impl DisplaySignedInteger< Signed, Unsigned, @@ -48,6 +72,7 @@ impl DisplaySignedInteger< } } +/// `Display` trait implementation for `NonZero` values. impl DisplayNonZero, +Copy, +Drop> of Display> { fn fmt(self: @NonZero, ref f: Formatter) -> Result<(), Error> { let value: T = (*self).into(); @@ -55,6 +80,7 @@ impl DisplayNonZero, +Copy, +Drop> of Display> { } } +/// `Display` trait implementation for booleans. impl DisplayBool of Display { fn fmt(self: @bool, ref f: Formatter) -> Result<(), Error> { if *self { @@ -65,6 +91,7 @@ impl DisplayBool of Display { } } +/// `Display` trait implementation for snapshots. impl DisplaySnapshot> of Display<@T> { fn fmt(self: @@T, ref f: Formatter) -> Result<(), Error> { Display::fmt(*self, ref f) @@ -72,10 +99,18 @@ impl DisplaySnapshot> of Display<@T> { } /// A trait for debug formatting, using the empty format ("{:?}"). +/// +/// # Examples +/// +/// ``` +/// let word: ByteArray = "123"; +/// println!("{:?}", word); +/// ``` pub trait Debug { fn fmt(self: @T, ref f: Formatter) -> Result<(), Error>; } +/// `Debug` trait implementation for `ByteArray`. impl DebugByteArray of Debug { fn fmt(self: @ByteArray, ref f: Formatter) -> Result<(), Error> { write!(f, "\"")?; @@ -84,6 +119,7 @@ impl DebugByteArray of Debug { } } +/// `Debug` trait implementation for unsigned integers. impl DebugInteger< T, +crate::to_byte_array::AppendFormattedToByteArray, +Into, +TryInto>, > of Debug { @@ -92,6 +128,7 @@ impl DebugInteger< } } +/// `Debug` trait implementation for signed integers. impl DebugSignedInteger< Signed, Unsigned, @@ -105,6 +142,7 @@ impl DebugSignedInteger< } } +/// `Debug` trait implementation for `NonZero` values. impl DebugNonZero, +Copy, +Drop> of Debug> { fn fmt(self: @NonZero, ref f: Formatter) -> Result<(), Error> { let value: T = (*self).into(); @@ -112,12 +150,14 @@ impl DebugNonZero, +Copy, +Drop> of Debug> { } } +/// `Debug` trait implementation for booleans. impl DebugBool of Debug { fn fmt(self: @bool, ref f: Formatter) -> Result<(), Error> { Display::fmt(self, ref f) } } +/// `Debug` trait implementation for snapshots. impl DebugSnapshot> of Debug<@T> { fn fmt(self: @@T, ref f: Formatter) -> Result<(), Error> { write!(f, "@")?; @@ -125,7 +165,7 @@ impl DebugSnapshot> of Debug<@T> { } } -/// Tuple `Debug` implementation. +/// `Debug` trait implementation for tuples. impl TupleDebug< T, impl TSF: crate::metaprogramming::TupleSnapForward, @@ -139,7 +179,7 @@ impl TupleDebug< } } -/// Fixed sized array `Debug` implementation. +/// `Debug` trait implementation for fixed-size arrays. impl FixedSizedArrayDebug< T, impl TSF: crate::metaprogramming::TupleSnapForward, @@ -158,21 +198,21 @@ trait TupleDebugHelper { fn fmt(value: T, ref f: Formatter) -> Result<(), Error>; } -/// An implementation of `TupleDebugHelper` for snapshots of types with `Debug` implementations. +/// An implementation of `TupleDebugHelper` for snapshots of types that implement `Debug`. impl TupleDebugHelperFromDebug> of TupleDebugHelper<@T> { fn fmt(value: @T, ref f: Formatter) -> Result<(), Error> { Debug::fmt(value, ref f) } } -/// `Debug` impl for tuples of size 0. +/// `Debug` implementation for tuples of size 0. impl TupleDebugHelperTuple0 of TupleDebugHelper<()> { fn fmt(value: (), ref f: Formatter) -> Result<(), Error> { Result::Ok(()) } } -/// `Debug` impl for tuples of size 1. +/// `Debug` implementation for tuples of size 1. impl TupleDebugHelperTuple1> of TupleDebugHelper<(@E0,)> { fn fmt(value: (@E0,), ref f: Formatter) -> Result<(), Error> { let (e0,) = value; @@ -181,7 +221,7 @@ impl TupleDebugHelperTuple1> of TupleDebugHelper<(@E0 } } -/// `Debug` impl for tuples of size 2. +/// `Debug` implementation for tuples of size 2. impl TupleDebugHelperTuple2< E0, E1, +TupleDebugHelper<@E0>, +TupleDebugHelper<@E1>, > of TupleDebugHelper<(@E0, @E1)> { @@ -193,7 +233,7 @@ impl TupleDebugHelperTuple2< } } -/// `Debug` impl for tuples of size 3 and above. +/// `Debug` implementation for tuples of size 3 and above. /// Not starting from size 1 since we have special cases for 0 and 1. impl TupleDebugHelperTupleNext< T, @@ -211,14 +251,14 @@ impl TupleDebugHelperTupleNext< } } -/// `Debug` impl for fixed sized arrays of size 0. +/// `Debug` implementation for fixed-sized arrays of size 0. impl TupleDebugHelperFixedSizedArray0 of TupleDebugHelper<[@T; 0]> { fn fmt(value: [@T; 0], ref f: Formatter) -> Result<(), Error> { Result::Ok(()) } } -/// `Debug` impl for fixed sized arrays of size 1. +/// `Debug` implementation for fixed-sized arrays of size 1. impl TupleDebugHelperFixedSizedArray1> of TupleDebugHelper<[@T; 1]> { fn fmt(value: [@T; 1], ref f: Formatter) -> Result<(), Error> { let [e0] = value; @@ -226,7 +266,7 @@ impl TupleDebugHelperFixedSizedArray1> of TupleDebugHel } } -/// `Debug` impl for fixed sized arrays of size 2 and above. +/// `Debug` implementation for fixed-sized arrays of size 2 and above. /// Not starting from size 1 since we have a special case for 0. impl TupleDebugHelperFixedSizedArrayNext< T, @@ -259,12 +299,14 @@ fn fmt_head_and_rest< TupleDebugHelper::fmt(rest, ref f) } +/// `Debug` trait implementation for `Array`. impl ArrayTDebug> of Debug> { fn fmt(self: @Array, ref f: Formatter) -> Result<(), Error> { Debug::fmt(@self.span(), ref f) } } +/// `Debug` trait implementation for `Span`. impl SpanTDebug> of Debug> { fn fmt(self: @Span, ref f: Formatter) -> Result<(), Error> { let mut self = *self; @@ -289,10 +331,13 @@ impl SpanTDebug> of Debug> { } } -/// Impls for `Debug` and `LowerHex` for types that can be converted into `felt252` using the `Into` +/// Implementations for `Debug` and `LowerHex` for types that can be converted into `felt252` using +/// the `Into` /// trait. -/// Usage example: -/// ```ignore +/// +/// # Examples +/// +/// ``` /// impl MyTypeDebug = crate::fmt::into_felt252_based::DebugImpl;` /// impl MyTypeLowerHex = crate::fmt::into_felt252_based::LowerHexImpl; /// ``` @@ -302,6 +347,7 @@ pub mod into_felt252_based { crate::fmt::DebugInteger::::fmt(@(*self).into(), ref f) } } + pub impl LowerHexImpl, +Copy> of core::fmt::LowerHex { fn fmt(self: @T, ref f: core::fmt::Formatter) -> Result<(), core::fmt::Error> { core::fmt::LowerHexInteger::::fmt(@(*self).into(), ref f) @@ -314,6 +360,7 @@ pub trait LowerHex { fn fmt(self: @T, ref f: Formatter) -> Result<(), Error>; } +/// `LowerHex` trait implementation for integers. impl LowerHexInteger< T, +crate::to_byte_array::AppendFormattedToByteArray, +Into, +TryInto>, > of LowerHex { @@ -324,6 +371,7 @@ impl LowerHexInteger< } } +/// `LowerHex` trait implementation for `NonZero` values. impl LowerHexNonZero, +Copy, +Drop> of LowerHex> { fn fmt(self: @NonZero, ref f: Formatter) -> Result<(), Error> { let value: T = (*self).into(); From ba69884e3093ff813ba3713026d605de7fbf0816 Mon Sep 17 00:00:00 2001 From: TAdev0 Date: Wed, 13 Nov 2024 16:18:24 +0100 Subject: [PATCH 26/31] fmt --- corelib/src/fmt.cairo | 28 ---------------------------- 1 file changed, 28 deletions(-) diff --git a/corelib/src/fmt.cairo b/corelib/src/fmt.cairo index f4aa944eac0..427bcf12a7a 100644 --- a/corelib/src/fmt.cairo +++ b/corelib/src/fmt.cairo @@ -34,7 +34,6 @@ pub trait Display { fn fmt(self: @T, ref f: Formatter) -> Result<(), Error>; } -/// `Display` trait implementation for `ByteArray`. impl DisplayByteArray of Display { fn fmt(self: @ByteArray, ref f: Formatter) -> Result<(), Error> { f.buffer.append(self); @@ -42,7 +41,6 @@ impl DisplayByteArray of Display { } } -/// `Display` trait implementation for unsigned integers. impl DisplayInteger< T, +crate::to_byte_array::AppendFormattedToByteArray, +Into, +TryInto>, > of Display { @@ -54,7 +52,6 @@ impl DisplayInteger< } } -/// `Display` trait implementation for signed integers. impl DisplaySignedInteger< Signed, Unsigned, @@ -72,7 +69,6 @@ impl DisplaySignedInteger< } } -/// `Display` trait implementation for `NonZero` values. impl DisplayNonZero, +Copy, +Drop> of Display> { fn fmt(self: @NonZero, ref f: Formatter) -> Result<(), Error> { let value: T = (*self).into(); @@ -80,7 +76,6 @@ impl DisplayNonZero, +Copy, +Drop> of Display> { } } -/// `Display` trait implementation for booleans. impl DisplayBool of Display { fn fmt(self: @bool, ref f: Formatter) -> Result<(), Error> { if *self { @@ -91,7 +86,6 @@ impl DisplayBool of Display { } } -/// `Display` trait implementation for snapshots. impl DisplaySnapshot> of Display<@T> { fn fmt(self: @@T, ref f: Formatter) -> Result<(), Error> { Display::fmt(*self, ref f) @@ -110,7 +104,6 @@ pub trait Debug { fn fmt(self: @T, ref f: Formatter) -> Result<(), Error>; } -/// `Debug` trait implementation for `ByteArray`. impl DebugByteArray of Debug { fn fmt(self: @ByteArray, ref f: Formatter) -> Result<(), Error> { write!(f, "\"")?; @@ -119,7 +112,6 @@ impl DebugByteArray of Debug { } } -/// `Debug` trait implementation for unsigned integers. impl DebugInteger< T, +crate::to_byte_array::AppendFormattedToByteArray, +Into, +TryInto>, > of Debug { @@ -128,7 +120,6 @@ impl DebugInteger< } } -/// `Debug` trait implementation for signed integers. impl DebugSignedInteger< Signed, Unsigned, @@ -142,7 +133,6 @@ impl DebugSignedInteger< } } -/// `Debug` trait implementation for `NonZero` values. impl DebugNonZero, +Copy, +Drop> of Debug> { fn fmt(self: @NonZero, ref f: Formatter) -> Result<(), Error> { let value: T = (*self).into(); @@ -150,14 +140,12 @@ impl DebugNonZero, +Copy, +Drop> of Debug> { } } -/// `Debug` trait implementation for booleans. impl DebugBool of Debug { fn fmt(self: @bool, ref f: Formatter) -> Result<(), Error> { Display::fmt(self, ref f) } } -/// `Debug` trait implementation for snapshots. impl DebugSnapshot> of Debug<@T> { fn fmt(self: @@T, ref f: Formatter) -> Result<(), Error> { write!(f, "@")?; @@ -165,7 +153,6 @@ impl DebugSnapshot> of Debug<@T> { } } -/// `Debug` trait implementation for tuples. impl TupleDebug< T, impl TSF: crate::metaprogramming::TupleSnapForward, @@ -179,7 +166,6 @@ impl TupleDebug< } } -/// `Debug` trait implementation for fixed-size arrays. impl FixedSizedArrayDebug< T, impl TSF: crate::metaprogramming::TupleSnapForward, @@ -198,21 +184,18 @@ trait TupleDebugHelper { fn fmt(value: T, ref f: Formatter) -> Result<(), Error>; } -/// An implementation of `TupleDebugHelper` for snapshots of types that implement `Debug`. impl TupleDebugHelperFromDebug> of TupleDebugHelper<@T> { fn fmt(value: @T, ref f: Formatter) -> Result<(), Error> { Debug::fmt(value, ref f) } } -/// `Debug` implementation for tuples of size 0. impl TupleDebugHelperTuple0 of TupleDebugHelper<()> { fn fmt(value: (), ref f: Formatter) -> Result<(), Error> { Result::Ok(()) } } -/// `Debug` implementation for tuples of size 1. impl TupleDebugHelperTuple1> of TupleDebugHelper<(@E0,)> { fn fmt(value: (@E0,), ref f: Formatter) -> Result<(), Error> { let (e0,) = value; @@ -221,7 +204,6 @@ impl TupleDebugHelperTuple1> of TupleDebugHelper<(@E0 } } -/// `Debug` implementation for tuples of size 2. impl TupleDebugHelperTuple2< E0, E1, +TupleDebugHelper<@E0>, +TupleDebugHelper<@E1>, > of TupleDebugHelper<(@E0, @E1)> { @@ -233,8 +215,6 @@ impl TupleDebugHelperTuple2< } } -/// `Debug` implementation for tuples of size 3 and above. -/// Not starting from size 1 since we have special cases for 0 and 1. impl TupleDebugHelperTupleNext< T, impl TS: crate::metaprogramming::TupleSplit, @@ -251,14 +231,12 @@ impl TupleDebugHelperTupleNext< } } -/// `Debug` implementation for fixed-sized arrays of size 0. impl TupleDebugHelperFixedSizedArray0 of TupleDebugHelper<[@T; 0]> { fn fmt(value: [@T; 0], ref f: Formatter) -> Result<(), Error> { Result::Ok(()) } } -/// `Debug` implementation for fixed-sized arrays of size 1. impl TupleDebugHelperFixedSizedArray1> of TupleDebugHelper<[@T; 1]> { fn fmt(value: [@T; 1], ref f: Formatter) -> Result<(), Error> { let [e0] = value; @@ -266,8 +244,6 @@ impl TupleDebugHelperFixedSizedArray1> of TupleDebugHel } } -/// `Debug` implementation for fixed-sized arrays of size 2 and above. -/// Not starting from size 1 since we have a special case for 0. impl TupleDebugHelperFixedSizedArrayNext< T, const N: usize, @@ -299,14 +275,12 @@ fn fmt_head_and_rest< TupleDebugHelper::fmt(rest, ref f) } -/// `Debug` trait implementation for `Array`. impl ArrayTDebug> of Debug> { fn fmt(self: @Array, ref f: Formatter) -> Result<(), Error> { Debug::fmt(@self.span(), ref f) } } -/// `Debug` trait implementation for `Span`. impl SpanTDebug> of Debug> { fn fmt(self: @Span, ref f: Formatter) -> Result<(), Error> { let mut self = *self; @@ -360,7 +334,6 @@ pub trait LowerHex { fn fmt(self: @T, ref f: Formatter) -> Result<(), Error>; } -/// `LowerHex` trait implementation for integers. impl LowerHexInteger< T, +crate::to_byte_array::AppendFormattedToByteArray, +Into, +TryInto>, > of LowerHex { @@ -371,7 +344,6 @@ impl LowerHexInteger< } } -/// `LowerHex` trait implementation for `NonZero` values. impl LowerHexNonZero, +Copy, +Drop> of LowerHex> { fn fmt(self: @NonZero, ref f: Formatter) -> Result<(), Error> { let value: T = (*self).into(); From 08f767be7b67e51a520facf0e9dc8b2a3e525806 Mon Sep 17 00:00:00 2001 From: TAdev0 Date: Wed, 13 Nov 2024 16:20:04 +0100 Subject: [PATCH 27/31] typo --- corelib/src/fmt.cairo | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/corelib/src/fmt.cairo b/corelib/src/fmt.cairo index 427bcf12a7a..2c11760fea8 100644 --- a/corelib/src/fmt.cairo +++ b/corelib/src/fmt.cairo @@ -4,7 +4,7 @@ //! //! - `Error`: A type representing formatting errors. //! - `Formatter`: A struct that holds the configuration and buffer for formatting. -//! - `Display`: A trait for standard formatting using the empty format (`{}`). +//! - `Display`: A trait for standard formatting using the empty format ("{}"). //! - `Debug`: A trait for debug formatting using the empty format ("{:?}"). //! - `LowerHex`: A trait for hex formatting in lower case. //! From 0db093cf053744b09419e1b9388b8e7e4f37484a Mon Sep 17 00:00:00 2001 From: TAdev0 Date: Wed, 13 Nov 2024 16:20:50 +0100 Subject: [PATCH 28/31] rename --- corelib/src/fmt.cairo | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/corelib/src/fmt.cairo b/corelib/src/fmt.cairo index 2c11760fea8..08688ebc293 100644 --- a/corelib/src/fmt.cairo +++ b/corelib/src/fmt.cairo @@ -1,4 +1,4 @@ -//! Fmt module that provides functionality for formatting values. +//! Functionality for formatting values. //! //! The main components of this module are: //! From 5553d3015d224f8df8588e8ee0674fce4461360b Mon Sep 17 00:00:00 2001 From: TAdev0 Date: Wed, 13 Nov 2024 16:24:12 +0100 Subject: [PATCH 29/31] add internal link --- corelib/src/fmt.cairo | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/corelib/src/fmt.cairo b/corelib/src/fmt.cairo index 08688ebc293..72ac1c3d4c8 100644 --- a/corelib/src/fmt.cairo +++ b/corelib/src/fmt.cairo @@ -8,7 +8,7 @@ //! - `Debug`: A trait for debug formatting using the empty format ("{:?}"). //! - `LowerHex`: A trait for hex formatting in lower case. //! -//! The module includes implementations of the `Display`, `Debug` and `LowerHex` traits for various +//! The module includes implementations of the [`Display`], [`Debug`] and [`LowerHex`] traits for various //! types. /// Dedicated type for representing formatting errors. From 15efec12780d607c49ba7146fb43571c5e3b59ee Mon Sep 17 00:00:00 2001 From: TAdev0 Date: Wed, 13 Nov 2024 16:48:00 +0100 Subject: [PATCH 30/31] fmt --- corelib/src/fmt.cairo | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/corelib/src/fmt.cairo b/corelib/src/fmt.cairo index 72ac1c3d4c8..dfb0124d5e7 100644 --- a/corelib/src/fmt.cairo +++ b/corelib/src/fmt.cairo @@ -8,8 +8,8 @@ //! - `Debug`: A trait for debug formatting using the empty format ("{:?}"). //! - `LowerHex`: A trait for hex formatting in lower case. //! -//! The module includes implementations of the [`Display`], [`Debug`] and [`LowerHex`] traits for various -//! types. +//! The module includes implementations of the [`Display`], [`Debug`] and [`LowerHex`] traits for +//! various types. /// Dedicated type for representing formatting errors. #[derive(Drop)] From 2cf8fcb386f9f7a57e45eade45bb89d39095a06f Mon Sep 17 00:00:00 2001 From: TAdev0 Date: Thu, 14 Nov 2024 20:05:23 +0100 Subject: [PATCH 31/31] address Orizi comments --- corelib/src/fmt.cairo | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/corelib/src/fmt.cairo b/corelib/src/fmt.cairo index dfb0124d5e7..7d8a19a5208 100644 --- a/corelib/src/fmt.cairo +++ b/corelib/src/fmt.cairo @@ -215,6 +215,8 @@ impl TupleDebugHelperTuple2< } } +// `Debug` impl for tuples of size 3 and above. +// Not starting from size 1 nor 2 since we have special cases for 1 and 2. impl TupleDebugHelperTupleNext< T, impl TS: crate::metaprogramming::TupleSplit, @@ -244,6 +246,8 @@ impl TupleDebugHelperFixedSizedArray1> of TupleDebugHel } } +// `Debug` impl for fixed sized arrays of size 2 and above. +// Not starting from size 1 since we have a special case for 1. impl TupleDebugHelperFixedSizedArrayNext< T, const N: usize, @@ -306,8 +310,7 @@ impl SpanTDebug> of Debug> { } /// Implementations for `Debug` and `LowerHex` for types that can be converted into `felt252` using -/// the `Into` -/// trait. +/// the `Into` trait. /// /// # Examples ///