From d1d080722997bbbe1263caa45f3c6a4dd733fcaf Mon Sep 17 00:00:00 2001 From: Ilya Gorbunov Date: Fri, 16 Oct 2015 23:34:27 +0300 Subject: [PATCH] Add a note about *Raw functions behavior. --- libraries/stdlib/src/generated/_Arrays.kt | 3 +++ .../stdlib/src/generated/_Collections.kt | 5 +++++ libraries/stdlib/src/generated/_Sequences.kt | 3 +++ .../stdlib/src/kotlin/collections/Maps.kt | 6 ++++++ .../kotlin/collections/MutableCollections.kt | 8 +++++++ .../src/templates/Elements.kt | 21 ++++++++++++++++--- 6 files changed, 43 insertions(+), 3 deletions(-) diff --git a/libraries/stdlib/src/generated/_Arrays.kt b/libraries/stdlib/src/generated/_Arrays.kt index 593beba3351..0e2c71039ae 100644 --- a/libraries/stdlib/src/generated/_Arrays.kt +++ b/libraries/stdlib/src/generated/_Arrays.kt @@ -437,6 +437,7 @@ public operator fun ShortArray.contains(element: Short): Boolean { /** * Returns `true` if [element] is found in the collection. + * Allows to overcome type-safety restriction of `contains` that requires to pass an element of type `T`. */ @Suppress("NOTHING_TO_INLINE") public inline fun Array.containsRaw(element: Any?): Boolean { @@ -1524,6 +1525,7 @@ public inline fun ShortArray.indexOfLast(predicate: (Short) -> Boolean): Int { /** * Returns first index of [element], or -1 if the collection does not contain element. + * Allows to overcome type-safety restriction of `indexOf` that requires to pass an element of type `T`. */ @Suppress("NOTHING_TO_INLINE") public inline fun Array.indexOfRaw(element: Any?): Int { @@ -1846,6 +1848,7 @@ public fun ShortArray.lastIndexOf(element: Short): Int { /** * Returns last index of [element], or -1 if the collection does not contain element. + * Allows to overcome type-safety restriction of `lastIndexOf` that requires to pass an element of type `T`. */ @Suppress("NOTHING_TO_INLINE") public inline fun Array.lastIndexOfRaw(element: Any?): Int { diff --git a/libraries/stdlib/src/generated/_Collections.kt b/libraries/stdlib/src/generated/_Collections.kt index 56f233eecc2..ed1a082b0b0 100644 --- a/libraries/stdlib/src/generated/_Collections.kt +++ b/libraries/stdlib/src/generated/_Collections.kt @@ -63,6 +63,7 @@ public operator fun Iterable.contains(element: T): Boolean { /** * Returns `true` if [element] is found in the collection. + * Allows to overcome type-safety restriction of `contains` that requires to pass an element of type `T`. */ @Suppress("NOTHING_TO_INLINE") public inline fun Iterable<*>.containsRaw(element: Any?): Boolean { @@ -312,6 +313,7 @@ public inline fun List.indexOfLast(predicate: (T) -> Boolean): Int { /** * Returns first index of [element], or -1 if the collection does not contain element. + * Allows to overcome type-safety restriction of `indexOf` that requires to pass an element of type `T`. */ @Suppress("NOTHING_TO_INLINE") public inline fun Iterable<*>.indexOfRaw(element: Any?): Int { @@ -320,6 +322,7 @@ public inline fun Iterable<*>.indexOfRaw(element: Any?): Int { /** * Returns first index of [element], or -1 if the collection does not contain element. + * Allows to overcome type-safety restriction of `indexOf` that requires to pass an element of type `T`. */ @Suppress("NOTHING_TO_INLINE") public inline fun List.indexOfRaw(element: Any?): Int { @@ -408,6 +411,7 @@ public fun Iterable.lastIndexOf(element: T): Int { /** * Returns last index of [element], or -1 if the collection does not contain element. + * Allows to overcome type-safety restriction of `lastIndexOf` that requires to pass an element of type `T`. */ @Suppress("NOTHING_TO_INLINE") public inline fun Iterable<*>.lastIndexOfRaw(element: Any?): Int { @@ -416,6 +420,7 @@ public inline fun Iterable<*>.lastIndexOfRaw(element: Any?): Int { /** * Returns last index of [element], or -1 if the collection does not contain element. + * Allows to overcome type-safety restriction of `lastIndexOf` that requires to pass an element of type `T`. */ @Suppress("NOTHING_TO_INLINE") public inline fun List.lastIndexOfRaw(element: Any?): Int { diff --git a/libraries/stdlib/src/generated/_Sequences.kt b/libraries/stdlib/src/generated/_Sequences.kt index e8c327eb0a8..bdc88df2c83 100644 --- a/libraries/stdlib/src/generated/_Sequences.kt +++ b/libraries/stdlib/src/generated/_Sequences.kt @@ -21,6 +21,7 @@ public operator fun Sequence.contains(element: T): Boolean { /** * Returns `true` if [element] is found in the collection. + * Allows to overcome type-safety restriction of `contains` that requires to pass an element of type `T`. */ @Suppress("NOTHING_TO_INLINE") public inline fun Sequence<*>.containsRaw(element: Any?): Boolean { @@ -160,6 +161,7 @@ public inline fun Sequence.indexOfLast(predicate: (T) -> Boolean): Int { /** * Returns first index of [element], or -1 if the collection does not contain element. + * Allows to overcome type-safety restriction of `indexOf` that requires to pass an element of type `T`. */ @Suppress("NOTHING_TO_INLINE") public inline fun Sequence<*>.indexOfRaw(element: Any?): Int { @@ -213,6 +215,7 @@ public fun Sequence.lastIndexOf(element: T): Int { /** * Returns last index of [element], or -1 if the collection does not contain element. + * Allows to overcome type-safety restriction of `lastIndexOf` that requires to pass an element of type `T`. */ @Suppress("NOTHING_TO_INLINE") public inline fun Sequence<*>.lastIndexOfRaw(element: Any?): Int { diff --git a/libraries/stdlib/src/kotlin/collections/Maps.kt b/libraries/stdlib/src/kotlin/collections/Maps.kt index 51d4807ca5a..e859d6c4d2e 100644 --- a/libraries/stdlib/src/kotlin/collections/Maps.kt +++ b/libraries/stdlib/src/kotlin/collections/Maps.kt @@ -105,18 +105,24 @@ public operator fun Map.contains(key : K) : Boolean = containsKey(key /** * Returns the value corresponding to the given [key], or `null` if such a key is not present in the map. + + * Allows to overcome type-safety restriction of `get` that requires to pass a key of type `Key`. */ @Suppress("NOTHING_TO_INLINE") public inline fun Map.getRaw(key: Any?): V? = (this as Map).get(key) /** * Returns `true` if the map contains the specified [key]. + * + * Allows to overcome type-safety restriction of `containsKey` that requires to pass a key of type `Key`. */ @Suppress("NOTHING_TO_INLINE") public inline fun Map.containsKeyRaw(key: Any?): Boolean = (this as Map).containsKey(key) /** * Returns `true` if the map maps one or more keys to the specified [value]. + * + * Allows to overcome type-safety restriction of `containsValue` that requires to pass a value of type `V`. */ @Suppress("NOTHING_TO_INLINE") public inline fun Map.containsValueRaw(value: Any?): Boolean = (this as Map).containsValue(value) diff --git a/libraries/stdlib/src/kotlin/collections/MutableCollections.kt b/libraries/stdlib/src/kotlin/collections/MutableCollections.kt index 0694f5258ec..ce71378f088 100644 --- a/libraries/stdlib/src/kotlin/collections/MutableCollections.kt +++ b/libraries/stdlib/src/kotlin/collections/MutableCollections.kt @@ -5,6 +5,8 @@ package kotlin /** * Checks if all elements in the specified collection are contained in this collection. + * + * Allows to overcome type-safety restriction of `containsAll` that requires to pass a collection of type `Collection`. */ @Suppress("NOTHING_TO_INLINE") public inline fun Collection<*>.containsAllRaw(collection: Collection): Boolean = (this as Collection).containsAll(collection) @@ -13,6 +15,8 @@ public inline fun Collection<*>.containsAllRaw(collection: Collection): Bo * Removes a single instance of the specified element from this * collection, if it is present. * + * Allows to overcome type-safety restriction of `remove` that requires to pass an element of type `E`. + * * @return `true` if the element has been successfully removed; `false` if it was not present in the collection. */ @Suppress("NOTHING_TO_INLINE") @@ -20,6 +24,8 @@ public inline fun MutableCollection.removeRaw(element: Any?): Boolean = ( /** * Removes all of this collection's elements that are also contained in the specified collection. + + * Allows to overcome type-safety restriction of `removeAll` that requires to pass a collection of type `Collection`. * * @return `true` if any of the specified elements was removed from the collection, `false` if the collection was not modified. */ @@ -29,6 +35,8 @@ public inline fun MutableCollection.removeAllRaw(collection: Collection`. + * * @return `true` if any element was removed from the collection, `false` if the collection was not modified. */ @Suppress("NOTHING_TO_INLINE") diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Elements.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Elements.kt index abd15317067..48f2a4d01e8 100644 --- a/libraries/tools/kotlin-stdlib-gen/src/templates/Elements.kt +++ b/libraries/tools/kotlin-stdlib-gen/src/templates/Elements.kt @@ -27,7 +27,12 @@ fun elements(): List { templates add f("containsRaw(element: Any?)") { only(Iterables, Sequences, ArraysOfObjects) - doc { "Returns `true` if [element] is found in the collection." } + doc { + """ + Returns `true` if [element] is found in the collection. + Allows to overcome type-safety restriction of `contains` that requires to pass an element of type `T`. + """ + } receiverAsterisk(Iterables, Sequences) { true } inline(true) annotations("""@Suppress("NOTHING_TO_INLINE")""") @@ -84,7 +89,12 @@ fun elements(): List { templates add f("indexOfRaw(element: Any?)") { only(Iterables, Sequences, ArraysOfObjects, Lists) - doc { "Returns first index of [element], or -1 if the collection does not contain element." } + doc { + """ + Returns first index of [element], or -1 if the collection does not contain element. + Allows to overcome type-safety restriction of `indexOf` that requires to pass an element of type `T`. + """ + } receiverAsterisk(Iterables, Sequences) { true } inline(true) annotations("""@Suppress("NOTHING_TO_INLINE")""") @@ -143,7 +153,12 @@ fun elements(): List { templates add f("lastIndexOfRaw(element: Any?)") { only(Iterables, Sequences, ArraysOfObjects, Lists) - doc { "Returns last index of [element], or -1 if the collection does not contain element." } + doc { + """ + Returns last index of [element], or -1 if the collection does not contain element. + Allows to overcome type-safety restriction of `lastIndexOf` that requires to pass an element of type `T`. + """ + } receiverAsterisk(Iterables, Sequences) { true } inline(true) annotations("""@Suppress("NOTHING_TO_INLINE")""")