diff --git a/corelib/src/fmt.cairo b/corelib/src/fmt.cairo index 1377248d0ef..7d8a19a5208 100644 --- a/corelib/src/fmt.cairo +++ b/corelib/src/fmt.cairo @@ -1,3 +1,17 @@ +//! 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,6 +23,13 @@ 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>; } @@ -72,6 +93,13 @@ 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>; } @@ -125,7 +153,6 @@ impl DebugSnapshot> of Debug<@T> { } } -/// Tuple `Debug` implementation. impl TupleDebug< T, impl TSF: crate::metaprogramming::TupleSnapForward, @@ -139,7 +166,6 @@ impl TupleDebug< } } -/// Fixed sized array `Debug` implementation. impl FixedSizedArrayDebug< T, impl TSF: crate::metaprogramming::TupleSnapForward, @@ -158,21 +184,18 @@ trait TupleDebugHelper { fn fmt(value: T, ref f: Formatter) -> Result<(), Error>; } -/// An implementation of `TupleDebugHelper` for snapshots of types with `Debug` implementations. 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. impl TupleDebugHelperTuple0 of TupleDebugHelper<()> { fn fmt(value: (), ref f: Formatter) -> Result<(), Error> { Result::Ok(()) } } -/// `Debug` impl for tuples of size 1. impl TupleDebugHelperTuple1> of TupleDebugHelper<(@E0,)> { fn fmt(value: (@E0,), ref f: Formatter) -> Result<(), Error> { let (e0,) = value; @@ -181,7 +204,6 @@ impl TupleDebugHelperTuple1> of TupleDebugHelper<(@E0 } } -/// `Debug` impl for tuples of size 2. impl TupleDebugHelperTuple2< E0, E1, +TupleDebugHelper<@E0>, +TupleDebugHelper<@E1>, > of TupleDebugHelper<(@E0, @E1)> { @@ -193,8 +215,8 @@ impl TupleDebugHelperTuple2< } } -/// `Debug` impl for tuples of size 3 and above. -/// Not starting from size 1 since we have special cases for 0 and 1. +// `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, @@ -211,14 +233,12 @@ impl TupleDebugHelperTupleNext< } } -/// `Debug` impl 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. impl TupleDebugHelperFixedSizedArray1> of TupleDebugHelper<[@T; 1]> { fn fmt(value: [@T; 1], ref f: Formatter) -> Result<(), Error> { let [e0] = value; @@ -226,8 +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 0. +// `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, @@ -289,10 +309,12 @@ impl SpanTDebug> of Debug> { } } -/// Impls for `Debug` and `LowerHex` for types that can be converted into `felt252` using the `Into` -/// trait. -/// Usage example: -/// ```ignore +/// Implementations for `Debug` and `LowerHex` for types that can be converted into `felt252` using +/// the `Into` trait. +/// +/// # Examples +/// +/// ``` /// impl MyTypeDebug = crate::fmt::into_felt252_based::DebugImpl;` /// impl MyTypeLowerHex = crate::fmt::into_felt252_based::LowerHexImpl; /// ``` @@ -302,6 +324,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)