From d26c0f777bd48c95b6a70a099a080e6424a3916e Mon Sep 17 00:00:00 2001
From: Takayuki Matsubara <takayuki.1229@gmail.com>
Date: Sun, 26 Aug 2018 23:40:33 +0900
Subject: [PATCH] KT-20357 Add samples for `Map.containsValue`

Co-authored-by: Ilya Gorbunov <ilya.gorbunov@jetbrains.com>
---
 .../samples/test/samples/collections/maps.kt     | 16 ++++++++++++++++
 libraries/stdlib/src/kotlin/collections/Maps.kt  |  2 ++
 2 files changed, 18 insertions(+)

diff --git a/libraries/stdlib/samples/test/samples/collections/maps.kt b/libraries/stdlib/samples/test/samples/collections/maps.kt
index 51ddab62236..c9c000d0104 100644
--- a/libraries/stdlib/samples/test/samples/collections/maps.kt
+++ b/libraries/stdlib/samples/test/samples/collections/maps.kt
@@ -142,6 +142,22 @@ class Maps {
             val sameMap = nonEmptyMap.ifEmpty { null }
             assertTrue(nonEmptyMap === sameMap)
         }
+
+        @Sample
+        fun containsValue() {
+            val map: Map<String, Int> = mapOf("x" to 1, "y" to 2)
+
+            // member containsValue is used
+            assertTrue(map.containsValue(1))
+
+            // extension containsValue is used when the argument type is a supertype of the map value type
+            assertTrue(map.containsValue(1 as Number))
+            assertTrue(map.containsValue(2 as Any))
+
+            assertFalse(map.containsValue("string" as Any))
+
+            // map.containsValue("string") // cannot call extension when the argument type and the map value type are unrelated at all
+        }
     }
 
     class Filtering {
diff --git a/libraries/stdlib/src/kotlin/collections/Maps.kt b/libraries/stdlib/src/kotlin/collections/Maps.kt
index c4b48ba8124..674574f3e21 100644
--- a/libraries/stdlib/src/kotlin/collections/Maps.kt
+++ b/libraries/stdlib/src/kotlin/collections/Maps.kt
@@ -211,6 +211,8 @@ public inline fun <@kotlin.internal.OnlyInputTypes K> Map<out K, *>.containsKey(
  * 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`.
+ *
+ * @sample samples.collections.Maps.Usage.containsValue
  */
 @Suppress("EXTENSION_SHADOWED_BY_MEMBER") // false warning, extension takes precedence in some cases
 @kotlin.internal.InlineOnly