Introduce the 'flatten' built-in method

Introduce the method in the 'Iterable' type.

Author: HugoGGuerrier

lkql_jit/language/src/main/java/com/adacore/lkql_jit/built_ins/methods/IterableMethods.java

@@ -13,6 +13,7 @@
 import com.adacore.lkql_jit.runtime.values.interfaces.Iterable;
 import com.adacore.lkql_jit.runtime.values.interfaces.Iterator;
 import com.adacore.lkql_jit.runtime.values.lists.BaseLKQLLazyList;
+import com.adacore.lkql_jit.runtime.values.lists.LKQLFlattenResult;
 import com.adacore.lkql_jit.runtime.values.lists.LKQLList;
 import com.adacore.lkql_jit.runtime.values.lists.LKQLMapResult;
 import com.adacore.lkql_jit.utils.Constants;
@@ -105,4 +106,19 @@ protected BaseLKQLLazyList onIterable(
             return new LKQLMapResult(iterable, function, functionLibrary);
         }
     }
+
+    @BuiltInMethod(
+        name = "flatten",
+        doc = """
+        Given an iterable of iterables, flatten all of them in a resulting iterable value. The \
+        returned value is lazy.""",
+        isProperty = true
+    )
+    abstract static class FlattenExpr extends BuiltInBody {
+
+        @Specialization
+        protected BaseLKQLLazyList onIterable(Iterable iterable) {
+            return new LKQLFlattenResult(iterable);
+        }
+    }
 }

lkql_jit/language/src/main/java/com/adacore/lkql_jit/runtime/values/lists/LKQLFlattenResult.java

@@ -0,0 +1,73 @@
+//
+//  Copyright (C) 2005-2025, AdaCore
+//  SPDX-License-Identifier: GPL-3.0-or-later
+//
+
+package com.adacore.lkql_jit.runtime.values.lists;
+
+import com.adacore.lkql_jit.exception.LKQLRuntimeException;
+import com.adacore.lkql_jit.runtime.ListStorage;
+import com.adacore.lkql_jit.runtime.values.interfaces.Iterable;
+import com.adacore.lkql_jit.runtime.values.interfaces.Iterator;
+import com.adacore.lkql_jit.utils.LKQLTypesHelper;
+
+public final class LKQLFlattenResult extends BaseLKQLLazyList {
+
+    /** Collection that is flatten. */
+    private final Iterator generatorIterator;
+
+    /** Iterator used to go though inner collections. */
+    private Iterator innerIterator;
+
+    // ----- Constructors -----
+
+    public LKQLFlattenResult(Iterable generator) {
+        super(new ListStorage<>(32));
+        this.generatorIterator = generator.iterator();
+    }
+
+    // ----- Lazy list required methods -----
+
+    @Override
+    protected void initCacheTo(long n) {
+        if (n >= this.cache.size() || n < 0) {
+            Object next;
+            do {
+                next = this.nextElem();
+                if (next != null) {
+                    this.cache.append(next);
+                }
+            } while (next != null && (n >= this.cache.size() || n < 0));
+        }
+    }
+
+    // ----- Instance methods -----
+
+    /**
+     * Util function to get the next element in the current inner collection.
+     * If there is no more elements in the current inner collection, this
+     * function fetch the next one.
+     * If there is no more inner collection, this function returns null.
+     */
+    private Object nextElem() {
+        // Ensure the inner iterator is initialized and has a next element
+        while (this.innerIterator == null || !this.innerIterator.hasNext()) {
+            if (!this.generatorIterator.hasNext()) {
+                return null;
+            }
+            var nextInner = this.generatorIterator.next();
+            if (nextInner instanceof Iterable nextInnerIterable) {
+                this.innerIterator = nextInnerIterable.iterator();
+            } else {
+                throw LKQLRuntimeException.wrongType(
+                    LKQLTypesHelper.LKQL_ITERABLE,
+                    LKQLTypesHelper.fromJava(nextInner),
+                    null
+                );
+            }
+        }
+
+        // Finally return the next element
+        return this.innerIterator.next();
+    }
+}

testsuite/tests/interpreter/builtins/flatten/script.lkql

@@ -0,0 +1,20 @@
+# Perform a simple flattening operation
+val inner = [1, 2, 3]
+val lst_1 = [inner, inner, inner]
+print(lst_1.flatten.to_list)
+
+# Ensure flattening is lazy
+fun double(x) = {
+    print("Computing double of " & x.img);
+    x * 2
+}
+val lst_2 = [[1, 2, 3].map(double), [4, 5, 6].map(double)].flatten
+print(lst_2[2])
+print(lst_2[5])
+print(lst_2[4])
+
+# Ensure there is an error when calling "flatten" on a list of non-iterables
+val lst_3 = [[1, 2, 3], "what?"].flatten
+print(lst_3[1])
+print(lst_3[3])
+print(lst_3[4])

testsuite/tests/interpreter/builtins/flatten/test.out

@@ -0,0 +1,12 @@
+[1, 2, 3, 1, 2, 3, 1, 2, 3]
+Computing double of 1
+Computing double of 2
+4
+Computing double of 3
+Computing double of 4
+Computing double of 5
+10
+8
+1
+3
+error: Type error: expected Iterable but got Str

testsuite/tests/interpreter/builtins/flatten/test.yaml

@@ -0,0 +1,3 @@
+driver: 'interpreter'
+project: 'default_project/default.gpr'
+lkt_refactor: True

user_manual/generated/std.rst

@@ -173,6 +173,10 @@ Methods for `LazyList`
 
     Return the content of the iterable object with each element associated to its index in a tuple: [(<index>, <elem>), ...]
 
+.. method:: LazyList.flatten(this)
+
+    Given an iterable of iterables, flatten all of them in a resulting iterable value. The returned value is lazy.
+
 .. method:: LazyList.help(this)
 
     Print formatted help for the given object
@@ -216,6 +220,10 @@ Methods for `List`
 
     Return the content of the iterable object with each element associated to its index in a tuple: [(<index>, <elem>), ...]
 
+.. method:: List.flatten(this)
+
+    Given an iterable of iterables, flatten all of them in a resulting iterable value. The returned value is lazy.
+
 .. method:: List.help(this)
 
     Print formatted help for the given object
@@ -535,6 +543,10 @@ Methods for `SelectorList`
 
     Return the content of the iterable object with each element associated to its index in a tuple: [(<index>, <elem>), ...]
 
+.. method:: SelectorList.flatten(this)
+
+    Given an iterable of iterables, flatten all of them in a resulting iterable value. The returned value is lazy.
+
 .. method:: SelectorList.help(this)
 
     Print formatted help for the given object