Introduce plusElement and minusElement to disambiguate situations like List<List<T>> + List<T>

#KT-9992 Fixed

js/js.libraries/src/core/kotlin_special.kt

@@ -488,6 +488,14 @@ public inline operator fun ShortArray.plus(elements: ShortArray): ShortArray {
     return this.asDynamic().concat(elements)
 }
 
+/**
+ * Returns an array containing all elements of the original array and then the given [element].
+ */
+@Suppress("NOTHING_TO_INLINE")
+public inline fun <T> Array<out T>.plusElement(element: T): Array<T> {
+    return this.asDynamic().concat(arrayOf(element))
+}
+
 /**
  * Sorts the array in-place.
  */

libraries/stdlib/src/generated/_Arrays.kt

@@ -12358,6 +12358,14 @@ public operator fun ShortArray.plus(elements: ShortArray): ShortArray {
     return result
 }
 
+/**
+ * Returns an array containing all elements of the original array and then the given [element].
+ */
+@kotlin.jvm.JvmVersion
+public fun <T> Array<T>.plusElement(element: T): Array<T> {
+    return plus(element)
+}
+
 /**
  * Sorts the array in-place.
  */

libraries/stdlib/src/generated/_Collections.kt

@@ -1599,6 +1599,13 @@ public operator fun <T> Iterable<T>.minus(elements: Sequence<T>): List<T> {
     return this.filterNot { it in other }
 }
 
+/**
+ * Returns a list containing all elements of the original collection without the first occurrence of the given [element].
+ */
+public fun <T> Iterable<T>.minusElement(element: T): List<T> {
+    return minus(element)
+}
+
 /**
  * Splits the original collection into pair of lists,
  * where *first* list contains elements for which [predicate] yielded `true`,
@@ -1706,6 +1713,20 @@ public operator fun <T> Iterable<T>.plus(elements: Sequence<T>): List<T> {
     return result
 }
 
+/**
+ * Returns a list containing all elements of the original collection and then the given [element].
+ */
+public fun <T> Collection<T>.plusElement(element: T): List<T> {
+    return plus(element)
+}
+
+/**
+ * Returns a list containing all elements of the original collection and then the given [element].
+ */
+public fun <T> Iterable<T>.plusElement(element: T): List<T> {
+    return plus(element)
+}
+
 /**
  * Returns a list of pairs built from elements of both collections with same indexes. List has length of shortest collection.
  */

libraries/stdlib/src/generated/_Sequences.kt

@@ -1024,6 +1024,13 @@ public operator fun <T> Sequence<T>.minus(elements: Sequence<T>): Sequence<T> {
     }
 }
 
+/**
+ * Returns a sequence containing all elements of the original sequence without the first occurrence of the given [element].
+ */
+public fun <T> Sequence<T>.minusElement(element: T): Sequence<T> {
+    return minus(element)
+}
+
 /**
  * Splits the original sequence into pair of lists,
  * where *first* list contains elements for which [predicate] yielded `true`,
@@ -1076,6 +1083,13 @@ public operator fun <T> Sequence<T>.plus(elements: Sequence<T>): Sequence<T> {
     return sequenceOf(this, elements).flatten()
 }
 
+/**
+ * Returns a sequence containing all elements of the original sequence and then the given [element].
+ */
+public fun <T> Sequence<T>.plusElement(element: T): Sequence<T> {
+    return plus(element)
+}
+
 /**
  * Returns a sequence of pairs built from elements of both sequences with same indexes.
  * Resulting sequence has length of shortest input sequence.

libraries/stdlib/src/generated/_Sets.kt

@@ -54,6 +54,13 @@ public operator fun <T> Set<T>.minus(elements: Sequence<T>): Set<T> {
     return result
 }
 
+/**
+ * Returns a set containing all elements of the original set except the given [element].
+ */
+public fun <T> Set<T>.minusElement(element: T): Set<T> {
+    return minus(element)
+}
+
 /**
  * Returns a set containing all elements of the original set and then the given [element].
  */
@@ -94,3 +101,10 @@ public operator fun <T> Set<T>.plus(elements: Sequence<T>): Set<T> {
     return result
 }
 
+/**
+ * Returns a set containing all elements of the original set and then the given [element].
+ */
+public fun <T> Set<T>.plusElement(element: T): Set<T> {
+    return plus(element)
+}
+

libraries/stdlib/test/collections/ArraysTest.kt

@@ -430,6 +430,20 @@ class ArraysTest {
         assertTrue(intArrayOf(1).isNotEmpty())
     }
 
+    @test fun plusInference() {
+        val arrayOfArrays: Array<Array<out Any>> = arrayOf(arrayOf<Any>("s") as Array<out Any>)
+        val elementArray = arrayOf<Any>("a") as Array<out Any>
+        val arrayPlusElement: Array<Array<out Any>> = arrayOfArrays.plusElement(elementArray)
+        assertEquals("a", arrayPlusElement[1][0])
+        // ambiguity
+        // val arrayPlusArray: Array<Array<out Any>> = arrayOfArrays + arrayOfArrays
+
+        val arrayOfStringArrays = arrayOf(arrayOf("s"))
+        val arrayPlusArray = arrayOfStringArrays + arrayOfStringArrays
+        assertEquals("s", arrayPlusArray[1][0])
+    }
+
+
     @test fun plus() {
         assertEquals(listOf("1", "2", "3", "4"), listOf("1", "2") + arrayOf("3", "4"))
         assertArrayNotSameButEquals(arrayOf("1", "2", "3"), arrayOf("1", "2") + "3")

libraries/stdlib/test/collections/CollectionTest.kt

@@ -247,6 +247,18 @@ class CollectionTest {
         assertEquals(listOf("foo", "bar", "cheese", "wine"), list)
     }
 
+    @test fun plusCollectionInference() {
+        val listOfLists = listOf(listOf("s"))
+        val elementList = listOf("a")
+        val result: List<List<String>> = listOfLists.plusElement(elementList)
+        assertEquals(listOf(listOf("s"), listOf("a")), result, "should be list + element")
+
+        val listOfAny = listOf<Any>("a") + listOf<Any>("b")
+        assertEquals(listOf("a", "b"), listOfAny,  "should be list + list")
+
+        val listOfAnyAndList = listOf<Any>("a") + listOf<Any>("b") as Any
+        assertEquals(listOf("a", listOf("b")), listOfAnyAndList, "should be list + Any")
+    }
 
     @test fun plusAssign() {
         // lets use a mutable variable of readonly list

libraries/tools/kotlin-stdlib-gen/src/templates/Generators.kt

@@ -5,6 +5,17 @@ import templates.Family.*
 fun generators(): List<GenericFunction> {
     val templates = arrayListOf<GenericFunction>()
 
+    templates add f("plusElement(element: T)") {
+        only(Iterables, Collections, Sets, Sequences)
+        doc { "Returns a list containing all elements of the original collection and then the given [element]." }
+        doc(Sets) { "Returns a set containing all elements of the original set and then the given [element]." }
+        doc(Sequences) { "Returns a sequence containing all elements of the original sequence and then the given [element]." }
+
+        returns("List<T>")
+        returns("SELF", Sets, Sequences)
+        body { "return plus(element)" }
+    }
+
     templates add f("plus(element: T)") {
         operator(true)
 
@@ -206,6 +217,17 @@ fun generators(): List<GenericFunction> {
         }
     }
 
+    templates add f("minusElement(element: T)") {
+        only(Iterables, Sets, Sequences)
+        doc { "Returns a list containing all elements of the original collection without the first occurrence of the given [element]." }
+        doc(Sets) { "Returns a set containing all elements of the original set except the given [element]." }
+        doc(Sequences) { "Returns a sequence containing all elements of the original sequence without the first occurrence of the given [element]." }
+
+        returns("List<T>")
+        returns("SELF", Sets, Sequences)
+        body { "return minus(element)" }
+    }
+
     templates add f("minus(element: T)") {
         operator(true)
 

libraries/tools/kotlin-stdlib-gen/src/templates/SpecialJS.kt

@@ -90,6 +90,20 @@ fun specialJS(): List<GenericFunction> {
         }
 
 
+    templates add f("plusElement(element: T)") {
+        only(ArraysOfObjects)
+        returns("SELF")
+        returns(ArraysOfObjects) { "Array<T>" }
+        inline(true)
+        annotations("""@Suppress("NOTHING_TO_INLINE")""")
+        doc { "Returns an array containing all elements of the original array and then the given [element]." }
+        body() {
+            """
+            return this.asDynamic().concat(arrayOf(element))
+            """
+        }
+    }
+
     templates add f("plus(element: T)") {
         operator(true)
 

libraries/tools/kotlin-stdlib-gen/src/templates/SpecialJVM.kt

@@ -5,6 +5,13 @@ import templates.Family.*
 fun specialJVM(): List<GenericFunction> {
     val templates = arrayListOf<GenericFunction>()
 
+    templates add f("plusElement(element: T)") {
+        only(InvariantArraysOfObjects)
+        returns("SELF")
+        doc { "Returns an array containing all elements of the original array and then the given [element]." }
+        body { "return plus(element)" }
+    }
+
     templates add f("plus(element: T)") {
         operator(true)