Adding Monoid#foldMap; adding @see refs in javadocs for Monoid and Semigroup

jnape · jnape · commit 99339b377631 · 2016-11-19T13:52:54.000-06:00
diff --git a/src/main/java/com/jnape/palatable/lambda/monoid/Monoid.java b/src/main/java/com/jnape/palatable/lambda/monoid/Monoid.java
@@ -1,9 +1,14 @@
 package com.jnape.palatable.lambda.monoid;
 
+import com.jnape.palatable.lambda.functions.builtin.fn2.Map;
 import com.jnape.palatable.lambda.functions.builtin.fn2.ReduceLeft;
 import com.jnape.palatable.lambda.functions.builtin.fn2.ReduceRight;
 import com.jnape.palatable.lambda.semigroup.Semigroup;
 
+import java.util.function.Function;
+
+import static com.jnape.palatable.lambda.functions.builtin.fn2.Map.map;
+
 /**
  * A {@link Monoid} is the pairing of a {@link Semigroup} with an identity element.
  *
@@ -24,6 +29,7 @@ public interface Monoid<A> extends Semigroup<A> {
      *
      * @param as the elements to reduce
      * @return the reduction, or {@link Monoid#identity} if empty
+     * @see ReduceLeft
      */
     default A reduceLeft(Iterable<A> as) {
         return ReduceLeft.reduceLeft(toBiFunction(), as).orElse(identity());
@@ -35,11 +41,28 @@ default A reduceLeft(Iterable<A> as) {
      *
      * @param as an Iterable of elements in this monoid
      * @return the reduction, or {@link Monoid#identity} if empty
+     * @see ReduceRight
      */
     default A reduceRight(Iterable<A> as) {
         return ReduceRight.reduceRight(toBiFunction(), as).orElse(identity());
     }
 
+    /**
+     * Homomorphism combined with catamorphism. Convert an <code>Iterable&lt;B&gt;</code> to an
+     * <code>Iterable&lt;A&gt;</code> (that is, an <code>Iterable</code> of elements this monoid is formed over), then
+     * reduce the result from left to right. Under algebraic data types, this is isomorphic to a flatMap.
+     *
+     * @param fn  the mapping function from A to B
+     * @param bs  the Iterable of Bs
+     * @param <B> the input Iterable element type
+     * @return the folded result under this Monoid
+     * @see Map
+     * @see Monoid#reduceLeft(Iterable)
+     */
+    default <B> A foldMap(Function<? super B, ? extends A> fn, Iterable<B> bs) {
+        return reduceLeft(map(fn, bs));
+    }
+
     /**
      * Promote a {@link Semigroup} to a {@link Monoid} by supplying an identity element.
      *
diff --git a/src/main/java/com/jnape/palatable/lambda/semigroup/Semigroup.java b/src/main/java/com/jnape/palatable/lambda/semigroup/Semigroup.java
@@ -20,6 +20,7 @@ public interface Semigroup<A> extends Fn2<A, A, A> {
      * @param a  the starting accumulator
      * @param as the elements to fold over
      * @return the folded result
+     * @see FoldLeft
      */
     default A foldLeft(A a, Iterable<A> as) {
         return FoldLeft.foldLeft(toBiFunction(), a, as);
@@ -32,6 +33,7 @@ default A foldLeft(A a, Iterable<A> as) {
      * @param a  the starting accumulator
      * @param as the elements to fold over
      * @return the folded result
+     * @see FoldRight
      */
     default A foldRight(A a, Iterable<A> as) {
         return FoldRight.foldRight(toBiFunction(), a, as);
diff --git a/src/test/java/com/jnape/palatable/lambda/monoid/MonoidTest.java b/src/test/java/com/jnape/palatable/lambda/monoid/MonoidTest.java
@@ -2,6 +2,9 @@
 
 import org.junit.Test;
 
+import java.util.List;
+import java.util.Optional;
+
 import static com.jnape.palatable.lambda.monoid.Monoid.monoid;
 import static java.util.Arrays.asList;
 import static org.junit.Assert.assertEquals;
@@ -19,4 +22,11 @@ public void reduceRight() {
         Monoid<Integer> sum = monoid((x, y) -> x + y, 0);
         assertEquals((Integer) 6, sum.reduceRight(asList(1, 2, 3)));
     }
+
+    @Test
+    public void foldMap() {
+        Monoid<Integer> sum = monoid((x, y) -> x + y, 0);
+        List<Optional<Integer>> optionalInts = asList(Optional.of(1), Optional.of(2), Optional.empty(), Optional.of(3), Optional.empty());
+        assertEquals((Integer) 6, sum.foldMap(optX -> optX.orElse(0), optionalInts));
+    }
 }
