Adding uncons

jnape · jnape · commit d5b346c49a4e · 2017-07-05T14:33:19.000-04:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,8 +4,8 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/).
 
 ## [Unreleased]
-
----
+### Added
+- `Uncons`, for destructuring an `Iterable` into its head and tail
 
 ## [1.6.1] - 2017-06-17
 ### Changed
diff --git a/src/main/java/com/jnape/palatable/lambda/functions/builtin/fn1/Uncons.java b/src/main/java/com/jnape/palatable/lambda/functions/builtin/fn1/Uncons.java
@@ -0,0 +1,38 @@
+package com.jnape.palatable.lambda.functions.builtin.fn1;
+
+import com.jnape.palatable.lambda.adt.hlist.Tuple2;
+import com.jnape.palatable.lambda.functions.Fn1;
+
+import java.util.Optional;
+
+import static com.jnape.palatable.lambda.adt.hlist.HList.tuple;
+import static com.jnape.palatable.lambda.functions.builtin.fn1.Head.head;
+import static com.jnape.palatable.lambda.functions.builtin.fn1.Tail.tail;
+
+/**
+ * Destructure an {@link Iterable} into a {@link Tuple2} of its head and tail, wrapped in an {@link Optional}. If the
+ * {@link Iterable} is empty, returns <code>Optional.empty()</code>.
+ *
+ * @param <A> the Iterable element type
+ */
+public final class Uncons<A> implements Fn1<Iterable<A>, Optional<Tuple2<A, Iterable<A>>>> {
+
+    private static final Uncons INSTANCE = new Uncons();
+
+    private Uncons() {
+    }
+
+    @Override
+    public Optional<Tuple2<A, Iterable<A>>> apply(Iterable<A> as) {
+        return head(as).map(a -> tuple(a, tail(as)));
+    }
+
+    @SuppressWarnings("unchecked")
+    public static <A> Uncons<A> uncons() {
+        return INSTANCE;
+    }
+
+    public static <A> Optional<Tuple2<A, Iterable<A>>> uncons(Iterable<A> as) {
+        return Uncons.<A>uncons().apply(as);
+    }
+}
diff --git a/src/test/java/com/jnape/palatable/lambda/functions/builtin/fn1/UnconsTest.java b/src/test/java/com/jnape/palatable/lambda/functions/builtin/fn1/UnconsTest.java
@@ -0,0 +1,40 @@
+package com.jnape.palatable.lambda.functions.builtin.fn1;
+
+import com.jnape.palatable.lambda.adt.hlist.Tuple2;
+import com.jnape.palatable.traitor.annotations.TestTraits;
+import com.jnape.palatable.traitor.runners.Traits;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import testsupport.traits.EmptyIterableSupport;
+
+import java.util.Optional;
+
+import static com.jnape.palatable.lambda.functions.builtin.fn1.Uncons.uncons;
+import static java.util.Arrays.asList;
+import static java.util.Collections.emptyList;
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertThat;
+import static testsupport.matchers.IterableMatcher.iterates;
+
+@RunWith(Traits.class)
+public class UnconsTest {
+
+    @TestTraits({EmptyIterableSupport.class})
+    public Uncons testSubject() {
+        return uncons();
+    }
+
+    @Test
+    public void nonEmptyIterable() {
+        Iterable<Integer> numbers = asList(1, 2, 3);
+        Tuple2<Integer, Iterable<Integer>> headAndTail = uncons(numbers).orElseThrow(AssertionError::new);
+
+        assertEquals((Integer) 1, headAndTail._1());
+        assertThat(headAndTail._2(), iterates(2, 3));
+    }
+
+    @Test
+    public void emptyIterable() {
+        assertEquals(Optional.empty(), uncons(emptyList()));
+    }
+}
