From c0fda15c3b47494d54c7488d8679a84cf9cdaf5a Mon Sep 17 00:00:00 2001
From: Sergei <sleepytomcat@gmail.com>
Date: Tue, 13 Jul 2021 23:22:09 -0700
Subject: [PATCH] Adding Traversable<T>.tapEach(Consumer<? super T>)

---
 .../io/vavr/collection/AbstractMultimap.java  |  5 ++
 src/main/java/io/vavr/collection/Array.java   | 10 +++
 src/main/java/io/vavr/collection/BitSet.java  |  5 ++
 src/main/java/io/vavr/collection/CharSeq.java |  9 +++
 .../java/io/vavr/collection/Collections.java  |  8 +++
 src/main/java/io/vavr/collection/HashMap.java |  5 ++
 src/main/java/io/vavr/collection/HashSet.java |  5 ++
 .../java/io/vavr/collection/Iterator.java     |  5 ++
 .../java/io/vavr/collection/LinearSeq.java    |  3 +
 .../io/vavr/collection/LinkedHashMap.java     |  5 ++
 .../io/vavr/collection/LinkedHashSet.java     |  5 ++
 src/main/java/io/vavr/collection/List.java    |  5 ++
 .../io/vavr/collection/PriorityQueue.java     |  9 +--
 src/main/java/io/vavr/collection/Queue.java   |  5 ++
 src/main/java/io/vavr/collection/Seq.java     |  3 +
 src/main/java/io/vavr/collection/Set.java     |  3 +
 src/main/java/io/vavr/collection/Stream.java  |  5 ++
 .../java/io/vavr/collection/Traversable.java  |  3 +
 src/main/java/io/vavr/collection/Tree.java    |  5 ++
 src/main/java/io/vavr/collection/TreeMap.java |  5 ++
 src/main/java/io/vavr/collection/TreeSet.java |  5 ++
 src/main/java/io/vavr/collection/Vector.java  |  5 ++
 .../collection/AbstractTraversableTest.java   | 66 +++++++++++++++++++
 src/test/java/io/vavr/collection/IntMap.java  |  5 ++
 .../java/io/vavr/collection/IntMultimap.java  |  5 ++
 25 files changed, 190 insertions(+), 4 deletions(-)

diff --git a/src/main/java/io/vavr/collection/AbstractMultimap.java b/src/main/java/io/vavr/collection/AbstractMultimap.java
index 67f63cbf4..a764e6389 100644
--- a/src/main/java/io/vavr/collection/AbstractMultimap.java
+++ b/src/main/java/io/vavr/collection/AbstractMultimap.java
@@ -441,6 +441,11 @@ public M peek(Consumer<? super Tuple2<K, V>> action) {
         return (M) this;
     }
 
+    @Override
+    public M tapEach(Consumer<? super Tuple2<K, V>> action) {
+        return peek(action);
+    }
+
     @SuppressWarnings("unchecked")
     @Override
     public M replace(Tuple2<K, V> currentElement, Tuple2<K, V> newElement) {
diff --git a/src/main/java/io/vavr/collection/Array.java b/src/main/java/io/vavr/collection/Array.java
index 76d59b19d..2da85834b 100644
--- a/src/main/java/io/vavr/collection/Array.java
+++ b/src/main/java/io/vavr/collection/Array.java
@@ -1069,6 +1069,16 @@ public Array<T> peek(Consumer<? super T> action) {
         return this;
     }
 
+    @Override
+    public Array<T> tapEach(Consumer<? super T> action) {
+        Objects.requireNonNull(action, "action is null");
+        for (int i = 0; i < length(); i++) {
+            final T value = get(i);
+            action.accept(value);
+        }
+        return this;
+    }
+
     @Override
     public Array<Array<T>> permutations() {
         if (isEmpty()) {
diff --git a/src/main/java/io/vavr/collection/BitSet.java b/src/main/java/io/vavr/collection/BitSet.java
index 14987311d..f763938fb 100644
--- a/src/main/java/io/vavr/collection/BitSet.java
+++ b/src/main/java/io/vavr/collection/BitSet.java
@@ -475,6 +475,11 @@ public final BitSet<T> peek(Consumer<? super T> action) {
         return this;
     }
 
+    @Override
+    public final BitSet<T> tapEach(Consumer<? super T> action) {
+        return Collections.tapEach(this, action);
+    }
+    
     @Override
     public final String stringPrefix() {
         return "BitSet";
diff --git a/src/main/java/io/vavr/collection/CharSeq.java b/src/main/java/io/vavr/collection/CharSeq.java
index fe49c11cb..6154974f5 100644
--- a/src/main/java/io/vavr/collection/CharSeq.java
+++ b/src/main/java/io/vavr/collection/CharSeq.java
@@ -746,6 +746,15 @@ public CharSeq peek(Consumer<? super Character> action) {
         return this;
     }
 
+    @Override
+    public CharSeq tapEach(Consumer<? super Character> action) {
+        Objects.requireNonNull(action, "action is null");
+        for (int i = 0; i < back.length(); i++) {
+            action.accept(get(i));
+        }
+        return this;
+    }
+
     @Override
     public IndexedSeq<CharSeq> permutations() {
         if (isEmpty()) {
diff --git a/src/main/java/io/vavr/collection/Collections.java b/src/main/java/io/vavr/collection/Collections.java
index a58171ea9..7775916a9 100644
--- a/src/main/java/io/vavr/collection/Collections.java
+++ b/src/main/java/io/vavr/collection/Collections.java
@@ -589,4 +589,12 @@ Object[] toArray() {
         }
     }
 
+    @SuppressWarnings("unchecked")
+    static <T, C extends Traversable<T>> C tapEach(C source, Consumer<? super T> action) {
+        Objects.requireNonNull(action, "action must not be null");
+        return (C) source.map(t -> {
+            action.accept(t);
+            return t;
+        });
+    }
 }
diff --git a/src/main/java/io/vavr/collection/HashMap.java b/src/main/java/io/vavr/collection/HashMap.java
index e6197517a..d6d3da4c7 100644
--- a/src/main/java/io/vavr/collection/HashMap.java
+++ b/src/main/java/io/vavr/collection/HashMap.java
@@ -735,6 +735,11 @@ public HashMap<K, V> peek(Consumer<? super Tuple2<K, V>> action) {
         return Maps.peek(this, action);
     }
 
+    @Override
+    public HashMap<K, V> tapEach(Consumer<? super Tuple2<K, V>> action) {
+        return Collections.tapEach(this, action);
+    }
+
     @Override
     public <U extends V> HashMap<K, V> put(K key, U value, BiFunction<? super V, ? super U, ? extends V> merge) {
         return Maps.put(this, key, value, merge);
diff --git a/src/main/java/io/vavr/collection/HashSet.java b/src/main/java/io/vavr/collection/HashSet.java
index 6c8fd6a94..21f63098b 100644
--- a/src/main/java/io/vavr/collection/HashSet.java
+++ b/src/main/java/io/vavr/collection/HashSet.java
@@ -735,6 +735,11 @@ public HashSet<T> peek(Consumer<? super T> action) {
         return this;
     }
 
+    @Override
+    public HashSet<T> tapEach(Consumer<? super T> action) {
+        return Collections.tapEach(this, action);
+    }
+
     @Override
     public HashSet<T> remove(T element) {
         final HashArrayMappedTrie<T, T> newTree = tree.remove(element);
diff --git a/src/main/java/io/vavr/collection/Iterator.java b/src/main/java/io/vavr/collection/Iterator.java
index 4034e310a..4989034eb 100644
--- a/src/main/java/io/vavr/collection/Iterator.java
+++ b/src/main/java/io/vavr/collection/Iterator.java
@@ -1747,6 +1747,11 @@ public T next() {
         }
     }
 
+    @Override
+    default Iterator<T> tapEach(Consumer<? super T> action) {
+        return peek(action);
+    }
+
     @Override
     default T reduceLeft(BiFunction<? super T, ? super T, ? extends T> op) {
         Objects.requireNonNull(op, "op is null");
diff --git a/src/main/java/io/vavr/collection/LinearSeq.java b/src/main/java/io/vavr/collection/LinearSeq.java
index f401998f3..83ddde809 100644
--- a/src/main/java/io/vavr/collection/LinearSeq.java
+++ b/src/main/java/io/vavr/collection/LinearSeq.java
@@ -214,6 +214,9 @@ default int lastIndexWhere(Predicate<? super T> predicate, int end) {
     @Override
     LinearSeq<T> peek(Consumer<? super T> action);
 
+    @Override
+    LinearSeq<T> tapEach(Consumer<? super T> action);
+
     @Override
     LinearSeq<? extends LinearSeq<T>> permutations();
 
diff --git a/src/main/java/io/vavr/collection/LinkedHashMap.java b/src/main/java/io/vavr/collection/LinkedHashMap.java
index c2d3a7961..0cab919ff 100644
--- a/src/main/java/io/vavr/collection/LinkedHashMap.java
+++ b/src/main/java/io/vavr/collection/LinkedHashMap.java
@@ -755,6 +755,11 @@ public LinkedHashMap<K, V> peek(Consumer<? super Tuple2<K, V>> action) {
         return Maps.peek(this, action);
     }
 
+    @Override
+    public LinkedHashMap<K, V> tapEach(Consumer<? super Tuple2<K, V>> action) {
+        return Collections.tapEach(this, action);
+    }
+
     @Override
     public <U extends V> LinkedHashMap<K, V> put(K key, U value, BiFunction<? super V, ? super U, ? extends V> merge) {
         return Maps.put(this, key, value, merge);
diff --git a/src/main/java/io/vavr/collection/LinkedHashSet.java b/src/main/java/io/vavr/collection/LinkedHashSet.java
index a77e0ea36..90cf61f7f 100644
--- a/src/main/java/io/vavr/collection/LinkedHashSet.java
+++ b/src/main/java/io/vavr/collection/LinkedHashSet.java
@@ -756,6 +756,11 @@ public LinkedHashSet<T> peek(Consumer<? super T> action) {
         return this;
     }
 
+    @Override
+    public LinkedHashSet<T> tapEach(Consumer<? super T> action) {
+        return Collections.tapEach(this, action);
+    }
+
     @Override
     public LinkedHashSet<T> remove(T element) {
         final LinkedHashMap<T, Object> newMap = map.remove(element);
diff --git a/src/main/java/io/vavr/collection/List.java b/src/main/java/io/vavr/collection/List.java
index 23ce0bbcd..cb3c31101 100644
--- a/src/main/java/io/vavr/collection/List.java
+++ b/src/main/java/io/vavr/collection/List.java
@@ -1116,6 +1116,11 @@ public final List<T> peek(Consumer<? super T> action) {
         return this;
     }
 
+    @Override
+    public List<T> tapEach(Consumer<? super T> action) {
+        return Collections.tapEach(this, action);
+    }
+
     @Override
     public final List<List<T>> permutations() {
         if (isEmpty()) {
diff --git a/src/main/java/io/vavr/collection/PriorityQueue.java b/src/main/java/io/vavr/collection/PriorityQueue.java
index c1e46bfa8..7e12eae7f 100644
--- a/src/main/java/io/vavr/collection/PriorityQueue.java
+++ b/src/main/java/io/vavr/collection/PriorityQueue.java
@@ -28,10 +28,7 @@
 import java.util.Comparator;
 import java.util.NoSuchElementException;
 import java.util.Objects;
-import java.util.function.BiFunction;
-import java.util.function.Function;
-import java.util.function.Predicate;
-import java.util.function.Supplier;
+import java.util.function.*;
 import java.util.stream.Collector;
 
 /**
@@ -663,6 +660,10 @@ public Comparator<T> comparator() {
         return (Comparator<T>) comparator;
     }
 
+    @Override
+    public PriorityQueue<T> tapEach(Consumer<? super T> action) {
+        return Collections.tapEach(this, action);
+    }
 
     /**
      * fun deleteMin [] = raise EMPTY
diff --git a/src/main/java/io/vavr/collection/Queue.java b/src/main/java/io/vavr/collection/Queue.java
index aa1900d72..6576e9138 100644
--- a/src/main/java/io/vavr/collection/Queue.java
+++ b/src/main/java/io/vavr/collection/Queue.java
@@ -1277,6 +1277,11 @@ public Queue<T> takeRightWhile(Predicate<? super T> predicate) {
         return takeRightUntil(predicate.negate());
     }
 
+    @Override
+    public Queue<T> tapEach(Consumer<? super T> action) {
+        return Collections.tapEach(this, action);
+    }
+
     /**
      * Transforms this {@code Queue}.
      *
diff --git a/src/main/java/io/vavr/collection/Seq.java b/src/main/java/io/vavr/collection/Seq.java
index d47b250ff..0418b6943 100644
--- a/src/main/java/io/vavr/collection/Seq.java
+++ b/src/main/java/io/vavr/collection/Seq.java
@@ -1224,6 +1224,9 @@ default <U> U foldRight(U zero, BiFunction<? super T, ? super U, ? extends U> f)
     @Override
     Seq<T> peek(Consumer<? super T> action);
 
+    @Override
+    Seq<T> tapEach(Consumer<? super T> action);
+    
     @Override
     Seq<T> replace(T currentElement, T newElement);
 
diff --git a/src/main/java/io/vavr/collection/Set.java b/src/main/java/io/vavr/collection/Set.java
index 58663873b..6b2687881 100644
--- a/src/main/java/io/vavr/collection/Set.java
+++ b/src/main/java/io/vavr/collection/Set.java
@@ -243,6 +243,9 @@ default boolean isDistinct() {
     @Override
     Set<T> peek(Consumer<? super T> action);
 
+    @Override
+    Set<T> tapEach(Consumer<? super T> action);
+    
     @Override
     Set<T> replace(T currentElement, T newElement);
 
diff --git a/src/main/java/io/vavr/collection/Stream.java b/src/main/java/io/vavr/collection/Stream.java
index 87bf382e8..1b123fcde 100644
--- a/src/main/java/io/vavr/collection/Stream.java
+++ b/src/main/java/io/vavr/collection/Stream.java
@@ -1293,6 +1293,11 @@ public final Stream<T> peek(Consumer<? super T> action) {
         }
     }
 
+    @Override
+    public final Stream<T> tapEach(Consumer<? super T> action) {
+        return Collections.tapEach(this, action);
+    }
+
     @Override
     public final Stream<Stream<T>> permutations() {
         if (isEmpty()) {
diff --git a/src/main/java/io/vavr/collection/Traversable.java b/src/main/java/io/vavr/collection/Traversable.java
index c8e20576f..02259960a 100644
--- a/src/main/java/io/vavr/collection/Traversable.java
+++ b/src/main/java/io/vavr/collection/Traversable.java
@@ -1154,6 +1154,9 @@ default boolean nonEmpty() {
     @Override
     Traversable<T> peek(Consumer<? super T> action);
 
+
+    Traversable<T> tapEach(Consumer<? super T> action);
+
     /**
      * Calculates the product of this elements. Supported component types are {@code Byte}, {@code Double}, {@code Float},
      * {@code Integer}, {@code Long}, {@code Short}, {@code BigInteger} and {@code BigDecimal}.
diff --git a/src/main/java/io/vavr/collection/Tree.java b/src/main/java/io/vavr/collection/Tree.java
index d231e757d..ab132ef7e 100644
--- a/src/main/java/io/vavr/collection/Tree.java
+++ b/src/main/java/io/vavr/collection/Tree.java
@@ -651,6 +651,11 @@ public final Tree<T> peek(Consumer<? super T> action) {
         return this;
     }
 
+    @Override
+    public final Tree<T> tapEach(Consumer<? super T> action) {
+        return Collections.tapEach(this, action);
+    }
+
     @Override
     public final Tree<T> replace(T currentElement, T newElement) {
         if (isEmpty()) {
diff --git a/src/main/java/io/vavr/collection/TreeMap.java b/src/main/java/io/vavr/collection/TreeMap.java
index bb60698e6..93709cc5f 100644
--- a/src/main/java/io/vavr/collection/TreeMap.java
+++ b/src/main/java/io/vavr/collection/TreeMap.java
@@ -1201,6 +1201,11 @@ public TreeMap<K, V> peek(Consumer<? super Tuple2<K, V>> action) {
         return Maps.peek(this, action);
     }
 
+    @Override
+    public TreeMap<K, V> tapEach(Consumer<? super Tuple2<K, V>> action) {
+        return Collections.tapEach(this, action);
+    }
+
     @Override
     public <U extends V> TreeMap<K, V> put(K key, U value, BiFunction<? super V, ? super U, ? extends V> merge) {
         return Maps.put(this, key, value, merge);
diff --git a/src/main/java/io/vavr/collection/TreeSet.java b/src/main/java/io/vavr/collection/TreeSet.java
index 98a479c10..784469cd3 100644
--- a/src/main/java/io/vavr/collection/TreeSet.java
+++ b/src/main/java/io/vavr/collection/TreeSet.java
@@ -805,6 +805,11 @@ public TreeSet<T> peek(Consumer<? super T> action) {
         return this;
     }
 
+    @Override
+    public TreeSet<T> tapEach(Consumer<? super T> action) {
+        return Collections.tapEach(this, action);
+    }
+
     @Override
     public TreeSet<T> remove(T element) {
         return new TreeSet<>(tree.delete(element));
diff --git a/src/main/java/io/vavr/collection/Vector.java b/src/main/java/io/vavr/collection/Vector.java
index 2f882a008..ac54cb062 100644
--- a/src/main/java/io/vavr/collection/Vector.java
+++ b/src/main/java/io/vavr/collection/Vector.java
@@ -899,6 +899,11 @@ public Vector<T> peek(Consumer<? super T> action) {
         }
         return this;
     }
+    
+    @Override
+    public Vector<T> tapEach(Consumer<? super T> action) {
+        return Collections.tapEach(this, action);
+    }
 
     @Override
     public Vector<Vector<T>> permutations() {
diff --git a/src/test/java/io/vavr/collection/AbstractTraversableTest.java b/src/test/java/io/vavr/collection/AbstractTraversableTest.java
index 99cd73c9c..14aec067e 100644
--- a/src/test/java/io/vavr/collection/AbstractTraversableTest.java
+++ b/src/test/java/io/vavr/collection/AbstractTraversableTest.java
@@ -42,6 +42,10 @@
 
 public abstract class AbstractTraversableTest extends AbstractValueTest {
 
+    protected final boolean isLazy() {
+        return empty().isLazy();
+    }
+
     protected final boolean isTraversableAgain() {
         return empty().isTraversableAgain();
     }
@@ -50,6 +54,10 @@ protected final boolean isOrdered() {
         return empty().isOrdered();
     }
 
+    protected final boolean isSequential() {
+        return empty().isSequential();
+    }
+
     protected abstract <T> Collector<T, ArrayList<T>, ? extends Traversable<T>> collector();
 
     @Override
@@ -2844,6 +2852,64 @@ public void ofAllShouldReturnTheSingletonEmpty() {
         assertThat(ofAll(io.vavr.collection.Iterator.empty())).isSameAs(empty());
     }
 
+    // eager traversable shall apply action immediately
+
+    @Test
+    public void tapEachShouldThrowIfActionIsNull() {
+        assertThatThrownBy(() -> of("one", "two", "three").tapEach(null))
+                .isInstanceOf(NullPointerException.class);
+    }
+    @Test
+    public void tapEachShouldDoNothingOnLazyTraversableUntilElementsMaterialized() {
+        // test is meaningful for lazy Traversable<T> only
+        if (isLazy()) {
+            String errorMessage = "tapEach() must not call effect on lazy Traversable<T> before its elements are materialized";
+            of("one", "two", "three").tapEach(__ -> fail(errorMessage)); // note: no elements materialized yet
+        }
+    }
+
+    @Test
+    public void tapEachShouldDoNothingOnEmptyTraversable() {
+        empty()
+                .tapEach(__ -> fail("tapEach() must never call effect on empty Traversable<T>"))
+                .forEach(__ -> {}); // enforcing all elements to materialize
+    }
+
+    @Test
+    public void tapEachShouldApplyEffectToEveryElementExactlyOnce() {
+        String[] values = {"one", "two", "three"};
+        // some collections may not guarantee the order of effect applications,
+        // so here we'll assert the 'exactly once' property only
+        java.util.Map<String, Integer> effectCallCounter = new java.util.HashMap<>();
+
+        // instantiating a Traversable<T> from elements provided, tappping each element
+        // and forcing all of its elements to materialize
+        of(values)
+                .tapEach(element -> effectCallCounter.compute(element, (__, v) -> v == null ? 1 : v + 1))
+                .forEach(__ -> {});
+
+        assertThat(effectCallCounter.get("one")).isEqualTo(1); // effect called for value "one" exactly once
+        assertThat(effectCallCounter.get("two")).isEqualTo(1); // ... for value "two" exactly once
+        assertThat(effectCallCounter.get("three")).isEqualTo(1); // ... for value "three" exactly once
+        assertThat(effectCallCounter.size()).isEqualTo(values.length);
+    }
+
+    @Test
+    public void tapEachShouldApplyEffectToEveryElementInOrder() {
+        // testing effects order is for ordered Traversable<T> only
+        if (this.isSequential()) {
+            String[] values = {"one", "two", "three"};
+            java.util.List<String> effectCallLog = new java.util.ArrayList<>();
+            // instantiating a Traversable<T> from elements provided, tappping each element
+            // and forcing all of its elements to materialize
+            of(values)
+                    .tapEach(element -> effectCallLog.add(element))
+                    .forEach(__ -> {});
+
+            assertThat(effectCallLog).isEqualTo(Arrays.asList(values));
+        }
+    }
+
     private void testCollector(Runnable test) {
         if (isTraversableAgain()) {
             test.run();
diff --git a/src/test/java/io/vavr/collection/IntMap.java b/src/test/java/io/vavr/collection/IntMap.java
index c8537630d..3481c67bf 100644
--- a/src/test/java/io/vavr/collection/IntMap.java
+++ b/src/test/java/io/vavr/collection/IntMap.java
@@ -247,6 +247,11 @@ public IntMap<T> peek(Consumer<? super T> action) {
         return this;
     }
 
+    @Override
+    public IntMap<T> tapEach(Consumer<? super T> action) {
+        return Collections.tapEach(this, action);
+    }
+
     @Override
     public IntMap<T> replace(T currentElement, T newElement) {
         final Option<Tuple2<Integer, T>> currentEntryOpt = original.find(e -> e._2.equals(currentElement));
diff --git a/src/test/java/io/vavr/collection/IntMultimap.java b/src/test/java/io/vavr/collection/IntMultimap.java
index 99ee05cb7..17477a2b2 100644
--- a/src/test/java/io/vavr/collection/IntMultimap.java
+++ b/src/test/java/io/vavr/collection/IntMultimap.java
@@ -248,6 +248,11 @@ public IntMultimap<T> peek(Consumer<? super T> action) {
         return this;
     }
 
+    @Override
+    public IntMultimap<T> tapEach(Consumer<? super T> action) {
+        return Collections.tapEach(this, action);
+    }
+
     @Override
     public IntMultimap<T> replace(T currentElement, T newElement) {
         final Option<Tuple2<Integer, T>> currentEntryOpt = original.find(e -> e._2.equals(currentElement));