Docs and samples for 'pairwise' function

js/js.libraries/src/core/generated/_CollectionsJs.kt

@@ -1844,11 +1844,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()

js/js.libraries/src/core/generated/_SequencesJs.kt

@@ -1401,11 +1401,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@ {

js/js.libraries/src/core/generated/_StringsJs.kt

@@ -1122,11 +1122,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

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

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

@@ -718,7 +718,16 @@ fun generators(): List<GenericFunction> {
         since("1.2")
         only(Iterables, Sequences, CharSequences)
         typeParam("R")
+        doc { f ->
+            """
+            Returns a ${f.mapResult} containing the results of applying the given [transform] function
+            to an each pair of two adjacent ${f.element.pluralize()} in this ${f.collection}.
 
+            The returned ${f.mapResult} is empty if this ${f.collection} contains less than two ${f.element.pluralize()}.
+
+            @sample samples.collections.Collections.Transformations.pairwiseToFindDeltas
+            """
+        }
         returns("List<R>")
         inline(true)
         body {
@@ -748,6 +757,7 @@ fun generators(): List<GenericFunction> {
 
         }
         inline(false, Sequences)
+        sequenceClassification(intermediate, stateless)
         returns(Sequences) { "Sequence<R>" }
         body(Sequences) {
             """
@@ -769,6 +779,16 @@ fun generators(): List<GenericFunction> {
         since("1.2")
         only(Iterables, Sequences, CharSequences)
         returns("List<Pair<T, T>>")
+        doc { f ->
+            """
+            Returns a ${f.mapResult} of pairs of each two adjacent ${f.element.pluralize()} in this ${f.collection}.
+
+            The returned ${f.mapResult} is empty if this ${f.collection} contains less than two ${f.element.pluralize()}.
+
+            @sample samples.collections.Collections.Transformations.pairwise
+            """
+        }
+        sequenceClassification(intermediate, stateless)
         returns(Sequences) { "Sequence<Pair<T, T>>" }
         body {
             "return pairwise { a, b -> a to b }"