Extensions for java.util.Optional (KT-50484)

Co-authored-by: Ilya Gorbunov <ilya.gorbunov@jetbrains.com>

libraries/stdlib/jdk8/java9/module-info.java

@@ -3,6 +3,7 @@ module kotlin.stdlib.jdk8 {
     requires transitive kotlin.stdlib;
     requires kotlin.stdlib.jdk7;
 
+    exports kotlin.jvm.optionals;
     exports kotlin.jvm.jdk8;
     exports kotlin.collections.jdk8;
     exports kotlin.streams.jdk8;

libraries/stdlib/jdk8/src/kotlin/jvm/optionals/Optionals.kt

@@ -0,0 +1,69 @@
+/*
+ * Copyright 2010-2022 JetBrains s.r.o. and Kotlin Programming Language contributors.
+ * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
+ */
+
+package kotlin.jvm.optionals
+
+import java.util.Optional
+
+/**
+ * Returns this [Optional]'s value if [present][Optional.isPresent], or otherwise `null`.
+ */
+@SinceKotlin("1.7")
+@ExperimentalStdlibApi
+public fun <T : Any> Optional<T>.getOrNull(): T? = orElse(null)
+
+/**
+ * Returns this [Optional]'s value if [present][Optional.isPresent], or otherwise [defaultValue].
+ */
+@SinceKotlin("1.7")
+@ExperimentalStdlibApi
+public fun <R, T : R & Any> Optional<T>.getOrDefault(defaultValue: R): R = if (isPresent) get() else defaultValue
+
+/**
+ * Returns this [Optional]'s value if [present][Optional.isPresent], or otherwise the result of the [defaultValue] function.
+ */
+@SinceKotlin("1.7")
+@ExperimentalStdlibApi
+public inline fun <R, T : R & Any> Optional<T>.getOrElse(defaultValue: () -> R): R =
+    if (isPresent) get() else defaultValue()
+
+/**
+ * Appends this [Optional]'s value to the given [destination] collection if [present][Optional.isPresent].
+ */
+@SinceKotlin("1.7")
+@ExperimentalStdlibApi
+public fun <T : Any, C : MutableCollection<in T>> Optional<T>.toCollection(destination: C): C {
+    if (isPresent) {
+        destination.add(get())
+    }
+    return destination
+}
+
+/**
+ * Returns a new read-only list of this [Optional]'s value if [present][Optional.isPresent], or otherwise an empty list.
+ * The returned list is serializable (JVM).
+ */
+@SinceKotlin("1.7")
+@ExperimentalStdlibApi
+public fun <T : Any> Optional<out T>.toList(): List<T> =
+    if (isPresent) listOf(get()) else emptyList()
+
+/**
+ * Returns a new read-only set of this [Optional]'s value if [present][Optional.isPresent], or otherwise an empty set.
+ * The returned set is serializable (JVM).
+ */
+@SinceKotlin("1.7")
+@ExperimentalStdlibApi
+public fun <T : Any> Optional<out T>.toSet(): Set<T> =
+    if (isPresent) setOf(get()) else emptySet()
+
+/**
+ * Returns a new sequence for this [Optional]'s value if [present][Optional.isPresent], or otherwise an empty sequence.
+ * The returned set is serializable (JVM).
+ */
+@SinceKotlin("1.7")
+@ExperimentalStdlibApi
+public fun <T : Any> Optional<out T>.asSequence(): Sequence<T> =
+    if (isPresent) sequenceOf(get()) else emptySequence()

libraries/stdlib/jdk8/test/jvm/optionals/OptionalsTest.kt

@@ -0,0 +1,87 @@
+/*
+ * Copyright 2010-2022 JetBrains s.r.o. and Kotlin Programming Language contributors.
+ * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
+ */
+
+package kotlin.jdk8.jvm.optionals.test
+
+import java.util.Optional
+import kotlin.test.*
+import kotlin.jvm.optionals.*
+
+class OptionalsTest {
+    @Test
+    fun getOrNull() {
+        assertEquals("foo", Optional.of("foo").getOrNull())
+        assertNull(Optional.empty<String>().getOrNull())
+    }
+
+    @Test
+    fun getOrDefault() {
+        assertEquals("foo", Optional.of("foo").getOrDefault("bar"))
+        assertEquals("bar", Optional.empty<String>().getOrDefault("bar"))
+
+        // Return type can be a supertype
+        assertNull(Optional.empty<String>().getOrDefault(null))
+        assertEquals(5.0, Optional.empty<Int>().getOrDefault<Number, Int>(5.0))
+    }
+
+    @Test
+    fun getOrElse() {
+        assertEquals("foo", Optional.of("foo").getOrElse { throw AssertionError() })
+        assertEquals("bar", Optional.empty<String>().getOrElse { "bar" })
+
+        // Return type can be a supertype
+        assertNull(Optional.empty<String>().getOrElse { null })
+        assertEquals(5.0, Optional.empty<Int>().getOrElse<Number, Int> { 5.0 })
+    }
+
+    @Test
+    fun getOrElse_propagatesException() {
+        val e = assertFailsWith<IllegalStateException> {
+            Optional.empty<String>().getOrElse { throw IllegalStateException("ran") }
+        }
+        assertEquals("ran", e.message)
+    }
+
+    @Test
+    fun optionalToCollection_presentAddsValue() {
+        val dest = mutableListOf<CharSequence>()
+        Optional.of("foo").toCollection(dest)
+        assertEquals(listOf<CharSequence>("foo"), dest)
+    }
+
+    @Test
+    fun optionalToCollection_emptyAddsNothing() {
+        val dest = mutableListOf<String>()
+        Optional.empty<String>().toCollection(dest)
+        assertEquals(emptyList(), dest)
+    }
+
+    @Test
+    fun optionalToList() {
+        assertEquals(listOf("foo"), Optional.of("foo").toList())
+        assertEquals(emptyList(), Optional.empty<String>().toList())
+
+        // List element type can be a supertype
+        assertEquals(listOf<CharSequence>("foo"), Optional.of("foo").toList<CharSequence>())
+    }
+
+    @Test
+    fun optionalToSet() {
+        assertEquals(setOf("foo"), Optional.of("foo").toSet())
+        assertEquals(emptySet(), Optional.empty<String>().toSet())
+
+        // List element type can be a supertype
+        assertEquals(setOf<CharSequence>("foo"), Optional.of("foo").toSet<CharSequence>())
+    }
+
+    @Test
+    fun optionalAsSequence() {
+        assertEquals(listOf("foo"), Optional.of("foo").asSequence().toList())
+        assertEquals(emptyList(), Optional.empty<String>().asSequence().toList())
+
+        // List element type can be a supertype
+        assertEquals(listOf<CharSequence>("foo"), Optional.of("foo").asSequence<CharSequence>().toList())
+    }
+}

libraries/stdlib/src/Module.md

@@ -71,6 +71,10 @@ Functions and other APIs specific to the JavaScript platform.
 
 Functions and annotations specific to the Java platform.
 
+# Package kotlin.jvm.optionals
+
+Convenience extension functions for `java.util.Optional` to simplify Kotlin-Java interop.
+
 # Package kotlin.math
 
 Mathematical functions and constants. 

libraries/tools/binary-compatibility-validator/reference-public-api/kotlin-stdlib-jdk8.txt

@@ -1,3 +1,13 @@
+public final class kotlin/jvm/optionals/OptionalsKt {
+	public static final fun asSequence (Ljava/util/Optional;)Lkotlin/sequences/Sequence;
+	public static final fun getOrDefault (Ljava/util/Optional;Ljava/lang/Object;)Ljava/lang/Object;
+	public static final fun getOrElse (Ljava/util/Optional;Lkotlin/jvm/functions/Function0;)Ljava/lang/Object;
+	public static final fun getOrNull (Ljava/util/Optional;)Ljava/lang/Object;
+	public static final fun toCollection (Ljava/util/Optional;Ljava/util/Collection;)Ljava/util/Collection;
+	public static final fun toList (Ljava/util/Optional;)Ljava/util/List;
+	public static final fun toSet (Ljava/util/Optional;)Ljava/util/Set;
+}
+
 public final class kotlin/streams/jdk8/StreamsKt {
 	public static final fun asSequence (Ljava/util/stream/DoubleStream;)Lkotlin/sequences/Sequence;
 	public static final fun asSequence (Ljava/util/stream/IntStream;)Lkotlin/sequences/Sequence;