Adding Upcast

jnape · jnape · commit 700d6253da8a · 2018-05-07T23:52:20.000-05:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,9 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/).
 ### Changed
 - `ToMap` accepts an `Iterable` covariant in `Map.Entry`
 
+### Added
+- `Upcast` for safely casting up a type hierarchy
+
 ## [3.0.0] - 2018-05-04
 ### Changed
 - ***Breaking Change***: `Sequence` now has two more type parameters to aid in inference
diff --git a/src/main/java/com/jnape/palatable/lambda/functions/builtin/fn1/Upcast.java b/src/main/java/com/jnape/palatable/lambda/functions/builtin/fn1/Upcast.java
@@ -0,0 +1,43 @@
+package com.jnape.palatable.lambda.functions.builtin.fn1;
+
+import com.jnape.palatable.lambda.functions.Fn1;
+
+/**
+ * Upcast a value of type <code>B</code> to a value of type <code>A</code> that <code>B</code> extends. This is
+ * principally useful when dealing with parametric types that are invariant in their parameters and a cast is
+ * necessary for compatibility purposes.
+ * <p>
+ * Example:
+ * <pre>
+ * {@code
+ * Iterable<String> have = new ArrayList<>();
+ * Iterable<CharSequence> want = map(upcast(), have); // necessary due to invariance in parameter
+ * }
+ * </pre>
+ * <p>
+ * Note that this is universally safe.
+ *
+ * @param <A> the covariant type
+ * @param <B> the contravariant type
+ */
+public final class Upcast<A extends B, B> implements Fn1<A, B> {
+
+    private static final Upcast INSTANCE = new Upcast<>();
+
+    private Upcast() {
+    }
+
+    @Override
+    public B apply(A a) {
+        return a;
+    }
+
+    @SuppressWarnings("unchecked")
+    public static <A extends B, B> Upcast<A, B> upcast() {
+        return INSTANCE;
+    }
+
+    public static <A extends B, B> B upcast(A a) {
+        return Upcast.<A, B>upcast().apply(a);
+    }
+}
diff --git a/src/test/java/com/jnape/palatable/lambda/functions/builtin/fn1/UpcastTest.java b/src/test/java/com/jnape/palatable/lambda/functions/builtin/fn1/UpcastTest.java
@@ -0,0 +1,18 @@
+package com.jnape.palatable.lambda.functions.builtin.fn1;
+
+import org.junit.Test;
+
+import static com.jnape.palatable.lambda.functions.builtin.fn1.Upcast.upcast;
+import static com.jnape.palatable.lambda.functions.builtin.fn2.Map.map;
+import static java.util.Arrays.asList;
+
+public class UpcastTest {
+
+    @Test
+    @SuppressWarnings("unused")
+    public void castsUp() {
+        Upcast<String, CharSequence> upcast = upcast();
+        Iterable<String> strings = asList("foo", "bar");
+        Iterable<CharSequence> charSequences = map(upcast, strings);
+    }
+}
