Docs and samples for 'pairwise' function

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

@@ -930,9 +930,24 @@ public expect operator fun <T> Iterable<T>.minus(elements: Sequence<T>): List<T>
 @kotlin.internal.InlineOnly
 public expect inline fun <T> Iterable<T>.minusElement(element: T): List<T>
 
+/**
+ * Returns a list of pairs of each two adjacent elements in this collection.
+ * 
+ * The returned list is empty if this collection contains less than two elements.
+ * 
+ * @sample samples.collections.Collections.Transformations.pairwise
+ */
 @SinceKotlin("1.2")
 public expect fun <T> Iterable<T>.pairwise(): List<Pair<T, T>>
 
+/**
+ * Returns a list containing the results of applying the given [transform] function
+ * to an each pair of two adjacent elements in this collection.
+ * 
+ * The returned list is empty if this collection contains less than two elements.
+ * 
+ * @sample samples.collections.Collections.Transformations.pairwiseToFindDeltas
+ */
 @SinceKotlin("1.2")
 public expect inline fun <T, R> Iterable<T>.pairwise(transform: (a: T, b: T) -> R): List<R>
 

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

@@ -854,9 +854,28 @@ public expect operator fun <T> Sequence<T>.minus(elements: Sequence<T>): Sequenc
 @kotlin.internal.InlineOnly
 public expect inline fun <T> Sequence<T>.minusElement(element: T): Sequence<T>
 
+/**
+ * Returns a sequence of pairs of each two adjacent elements in this sequence.
+ * 
+ * The returned sequence is empty if this sequence contains less than two elements.
+ * 
+ * @sample samples.collections.Collections.Transformations.pairwise
+ *
+ * The operation is _intermediate_ and _stateless_.
+ */
 @SinceKotlin("1.2")
 public expect fun <T> Sequence<T>.pairwise(): Sequence<Pair<T, T>>
 
+/**
+ * Returns a sequence containing the results of applying the given [transform] function
+ * to an each pair of two adjacent elements in this sequence.
+ * 
+ * The returned sequence is empty if this sequence contains less than two elements.
+ * 
+ * @sample samples.collections.Collections.Transformations.pairwiseToFindDeltas
+ *
+ * The operation is _intermediate_ and _stateless_.
+ */
 @SinceKotlin("1.2")
 public expect fun <T, R> Sequence<T>.pairwise(transform: (a: T, b: T) -> R): Sequence<R>
 

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

@@ -650,9 +650,24 @@ public expect fun CharSequence.chunkedSequence(size: Int): Sequence<String>
 @SinceKotlin("1.2")
 public expect fun <R> CharSequence.chunkedSequence(size: Int, transform: (CharSequence) -> R): Sequence<R> 
 
+/**
+ * Returns a list of pairs of each two adjacent characters in this char sequence.
+ * 
+ * The returned list is empty if this char sequence contains less than two characters.
+ * 
+ * @sample samples.collections.Collections.Transformations.pairwise
+ */
 @SinceKotlin("1.2")
 public expect fun CharSequence.pairwise(): List<Pair<Char, Char>>
 
+/**
+ * Returns a list containing the results of applying the given [transform] function
+ * to an each pair of two adjacent characters in this char sequence.
+ * 
+ * The returned list is empty if this char sequence contains less than two characters.
+ * 
+ * @sample samples.collections.Collections.Transformations.pairwiseToFindDeltas
+ */
 @SinceKotlin("1.2")
 public expect inline fun <R> CharSequence.pairwise(transform: (a: Char, b: Char) -> R): List<R>
 

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2010-2016 JetBrains s.r.o.
+ * Copyright 2010-2017 JetBrains s.r.o.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -70,6 +70,23 @@ class Collections {
             val moreFrequencies = moreWords.groupingBy { it.first() }.eachCountTo(frequenciesByFirstChar.toMutableMap())
             assertPrints(moreFrequencies, "{o=1, t=4, f=2, s=2, e=2, n=1}")
         }
+
+        @Sample
+        fun pairwise() {
+            val letters = ('a'..'f').toList()
+            val pairs = letters.pairwise()
+
+            assertPrints(letters, "[a, b, c, d, e, f]")
+            assertPrints(pairs, "[(a, b), (b, c), (c, d), (d, e), (e, f)]")
+        }
+
+        @Sample
+        fun pairwiseToFindDeltas() {
+            val values = listOf(1, 4, 9, 16, 25, 36)
+            val deltas = values.pairwise { a, b -> b - a }
+
+            assertPrints(deltas, "[3, 5, 7, 9, 11]")
+        }
     }
 
 }

libraries/stdlib/src/generated/_Collections.kt

@@ -1854,11 +1854,26 @@ public inline fun <T> Iterable<T>.minusElement(element: T): List<T> {
     return minus(element)
 }
 
+/**
+ * Returns a list of pairs of each two adjacent elements in this collection.
+ * 
+ * The returned list is empty if this collection contains less than two elements.
+ * 
+ * @sample samples.collections.Collections.Transformations.pairwise
+ */
 @SinceKotlin("1.2")
 public fun <T> Iterable<T>.pairwise(): List<Pair<T, T>> {
     return pairwise { a, b -> a to b }
 }
 
+/**
+ * Returns a list containing the results of applying the given [transform] function
+ * to an each pair of two adjacent elements in this collection.
+ * 
+ * The returned list is empty if this collection contains less than two elements.
+ * 
+ * @sample samples.collections.Collections.Transformations.pairwiseToFindDeltas
+ */
 @SinceKotlin("1.2")
 public inline fun <T, R> Iterable<T>.pairwise(transform: (a: T, b: T) -> R): List<R> {
     val iterator = iterator()

libraries/stdlib/src/generated/_Sequences.kt

@@ -1423,11 +1423,30 @@ public inline fun <T> Sequence<T>.minusElement(element: T): Sequence<T> {
     return minus(element)
 }
 
+/**
+ * Returns a sequence of pairs of each two adjacent elements in this sequence.
+ * 
+ * The returned sequence is empty if this sequence contains less than two elements.
+ * 
+ * @sample samples.collections.Collections.Transformations.pairwise
+ *
+ * The operation is _intermediate_ and _stateless_.
+ */
 @SinceKotlin("1.2")
 public fun <T> Sequence<T>.pairwise(): Sequence<Pair<T, T>> {
     return pairwise { a, b -> a to b }
 }
 
+/**
+ * Returns a sequence containing the results of applying the given [transform] function
+ * to an each pair of two adjacent elements in this sequence.
+ * 
+ * The returned sequence is empty if this sequence contains less than two elements.
+ * 
+ * @sample samples.collections.Collections.Transformations.pairwiseToFindDeltas
+ *
+ * The operation is _intermediate_ and _stateless_.
+ */
 @SinceKotlin("1.2")
 public fun <T, R> Sequence<T>.pairwise(transform: (a: T, b: T) -> R): Sequence<R> {
     return buildSequence result@ {

libraries/stdlib/src/generated/_Strings.kt

@@ -1130,11 +1130,26 @@ public fun <R> CharSequence.chunkedSequence(size: Int, transform: (CharSequence)
     return windowedSequence(size, size, transform)
 }
 
+/**
+ * Returns a list of pairs of each two adjacent characters in this char sequence.
+ * 
+ * The returned list is empty if this char sequence contains less than two characters.
+ * 
+ * @sample samples.collections.Collections.Transformations.pairwise
+ */
 @SinceKotlin("1.2")
 public fun CharSequence.pairwise(): List<Pair<Char, Char>> {
     return pairwise { a, b -> a to b }
 }
 
+/**
+ * Returns a list containing the results of applying the given [transform] function
+ * to an each pair of two adjacent characters in this char sequence.
+ * 
+ * The returned list is empty if this char sequence contains less than two characters.
+ * 
+ * @sample samples.collections.Collections.Transformations.pairwiseToFindDeltas
+ */
 @SinceKotlin("1.2")
 public inline fun <R> CharSequence.pairwise(transform: (a: Char, b: Char) -> R): List<R> {
     val size = length - 1