cairo_lang_sierra/extensions/modules/
felt252_dict.rs

1use super::enm::EnumType;
2use super::felt252::Felt252Type;
3use super::gas::GasBuiltinType;
4use super::int::unsigned::{Uint8Type, Uint16Type, Uint32Type, Uint64Type};
5use super::int::unsigned128::Uint128Type;
6use super::nullable::NullableType;
7use super::range_check::RangeCheckType;
8use super::segment_arena::SegmentArenaType;
9use super::squashed_felt252_dict::SquashedFelt252DictType;
10use crate::define_libfunc_hierarchy;
11use crate::extensions::lib_func::{
12    DeferredOutputKind, LibfuncSignature, OutputVarInfo, ParamSignature, SierraApChange,
13    SignatureAndTypeGenericLibfunc, SignatureOnlyGenericLibfunc, SignatureSpecializationContext,
14    WrapSignatureAndTypeGenericLibfunc,
15};
16use crate::extensions::type_specialization_context::TypeSpecializationContext;
17use crate::extensions::types::{
18    GenericTypeArgGenericType, GenericTypeArgGenericTypeWrapper, TypeInfo,
19};
20use crate::extensions::{
21    NamedType, OutputVarReferenceInfo, SpecializationError, args_as_single_type,
22};
23use crate::ids::{ConcreteTypeId, GenericTypeId};
24use crate::program::{ConcreteTypeLongId, GenericArg};
25
26/// Type representing a dictionary from a felt252 to types of size one.
27///
28/// This is currently only bounded for all numeric types, Nullable, and Enum types with 2 or less
29/// variants, as this are the types that has proper default as 0, and therefore can be properly used
30/// as a value in the dictionary.
31#[derive(Default)]
32pub struct Felt252DictTypeWrapped {}
33impl GenericTypeArgGenericType for Felt252DictTypeWrapped {
34    const ID: GenericTypeId = GenericTypeId::new_inline("Felt252Dict");
35
36    fn calc_info(
37        &self,
38        context: &dyn TypeSpecializationContext,
39        long_id: crate::program::ConcreteTypeLongId,
40        wrapped_type_info: TypeInfo,
41    ) -> Result<TypeInfo, SpecializationError> {
42        specialize_with_dict_value_param(context, long_id, wrapped_type_info)
43    }
44}
45
46/// Specializes a generic type matching a dictionary value parameter.
47/// Called for both `Felt252Dict` and `Felt252DictEntry`.
48fn specialize_with_dict_value_param(
49    context: &dyn TypeSpecializationContext,
50    long_id: ConcreteTypeLongId,
51    TypeInfo {
52        long_id: ConcreteTypeLongId { generic_id, generic_args },
53        storable,
54        droppable,
55        duplicatable: _,
56        zero_sized: _,
57    }: TypeInfo,
58) -> Result<TypeInfo, SpecializationError> {
59    // Checking for specific types allowed as dictionary values.
60    // TODO(Gil): Check in the higher level compiler and raise proper diagnostic (when we'll
61    // have a 'where' equivalent).
62    // TODO(Gil): Allow any type of size 1 which implement the 'Felt252DictValue' trait.
63    let allowed = match generic_id {
64        id if id == Felt252Type::id() => generic_args.is_empty(),
65        id if id == Uint8Type::id() => generic_args.is_empty(),
66        id if id == Uint16Type::id() => generic_args.is_empty(),
67        id if id == Uint32Type::id() => generic_args.is_empty(),
68        id if id == Uint64Type::id() => generic_args.is_empty(),
69        id if id == Uint128Type::id() => generic_args.is_empty(),
70        id if id == NullableType::id() => generic_args.len() == 1,
71        id if id == EnumType::id() => {
72            // Checking the enum type is valid.
73            !generic_args.is_empty()
74            // Zero is not a valid value for enums with 3 or more variants, so they cannot be
75            // used in a dict (whose default value is zero).
76            // (the additional argument is the user type).
77            && generic_args.len() <= 3
78                // All contained types must be 0-sized, so the total size will be exactly 1.
79                && generic_args.into_iter().skip(1).all(|arg| {
80                    let GenericArg::Type(ty) = arg else {
81                        return false;
82                    };
83                    let Ok(info) = context.get_type_info(ty) else {
84                        return false;
85                    };
86                    info.zero_sized
87                })
88        }
89        _ => false,
90    };
91    if allowed && storable && droppable {
92        Ok(TypeInfo {
93            long_id,
94            duplicatable: false,
95            droppable: false,
96            storable: true,
97            zero_sized: false,
98        })
99    } else {
100        Err(SpecializationError::UnsupportedGenericArg)
101    }
102}
103pub type Felt252DictType = GenericTypeArgGenericTypeWrapper<Felt252DictTypeWrapped>;
104
105define_libfunc_hierarchy! {
106    pub enum Felt252DictLibfunc {
107        New(Felt252DictNewLibfunc),
108        Squash(Felt252DictSquashLibfunc),
109    }, Felt252DictConcreteLibfunc
110}
111
112/// Libfunc for creating a new felt252_dict.
113#[derive(Default)]
114pub struct Felt252DictNewLibfunc {}
115impl SignatureOnlyGenericLibfunc for Felt252DictNewLibfunc {
116    const STR_ID: &'static str = "felt252_dict_new";
117
118    fn specialize_signature(
119        &self,
120        context: &dyn SignatureSpecializationContext,
121        args: &[GenericArg],
122    ) -> Result<LibfuncSignature, SpecializationError> {
123        let ty = args_as_single_type(args)?;
124        let segment_arena_ty = context.get_concrete_type(SegmentArenaType::id(), &[])?;
125        Ok(LibfuncSignature::new_non_branch_ex(
126            vec![ParamSignature::new(segment_arena_ty.clone()).with_allow_add_const()],
127            vec![OutputVarInfo::new_builtin(segment_arena_ty, 0), OutputVarInfo {
128                ty: context.get_wrapped_concrete_type(Felt252DictType::id(), ty)?,
129                ref_info: OutputVarReferenceInfo::Deferred(DeferredOutputKind::Generic),
130            }],
131            SierraApChange::Known { new_vars_only: false },
132        ))
133    }
134}
135
136/// Libfunc for performing a `squash` operation on a dict. Returns a pointer to the squashed dict.
137#[derive(Default)]
138pub struct Felt252DictSquashLibfunc {}
139impl SignatureOnlyGenericLibfunc for Felt252DictSquashLibfunc {
140    const STR_ID: &'static str = "felt252_dict_squash";
141
142    fn specialize_signature(
143        &self,
144        context: &dyn SignatureSpecializationContext,
145        args: &[GenericArg],
146    ) -> Result<LibfuncSignature, SpecializationError> {
147        let generic_ty = args_as_single_type(args)?;
148        let dict_ty =
149            context.get_wrapped_concrete_type(Felt252DictType::id(), generic_ty.clone())?;
150        let squashed_dict_ty =
151            context.get_wrapped_concrete_type(SquashedFelt252DictType::id(), generic_ty)?;
152        let range_check_type = context.get_concrete_type(RangeCheckType::id(), &[])?;
153        let gas_builtin_type = context.get_concrete_type(GasBuiltinType::id(), &[])?;
154        let segment_arena_ty = context.get_concrete_type(SegmentArenaType::id(), &[])?;
155        Ok(LibfuncSignature::new_non_branch(
156            vec![
157                range_check_type.clone(),
158                gas_builtin_type.clone(),
159                segment_arena_ty.clone(),
160                dict_ty,
161            ],
162            vec![
163                OutputVarInfo {
164                    ty: range_check_type,
165                    ref_info: OutputVarReferenceInfo::NewTempVar { idx: 0 },
166                },
167                OutputVarInfo {
168                    ty: gas_builtin_type,
169                    ref_info: OutputVarReferenceInfo::NewTempVar { idx: 1 },
170                },
171                OutputVarInfo {
172                    ty: segment_arena_ty,
173                    ref_info: OutputVarReferenceInfo::NewTempVar { idx: 2 },
174                },
175                OutputVarInfo {
176                    ty: squashed_dict_ty,
177                    ref_info: OutputVarReferenceInfo::NewTempVar { idx: 3 },
178                },
179            ],
180            SierraApChange::Unknown,
181        ))
182    }
183}
184
185/// Type representing an entry access to a felt252_dict.
186#[derive(Default)]
187pub struct Felt252DictEntryTypeWrapped {}
188impl GenericTypeArgGenericType for Felt252DictEntryTypeWrapped {
189    const ID: GenericTypeId = GenericTypeId::new_inline("Felt252DictEntry");
190
191    fn calc_info(
192        &self,
193        context: &dyn TypeSpecializationContext,
194        long_id: crate::program::ConcreteTypeLongId,
195        wrapped_type_info: TypeInfo,
196    ) -> Result<TypeInfo, SpecializationError> {
197        specialize_with_dict_value_param(context, long_id, wrapped_type_info)
198    }
199}
200pub type Felt252DictEntryType = GenericTypeArgGenericTypeWrapper<Felt252DictEntryTypeWrapped>;
201
202define_libfunc_hierarchy! {
203    pub enum Felt252DictEntryLibfunc {
204        Get(Felt252DictEntryGetLibfunc),
205        Finalize(Felt252DictEntryFinalizeLibfunc),
206    }, Felt252DictEntryConcreteLibfunc
207}
208
209/// Libfunc for creating a new felt252_dict_entry, it owns the dictionary until finalized.
210#[derive(Default)]
211pub struct Felt252DictEntryGetLibfuncWrapped {}
212impl SignatureAndTypeGenericLibfunc for Felt252DictEntryGetLibfuncWrapped {
213    const STR_ID: &'static str = "felt252_dict_entry_get";
214
215    fn specialize_signature(
216        &self,
217        context: &dyn SignatureSpecializationContext,
218        ty: ConcreteTypeId,
219    ) -> Result<LibfuncSignature, SpecializationError> {
220        let dict_ty = context.get_wrapped_concrete_type(Felt252DictType::id(), ty.clone())?;
221        let dict_entry_ty =
222            context.get_wrapped_concrete_type(Felt252DictEntryType::id(), ty.clone())?;
223        let felt252_ty = context.get_concrete_type(Felt252Type::id(), &[])?;
224        Ok(LibfuncSignature::new_non_branch_ex(
225            vec![
226                ParamSignature::new(dict_ty).with_allow_add_const(),
227                // Key.
228                ParamSignature::new(felt252_ty),
229            ],
230            vec![
231                OutputVarInfo {
232                    ty: dict_entry_ty,
233                    ref_info: OutputVarReferenceInfo::Deferred(DeferredOutputKind::AddConst {
234                        param_idx: 0,
235                    }),
236                },
237                // Current value.
238                OutputVarInfo {
239                    ty,
240                    ref_info: OutputVarReferenceInfo::Deferred(DeferredOutputKind::Generic),
241                },
242            ],
243            SierraApChange::Known { new_vars_only: true },
244        ))
245    }
246}
247pub type Felt252DictEntryGetLibfunc =
248    WrapSignatureAndTypeGenericLibfunc<Felt252DictEntryGetLibfuncWrapped>;
249
250/// Libfunc for finalizing a felt252_dict_entry, returns the owned dict.
251#[derive(Default)]
252pub struct Felt252DictEntryFinalizeLibfuncWrapped {}
253impl SignatureAndTypeGenericLibfunc for Felt252DictEntryFinalizeLibfuncWrapped {
254    const STR_ID: &'static str = "felt252_dict_entry_finalize";
255
256    fn specialize_signature(
257        &self,
258        context: &dyn SignatureSpecializationContext,
259        ty: ConcreteTypeId,
260    ) -> Result<LibfuncSignature, SpecializationError> {
261        let dict_ty = context.get_wrapped_concrete_type(Felt252DictType::id(), ty.clone())?;
262        let dict_entry_ty =
263            context.get_wrapped_concrete_type(Felt252DictEntryType::id(), ty.clone())?;
264        Ok(LibfuncSignature::new_non_branch_ex(
265            vec![
266                ParamSignature::new(dict_entry_ty).with_allow_add_const(),
267                // New value.
268                ParamSignature::new(ty),
269            ],
270            vec![OutputVarInfo {
271                ty: dict_ty,
272                ref_info: OutputVarReferenceInfo::SameAsParam { param_idx: 0 },
273            }],
274            SierraApChange::Known { new_vars_only: true },
275        ))
276    }
277}
278
279pub type Felt252DictEntryFinalizeLibfunc =
280    WrapSignatureAndTypeGenericLibfunc<Felt252DictEntryFinalizeLibfuncWrapped>;
cairo_lang_sierra/extensions/modules/felt252_dict.rs

cairo_lang_sierra/extensions/modules/
felt252_dict.rs
