tpy-lang 0.3.0.dev0__py3-none-any.whl

tpyc/_data/runtime/cpp/include/tpy/itertools.hpp

@@ -0,0 +1,749 @@
+/**
+ * TurboPython Runtime - Iterator Builtins
+ *
+ * enumerate(), zip(), reversed(), map(), and filter() implementations.
+ * Depends on: next_iter.hpp, dunder.hpp (for __iter__, __len__, __getitem__)
+ */
+
+#pragma once
+
+#include "next_iter.hpp"
+#include "dunder.hpp"
+#include "type_traits.hpp"
+
+#include <cstdint>
+#include <expected>
+#include <optional>
+#include <tuple>
+
+namespace tpy {
+
+// -- enumerate --
+
+template<typename T, typename Iter>
+class enumerate_iter : public next_iter_mixin<enumerate_iter<T, Iter>, std::tuple<int32_t, T>> {
+    Iter iter_;
+    int32_t index_;  // TPy uses Int32; Python enumerate uses arbitrary-precision
+public:
+    enumerate_iter(Iter&& iter, int32_t start = 0) : iter_(std::move(iter)), index_(start) {}
+
+    std::expected<std::tuple<int32_t, T>, StopIteration> __next__() {
+        auto r = iter_.__next__();
+        if (!r.has_value()) return tpy::make_unexpected(StopIteration{});
+        return std::tuple<int32_t, T>{index_++, unwrap_ref(*r)};
+    }
+
+    enumerate_iter& __iter__() { return *this; }
+
+    friend std::ostream& operator<<(std::ostream& os, const enumerate_iter&) {
+        return os << "<enumerate>";
+    }
+};
+
+// Owning variant: moves the container in so rvalue arguments don't dangle.
+template<typename T, typename Container>
+class owning_enumerate_iter
+    : public next_iter_mixin<owning_enumerate_iter<T, Container>, std::tuple<int32_t, T>> {
+    using Iter = decltype(tpy::__iter__(std::declval<Container&>()));
+    Container owned_;
+    Iter iter_;
+    int32_t index_;
+public:
+    owning_enumerate_iter(Container&& c, int32_t start = 0)
+        : owned_(std::move(c)), iter_(tpy::__iter__(owned_)), index_(start) {}
+
+    // iter_ points into owned_; moving would invalidate it (e.g. for std::array).
+    // Rely on guaranteed copy elision from the factory functions.
+    owning_enumerate_iter(owning_enumerate_iter&&) = delete;
+    owning_enumerate_iter& operator=(owning_enumerate_iter&&) = delete;
+
+    std::expected<std::tuple<int32_t, T>, StopIteration> __next__() {
+        auto r = iter_.__next__();
+        if (!r.has_value()) return tpy::make_unexpected(StopIteration{});
+        return std::tuple<int32_t, T>{index_++, unwrap_ref(*r)};
+    }
+
+    owning_enumerate_iter& __iter__() { return *this; }
+
+    friend std::ostream& operator<<(std::ostream& os, const owning_enumerate_iter&) {
+        return os << "<enumerate>";
+    }
+};
+
+// Direct-iteration variant: uses C++ begin/end to get references to container
+// elements instead of going through __iter__/__next__() which copies.
+template<typename T, typename Container>
+class enumerate_direct_iter
+    : public next_iter_mixin<enumerate_direct_iter<T, Container>,
+                             std::tuple<int32_t, val_or_ref_t<T>>> {
+    using CppIter = decltype(std::declval<Container&>().begin());
+    Container& container_;
+    CppIter it_;
+    CppIter end_;
+    int32_t index_;
+public:
+    enumerate_direct_iter(Container& c, int32_t start = 0)
+        : container_(c), it_(c.begin()), end_(c.end()), index_(start) {}
+
+    std::expected<std::tuple<int32_t, val_or_ref_t<T>>, StopIteration> __next__() {
+        if (it_ == end_) return tpy::make_unexpected(StopIteration{});
+        return std::tuple<int32_t, val_or_ref_t<T>>{index_++, *it_++};
+    }
+
+    enumerate_direct_iter& __iter__() { return *this; }
+
+    friend std::ostream& operator<<(std::ostream& os, const enumerate_direct_iter&) {
+        return os << "<enumerate>";
+    }
+};
+
+// Owning direct-iteration variant for rvalue containers.
+template<typename T, typename Container>
+class owning_enumerate_direct_iter
+    : public next_iter_mixin<owning_enumerate_direct_iter<T, Container>,
+                             std::tuple<int32_t, val_or_ref_t<T>>> {
+    using CppIter = decltype(std::declval<Container&>().begin());
+    Container owned_;
+    CppIter it_;
+    CppIter end_;
+    int32_t index_;
+public:
+    owning_enumerate_direct_iter(Container&& c, int32_t start = 0)
+        : owned_(std::move(c)), it_(owned_.begin()), end_(owned_.end()), index_(start) {}
+
+    owning_enumerate_direct_iter(owning_enumerate_direct_iter&&) = delete;
+    owning_enumerate_direct_iter& operator=(owning_enumerate_direct_iter&&) = delete;
+
+    std::expected<std::tuple<int32_t, val_or_ref_t<T>>, StopIteration> __next__() {
+        if (it_ == end_) return tpy::make_unexpected(StopIteration{});
+        return std::tuple<int32_t, val_or_ref_t<T>>{index_++, *it_++};
+    }
+
+    owning_enumerate_direct_iter& __iter__() { return *this; }
+
+    friend std::ostream& operator<<(std::ostream& os, const owning_enumerate_direct_iter&) {
+        return os << "<enumerate>";
+    }
+};
+
+namespace detail {
+// Requires homogeneous begin/end (same iterator type) so enumerate_direct_iter
+// can store both as CppIter. Excludes next_iter_mixin-derived types whose
+// begin() returns NextIterator<...> but end() returns NextSentinel.
+template<typename T>
+concept has_begin_end = requires(T& t) { t.begin(); t.end(); }
+    && std::same_as<decltype(std::declval<T&>().begin()), decltype(std::declval<T&>().end())>;
+
+// Extract Nth parameter type from a callable (function pointer, lambda, std::function).
+// Used by map_multi_iter to forward Own[T] args as rvalue refs.
+// Generic lambdas (auto params) are not supported -- tpyc always emits
+// monomorphic lambdas with concrete parameter types.
+template<typename F> struct fn_params;
+template<typename R, typename... A> struct fn_params<R(*)(A...)> { using types = std::tuple<A...>; };
+template<typename R, typename... A> struct fn_params<R(&)(A...)> { using types = std::tuple<A...>; };
+template<typename C, typename R, typename... A> struct fn_params<R(C::*)(A...) const> { using types = std::tuple<A...>; };
+template<typename C, typename R, typename... A> struct fn_params<R(C::*)(A...)> { using types = std::tuple<A...>; };
+
+template<typename F>
+concept has_call_op = requires { &std::remove_cvref_t<F>::operator(); };
+
+template<has_call_op F> struct fn_params<F> : fn_params<decltype(&std::remove_cvref_t<F>::operator())> {};
+
+template<typename F, size_t N>
+using fn_param_t = std::tuple_element_t<N, typename fn_params<std::remove_cvref_t<F>>::types>;
+}
+
+// lvalue: direct iteration for containers (preserves references),
+// __iter__/__next__() fallback for TPy iterators
+template<typename T, typename Iterable>
+auto builtin_enumerate(Iterable& iterable) {
+    if constexpr (detail::has_begin_end<Iterable>) {
+        return enumerate_direct_iter<T, Iterable>(iterable);
+    } else {
+        auto iter = tpy::__iter__(iterable);
+        return enumerate_iter<T, decltype(iter)>(std::move(iter));
+    }
+}
+
+// rvalue: own the container to prevent dangling iterators
+template<typename T, typename Iterable>
+    requires (!std::is_lvalue_reference_v<Iterable&&>)
+auto builtin_enumerate(Iterable&& iterable) {
+    if constexpr (detail::has_begin_end<Iterable>) {
+        return owning_enumerate_direct_iter<T, std::remove_cvref_t<Iterable>>(std::move(iterable));
+    } else {
+        return owning_enumerate_iter<T, std::remove_cvref_t<Iterable>>(std::move(iterable));
+    }
+}
+
+// lvalue with start
+template<typename T, typename Iterable>
+auto builtin_enumerate_start(Iterable& iterable, int32_t start) {
+    if constexpr (detail::has_begin_end<Iterable>) {
+        return enumerate_direct_iter<T, Iterable>(iterable, start);
+    } else {
+        auto iter = tpy::__iter__(iterable);
+        return enumerate_iter<T, decltype(iter)>(std::move(iter), start);
+    }
+}
+
+// rvalue with start
+template<typename T, typename Iterable>
+    requires (!std::is_lvalue_reference_v<Iterable&&>)
+auto builtin_enumerate_start(Iterable&& iterable, int32_t start) {
+    if constexpr (detail::has_begin_end<Iterable>) {
+        return owning_enumerate_direct_iter<T, std::remove_cvref_t<Iterable>>(std::move(iterable), start);
+    } else {
+        return owning_enumerate_iter<T, std::remove_cvref_t<Iterable>>(std::move(iterable), start);
+    }
+}
+
+// -- zip (variadic) --
+
+// Tag to carry element types through partial specialization (two-pack workaround).
+template<typename... Ts> struct zip_types {};
+
+namespace detail {
+
+// Advance all iterators into optionals; returns false if any is exhausted.
+// Uses unwrap() to unwrap val_or_ref from native_iterator __next__().
+template<typename Tuple, typename... Opts, std::size_t... Is>
+bool zip_advance(Tuple& iters, std::tuple<Opts...>& opts, std::index_sequence<Is...>) {
+    bool ok = true;
+    // && short-circuits: once ok is false, remaining lambdas are not called.
+    // Matches Python zip() -- stop at shortest without over-advancing.
+    ((ok = ok && [&]{
+        auto r = std::get<Is>(iters).__next__();
+        if (!r.has_value()) return false;
+        std::get<Is>(opts).emplace(tpy::unwrap_ref(*r));
+        return true;
+    }()), ...);
+    return ok;
+}
+
+// Build a tuple by moving out of the optionals.
+template<typename... Ts, std::size_t... Is>
+std::tuple<Ts...> zip_collect(std::tuple<std::optional<Ts>...>& opts, std::index_sequence<Is...>) {
+    return std::tuple<Ts...>{std::move(*std::get<Is>(opts))...};
+}
+
+} // namespace detail
+
+// Primary template (never instantiated directly).
+template<typename TypeTag, typename... Iters>
+class zip_iter;
+
+// Partial specialization unpacks the element types from the tag.
+template<typename... Ts, typename... Iters>
+class zip_iter<zip_types<Ts...>, Iters...>
+    : public next_iter_mixin<zip_iter<zip_types<Ts...>, Iters...>, std::tuple<Ts...>> {
+    std::tuple<Iters...> iters_;
+public:
+    explicit zip_iter(Iters&&... iters) : iters_(std::move(iters)...) {}
+
+    std::expected<std::tuple<Ts...>, StopIteration> __next__() {
+        std::tuple<std::optional<Ts>...> opts;
+        if (!detail::zip_advance(iters_, opts, std::index_sequence_for<Iters...>{}))
+            return tpy::make_unexpected(StopIteration{});
+        return detail::zip_collect<Ts...>(opts, std::index_sequence_for<Ts...>{});
+    }
+
+    zip_iter& __iter__() { return *this; }
+
+    friend std::ostream& operator<<(std::ostream& os, const zip_iter&) {
+        return os << "<zip>";
+    }
+};
+
+template<typename TypeTag, typename... Containers>
+class owning_zip_iter;
+
+template<typename... Ts, typename... Containers>
+class owning_zip_iter<zip_types<Ts...>, Containers...>
+    : public next_iter_mixin<owning_zip_iter<zip_types<Ts...>, Containers...>, std::tuple<Ts...>> {
+    std::tuple<Containers...> owned_;
+    // Store iterators by value (not reference). __iter__() on __next__-based
+    // types (map_iter, etc.) returns Self& -- storing that reference would
+    // dangle after make_iters returns. remove_reference_t copies the iterator.
+    std::tuple<std::remove_reference_t<decltype(tpy::__iter__(std::declval<Containers&>()))>...> iters_;
+
+    template<std::size_t... Is>
+    auto make_iters(std::index_sequence<Is...>) {
+        return std::tuple{tpy::__iter__(std::get<Is>(owned_))...};
+    }
+public:
+    template<typename... Us>
+    explicit owning_zip_iter(Us&&... cs)
+        : owned_(std::forward<Us>(cs)...),
+          iters_(make_iters(std::index_sequence_for<Containers...>{})) {}
+
+    owning_zip_iter(const owning_zip_iter&) = delete;
+    owning_zip_iter& operator=(const owning_zip_iter&) = delete;
+    owning_zip_iter(owning_zip_iter&&) = delete;
+    owning_zip_iter& operator=(owning_zip_iter&&) = delete;
+
+    std::expected<std::tuple<Ts...>, StopIteration> __next__() {
+        std::tuple<std::optional<Ts>...> opts;
+        if (!detail::zip_advance(iters_, opts, std::index_sequence_for<Containers...>{}))
+            return tpy::make_unexpected(StopIteration{});
+        return detail::zip_collect<Ts...>(opts, std::index_sequence_for<Ts...>{});
+    }
+
+    owning_zip_iter& __iter__() { return *this; }
+
+    friend std::ostream& operator<<(std::ostream& os, const owning_zip_iter&) {
+        return os << "<zip>";
+    }
+};
+
+// Direct-iteration zip: uses C++ begin/end for reference-preserving iteration.
+template<typename TypeTag, typename... Containers>
+class zip_direct_iter;
+
+template<typename... Ts, typename... Containers>
+class zip_direct_iter<zip_types<Ts...>, Containers...>
+    : public next_iter_mixin<zip_direct_iter<zip_types<Ts...>, Containers...>,
+                             std::tuple<val_or_ref_t<Ts>...>> {
+    std::tuple<decltype(std::declval<Containers&>().begin())...> its_;
+    std::tuple<decltype(std::declval<Containers&>().end())...> ends_;
+
+    template<std::size_t... Is>
+    bool any_at_end(std::index_sequence<Is...>) const {
+        return ((std::get<Is>(its_) == std::get<Is>(ends_)) || ...);
+    }
+    template<std::size_t... Is>
+    std::tuple<val_or_ref_t<Ts>...> deref_and_advance(std::index_sequence<Is...>) {
+        return std::tuple<val_or_ref_t<Ts>...>{*std::get<Is>(its_)++...};
+    }
+public:
+    explicit zip_direct_iter(Containers&... cs)
+        : its_(cs.begin()...), ends_(cs.end()...) {}
+
+    std::expected<std::tuple<val_or_ref_t<Ts>...>, StopIteration> __next__() {
+        if (any_at_end(std::index_sequence_for<Containers...>{}))
+            return tpy::make_unexpected(StopIteration{});
+        return deref_and_advance(std::index_sequence_for<Containers...>{});
+    }
+
+    zip_direct_iter& __iter__() { return *this; }
+
+    friend std::ostream& operator<<(std::ostream& os, const zip_direct_iter&) {
+        return os << "<zip>";
+    }
+};
+
+// lvalue factory: direct iteration for containers, __iter__ fallback otherwise
+template<typename... Ts, typename... Cs>
+auto builtin_zip(Cs&... cs) {
+    if constexpr ((detail::has_begin_end<Cs> && ...)) {
+        return zip_direct_iter<zip_types<Ts...>, Cs...>(cs...);
+    } else {
+        return zip_iter<zip_types<Ts...>, decltype(tpy::__iter__(cs))...>(tpy::__iter__(cs)...);
+    }
+}
+
+// Mixed factory (at least one rvalue): per-arg own (rvalue) or borrow (lvalue).
+// std::tuple natively supports reference members, so lvalue args store as C&
+// (zero-copy borrow) while rvalue args store as C (moved in).
+template<typename... Ts, typename... Cs>
+    requires ((!std::is_lvalue_reference_v<Cs&&>) || ...)
+auto builtin_zip(Cs&&... cs) {
+    return owning_zip_iter<zip_types<Ts...>,
+        std::conditional_t<std::is_lvalue_reference_v<Cs&&>,
+                           std::remove_reference_t<Cs>&,
+                           std::remove_cvref_t<Cs>>...>(
+        std::forward<Cs>(cs)...);
+}
+
+
+// -- reversed --
+
+template<typename T, typename Seq>
+class reversed_iter : public next_iter_mixin<reversed_iter<T, Seq>, T> {
+    const Seq& seq_;
+    int32_t index_;
+public:
+    reversed_iter(const Seq& seq) : seq_(seq), index_(tpy::__len__(seq) - 1) {}
+
+    std::expected<T, StopIteration> __next__() {
+        if (index_ < 0) return tpy::make_unexpected(StopIteration{});
+        return tpy::__getitem__(seq_, index_--);
+    }
+
+    reversed_iter& __iter__() { return *this; }
+
+    friend std::ostream& operator<<(std::ostream& os, const reversed_iter&) {
+        return os << "<reversed>";
+    }
+};
+
+// Owning variant for rvalue sequences.
+template<typename T, typename Seq>
+class owning_reversed_iter : public next_iter_mixin<owning_reversed_iter<T, Seq>, T> {
+    Seq owned_;
+    int32_t index_;
+public:
+    owning_reversed_iter(Seq&& seq) : owned_(std::move(seq)), index_(tpy::__len__(owned_) - 1) {}
+
+    owning_reversed_iter(owning_reversed_iter&&) = delete;
+    owning_reversed_iter& operator=(owning_reversed_iter&&) = delete;
+
+    std::expected<T, StopIteration> __next__() {
+        if (index_ < 0) return tpy::make_unexpected(StopIteration{});
+        return tpy::__getitem__(owned_, index_--);
+    }
+
+    owning_reversed_iter& __iter__() { return *this; }
+
+    friend std::ostream& operator<<(std::ostream& os, const owning_reversed_iter&) {
+        return os << "<reversed>";
+    }
+};
+
+// lvalue: store reference (container outlives the loop)
+template<typename T, typename Seq>
+auto builtin_reversed(const Seq& seq) {
+    return reversed_iter<T, Seq>(seq);
+}
+
+// rvalue: own the container
+template<typename T, typename Seq>
+    requires (!std::is_lvalue_reference_v<Seq&&>)
+auto builtin_reversed(Seq&& seq) {
+    return owning_reversed_iter<T, std::remove_cvref_t<Seq>>(std::move(seq));
+}
+
+
+// -- map --
+
+template<typename U, typename Iter, typename Fn>
+class map_iter : public next_iter_mixin<map_iter<U, Iter, Fn>, U> {
+    Iter iter_;
+    Fn fn_;
+public:
+    map_iter(Iter&& iter, Fn fn)
+        : iter_(std::move(iter)), fn_(std::move(fn)) {}
+
+    std::expected<U, StopIteration> __next__() {
+        auto r = iter_.__next__();
+        if (!r.has_value()) return tpy::make_unexpected(StopIteration{});
+        return fn_(unwrap_ref(*r));
+    }
+
+    map_iter& __iter__() { return *this; }
+
+    friend std::ostream& operator<<(std::ostream& os, const map_iter&) {
+        return os << "<map>";
+    }
+};
+
+// Owning variant: moves the container in so rvalue arguments don't dangle.
+template<typename U, typename Container, typename Fn>
+class owning_map_iter
+    : public next_iter_mixin<owning_map_iter<U, Container, Fn>, U> {
+    using Iter = decltype(tpy::__iter__(std::declval<Container&>()));
+    Container owned_;
+    Iter iter_;
+    Fn fn_;
+public:
+    owning_map_iter(Fn fn, Container&& c)
+        : owned_(std::move(c)), iter_(tpy::__iter__(owned_)), fn_(std::move(fn)) {}
+
+    owning_map_iter(owning_map_iter&&) = delete;
+    owning_map_iter& operator=(owning_map_iter&&) = delete;
+
+    std::expected<U, StopIteration> __next__() {
+        auto r = iter_.__next__();
+        if (!r.has_value()) return tpy::make_unexpected(StopIteration{});
+        return fn_(unwrap_ref(*r));
+    }
+
+    owning_map_iter& __iter__() { return *this; }
+
+    friend std::ostream& operator<<(std::ostream& os, const owning_map_iter&) {
+        return os << "<map>";
+    }
+};
+
+// lvalue: iterate via __iter__/__next__() protocol.
+// T is the input element type -- unused in the body but required by the codegen
+// template syntax (::tpy::builtin_map<{T}, {U}>).
+template<typename T, typename U, typename Fn, typename Iterable>
+auto builtin_map(Fn&& fn, Iterable& iterable) {
+    auto iter = tpy::__iter__(iterable);
+    return map_iter<U, decltype(iter), std::decay_t<Fn>>(
+        std::move(iter), std::forward<Fn>(fn));
+}
+
+// rvalue: own the container to prevent dangling iterators
+template<typename T, typename U, typename Fn, typename Iterable>
+    requires (!std::is_lvalue_reference_v<Iterable&&>)
+auto builtin_map(Fn&& fn, Iterable&& iterable) {
+    return owning_map_iter<U, std::remove_cvref_t<Iterable>, std::decay_t<Fn>>(
+        std::forward<Fn>(fn), std::move(iterable));
+}
+
+
+// -- map_multi (N-iterable, variadic) --
+
+template<typename U, typename Fn, typename IterTuple>
+class map_multi_iter : public next_iter_mixin<map_multi_iter<U, Fn, IterTuple>, U> {
+    IterTuple iters_;
+    Fn fn_;
+
+    template<size_t... Is>
+    std::expected<U, StopIteration> call_next(std::index_sequence<Is...>) {
+        // Brace-init guarantees left-to-right evaluation order
+        auto results = std::tuple{std::get<Is>(iters_).__next__()...};
+        if ((!std::get<Is>(results).has_value() || ...))
+            return tpy::make_unexpected(StopIteration{});
+        // static_cast forwards Own[T] args (Point&&) as rvalues, others as lvalues
+        return fn_(static_cast<detail::fn_param_t<Fn, Is>>(unwrap_ref(*std::get<Is>(results)))...);
+    }
+
+public:
+    map_multi_iter(IterTuple&& iters, Fn fn)
+        : iters_(std::move(iters)), fn_(std::move(fn)) {}
+
+    std::expected<U, StopIteration> __next__() {
+        return call_next(std::make_index_sequence<std::tuple_size_v<IterTuple>>{});
+    }
+
+    map_multi_iter& __iter__() { return *this; }
+
+    friend std::ostream& operator<<(std::ostream& os, const map_multi_iter&) {
+        return os << "<map>";
+    }
+};
+
+template<typename U, typename Fn, typename... Containers>
+class owning_map_multi_iter
+    : public next_iter_mixin<owning_map_multi_iter<U, Fn, Containers...>, U> {
+    using IterTuple = std::tuple<decltype(tpy::__iter__(std::declval<Containers&>()))...>;
+    std::tuple<Containers...> owned_;
+    IterTuple iters_;
+    Fn fn_;
+
+    template<size_t... Is>
+    static IterTuple make_iters(std::tuple<Containers...>& owned, std::index_sequence<Is...>) {
+        return IterTuple{tpy::__iter__(std::get<Is>(owned))...};
+    }
+
+    template<size_t... Is>
+    std::expected<U, StopIteration> call_next(std::index_sequence<Is...>) {
+        auto results = std::tuple{std::get<Is>(iters_).__next__()...};
+        if ((!std::get<Is>(results).has_value() || ...))
+            return tpy::make_unexpected(StopIteration{});
+        return fn_(static_cast<detail::fn_param_t<Fn, Is>>(unwrap_ref(*std::get<Is>(results)))...);
+    }
+
+public:
+    template<typename... CCs>
+    owning_map_multi_iter(Fn fn, CCs&&... cs)
+        : owned_{std::forward<CCs>(cs)...},
+          iters_(make_iters(owned_, std::index_sequence_for<Containers...>{})),
+          fn_(std::move(fn)) {}
+
+    owning_map_multi_iter(owning_map_multi_iter&&) = delete;
+    owning_map_multi_iter& operator=(owning_map_multi_iter&&) = delete;
+
+    std::expected<U, StopIteration> __next__() {
+        return call_next(std::index_sequence_for<Containers...>{});
+    }
+
+    owning_map_multi_iter& __iter__() { return *this; }
+
+    friend std::ostream& operator<<(std::ostream& os, const owning_map_multi_iter&) {
+        return os << "<map>";
+    }
+};
+
+// Variadic factory: lvalue (all iterables are lvalue references)
+template<typename U, typename Fn, typename... Its>
+auto builtin_map_n(Fn&& fn, Its&... its) {
+    auto iters = std::tuple{tpy::__iter__(its)...};
+    return map_multi_iter<U, std::decay_t<Fn>, decltype(iters)>(
+        std::move(iters), std::forward<Fn>(fn));
+}
+
+// Variadic factory: rvalue (at least one iterable is an rvalue)
+template<typename U, typename Fn, typename... Its>
+    requires ((!std::is_lvalue_reference_v<Its&&>) || ...)
+auto builtin_map_n(Fn&& fn, Its&&... its) {
+    return owning_map_multi_iter<U, std::decay_t<Fn>, std::remove_cvref_t<Its>...>(
+        std::forward<Fn>(fn), std::forward<Its>(its)...);
+}
+
+
+// -- filter --
+
+template<typename T, typename Iter, typename Fn>
+class filter_iter : public next_iter_mixin<filter_iter<T, Iter, Fn>, T> {
+    Iter iter_;
+    Fn fn_;
+public:
+    filter_iter(Iter&& iter, Fn fn)
+        : iter_(std::move(iter)), fn_(std::move(fn)) {}
+
+    std::expected<T, StopIteration> __next__() {
+        while (true) {
+            auto r = iter_.__next__();
+            if (!r.has_value()) return tpy::make_unexpected(StopIteration{});
+            auto&& elem = unwrap_ref(*r);
+            if (fn_(elem)) {
+                return elem;
+            }
+        }
+    }
+
+    filter_iter& __iter__() { return *this; }
+
+    friend std::ostream& operator<<(std::ostream& os, const filter_iter&) {
+        return os << "<filter>";
+    }
+};
+
+// Owning variant for rvalue iterables (protocol path).
+template<typename T, typename Container, typename Fn>
+class owning_filter_iter
+    : public next_iter_mixin<owning_filter_iter<T, Container, Fn>, T> {
+    using Iter = decltype(tpy::__iter__(std::declval<Container&>()));
+    Container owned_;
+    Iter iter_;
+    Fn fn_;
+public:
+    owning_filter_iter(Fn fn, Container&& c)
+        : owned_(std::move(c)), iter_(tpy::__iter__(owned_)), fn_(std::move(fn)) {}
+
+    owning_filter_iter(owning_filter_iter&&) = delete;
+    owning_filter_iter& operator=(owning_filter_iter&&) = delete;
+
+    std::expected<T, StopIteration> __next__() {
+        while (true) {
+            auto r = iter_.__next__();
+            if (!r.has_value()) return tpy::make_unexpected(StopIteration{});
+            auto&& elem = unwrap_ref(*r);
+            if (fn_(elem)) {
+                return elem;
+            }
+        }
+    }
+
+    owning_filter_iter& __iter__() { return *this; }
+
+    friend std::ostream& operator<<(std::ostream& os, const owning_filter_iter&) {
+        return os << "<filter>";
+    }
+};
+
+// Direct-iteration variant: uses C++ begin/end for reference-preserving filter.
+// Returns val_or_ref<T> so non-value types yield references into the container.
+template<typename T, typename Container, typename Fn>
+class filter_direct_iter
+    : public next_iter_mixin<filter_direct_iter<T, Container, Fn>, val_or_ref<T>> {
+    using CppIter = decltype(std::declval<Container&>().begin());
+    CppIter it_;
+    CppIter end_;
+    Fn fn_;
+public:
+    filter_direct_iter(Fn fn, Container& c)
+        : it_(c.begin()), end_(c.end()), fn_(std::move(fn)) {}
+
+    std::expected<val_or_ref<T>, StopIteration> __next__() {
+        while (it_ != end_) {
+            auto& elem = *it_;
+            ++it_;
+            if (fn_(elem)) {
+                return val_or_ref<T>(elem);
+            }
+        }
+        return tpy::make_unexpected(StopIteration{});
+    }
+
+    filter_direct_iter& __iter__() { return *this; }
+
+    friend std::ostream& operator<<(std::ostream& os, const filter_direct_iter&) {
+        return os << "<filter>";
+    }
+};
+
+// Owning direct-iteration variant for rvalue containers.
+template<typename T, typename Container, typename Fn>
+class owning_filter_direct_iter
+    : public next_iter_mixin<owning_filter_direct_iter<T, Container, Fn>, val_or_ref<T>> {
+    using CppIter = decltype(std::declval<Container&>().begin());
+    Container owned_;
+    CppIter it_;
+    CppIter end_;
+    Fn fn_;
+public:
+    owning_filter_direct_iter(Fn fn, Container&& c)
+        : owned_(std::move(c)), it_(owned_.begin()), end_(owned_.end()),
+          fn_(std::move(fn)) {}
+
+    owning_filter_direct_iter(owning_filter_direct_iter&&) = delete;
+    owning_filter_direct_iter& operator=(owning_filter_direct_iter&&) = delete;
+
+    std::expected<val_or_ref<T>, StopIteration> __next__() {
+        while (it_ != end_) {
+            auto& elem = *it_;
+            ++it_;
+            if (fn_(elem)) {
+                return val_or_ref<T>(elem);
+            }
+        }
+        return tpy::make_unexpected(StopIteration{});
+    }
+
+    owning_filter_direct_iter& __iter__() { return *this; }
+
+    friend std::ostream& operator<<(std::ostream& os, const owning_filter_direct_iter&) {
+        return os << "<filter>";
+    }
+};
+
+// lvalue: direct iteration for containers (preserves references),
+// __iter__/__next__() fallback for TPy iterators
+template<typename T, typename Fn, typename Iterable>
+auto builtin_filter(Fn&& fn, Iterable& iterable) {
+    if constexpr (detail::has_begin_end<Iterable>) {
+        return filter_direct_iter<T, Iterable, std::decay_t<Fn>>(
+            std::forward<Fn>(fn), iterable);
+    } else {
+        auto iter = tpy::__iter__(iterable);
+        return filter_iter<T, decltype(iter), std::decay_t<Fn>>(
+            std::move(iter), std::forward<Fn>(fn));
+    }
+}
+
+// rvalue: own the container to prevent dangling iterators
+template<typename T, typename Fn, typename Iterable>
+    requires (!std::is_lvalue_reference_v<Iterable&&>)
+auto builtin_filter(Fn&& fn, Iterable&& iterable) {
+    if constexpr (detail::has_begin_end<Iterable>) {
+        return owning_filter_direct_iter<T, std::remove_cvref_t<Iterable>,
+                                         std::decay_t<Fn>>(
+            std::forward<Fn>(fn), std::move(iterable));
+    } else {
+        return owning_filter_iter<T, std::remove_cvref_t<Iterable>,
+                                  std::decay_t<Fn>>(
+            std::forward<Fn>(fn), std::move(iterable));
+    }
+}
+
+// -- filter(None, ...) -- truthy filtering via to_bool
+
+template<typename T, typename Iterable>
+auto builtin_filter_truthy(Iterable& iterable) {
+    auto pred = [](const auto& x) -> bool { return to_bool(x); };
+    return builtin_filter<T>(pred, iterable);
+}
+
+template<typename T, typename Iterable>
+    requires (!std::is_lvalue_reference_v<Iterable&&>)
+auto builtin_filter_truthy(Iterable&& iterable) {
+    auto pred = [](const auto& x) -> bool { return to_bool(x); };
+    return builtin_filter<T>(pred, std::move(iterable));
+}
+
+} // namespace tpy