cairo_lang_utils/
lib.rs

1//! Cairo utilities.
2
3#![cfg_attr(not(feature = "std"), no_std)]
4
5#[cfg(not(feature = "std"))]
6extern crate alloc;
7
8#[cfg(not(feature = "std"))]
9use alloc::boxed::Box;
10use core::fmt;
11
12pub mod bigint;
13pub mod byte_array;
14pub mod casts;
15pub mod collection_arithmetics;
16pub mod extract_matches;
17#[cfg(feature = "std")]
18pub mod graph_algos;
19pub mod iterators;
20#[cfg(feature = "env_logger")]
21pub mod logging;
22pub mod ordered_hash_map;
23pub mod ordered_hash_set;
24pub mod unordered_hash_map;
25pub mod unordered_hash_set;
26
27/// Similar to From / TryFrom, but returns an option.
28pub trait OptionFrom<T>
29where
30    Self: Sized,
31{
32    fn option_from(other: T) -> Option<Self>;
33}
34
35pub fn write_comma_separated<Iter: IntoIterator<Item = V>, V: core::fmt::Display>(
36    f: &mut fmt::Formatter<'_>,
37    values: Iter,
38) -> fmt::Result {
39    let mut iter = values.into_iter();
40    if let Some(value) = iter.next() {
41        write!(f, "{value}")?;
42    }
43    for value in iter {
44        write!(f, ", {value}")?;
45    }
46    Ok(())
47}
48
49/// Helper operations on `Option<T>`.
50pub trait OptionHelper {
51    fn on_none<F: FnOnce()>(self, f: F) -> Self;
52}
53impl<T> OptionHelper for Option<T> {
54    fn on_none<F: FnOnce()>(self, f: F) -> Self {
55        if self.is_none() {
56            f();
57        }
58        self
59    }
60}
61
62/// Borrows a mutable reference as Box for the lifespan of this function.
63///
64/// Runs the given closure with the boxed value as a parameter.
65/// The closure is expected to return a boxed value, whose changes will be reflected on the mutable
66/// reference.
67/// Example:
68/// ```
69/// use cairo_lang_utils::borrow_as_box;
70/// let mut x = 5;
71/// borrow_as_box(&mut x, |mut x: Box<usize>| {
72///     *x += 1;
73///     ((), x)
74/// });
75/// assert_eq!(x, 6);
76/// ```
77pub fn borrow_as_box<T: Default, R, F: FnOnce(Box<T>) -> (R, Box<T>)>(ptr: &mut T, f: F) -> R {
78    // TODO(spapini): Consider replacing take with something the leaves the memory dangling, instead
79    // of filling with default().
80    let (res, boxed) = f(Box::new(core::mem::take(ptr)));
81    *ptr = *boxed;
82    res
83}
84
85/// A trait for the `lookup_intern` method for short IDs (returning the long ID).
86pub trait LookupIntern<'a, DynDbGroup: ?Sized, LongId> {
87    fn lookup_intern(&self, db: &(impl Upcast<DynDbGroup> + ?Sized)) -> LongId;
88}
89pub trait Intern<'a, DynDbGroup: ?Sized, ShortId> {
90    fn intern(self, db: &(impl Upcast<DynDbGroup> + ?Sized)) -> ShortId;
91}
92
93// Defines a short id struct for use with salsa interning.
94// Interning is the process of representing a value as an id in a table.
95// We usually denote the value type as "long id", and the id type as "short id" or just "id".
96// Example:
97//   A function's long id may be the module in which it is defined and its name. The function is
98//   assigned a sequential integer (salsa::InternId) which will be its short id. Salsa will hold a
99//   table to translate between the two representations. Note that a long id of an entity will
100//   usually include the short id of the entity's parent.
101#[macro_export]
102macro_rules! define_short_id {
103    ($short_id:ident, $long_id:path, $db:ident, $lookup:ident, $intern:ident) => {
104        #[derive(Copy, Clone, Debug, Hash, PartialEq, Eq)]
105        pub struct $short_id(salsa::InternId);
106        impl<'a> cairo_lang_utils::LookupIntern<'a, dyn $db + 'a, $long_id> for $short_id {
107            fn lookup_intern(
108                &self,
109                db: &(impl cairo_lang_utils::Upcast<dyn $db + 'a> + ?Sized),
110            ) -> $long_id {
111                $db::$lookup(db.upcast(), *self)
112            }
113        }
114        impl<'a> cairo_lang_utils::Intern<'a, dyn $db + 'a, $short_id> for $long_id {
115            fn intern(
116                self,
117                db: &(impl cairo_lang_utils::Upcast<dyn $db + 'a> + ?Sized),
118            ) -> $short_id {
119                $db::$intern(db.upcast(), self)
120            }
121        }
122        impl salsa::InternKey for $short_id {
123            fn from_intern_id(salsa_id: salsa::InternId) -> Self {
124                Self(salsa_id)
125            }
126
127            fn as_intern_id(&self) -> salsa::InternId {
128                self.0
129            }
130        }
131        // Impl transparent DebugWithDb.
132        impl<T: ?Sized + cairo_lang_utils::Upcast<dyn $db + 'static>>
133            cairo_lang_debug::DebugWithDb<T> for $short_id
134        {
135            fn fmt(&self, f: &mut std::fmt::Formatter<'_>, db: &T) -> std::fmt::Result {
136                use core::fmt::Debug;
137
138                use cairo_lang_debug::helper::Fallback;
139                let db = db.upcast();
140                cairo_lang_debug::helper::HelperDebug::<$long_id, dyn $db>::helper_debug(
141                    &db.$lookup(*self),
142                    db,
143                )
144                .fmt(f)
145            }
146        }
147    };
148}
149
150pub trait Upcast<T: ?Sized> {
151    fn upcast(&self) -> &T;
152}
153
154impl<T: ?Sized> Upcast<T> for T {
155    fn upcast(&self) -> &T {
156        self
157    }
158}
159
160pub trait UpcastMut<T: ?Sized> {
161    fn upcast_mut(&mut self) -> &mut T;
162}
163
164impl<T: ?Sized> UpcastMut<T> for T {
165    fn upcast_mut(&mut self) -> &mut T {
166        self
167    }
168}
169
170/// Returns `Some(())` if the condition is true, otherwise `None`.
171///
172/// Useful in functions returning `None` on some condition:
173/// `require(condition)?;`
174/// And for functions returning `Err` on some condition:
175/// `require(condition).ok_or_else(|| create_err())?;`
176#[must_use = "This function is only relevant to create a possible return."]
177pub fn require(condition: bool) -> Option<()> {
178    condition.then_some(())
179}
cairo_lang_utils/lib.rs

cairo_lang_utils/
lib.rs
