KT-20357: Add samples for filter functions

libraries/stdlib/common/src/generated/_Arrays.kt

@@ -3687,6 +3687,8 @@ public inline fun CharArray.filter(predicate: (Char) -> Boolean): List<Char> {
  * Returns a list containing only elements matching the given [predicate].
  * @param [predicate] function that takes the index of an element and the element itself
  * and returns the result of predicate evaluation on the element.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIndexed
  */
 public inline fun <T> Array<out T>.filterIndexed(predicate: (index: Int, T) -> Boolean): List<T> {
     return filterIndexedTo(ArrayList<T>(), predicate)
@@ -3696,6 +3698,8 @@ public inline fun <T> Array<out T>.filterIndexed(predicate: (index: Int, T) -> B
  * Returns a list containing only elements matching the given [predicate].
  * @param [predicate] function that takes the index of an element and the element itself
  * and returns the result of predicate evaluation on the element.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIndexed
  */
 public inline fun ByteArray.filterIndexed(predicate: (index: Int, Byte) -> Boolean): List<Byte> {
     return filterIndexedTo(ArrayList<Byte>(), predicate)
@@ -3705,6 +3709,8 @@ public inline fun ByteArray.filterIndexed(predicate: (index: Int, Byte) -> Boole
  * Returns a list containing only elements matching the given [predicate].
  * @param [predicate] function that takes the index of an element and the element itself
  * and returns the result of predicate evaluation on the element.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIndexed
  */
 public inline fun ShortArray.filterIndexed(predicate: (index: Int, Short) -> Boolean): List<Short> {
     return filterIndexedTo(ArrayList<Short>(), predicate)
@@ -3714,6 +3720,8 @@ public inline fun ShortArray.filterIndexed(predicate: (index: Int, Short) -> Boo
  * Returns a list containing only elements matching the given [predicate].
  * @param [predicate] function that takes the index of an element and the element itself
  * and returns the result of predicate evaluation on the element.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIndexed
  */
 public inline fun IntArray.filterIndexed(predicate: (index: Int, Int) -> Boolean): List<Int> {
     return filterIndexedTo(ArrayList<Int>(), predicate)
@@ -3723,6 +3731,8 @@ public inline fun IntArray.filterIndexed(predicate: (index: Int, Int) -> Boolean
  * Returns a list containing only elements matching the given [predicate].
  * @param [predicate] function that takes the index of an element and the element itself
  * and returns the result of predicate evaluation on the element.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIndexed
  */
 public inline fun LongArray.filterIndexed(predicate: (index: Int, Long) -> Boolean): List<Long> {
     return filterIndexedTo(ArrayList<Long>(), predicate)
@@ -3732,6 +3742,8 @@ public inline fun LongArray.filterIndexed(predicate: (index: Int, Long) -> Boole
  * Returns a list containing only elements matching the given [predicate].
  * @param [predicate] function that takes the index of an element and the element itself
  * and returns the result of predicate evaluation on the element.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIndexed
  */
 public inline fun FloatArray.filterIndexed(predicate: (index: Int, Float) -> Boolean): List<Float> {
     return filterIndexedTo(ArrayList<Float>(), predicate)
@@ -3741,6 +3753,8 @@ public inline fun FloatArray.filterIndexed(predicate: (index: Int, Float) -> Boo
  * Returns a list containing only elements matching the given [predicate].
  * @param [predicate] function that takes the index of an element and the element itself
  * and returns the result of predicate evaluation on the element.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIndexed
  */
 public inline fun DoubleArray.filterIndexed(predicate: (index: Int, Double) -> Boolean): List<Double> {
     return filterIndexedTo(ArrayList<Double>(), predicate)
@@ -3750,6 +3764,8 @@ public inline fun DoubleArray.filterIndexed(predicate: (index: Int, Double) -> B
  * Returns a list containing only elements matching the given [predicate].
  * @param [predicate] function that takes the index of an element and the element itself
  * and returns the result of predicate evaluation on the element.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIndexed
  */
 public inline fun BooleanArray.filterIndexed(predicate: (index: Int, Boolean) -> Boolean): List<Boolean> {
     return filterIndexedTo(ArrayList<Boolean>(), predicate)
@@ -3759,6 +3775,8 @@ public inline fun BooleanArray.filterIndexed(predicate: (index: Int, Boolean) ->
  * Returns a list containing only elements matching the given [predicate].
  * @param [predicate] function that takes the index of an element and the element itself
  * and returns the result of predicate evaluation on the element.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIndexed
  */
 public inline fun CharArray.filterIndexed(predicate: (index: Int, Char) -> Boolean): List<Char> {
     return filterIndexedTo(ArrayList<Char>(), predicate)
@@ -3768,6 +3786,8 @@ public inline fun CharArray.filterIndexed(predicate: (index: Int, Char) -> Boole
  * Appends all elements matching the given [predicate] to the given [destination].
  * @param [predicate] function that takes the index of an element and the element itself
  * and returns the result of predicate evaluation on the element.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIndexedTo
  */
 public inline fun <T, C : MutableCollection<in T>> Array<out T>.filterIndexedTo(destination: C, predicate: (index: Int, T) -> Boolean): C {
     forEachIndexed { index, element ->
@@ -3780,6 +3800,8 @@ public inline fun <T, C : MutableCollection<in T>> Array<out T>.filterIndexedTo(
  * Appends all elements matching the given [predicate] to the given [destination].
  * @param [predicate] function that takes the index of an element and the element itself
  * and returns the result of predicate evaluation on the element.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIndexedTo
  */
 public inline fun <C : MutableCollection<in Byte>> ByteArray.filterIndexedTo(destination: C, predicate: (index: Int, Byte) -> Boolean): C {
     forEachIndexed { index, element ->
@@ -3792,6 +3814,8 @@ public inline fun <C : MutableCollection<in Byte>> ByteArray.filterIndexedTo(des
  * Appends all elements matching the given [predicate] to the given [destination].
  * @param [predicate] function that takes the index of an element and the element itself
  * and returns the result of predicate evaluation on the element.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIndexedTo
  */
 public inline fun <C : MutableCollection<in Short>> ShortArray.filterIndexedTo(destination: C, predicate: (index: Int, Short) -> Boolean): C {
     forEachIndexed { index, element ->
@@ -3804,6 +3828,8 @@ public inline fun <C : MutableCollection<in Short>> ShortArray.filterIndexedTo(d
  * Appends all elements matching the given [predicate] to the given [destination].
  * @param [predicate] function that takes the index of an element and the element itself
  * and returns the result of predicate evaluation on the element.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIndexedTo
  */
 public inline fun <C : MutableCollection<in Int>> IntArray.filterIndexedTo(destination: C, predicate: (index: Int, Int) -> Boolean): C {
     forEachIndexed { index, element ->
@@ -3816,6 +3842,8 @@ public inline fun <C : MutableCollection<in Int>> IntArray.filterIndexedTo(desti
  * Appends all elements matching the given [predicate] to the given [destination].
  * @param [predicate] function that takes the index of an element and the element itself
  * and returns the result of predicate evaluation on the element.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIndexedTo
  */
 public inline fun <C : MutableCollection<in Long>> LongArray.filterIndexedTo(destination: C, predicate: (index: Int, Long) -> Boolean): C {
     forEachIndexed { index, element ->
@@ -3828,6 +3856,8 @@ public inline fun <C : MutableCollection<in Long>> LongArray.filterIndexedTo(des
  * Appends all elements matching the given [predicate] to the given [destination].
  * @param [predicate] function that takes the index of an element and the element itself
  * and returns the result of predicate evaluation on the element.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIndexedTo
  */
 public inline fun <C : MutableCollection<in Float>> FloatArray.filterIndexedTo(destination: C, predicate: (index: Int, Float) -> Boolean): C {
     forEachIndexed { index, element ->
@@ -3840,6 +3870,8 @@ public inline fun <C : MutableCollection<in Float>> FloatArray.filterIndexedTo(d
  * Appends all elements matching the given [predicate] to the given [destination].
  * @param [predicate] function that takes the index of an element and the element itself
  * and returns the result of predicate evaluation on the element.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIndexedTo
  */
 public inline fun <C : MutableCollection<in Double>> DoubleArray.filterIndexedTo(destination: C, predicate: (index: Int, Double) -> Boolean): C {
     forEachIndexed { index, element ->
@@ -3852,6 +3884,8 @@ public inline fun <C : MutableCollection<in Double>> DoubleArray.filterIndexedTo
  * Appends all elements matching the given [predicate] to the given [destination].
  * @param [predicate] function that takes the index of an element and the element itself
  * and returns the result of predicate evaluation on the element.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIndexedTo
  */
 public inline fun <C : MutableCollection<in Boolean>> BooleanArray.filterIndexedTo(destination: C, predicate: (index: Int, Boolean) -> Boolean): C {
     forEachIndexed { index, element ->
@@ -3864,6 +3898,8 @@ public inline fun <C : MutableCollection<in Boolean>> BooleanArray.filterIndexed
  * Appends all elements matching the given [predicate] to the given [destination].
  * @param [predicate] function that takes the index of an element and the element itself
  * and returns the result of predicate evaluation on the element.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIndexedTo
  */
 public inline fun <C : MutableCollection<in Char>> CharArray.filterIndexedTo(destination: C, predicate: (index: Int, Char) -> Boolean): C {
     forEachIndexed { index, element ->
@@ -3874,6 +3910,8 @@ public inline fun <C : MutableCollection<in Char>> CharArray.filterIndexedTo(des
 
 /**
  * Returns a list containing all elements that are instances of specified type parameter R.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIsInstance
  */
 public inline fun <reified R> Array<*>.filterIsInstance(): List<@kotlin.internal.NoInfer R> {
     return filterIsInstanceTo(ArrayList<R>())
@@ -3881,6 +3919,8 @@ public inline fun <reified R> Array<*>.filterIsInstance(): List<@kotlin.internal
 
 /**
  * Appends all elements that are instances of specified type parameter R to the given [destination].
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIsInstanceTo
  */
 public inline fun <reified R, C : MutableCollection<in R>> Array<*>.filterIsInstanceTo(destination: C): C {
     for (element in this) if (element is R) destination.add(element)
@@ -3979,6 +4019,8 @@ public fun <T : Any> Array<out T?>.filterNotNull(): List<T> {
 
 /**
  * Appends all elements that are not `null` to the given [destination].
+ * 
+ * @sample samples.collections.Collections.Filtering.filterNotNullTo
  */
 public fun <C : MutableCollection<in T>, T : Any> Array<out T?>.filterNotNullTo(destination: C): C {
     for (element in this) if (element != null) destination.add(element)
@@ -3987,6 +4029,8 @@ public fun <C : MutableCollection<in T>, T : Any> Array<out T?>.filterNotNullTo(
 
 /**
  * Appends all elements not matching the given [predicate] to the given [destination].
+ * 
+ * @sample samples.collections.Collections.Filtering.filterTo
  */
 public inline fun <T, C : MutableCollection<in T>> Array<out T>.filterNotTo(destination: C, predicate: (T) -> Boolean): C {
     for (element in this) if (!predicate(element)) destination.add(element)
@@ -3995,6 +4039,8 @@ public inline fun <T, C : MutableCollection<in T>> Array<out T>.filterNotTo(dest
 
 /**
  * Appends all elements not matching the given [predicate] to the given [destination].
+ * 
+ * @sample samples.collections.Collections.Filtering.filterTo
  */
 public inline fun <C : MutableCollection<in Byte>> ByteArray.filterNotTo(destination: C, predicate: (Byte) -> Boolean): C {
     for (element in this) if (!predicate(element)) destination.add(element)
@@ -4003,6 +4049,8 @@ public inline fun <C : MutableCollection<in Byte>> ByteArray.filterNotTo(destina
 
 /**
  * Appends all elements not matching the given [predicate] to the given [destination].
+ * 
+ * @sample samples.collections.Collections.Filtering.filterTo
  */
 public inline fun <C : MutableCollection<in Short>> ShortArray.filterNotTo(destination: C, predicate: (Short) -> Boolean): C {
     for (element in this) if (!predicate(element)) destination.add(element)
@@ -4011,6 +4059,8 @@ public inline fun <C : MutableCollection<in Short>> ShortArray.filterNotTo(desti
 
 /**
  * Appends all elements not matching the given [predicate] to the given [destination].
+ * 
+ * @sample samples.collections.Collections.Filtering.filterTo
  */
 public inline fun <C : MutableCollection<in Int>> IntArray.filterNotTo(destination: C, predicate: (Int) -> Boolean): C {
     for (element in this) if (!predicate(element)) destination.add(element)
@@ -4019,6 +4069,8 @@ public inline fun <C : MutableCollection<in Int>> IntArray.filterNotTo(destinati
 
 /**
  * Appends all elements not matching the given [predicate] to the given [destination].
+ * 
+ * @sample samples.collections.Collections.Filtering.filterTo
  */
 public inline fun <C : MutableCollection<in Long>> LongArray.filterNotTo(destination: C, predicate: (Long) -> Boolean): C {
     for (element in this) if (!predicate(element)) destination.add(element)
@@ -4027,6 +4079,8 @@ public inline fun <C : MutableCollection<in Long>> LongArray.filterNotTo(destina
 
 /**
  * Appends all elements not matching the given [predicate] to the given [destination].
+ * 
+ * @sample samples.collections.Collections.Filtering.filterTo
  */
 public inline fun <C : MutableCollection<in Float>> FloatArray.filterNotTo(destination: C, predicate: (Float) -> Boolean): C {
     for (element in this) if (!predicate(element)) destination.add(element)
@@ -4035,6 +4089,8 @@ public inline fun <C : MutableCollection<in Float>> FloatArray.filterNotTo(desti
 
 /**
  * Appends all elements not matching the given [predicate] to the given [destination].
+ * 
+ * @sample samples.collections.Collections.Filtering.filterTo
  */
 public inline fun <C : MutableCollection<in Double>> DoubleArray.filterNotTo(destination: C, predicate: (Double) -> Boolean): C {
     for (element in this) if (!predicate(element)) destination.add(element)
@@ -4043,6 +4099,8 @@ public inline fun <C : MutableCollection<in Double>> DoubleArray.filterNotTo(des
 
 /**
  * Appends all elements not matching the given [predicate] to the given [destination].
+ * 
+ * @sample samples.collections.Collections.Filtering.filterTo
  */
 public inline fun <C : MutableCollection<in Boolean>> BooleanArray.filterNotTo(destination: C, predicate: (Boolean) -> Boolean): C {
     for (element in this) if (!predicate(element)) destination.add(element)
@@ -4051,6 +4109,8 @@ public inline fun <C : MutableCollection<in Boolean>> BooleanArray.filterNotTo(d
 
 /**
  * Appends all elements not matching the given [predicate] to the given [destination].
+ * 
+ * @sample samples.collections.Collections.Filtering.filterTo
  */
 public inline fun <C : MutableCollection<in Char>> CharArray.filterNotTo(destination: C, predicate: (Char) -> Boolean): C {
     for (element in this) if (!predicate(element)) destination.add(element)
@@ -4059,6 +4119,8 @@ public inline fun <C : MutableCollection<in Char>> CharArray.filterNotTo(destina
 
 /**
  * Appends all elements matching the given [predicate] to the given [destination].
+ * 
+ * @sample samples.collections.Collections.Filtering.filterTo
  */
 public inline fun <T, C : MutableCollection<in T>> Array<out T>.filterTo(destination: C, predicate: (T) -> Boolean): C {
     for (element in this) if (predicate(element)) destination.add(element)
@@ -4067,6 +4129,8 @@ public inline fun <T, C : MutableCollection<in T>> Array<out T>.filterTo(destina
 
 /**
  * Appends all elements matching the given [predicate] to the given [destination].
+ * 
+ * @sample samples.collections.Collections.Filtering.filterTo
  */
 public inline fun <C : MutableCollection<in Byte>> ByteArray.filterTo(destination: C, predicate: (Byte) -> Boolean): C {
     for (element in this) if (predicate(element)) destination.add(element)
@@ -4075,6 +4139,8 @@ public inline fun <C : MutableCollection<in Byte>> ByteArray.filterTo(destinatio
 
 /**
  * Appends all elements matching the given [predicate] to the given [destination].
+ * 
+ * @sample samples.collections.Collections.Filtering.filterTo
  */
 public inline fun <C : MutableCollection<in Short>> ShortArray.filterTo(destination: C, predicate: (Short) -> Boolean): C {
     for (element in this) if (predicate(element)) destination.add(element)
@@ -4083,6 +4149,8 @@ public inline fun <C : MutableCollection<in Short>> ShortArray.filterTo(destinat
 
 /**
  * Appends all elements matching the given [predicate] to the given [destination].
+ * 
+ * @sample samples.collections.Collections.Filtering.filterTo
  */
 public inline fun <C : MutableCollection<in Int>> IntArray.filterTo(destination: C, predicate: (Int) -> Boolean): C {
     for (element in this) if (predicate(element)) destination.add(element)
@@ -4091,6 +4159,8 @@ public inline fun <C : MutableCollection<in Int>> IntArray.filterTo(destination:
 
 /**
  * Appends all elements matching the given [predicate] to the given [destination].
+ * 
+ * @sample samples.collections.Collections.Filtering.filterTo
  */
 public inline fun <C : MutableCollection<in Long>> LongArray.filterTo(destination: C, predicate: (Long) -> Boolean): C {
     for (element in this) if (predicate(element)) destination.add(element)
@@ -4099,6 +4169,8 @@ public inline fun <C : MutableCollection<in Long>> LongArray.filterTo(destinatio
 
 /**
  * Appends all elements matching the given [predicate] to the given [destination].
+ * 
+ * @sample samples.collections.Collections.Filtering.filterTo
  */
 public inline fun <C : MutableCollection<in Float>> FloatArray.filterTo(destination: C, predicate: (Float) -> Boolean): C {
     for (element in this) if (predicate(element)) destination.add(element)
@@ -4107,6 +4179,8 @@ public inline fun <C : MutableCollection<in Float>> FloatArray.filterTo(destinat
 
 /**
  * Appends all elements matching the given [predicate] to the given [destination].
+ * 
+ * @sample samples.collections.Collections.Filtering.filterTo
  */
 public inline fun <C : MutableCollection<in Double>> DoubleArray.filterTo(destination: C, predicate: (Double) -> Boolean): C {
     for (element in this) if (predicate(element)) destination.add(element)
@@ -4115,6 +4189,8 @@ public inline fun <C : MutableCollection<in Double>> DoubleArray.filterTo(destin
 
 /**
  * Appends all elements matching the given [predicate] to the given [destination].
+ * 
+ * @sample samples.collections.Collections.Filtering.filterTo
  */
 public inline fun <C : MutableCollection<in Boolean>> BooleanArray.filterTo(destination: C, predicate: (Boolean) -> Boolean): C {
     for (element in this) if (predicate(element)) destination.add(element)
@@ -4123,6 +4199,8 @@ public inline fun <C : MutableCollection<in Boolean>> BooleanArray.filterTo(dest
 
 /**
  * Appends all elements matching the given [predicate] to the given [destination].
+ * 
+ * @sample samples.collections.Collections.Filtering.filterTo
  */
 public inline fun <C : MutableCollection<in Char>> CharArray.filterTo(destination: C, predicate: (Char) -> Boolean): C {
     for (element in this) if (predicate(element)) destination.add(element)

libraries/stdlib/common/src/generated/_Collections.kt

@@ -710,6 +710,8 @@ public inline fun <T> Iterable<T>.filter(predicate: (T) -> Boolean): List<T> {
  * Returns a list containing only elements matching the given [predicate].
  * @param [predicate] function that takes the index of an element and the element itself
  * and returns the result of predicate evaluation on the element.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIndexed
  */
 public inline fun <T> Iterable<T>.filterIndexed(predicate: (index: Int, T) -> Boolean): List<T> {
     return filterIndexedTo(ArrayList<T>(), predicate)
@@ -719,6 +721,8 @@ public inline fun <T> Iterable<T>.filterIndexed(predicate: (index: Int, T) -> Bo
  * Appends all elements matching the given [predicate] to the given [destination].
  * @param [predicate] function that takes the index of an element and the element itself
  * and returns the result of predicate evaluation on the element.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIndexedTo
  */
 public inline fun <T, C : MutableCollection<in T>> Iterable<T>.filterIndexedTo(destination: C, predicate: (index: Int, T) -> Boolean): C {
     forEachIndexed { index, element ->
@@ -729,6 +733,8 @@ public inline fun <T, C : MutableCollection<in T>> Iterable<T>.filterIndexedTo(d
 
 /**
  * Returns a list containing all elements that are instances of specified type parameter R.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIsInstance
  */
 public inline fun <reified R> Iterable<*>.filterIsInstance(): List<@kotlin.internal.NoInfer R> {
     return filterIsInstanceTo(ArrayList<R>())
@@ -736,6 +742,8 @@ public inline fun <reified R> Iterable<*>.filterIsInstance(): List<@kotlin.inter
 
 /**
  * Appends all elements that are instances of specified type parameter R to the given [destination].
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIsInstanceTo
  */
 public inline fun <reified R, C : MutableCollection<in R>> Iterable<*>.filterIsInstanceTo(destination: C): C {
     for (element in this) if (element is R) destination.add(element)
@@ -762,6 +770,8 @@ public fun <T : Any> Iterable<T?>.filterNotNull(): List<T> {
 
 /**
  * Appends all elements that are not `null` to the given [destination].
+ * 
+ * @sample samples.collections.Collections.Filtering.filterNotNullTo
  */
 public fun <C : MutableCollection<in T>, T : Any> Iterable<T?>.filterNotNullTo(destination: C): C {
     for (element in this) if (element != null) destination.add(element)
@@ -770,6 +780,8 @@ public fun <C : MutableCollection<in T>, T : Any> Iterable<T?>.filterNotNullTo(d
 
 /**
  * Appends all elements not matching the given [predicate] to the given [destination].
+ * 
+ * @sample samples.collections.Collections.Filtering.filterTo
  */
 public inline fun <T, C : MutableCollection<in T>> Iterable<T>.filterNotTo(destination: C, predicate: (T) -> Boolean): C {
     for (element in this) if (!predicate(element)) destination.add(element)
@@ -778,6 +790,8 @@ public inline fun <T, C : MutableCollection<in T>> Iterable<T>.filterNotTo(desti
 
 /**
  * Appends all elements matching the given [predicate] to the given [destination].
+ * 
+ * @sample samples.collections.Collections.Filtering.filterTo
  */
 public inline fun <T, C : MutableCollection<in T>> Iterable<T>.filterTo(destination: C, predicate: (T) -> Boolean): C {
     for (element in this) if (predicate(element)) destination.add(element)

libraries/stdlib/common/src/generated/_Sequences.kt

@@ -388,6 +388,8 @@ public fun <T> Sequence<T>.filter(predicate: (T) -> Boolean): Sequence<T> {
  * and returns the result of predicate evaluation on the element.
  *
  * The operation is _intermediate_ and _stateless_.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIndexed
  */
 public fun <T> Sequence<T>.filterIndexed(predicate: (index: Int, T) -> Boolean): Sequence<T> {
     // TODO: Rewrite with generalized MapFilterIndexingSequence
@@ -400,6 +402,8 @@ public fun <T> Sequence<T>.filterIndexed(predicate: (index: Int, T) -> Boolean):
  * and returns the result of predicate evaluation on the element.
  *
  * The operation is _terminal_.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIndexedTo
  */
 public inline fun <T, C : MutableCollection<in T>> Sequence<T>.filterIndexedTo(destination: C, predicate: (index: Int, T) -> Boolean): C {
     forEachIndexed { index, element ->
@@ -412,6 +416,8 @@ public inline fun <T, C : MutableCollection<in T>> Sequence<T>.filterIndexedTo(d
  * Returns a sequence containing all elements that are instances of specified type parameter R.
  *
  * The operation is _intermediate_ and _stateless_.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIsInstance
  */
 public inline fun <reified R> Sequence<*>.filterIsInstance(): Sequence<@kotlin.internal.NoInfer R> {
     @Suppress("UNCHECKED_CAST")
@@ -422,6 +428,8 @@ public inline fun <reified R> Sequence<*>.filterIsInstance(): Sequence<@kotlin.i
  * Appends all elements that are instances of specified type parameter R to the given [destination].
  *
  * The operation is _terminal_.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIsInstanceTo
  */
 public inline fun <reified R, C : MutableCollection<in R>> Sequence<*>.filterIsInstanceTo(destination: C): C {
     for (element in this) if (element is R) destination.add(element)
@@ -455,6 +463,8 @@ public fun <T : Any> Sequence<T?>.filterNotNull(): Sequence<T> {
  * Appends all elements that are not `null` to the given [destination].
  *
  * The operation is _terminal_.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterNotNullTo
  */
 public fun <C : MutableCollection<in T>, T : Any> Sequence<T?>.filterNotNullTo(destination: C): C {
     for (element in this) if (element != null) destination.add(element)
@@ -465,6 +475,8 @@ public fun <C : MutableCollection<in T>, T : Any> Sequence<T?>.filterNotNullTo(d
  * Appends all elements not matching the given [predicate] to the given [destination].
  *
  * The operation is _terminal_.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterTo
  */
 public inline fun <T, C : MutableCollection<in T>> Sequence<T>.filterNotTo(destination: C, predicate: (T) -> Boolean): C {
     for (element in this) if (!predicate(element)) destination.add(element)
@@ -475,6 +487,8 @@ public inline fun <T, C : MutableCollection<in T>> Sequence<T>.filterNotTo(desti
  * Appends all elements matching the given [predicate] to the given [destination].
  *
  * The operation is _terminal_.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterTo
  */
 public inline fun <T, C : MutableCollection<in T>> Sequence<T>.filterTo(destination: C, predicate: (T) -> Boolean): C {
     for (element in this) if (predicate(element)) destination.add(element)

libraries/stdlib/common/src/generated/_Strings.kt

@@ -386,6 +386,8 @@ public inline fun String.filter(predicate: (Char) -> Boolean): String {
  * Returns a char sequence containing only those characters from the original char sequence that match the given [predicate].
  * @param [predicate] function that takes the index of a character and the character itself
  * and returns the result of predicate evaluation on the character.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIndexed
  */
 public inline fun CharSequence.filterIndexed(predicate: (index: Int, Char) -> Boolean): CharSequence {
     return filterIndexedTo(StringBuilder(), predicate)
@@ -395,6 +397,8 @@ public inline fun CharSequence.filterIndexed(predicate: (index: Int, Char) -> Bo
  * Returns a string containing only those characters from the original string that match the given [predicate].
  * @param [predicate] function that takes the index of a character and the character itself
  * and returns the result of predicate evaluation on the character.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIndexed
  */
 public inline fun String.filterIndexed(predicate: (index: Int, Char) -> Boolean): String {
     return filterIndexedTo(StringBuilder(), predicate).toString()
@@ -404,6 +408,8 @@ public inline fun String.filterIndexed(predicate: (index: Int, Char) -> Boolean)
  * Appends all characters matching the given [predicate] to the given [destination].
  * @param [predicate] function that takes the index of a character and the character itself
  * and returns the result of predicate evaluation on the character.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIndexedTo
  */
 public inline fun <C : Appendable> CharSequence.filterIndexedTo(destination: C, predicate: (index: Int, Char) -> Boolean): C {
     forEachIndexed { index, element ->
@@ -432,6 +438,8 @@ public inline fun String.filterNot(predicate: (Char) -> Boolean): String {
 
 /**
  * Appends all characters not matching the given [predicate] to the given [destination].
+ * 
+ * @sample samples.collections.Collections.Filtering.filterTo
  */
 public inline fun <C : Appendable> CharSequence.filterNotTo(destination: C, predicate: (Char) -> Boolean): C {
     for (element in this) if (!predicate(element)) destination.append(element)
@@ -440,6 +448,8 @@ public inline fun <C : Appendable> CharSequence.filterNotTo(destination: C, pred
 
 /**
  * Appends all characters matching the given [predicate] to the given [destination].
+ * 
+ * @sample samples.collections.Collections.Filtering.filterTo
  */
 public inline fun <C : Appendable> CharSequence.filterTo(destination: C, predicate: (Char) -> Boolean): C {
     for (index in 0 until length) {

libraries/stdlib/common/src/generated/_UArrays.kt

@@ -1842,6 +1842,8 @@ public inline fun UShortArray.filter(predicate: (UShort) -> Boolean): List<UShor
  * Returns a list containing only elements matching the given [predicate].
  * @param [predicate] function that takes the index of an element and the element itself
  * and returns the result of predicate evaluation on the element.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIndexed
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
@@ -1854,6 +1856,8 @@ public inline fun UIntArray.filterIndexed(predicate: (index: Int, UInt) -> Boole
  * Returns a list containing only elements matching the given [predicate].
  * @param [predicate] function that takes the index of an element and the element itself
  * and returns the result of predicate evaluation on the element.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIndexed
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
@@ -1866,6 +1870,8 @@ public inline fun ULongArray.filterIndexed(predicate: (index: Int, ULong) -> Boo
  * Returns a list containing only elements matching the given [predicate].
  * @param [predicate] function that takes the index of an element and the element itself
  * and returns the result of predicate evaluation on the element.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIndexed
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
@@ -1878,6 +1884,8 @@ public inline fun UByteArray.filterIndexed(predicate: (index: Int, UByte) -> Boo
  * Returns a list containing only elements matching the given [predicate].
  * @param [predicate] function that takes the index of an element and the element itself
  * and returns the result of predicate evaluation on the element.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIndexed
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
@@ -1890,6 +1898,8 @@ public inline fun UShortArray.filterIndexed(predicate: (index: Int, UShort) -> B
  * Appends all elements matching the given [predicate] to the given [destination].
  * @param [predicate] function that takes the index of an element and the element itself
  * and returns the result of predicate evaluation on the element.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIndexedTo
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
@@ -1905,6 +1915,8 @@ public inline fun <C : MutableCollection<in UInt>> UIntArray.filterIndexedTo(des
  * Appends all elements matching the given [predicate] to the given [destination].
  * @param [predicate] function that takes the index of an element and the element itself
  * and returns the result of predicate evaluation on the element.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIndexedTo
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
@@ -1920,6 +1932,8 @@ public inline fun <C : MutableCollection<in ULong>> ULongArray.filterIndexedTo(d
  * Appends all elements matching the given [predicate] to the given [destination].
  * @param [predicate] function that takes the index of an element and the element itself
  * and returns the result of predicate evaluation on the element.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIndexedTo
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
@@ -1935,6 +1949,8 @@ public inline fun <C : MutableCollection<in UByte>> UByteArray.filterIndexedTo(d
  * Appends all elements matching the given [predicate] to the given [destination].
  * @param [predicate] function that takes the index of an element and the element itself
  * and returns the result of predicate evaluation on the element.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIndexedTo
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
@@ -1996,6 +2012,8 @@ public inline fun UShortArray.filterNot(predicate: (UShort) -> Boolean): List<US
 
 /**
  * Appends all elements not matching the given [predicate] to the given [destination].
+ * 
+ * @sample samples.collections.Collections.Filtering.filterTo
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
@@ -2007,6 +2025,8 @@ public inline fun <C : MutableCollection<in UInt>> UIntArray.filterNotTo(destina
 
 /**
  * Appends all elements not matching the given [predicate] to the given [destination].
+ * 
+ * @sample samples.collections.Collections.Filtering.filterTo
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
@@ -2018,6 +2038,8 @@ public inline fun <C : MutableCollection<in ULong>> ULongArray.filterNotTo(desti
 
 /**
  * Appends all elements not matching the given [predicate] to the given [destination].
+ * 
+ * @sample samples.collections.Collections.Filtering.filterTo
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
@@ -2029,6 +2051,8 @@ public inline fun <C : MutableCollection<in UByte>> UByteArray.filterNotTo(desti
 
 /**
  * Appends all elements not matching the given [predicate] to the given [destination].
+ * 
+ * @sample samples.collections.Collections.Filtering.filterTo
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
@@ -2040,6 +2064,8 @@ public inline fun <C : MutableCollection<in UShort>> UShortArray.filterNotTo(des
 
 /**
  * Appends all elements matching the given [predicate] to the given [destination].
+ * 
+ * @sample samples.collections.Collections.Filtering.filterTo
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
@@ -2051,6 +2077,8 @@ public inline fun <C : MutableCollection<in UInt>> UIntArray.filterTo(destinatio
 
 /**
  * Appends all elements matching the given [predicate] to the given [destination].
+ * 
+ * @sample samples.collections.Collections.Filtering.filterTo
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
@@ -2062,6 +2090,8 @@ public inline fun <C : MutableCollection<in ULong>> ULongArray.filterTo(destinat
 
 /**
  * Appends all elements matching the given [predicate] to the given [destination].
+ * 
+ * @sample samples.collections.Collections.Filtering.filterTo
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
@@ -2073,6 +2103,8 @@ public inline fun <C : MutableCollection<in UByte>> UByteArray.filterTo(destinat
 
 /**
  * Appends all elements matching the given [predicate] to the given [destination].
+ * 
+ * @sample samples.collections.Collections.Filtering.filterTo
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes

libraries/stdlib/jvm/src/generated/_ArraysJvm.kt

@@ -108,6 +108,8 @@ public actual inline fun CharArray.elementAt(index: Int): Char {
 
 /**
  * Returns a list containing all elements that are instances of specified class.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIsInstanceJVM
  */
 public fun <R> Array<*>.filterIsInstance(klass: Class<R>): List<R> {
     return filterIsInstanceTo(ArrayList<R>(), klass)
@@ -115,6 +117,8 @@ public fun <R> Array<*>.filterIsInstance(klass: Class<R>): List<R> {
 
 /**
  * Appends all elements that are instances of specified class to the given [destination].
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIsInstanceToJVM
  */
 public fun <C : MutableCollection<in R>, R> Array<*>.filterIsInstanceTo(destination: C, klass: Class<R>): C {
     @Suppress("UNCHECKED_CAST")

libraries/stdlib/jvm/src/generated/_CollectionsJvm.kt

@@ -18,6 +18,8 @@ import kotlin.ranges.reversed
 
 /**
  * Returns a list containing all elements that are instances of specified class.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIsInstanceJVM
  */
 public fun <R> Iterable<*>.filterIsInstance(klass: Class<R>): List<R> {
     return filterIsInstanceTo(ArrayList<R>(), klass)
@@ -25,6 +27,8 @@ public fun <R> Iterable<*>.filterIsInstance(klass: Class<R>): List<R> {
 
 /**
  * Appends all elements that are instances of specified class to the given [destination].
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIsInstanceToJVM
  */
 public fun <C : MutableCollection<in R>, R> Iterable<*>.filterIsInstanceTo(destination: C, klass: Class<R>): C {
     @Suppress("UNCHECKED_CAST")

libraries/stdlib/jvm/src/generated/_SequencesJvm.kt

@@ -18,6 +18,8 @@ package kotlin.sequences
  * Returns a sequence containing all elements that are instances of specified class.
  *
  * The operation is _intermediate_ and _stateless_.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIsInstanceJVM
  */
 public fun <R> Sequence<*>.filterIsInstance(klass: Class<R>): Sequence<R> {
     @Suppress("UNCHECKED_CAST")
@@ -28,6 +30,8 @@ public fun <R> Sequence<*>.filterIsInstance(klass: Class<R>): Sequence<R> {
  * Appends all elements that are instances of specified class to the given [destination].
  *
  * The operation is _terminal_.
+ * 
+ * @sample samples.collections.Collections.Filtering.filterIsInstanceToJVM
  */
 public fun <C : MutableCollection<in R>, R> Sequence<*>.filterIsInstanceTo(destination: C, klass: Class<R>): C {
     @Suppress("UNCHECKED_CAST")

libraries/stdlib/samples/test/samples/collections/collections.kt

@@ -828,6 +828,21 @@ class Collections {
             assertPrints(notMultiplesOf3, "[1, 2, 4, 5, 7]")
         }
 
+        @Sample
+        fun filterTo() {
+            val numbers: List<Int> = listOf(1, 2, 3, 4, 5, 6, 7)
+            val evenNumbers = mutableListOf<Int>()
+            val notMultiplesOf3 = mutableListOf<Int>()
+
+            assertPrints(evenNumbers, "[]")
+
+            numbers.filterTo(evenNumbers) { it % 2 == 0 }
+            numbers.filterNotTo(notMultiplesOf3) { number -> number % 3 == 0 }
+
+            assertPrints(evenNumbers, "[2, 4, 6]")
+            assertPrints(notMultiplesOf3, "[1, 2, 4, 5, 7]")
+        }
+
         @Sample
         fun filterNotNull() {
             val numbers: List<Int?> = listOf(1, 2, null, 4)
@@ -835,5 +850,110 @@ class Collections {
 
             assertPrints(nonNullNumbers, "[1, 2, 4]")
         }
+
+        @Sample
+        fun filterNotNullTo() {
+            val numbers: List<Int?> = listOf(1, 2, null, 4)
+            val nonNullNumbers = mutableListOf<Int>()
+
+            assertPrints(nonNullNumbers, "[]")
+
+            numbers.filterNotNullTo(nonNullNumbers)
+
+            assertPrints(nonNullNumbers, "[1, 2, 4]")
+        }
+
+        @Sample
+        fun filterIndexed() {
+            val numbers: List<Int> = listOf(0, 1, 2, 3, 4, 8, 6)
+            val numbersOnSameIndexAsValue = numbers.filterIndexed { index, i -> index == i }
+
+            assertPrints(numbersOnSameIndexAsValue, "[0, 1, 2, 3, 4, 6]")
+        }
+
+        @Sample
+        fun filterIndexedTo() {
+            val numbers: List<Int> = listOf(0, 1, 2, 3, 4, 8, 6)
+            val numbersOnSameIndexAsValue = mutableListOf<Int>()
+
+            assertPrints(numbersOnSameIndexAsValue, "[]")
+
+            numbers.filterIndexedTo(numbersOnSameIndexAsValue) { index, i -> index == i }
+
+            assertPrints(numbersOnSameIndexAsValue, "[0, 1, 2, 3, 4, 6]")
+        }
+
+        @Sample
+        fun filterIsInstance() {
+            open class Animal(val name: String) {
+                override fun toString(): String {
+                    return name
+                }
+            }
+            class Dog(name: String): Animal(name)
+            class Cat(name: String): Animal(name)
+
+            val animals: List<Animal> = listOf(Cat("Scratchy"), Dog("Poochie"))
+            val cats = animals.filterIsInstance<Cat>()
+
+            assertPrints(cats, "[Scratchy]")
+        }
+
+        @Sample
+        fun filterIsInstanceJVM() {
+            open class Animal(val name: String) {
+                override fun toString(): String {
+                    return name
+                }
+            }
+            class Dog(name: String): Animal(name)
+            class Cat(name: String): Animal(name)
+
+            val animals: List<Animal> = listOf(Cat("Scratchy"), Dog("Poochie"))
+            val cats = animals.filterIsInstance(Cat::class.java)
+
+            assertPrints(cats, "[Scratchy]")
+        }
+
+        @Sample
+        fun filterIsInstanceTo() {
+            open class Animal(val name: String) {
+                override fun toString(): String {
+                    return name
+                }
+            }
+            class Dog(name: String): Animal(name)
+            class Cat(name: String): Animal(name)
+
+            val animals: List<Animal> = listOf(Cat("Scratchy"), Dog("Poochie"))
+            val cats = mutableListOf<Cat>()
+
+            assertPrints(cats, "[]")
+
+            animals.filterIsInstanceTo<Cat, MutableList<Cat>>(cats)
+
+            assertPrints(cats, "[Scratchy]")
+        }
+
+        @Sample
+        fun filterIsInstanceToJVM() {
+            open class Animal(val name: String) {
+                override fun toString(): String {
+                    return name
+                }
+            }
+            class Dog(name: String): Animal(name)
+            class Cat(name: String): Animal(name)
+
+            val animals: List<Animal> = listOf(Cat("Scratchy"), Dog("Poochie"))
+            val cats = mutableListOf<Cat>()
+
+            assertPrints(cats, "[]")
+
+            animals.filterIsInstanceTo(cats, Cat::class.java)
+
+            assertPrints(cats, "[Scratchy]")
+        }
+
     }
 }

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

@@ -578,6 +578,7 @@ object Filtering : TemplateGroupBase() {
         specialFor(ArraysOfUnsigned) { inlineOnly() }
 
         doc { "Appends all ${f.element.pluralize()} matching the given [predicate] to the given [destination]." }
+        sample("samples.collections.Collections.Filtering.filterTo")
         typeParam("C : TCollection")
         returns("C")
 
@@ -613,6 +614,7 @@ object Filtering : TemplateGroupBase() {
             and returns the result of predicate evaluation on the ${f.element}.
             """
         }
+        sample("samples.collections.Collections.Filtering.filterIndexed")
         returns("List<T>")
         body {
             """
@@ -657,6 +659,7 @@ object Filtering : TemplateGroupBase() {
             @param [predicate] function that takes the index of ${f.element.prefixWithArticle()} and the ${f.element} itself
             and returns the result of predicate evaluation on the ${f.element}.
             """ }
+        sample("samples.collections.Collections.Filtering.filterIndexedTo")
         typeParam("C : TCollection")
         returns("C")
 
@@ -709,6 +712,7 @@ object Filtering : TemplateGroupBase() {
         specialFor(ArraysOfUnsigned) { inlineOnly() }
 
         doc { "Appends all elements not matching the given [predicate] to the given [destination]." }
+        sample("samples.collections.Collections.Filtering.filterTo")
         typeParam("C : TCollection")
         returns("C")
 
@@ -760,6 +764,7 @@ object Filtering : TemplateGroupBase() {
         include(Iterables, Sequences, ArraysOfObjects)
     } builder {
         doc { "Appends all elements that are not `null` to the given [destination]." }
+        sample("samples.collections.Collections.Filtering.filterNotNullTo")
         returns("C")
         typeParam("C : TCollection")
         typeParam("T : Any")
@@ -776,6 +781,7 @@ object Filtering : TemplateGroupBase() {
         include(Iterables, Sequences, ArraysOfObjects)
     } builder {
         doc { "Appends all elements that are instances of specified type parameter R to the given [destination]." }
+        sample("samples.collections.Collections.Filtering.filterIsInstanceTo")
         typeParam("reified R")
         typeParam("C : MutableCollection<in R>")
         inline()
@@ -793,6 +799,7 @@ object Filtering : TemplateGroupBase() {
         include(Iterables, Sequences, ArraysOfObjects)
     } builder {
         doc { "Returns a list containing all elements that are instances of specified type parameter R." }
+        sample("samples.collections.Collections.Filtering.filterIsInstance")
         typeParam("reified R")
         returns("List<@kotlin.internal.NoInfer R>")
         inline()
@@ -820,6 +827,7 @@ object Filtering : TemplateGroupBase() {
         include(Iterables, ArraysOfObjects, Sequences)
     } builder {
         doc { "Appends all elements that are instances of specified class to the given [destination]." }
+        sample("samples.collections.Collections.Filtering.filterIsInstanceToJVM")
         genericStarProjection = true
         typeParam("C : MutableCollection<in R>")
         typeParam("R")
@@ -838,6 +846,7 @@ object Filtering : TemplateGroupBase() {
         include(Iterables, ArraysOfObjects, Sequences)
     } builder {
         doc { "Returns a list containing all elements that are instances of specified class." }
+        sample("samples.collections.Collections.Filtering.filterIsInstanceJVM")
         genericStarProjection = true
         typeParam("R")
         returns("List<R>")