From 8b5e3e910be9db6fa3e462ff1d05f6d355ab103d Mon Sep 17 00:00:00 2001
From: adienes <51664769+adienes@users.noreply.github.com>
Date: Mon, 7 Aug 2023 14:40:48 -0400
Subject: [PATCH] add warning to `Iterators.filter` about assumptions on
 predicate (#50497)

addresses #50440
---
 base/iterators.jl | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/base/iterators.jl b/base/iterators.jl
index 11e94d3384de8..14f4f0681d629 100644
--- a/base/iterators.jl
+++ b/base/iterators.jl
@@ -491,6 +491,15 @@ invocation of `filter`. Calls to `flt` will be made when iterating over the
 returned iterable object. These calls are not cached and repeated calls will be
 made when reiterating.
 
+!!! warning
+    Subsequent *lazy* transformations on the iterator returned from `filter`, such
+    as those performed by `Iterators.reverse` or `cycle`, will also delay calls to `flt`
+    until collecting or iterating over the returned iterable object. If the filter
+    predicate is nondeterministic or its return values depend on the order of iteration
+    over the elements of `itr`, composition with lazy transformations may result in
+    surprising behavior. If this is undesirable, either ensure that `flt` is a pure
+    function or collect intermediate `filter` iterators before further transformations.
+
 See [`Base.filter`](@ref) for an eager implementation of filtering for arrays.
 
 # Examples