feature(cairo): Support Span<T> destructuring via fixed-size array patterns

Add support for `let [a, b] = span else { ... }` syntax by introducing
a SliceDestructure flow control node that calls tuple_from_span to
convert Span<T> to [T; N] at runtime.

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

Author: ilyalesokhin-starkware

corelib/src/test/language_features/match_test.cairo

@@ -12,6 +12,22 @@ fn test_match_multienum_binding() {
     panic!("Match expression did not return - this should be unreachable");
 }
 
+#[test]
+fn test_match_span_to_fixed_size_array() {
+    let span: Span<u32> = array![10, 20, 30].span();
+
+    match span {
+        [_a, _b, _c, _d] => { panic!("Expected 3 elements, but got 4"); },
+        [_a, _b] => { panic!("Expected 3 elements, but got 2"); },
+        [a, b, c] => {
+            assert_eq!(a, @10);
+            assert_eq!(b, @20);
+            assert_eq!(c, @30);
+        },
+        _ => panic!("Expected 3 elements, but got a different pattern"),
+    }
+}
+
 #[test]
 fn test_match_extern_multilevel() {
     if true {

crates/cairo-lang-lowering/src/lower/flow_control/create_graph/patterns.rs

@@ -2,17 +2,23 @@ use cairo_lang_debug::DebugWithDb;
 use cairo_lang_defs::ids::NamedLanguageElementId;
 use cairo_lang_diagnostics::{DiagnosticNote, Maybe};
 use cairo_lang_filesystem::flag::FlagsGroup;
-use cairo_lang_semantic::corelib::{CorelibSemantic, validate_literal};
+use cairo_lang_filesystem::ids::SmolStrId;
+use cairo_lang_semantic::corelib::{
+    CorelibSemantic, get_usize_ty, try_get_core_ty_by_name, validate_literal,
+};
 use cairo_lang_semantic::expr::compute::unwrap_pattern_type;
+use cairo_lang_semantic::items::constant::ConstValue;
 use cairo_lang_semantic::items::enm::SemanticEnumEx;
 use cairo_lang_semantic::items::structure::StructSemantic;
+use cairo_lang_semantic::types::wrap_in_snapshots;
 use cairo_lang_semantic::{
     self as semantic, ConcreteEnumId, ConcreteStructId, ConcreteTypeId, ExprNumericLiteral,
-    PatternEnumVariant, PatternLiteral, PatternStruct, PatternTuple, PatternWrappingInfo, TypeId,
-    TypeLongId, corelib,
+    GenericArgumentId, PatternEnumVariant, PatternLiteral, PatternStruct, PatternTuple,
+    PatternWrappingInfo, TypeId, TypeLongId, corelib,
 };
 use cairo_lang_syntax::node::TypedStablePtr;
 use cairo_lang_syntax::node::ast::ExprPtr;
+use cairo_lang_utils::Intern;
 use cairo_lang_utils::ordered_hash_map::OrderedHashMap;
 use itertools::{Itertools, zip_eq};
 use num_bigint::BigInt;
@@ -26,7 +32,9 @@ use super::filtered_patterns::{Bindings, FilteredPatterns};
 use crate::diagnostic::{LoweringDiagnosticKind, MatchDiagnostic, MatchError};
 use crate::ids::LocationId;
 use crate::lower::context::LoweringContext;
-use crate::lower::flow_control::graph::{Downcast, EqualsLiteral, Upcast, ValueMatch};
+use crate::lower::flow_control::graph::{
+    Downcast, EqualsLiteral, SliceDestructure, Upcast, ValueMatch,
+};
 
 /// A callback that gets a [FilteredPatterns] and constructs a node that continues the pattern
 /// matching restricted to the filtered patterns.
@@ -150,21 +158,6 @@ pub fn create_node_for_patterns<'db>(
             create_node_for_enum(params, input_var, concrete_enum_id, wrapping_info)
         }
         TypeLongId::Concrete(ConcreteTypeId::Struct(concrete_struct_id)) => {
-            // Check if any non-any pattern is a FixedSizeArray (i.e. Span destructure).
-            // Span destructuring in match/if-let is not yet supported in lowering.
-            let has_fixed_size_array_pattern = patterns
-                .iter()
-                .flatten()
-                .any(|p| matches!(p, semantic::Pattern::FixedSizeArray(..)));
-            if has_fixed_size_array_pattern {
-                return graph.report_with_missing_node(
-                    first_non_any_pattern.stable_ptr(),
-                    LoweringDiagnosticKind::MatchError(MatchError {
-                        kind: graph.kind(),
-                        error: MatchDiagnostic::UnsupportedMatchedType(long_ty.format(ctx.db)),
-                    }),
-                );
-            }
             create_node_for_struct(params, input_var, concrete_struct_id, wrapping_info)
         }
         TypeLongId::Tuple(types) => create_node_for_tuple(params, input_var, &types, wrapping_info),
@@ -354,6 +347,19 @@ fn create_node_for_struct<'db>(
 ) -> NodeId {
     let CreateNodeParams { ctx, graph, patterns, build_node_callback, location } = params;
 
+    if let Some(node) = try_create_slice_destructure_chain(
+        ctx,
+        graph,
+        patterns,
+        build_node_callback,
+        location,
+        input_var,
+        concrete_struct_id,
+        wrapping_info,
+    ) {
+        return node;
+    }
+
     let members = match ctx.db.concrete_struct_members(concrete_struct_id) {
         Ok(members) => members,
         Err(diag_added) => return graph.add_node(FlowControlNode::Missing(diag_added)),
@@ -390,6 +396,158 @@ fn create_node_for_struct<'db>(
     }))
 }
 
+/// Tries to create a chain of [`SliceDestructure`] nodes for matching a `Span<T>` against
+/// fixed-size array patterns with different sizes.
+///
+/// Returns `None` if no `FixedSizeArray` patterns are present or the struct is not a `Span`.
+/// Each size is tried in order. On failure, the next size is attempted. If all sizes fail,
+/// the wildcard/otherwise patterns are used.
+#[allow(clippy::too_many_arguments)]
+fn try_create_slice_destructure_chain<'db>(
+    ctx: &LoweringContext<'db, '_>,
+    graph: &mut FlowControlGraphBuilder<'db>,
+    patterns: &[PatternOption<'_, 'db>],
+    build_node_callback: BuildNodeCallback<'db, '_>,
+    location: LocationId<'db>,
+    input_var: FlowControlVar,
+    concrete_struct_id: ConcreteStructId<'db>,
+    wrapping_info: PatternWrappingInfo,
+) -> Option<NodeId> {
+    if !patterns.iter().any(|p| matches!(p, Some(semantic::Pattern::FixedSizeArray(..)))) {
+        return None;
+    }
+    let [GenericArgumentId::Type(elem_ty)] = concrete_struct_id.long(ctx.db).generic_args[..]
+    else {
+        return None;
+    };
+    if try_get_core_ty_by_name(
+        ctx.db,
+        SmolStrId::from(ctx.db, "Span"),
+        vec![GenericArgumentId::Type(elem_ty)],
+    )
+    .is_err()
+    {
+        // Not a Span - report error on the first FixedSizeArray pattern.
+        let first_fsa = patterns.iter().find_map(|p| match p {
+            Some(semantic::Pattern::FixedSizeArray(p)) => Some(p),
+            _ => None,
+        });
+        return Some(graph.report_with_missing_node(
+            first_fsa.unwrap().stable_ptr.untyped(),
+            LoweringDiagnosticKind::UnexpectedError,
+        ));
+    }
+    // Deconstruct Span<T> to get its single member @Array<T>.
+    let members = ctx.db.concrete_struct_members(concrete_struct_id).ok()?;
+    let snapshot_array_ty = members.iter().next().unwrap().1.ty;
+    let snapshot_array_var = graph.new_var(snapshot_array_ty, location);
+
+    // Group patterns by array size. Wildcards/otherwise are added to all groups.
+    // Use an OrderedHashMap to preserve insertion order (first-seen size first).
+    let mut size_groups: OrderedHashMap<usize, SizeGroupInfo<'_, '_>> = OrderedHashMap::default();
+    let mut wildcard_filter = FilteredPatterns::default();
+    // Track accumulated wildcards so newly created size groups inherit earlier wildcards.
+    let mut accumulated_wildcards: Vec<usize> = Vec::new();
+
+    for (idx, pattern) in patterns.iter().enumerate() {
+        match pattern {
+            Some(semantic::Pattern::FixedSizeArray(p)) => {
+                let n = p.elements_patterns.len();
+                let is_new = !size_groups.contains_key(&n);
+                if is_new {
+                    size_groups.insert(n, SizeGroupInfo::default());
+                }
+                let group = size_groups.get_mut(&n).unwrap();
+                if is_new {
+                    // Seed new size group with all previously accumulated wildcards.
+                    for &wc_idx in &accumulated_wildcards {
+                        group.filter.add(wc_idx);
+                        group.patterns.push(None);
+                    }
+                }
+                group.filter.add(idx);
+                group.patterns.push(*pattern);
+            }
+            Some(semantic::Pattern::Otherwise(..)) | None => {
+                wildcard_filter.add(idx);
+                accumulated_wildcards.push(idx);
+                for group in size_groups.values_mut() {
+                    group.filter.add(idx);
+                    group.patterns.push(None);
+                }
+            }
+            _ => unreachable!("Non-FixedSizeArray/Otherwise pattern in slice destructure chain"),
+        }
+    }
+
+    let sizes: Vec<usize> = size_groups.keys().copied().collect();
+
+    // Build the chain from back to front. The final fallback is the wildcard-only callback.
+    let mut failure_node = build_node_callback(graph, wildcard_filter, "[slice_no_match]".into());
+
+    for &size in sizes.iter().rev() {
+        let group = size_groups.swap_remove(&size).unwrap();
+        let n = size;
+        let types = vec![wrap_in_snapshots(ctx.db, elem_ty, 1); n];
+        let inner_vars = types
+            .iter()
+            .map(|ty| graph.new_var(wrapping_info.wrap(ctx.db, *ty), location))
+            .collect_vec();
+
+        // Build the success path: process element patterns within this size group.
+        let group_filter = group.filter;
+        let group_patterns: Vec<PatternOption<'_, 'db>> = group.patterns;
+        let success = create_node_for_tuple_inner(
+            CreateNodeParams {
+                ctx,
+                graph,
+                patterns: &group_patterns,
+                build_node_callback: &mut |graph, pattern_indices, path| {
+                    build_node_callback(
+                        graph,
+                        pattern_indices.lift(&group_filter),
+                        format!("[{path}]"),
+                    )
+                },
+                location,
+            },
+            &inner_vars,
+            &types,
+            0,
+            None,
+        );
+
+        let fixed_array_ty = TypeLongId::FixedSizeArray {
+            type_id: elem_ty,
+            size: ConstValue::Int(n.into(), get_usize_ty(ctx.db)).intern(ctx.db),
+        }
+        .intern(ctx.db);
+
+        failure_node = graph.add_node(FlowControlNode::SliceDestructure(SliceDestructure {
+            input: snapshot_array_var,
+            fixed_array_ty,
+            outputs: inner_vars,
+            success,
+            failure: failure_node,
+        }));
+    }
+
+    // Wrap in a Deconstruct to extract @Array<T> from Span<T> once.
+    let chain = graph.add_node(FlowControlNode::Deconstruct(Deconstruct {
+        input: input_var,
+        outputs: vec![snapshot_array_var],
+        next: failure_node,
+    }));
+
+    Some(chain)
+}
+
+#[derive(Default)]
+struct SizeGroupInfo<'a, 'db> {
+    filter: FilteredPatterns,
+    patterns: Vec<PatternOption<'a, 'db>>,
+}
+
 /// Helper function for [create_node_for_tuple].
 ///
 /// `item_idx` is the index of the current member that is being processed in the tuple.
@@ -444,6 +602,13 @@ fn create_node_for_tuple_inner<'db>(
                     patterns_on_current_item.push(Some(inner_pattern))
                 }
             }
+            Some(semantic::Pattern::FixedSizeArray(semantic::PatternFixedSizeArray {
+                elements_patterns,
+                ..
+            })) if current_member.is_none() => {
+                patterns_on_current_item
+                    .push(Some(get_pattern(ctx, elements_patterns[item_idx]).clone()));
+            }
             Some(
                 pattern @ (semantic::Pattern::StringLiteral(..)
                 | semantic::Pattern::EnumVariant(..)

crates/cairo-lang-lowering/src/lower/flow_control/graph.rs

@@ -224,6 +224,34 @@ pub struct Downcast {
     pub out_of_range: NodeId,
 }
 
+/// Destructures a `@Array<T>` into a fixed-size array `[T; N]` by calling `tuple_from_span`.
+///
+/// On success, the array has exactly `N` elements and the output variables are bound to them.
+/// On failure (wrong number of elements), execution continues to the `failure` node.
+pub struct SliceDestructure<'db> {
+    /// The input `@Array<T>` variable (already extracted from the Span).
+    pub input: FlowControlVar,
+    /// The fixed-size array type `[T; N]`.
+    pub fixed_array_ty: semantic::TypeId<'db>,
+    /// The output element variables (if the slice has the right size).
+    pub outputs: Vec<FlowControlVar>,
+    /// The next node if the slice has the right number of elements.
+    pub success: NodeId,
+    /// The next node if the slice doesn't have the right number of elements.
+    pub failure: NodeId,
+}
+impl Debug for SliceDestructure<'_> {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("SliceDestructure")
+            .field("input", &self.input)
+            .field("n_elements", &self.outputs.len())
+            .field("outputs", &self.outputs)
+            .field("success", &self.success)
+            .field("failure", &self.failure)
+            .finish()
+    }
+}
+
 /// An arm (final node) that returns a tuple of bound variables for the let-else success arm.
 ///
 /// See [crate::lower::lower_let_else::lower_let_else] for more details.
@@ -257,6 +285,8 @@ pub enum FlowControlNode<'db> {
     Upcast(Upcast),
     /// Downcasts a value to a smaller type.
     Downcast(Downcast),
+    /// Unpacks a `Span<T>` into a fixed-size array `[T; N]`.
+    SliceDestructure(SliceDestructure<'db>),
     /// An arm (final node) that returns a tuple of bound variables for the let-else success arm.
     LetElseSuccess(LetElseSuccess<'db>),
     /// An arm (final node) that returns a unit value - `()`.
@@ -285,6 +315,7 @@ impl<'db> FlowControlNode<'db> {
             FlowControlNode::BindVar(node) => Some(node.input),
             FlowControlNode::Upcast(node) => Some(node.input),
             FlowControlNode::Downcast(node) => Some(node.input),
+            FlowControlNode::SliceDestructure(node) => Some(node.input),
             FlowControlNode::LetElseSuccess(..) => None,
             FlowControlNode::UnitResult => None,
             FlowControlNode::Missing(_) => None,
@@ -306,6 +337,7 @@ impl<'db> Debug for FlowControlNode<'db> {
             FlowControlNode::BindVar(node) => node.fmt(f),
             FlowControlNode::Upcast(node) => node.fmt(f),
             FlowControlNode::Downcast(node) => node.fmt(f),
+            FlowControlNode::SliceDestructure(node) => node.fmt(f),
             FlowControlNode::LetElseSuccess(node) => node.fmt(f),
             FlowControlNode::UnitResult => write!(f, "UnitResult"),
             FlowControlNode::Missing(_) => write!(f, "Missing"),