Docs and samples for 'windowed' function

2017-05-18 08:33:13 +03:00
parent b2f2e3537b
commit 99bd54116e
11 changed files with 443 additions and 15 deletions
@@ -1809,7 +1809,7 @@ public fun <T> Iterable<T>.chunked(size: Int): List<List<T>> {
 * @return list of results of the [transform] applied to an each list.
 * 
 * Note that the list passed to the [transform] function is ephemeral and is valid only inside that function.
- * You should not store it or allow it escape someway, unless you made a snapshot of it.
+ * You should not store it or allow it to escape in some way, unless you made a snapshot of it.
 * The last list may have less elements than the given [size].
 * 
 * @param size the number of elements to take in each list, must be positive and can be greater than the number of elements in this collection.
@@ -2024,6 +2024,19 @@ public inline fun <T> Collection<T>.plusElement(element: T): List<T> {
    return plus(element)
 }

+/**
+ * Returns a list of snapshots of the window of the given [size]
+ * sliding along this collection with the given [step], where each
+ * snapshot is a list.
+ * 
+ * Several last lists may have less elements than the given [size].
+ * 
+ * Both [size] and [step] must be positive and can be greater than the number of elements in this collection.
+ * @param size the number of elements to take in each window
+ * @param step the number of elements to move the window forward by on an each step
+ * 
+ * @sample samples.collections.Sequences.Transformations.takeWindows
+ */
@SinceKotlin("1.2")
 public fun <T> Iterable<T>.windowed(size: Int, step: Int): List<List<T>> {
    checkWindowSizeStep(size, step)
@@ -2044,6 +2057,21 @@ public fun <T> Iterable<T>.windowed(size: Int, step: Int): List<List<T>> {
    return result
 }

+/**
+ * Returns a list of results of applying the given [transform] function to
+ * an each list representing a view over the window of the given [size]
+ * sliding along this collection with the given [step].
+ * 
+ * Note that the list passed to the [transform] function is ephemeral and is valid only inside that function.
+ * You should not store it or allow it to escape in some way, unless you made a snapshot of it.
+ * Several last lists may have less elements than the given [size].
+ * 
+ * Both [size] and [step] must be positive and can be greater than the number of elements in this collection.
+ * @param size the number of elements to take in each window
+ * @param step the number of elements to move the window forward by on an each step
+ * 
+ * @sample samples.collections.Sequences.Transformations.averageWindows
+ */
@SinceKotlin("1.2")
 public fun <T, R> Iterable<T>.windowed(size: Int, step: Int, transform: (List<T>) -> R): List<R> {
    checkWindowSizeStep(size, step)
@@ -1332,7 +1332,7 @@ public fun <T> Sequence<T>.chunked(size: Int): Sequence<List<T>> {
 * @return sequence of results of the [transform] applied to an each list.
 * 
 * Note that the list passed to the [transform] function is ephemeral and is valid only inside that function.
- * You should not store it or allow it escape someway, unless you made a snapshot of it.
+ * You should not store it or allow it to escape in some way, unless you made a snapshot of it.
 * The last list may have less elements than the given [size].
 * 
 * @param size the number of elements to take in each list, must be positive and can be greater than the number of elements in this sequence.
@@ -1541,11 +1541,39 @@ public inline fun <T> Sequence<T>.plusElement(element: T): Sequence<T> {
    return plus(element)
 }

+/**
+ * Returns a sequence of snapshots of the window of the given [size]
+ * sliding along this sequence with the given [step], where each
+ * snapshot is a list.
+ * 
+ * Several last lists may have less elements than the given [size].
+ * 
+ * Both [size] and [step] must be positive and can be greater than the number of elements in this sequence.
+ * @param size the number of elements to take in each window
+ * @param step the number of elements to move the window forward by on an each step
+ * 
+ * @sample samples.collections.Sequences.Transformations.takeWindows
+ */
@SinceKotlin("1.2")
 public fun <T> Sequence<T>.windowed(size: Int, step: Int): Sequence<List<T>> {
    return windowedSequence(size, step, dropTrailing = false, reuseBuffer = false)
 }

+/**
+ * Returns a sequence of results of applying the given [transform] function to
+ * an each list representing a view over the window of the given [size]
+ * sliding along this sequence with the given [step].
+ * 
+ * Note that the list passed to the [transform] function is ephemeral and is valid only inside that function.
+ * You should not store it or allow it to escape in some way, unless you made a snapshot of it.
+ * Several last lists may have less elements than the given [size].
+ * 
+ * Both [size] and [step] must be positive and can be greater than the number of elements in this sequence.
+ * @param size the number of elements to take in each window
+ * @param step the number of elements to move the window forward by on an each step
+ * 
+ * @sample samples.collections.Sequences.Transformations.averageWindows
+ */
@SinceKotlin("1.2")
 public fun <T, R> Sequence<T>.windowed(size: Int, step: Int, transform: (List<T>) -> R): Sequence<R> {
    return windowedSequence(size, step, dropTrailing = false, reuseBuffer = true).map(transform)
@@ -1123,7 +1123,7 @@ public fun CharSequence.chunked(size: Int): List<String> {
 * @return list of results of the [transform] applied to an each char sequence.
 * 
 * Note that the char sequence passed to the [transform] function is ephemeral and is valid only inside that function.
- * You should not store it or allow it escape someway, unless you made a snapshot of it.
+ * You should not store it or allow it to escape in some way, unless you made a snapshot of it.
 * The last char sequence may have less characters than the given [size].
 * 
 * @param size the number of elements to take in each char sequence, must be positive and can be greater than the number of elements in this char sequence.
@@ -1156,7 +1156,7 @@ public fun CharSequence.chunkedSequence(size: Int): Sequence<String>  {
 * @return sequence of results of the [transform] applied to an each char sequence.
 * 
 * Note that the char sequence passed to the [transform] function is ephemeral and is valid only inside that function.
- * You should not store it or allow it to escape someway, unless you made a snapshot of it.
+ * You should not store it or allow it to escape in some way, unless you made a snapshot of it.
 * The last char sequence may have less characters than the given [size].
 * 
 * @param size the number of elements to take in each char sequence, must be positive and can be greater than the number of elements in this char sequence.
@@ -1235,11 +1235,39 @@ public inline fun String.partition(predicate: (Char) -> Boolean): Pair<String, S
    return Pair(first.toString(), second.toString())
 }

+/**
+ * Returns a list of snapshots of the window of the given [size]
+ * sliding along this char sequence with the given [step], where each
+ * snapshot is a string.
+ * 
+ * Several last strings may have less characters than the given [size].
+ * 
+ * Both [size] and [step] must be positive and can be greater than the number of elements in this char sequence.
+ * @param size the number of elements to take in each window
+ * @param step the number of elements to move the window forward by on an each step
+ * 
+ * @sample samples.collections.Sequences.Transformations.takeWindows
+ */
@SinceKotlin("1.2")
 public fun CharSequence.windowed(size: Int, step: Int): List<String> {
    return windowed(size, step) { it.toString() }
 }

+/**
+ * Returns a list of results of applying the given [transform] function to
+ * an each char sequence representing a view over the window of the given [size]
+ * sliding along this char sequence with the given [step].
+ * 
+ * Note that the char sequence passed to the [transform] function is ephemeral and is valid only inside that function.
+ * You should not store it or allow it to escape in some way, unless you made a snapshot of it.
+ * Several last char sequences may have less characters than the given [size].
+ * 
+ * Both [size] and [step] must be positive and can be greater than the number of elements in this char sequence.
+ * @param size the number of elements to take in each window
+ * @param step the number of elements to move the window forward by on an each step
+ * 
+ * @sample samples.collections.Sequences.Transformations.averageWindows
+ */
@SinceKotlin("1.2")
 public fun <R> CharSequence.windowed(size: Int, step: Int, transform: (CharSequence) -> R): List<R> {
    checkWindowSizeStep(size, step)
@@ -1253,11 +1281,39 @@ public fun <R> CharSequence.windowed(size: Int, step: Int, transform: (CharSeque
    return result
 }

+/**
+ * Returns a sequence of snapshots of the window of the given [size]
+ * sliding along this char sequence with the given [step], where each
+ * snapshot is a string.
+ * 
+ * Several last strings may have less characters than the given [size].
+ * 
+ * Both [size] and [step] must be positive and can be greater than the number of elements in this char sequence.
+ * @param size the number of elements to take in each window
+ * @param step the number of elements to move the window forward by on an each step
+ * 
+ * @sample samples.collections.Sequences.Transformations.takeWindows
+ */
@SinceKotlin("1.2")
 public fun CharSequence.windowedSequence(size: Int, step: Int): Sequence<String>  {
    return windowedSequence(size, step) { it.toString() }
 }

+/**
+ * Returns a sequence of results of applying the given [transform] function to
+ * an each char sequence representing a view over the window of the given [size]
+ * sliding along this char sequence with the given [step].
+ * 
+ * Note that the char sequence passed to the [transform] function is ephemeral and is valid only inside that function.
+ * You should not store it or allow it to escape in some way, unless you made a snapshot of it.
+ * Several last char sequences may have less characters than the given [size].
+ * 
+ * Both [size] and [step] must be positive and can be greater than the number of elements in this char sequence.
+ * @param size the number of elements to take in each window
+ * @param step the number of elements to move the window forward by on an each step
+ * 
+ * @sample samples.collections.Sequences.Transformations.averageWindows
+ */
@SinceKotlin("1.2")
 public fun <R> CharSequence.windowedSequence(size: Int, step: Int, transform: (CharSequence) -> R): Sequence<R>  {
    checkWindowSizeStep(size, step)
@@ -917,7 +917,7 @@ public expect fun <T> Iterable<T>.chunked(size: Int): List<List<T>>
 * @return list of results of the [transform] applied to an each list.
 * 
 * Note that the list passed to the [transform] function is ephemeral and is valid only inside that function.
- * You should not store it or allow it escape someway, unless you made a snapshot of it.
+ * You should not store it or allow it to escape in some way, unless you made a snapshot of it.
 * The last list may have less elements than the given [size].
 * 
 * @param size the number of elements to take in each list, must be positive and can be greater than the number of elements in this collection.
@@ -1033,9 +1033,37 @@ public expect inline fun <T> Iterable<T>.plusElement(element: T): List<T>
@kotlin.internal.InlineOnly
 public expect inline fun <T> Collection<T>.plusElement(element: T): List<T>

+/**
+ * Returns a list of snapshots of the window of the given [size]
+ * sliding along this collection with the given [step], where each
+ * snapshot is a list.
+ * 
+ * Several last lists may have less elements than the given [size].
+ * 
+ * Both [size] and [step] must be positive and can be greater than the number of elements in this collection.
+ * @param size the number of elements to take in each window
+ * @param step the number of elements to move the window forward by on an each step
+ * 
+ * @sample samples.collections.Sequences.Transformations.takeWindows
+ */
@SinceKotlin("1.2")
 public expect fun <T> Iterable<T>.windowed(size: Int, step: Int): List<List<T>>

+/**
+ * Returns a list of results of applying the given [transform] function to
+ * an each list representing a view over the window of the given [size]
+ * sliding along this collection with the given [step].
+ * 
+ * Note that the list passed to the [transform] function is ephemeral and is valid only inside that function.
+ * You should not store it or allow it to escape in some way, unless you made a snapshot of it.
+ * Several last lists may have less elements than the given [size].
+ * 
+ * Both [size] and [step] must be positive and can be greater than the number of elements in this collection.
+ * @param size the number of elements to take in each window
+ * @param step the number of elements to move the window forward by on an each step
+ * 
+ * @sample samples.collections.Sequences.Transformations.averageWindows
+ */
@SinceKotlin("1.2")
 public expect fun <T, R> Iterable<T>.windowed(size: Int, step: Int, transform: (List<T>) -> R): List<R>

@@ -824,7 +824,7 @@ public expect fun <T> Sequence<T>.chunked(size: Int): Sequence<List<T>>
 * @return sequence of results of the [transform] applied to an each list.
 * 
 * Note that the list passed to the [transform] function is ephemeral and is valid only inside that function.
- * You should not store it or allow it escape someway, unless you made a snapshot of it.
+ * You should not store it or allow it to escape in some way, unless you made a snapshot of it.
 * The last list may have less elements than the given [size].
 * 
 * @param size the number of elements to take in each list, must be positive and can be greater than the number of elements in this sequence.
@@ -960,9 +960,37 @@ public expect operator fun <T> Sequence<T>.plus(elements: Sequence<T>): Sequence
@kotlin.internal.InlineOnly
 public expect inline fun <T> Sequence<T>.plusElement(element: T): Sequence<T>

+/**
+ * Returns a sequence of snapshots of the window of the given [size]
+ * sliding along this sequence with the given [step], where each
+ * snapshot is a list.
+ * 
+ * Several last lists may have less elements than the given [size].
+ * 
+ * Both [size] and [step] must be positive and can be greater than the number of elements in this sequence.
+ * @param size the number of elements to take in each window
+ * @param step the number of elements to move the window forward by on an each step
+ * 
+ * @sample samples.collections.Sequences.Transformations.takeWindows
+ */
@SinceKotlin("1.2")
 public expect fun <T> Sequence<T>.windowed(size: Int, step: Int): Sequence<List<T>>

+/**
+ * Returns a sequence of results of applying the given [transform] function to
+ * an each list representing a view over the window of the given [size]
+ * sliding along this sequence with the given [step].
+ * 
+ * Note that the list passed to the [transform] function is ephemeral and is valid only inside that function.
+ * You should not store it or allow it to escape in some way, unless you made a snapshot of it.
+ * Several last lists may have less elements than the given [size].
+ * 
+ * Both [size] and [step] must be positive and can be greater than the number of elements in this sequence.
+ * @param size the number of elements to take in each window
+ * @param step the number of elements to move the window forward by on an each step
+ * 
+ * @sample samples.collections.Sequences.Transformations.averageWindows
+ */
@SinceKotlin("1.2")
 public expect fun <T, R> Sequence<T>.windowed(size: Int, step: Int, transform: (List<T>) -> R): Sequence<R>

@@ -657,7 +657,7 @@ public expect fun CharSequence.chunked(size: Int): List<String>
 * @return list of results of the [transform] applied to an each char sequence.
 * 
 * Note that the char sequence passed to the [transform] function is ephemeral and is valid only inside that function.
- * You should not store it or allow it escape someway, unless you made a snapshot of it.
+ * You should not store it or allow it to escape in some way, unless you made a snapshot of it.
 * The last char sequence may have less characters than the given [size].
 * 
 * @param size the number of elements to take in each char sequence, must be positive and can be greater than the number of elements in this char sequence.
@@ -686,7 +686,7 @@ public expect fun CharSequence.chunkedSequence(size: Int): Sequence<String>
 * @return sequence of results of the [transform] applied to an each char sequence.
 * 
 * Note that the char sequence passed to the [transform] function is ephemeral and is valid only inside that function.
- * You should not store it or allow it to escape someway, unless you made a snapshot of it.
+ * You should not store it or allow it to escape in some way, unless you made a snapshot of it.
 * The last char sequence may have less characters than the given [size].
 * 
 * @param size the number of elements to take in each char sequence, must be positive and can be greater than the number of elements in this char sequence.
@@ -731,15 +731,71 @@ public expect inline fun CharSequence.partition(predicate: (Char) -> Boolean): P
 */
 public expect inline fun String.partition(predicate: (Char) -> Boolean): Pair<String, String>

+/**
+ * Returns a list of snapshots of the window of the given [size]
+ * sliding along this char sequence with the given [step], where each
+ * snapshot is a string.
+ * 
+ * Several last strings may have less characters than the given [size].
+ * 
+ * Both [size] and [step] must be positive and can be greater than the number of elements in this char sequence.
+ * @param size the number of elements to take in each window
+ * @param step the number of elements to move the window forward by on an each step
+ * 
+ * @sample samples.collections.Sequences.Transformations.takeWindows
+ */
@SinceKotlin("1.2")
 public expect fun CharSequence.windowed(size: Int, step: Int): List<String>

+/**
+ * Returns a list of results of applying the given [transform] function to
+ * an each char sequence representing a view over the window of the given [size]
+ * sliding along this char sequence with the given [step].
+ * 
+ * Note that the char sequence passed to the [transform] function is ephemeral and is valid only inside that function.
+ * You should not store it or allow it to escape in some way, unless you made a snapshot of it.
+ * Several last char sequences may have less characters than the given [size].
+ * 
+ * Both [size] and [step] must be positive and can be greater than the number of elements in this char sequence.
+ * @param size the number of elements to take in each window
+ * @param step the number of elements to move the window forward by on an each step
+ * 
+ * @sample samples.collections.Sequences.Transformations.averageWindows
+ */
@SinceKotlin("1.2")
 public expect fun <R> CharSequence.windowed(size: Int, step: Int, transform: (CharSequence) -> R): List<R>

+/**
+ * Returns a sequence of snapshots of the window of the given [size]
+ * sliding along this char sequence with the given [step], where each
+ * snapshot is a string.
+ * 
+ * Several last strings may have less characters than the given [size].
+ * 
+ * Both [size] and [step] must be positive and can be greater than the number of elements in this char sequence.
+ * @param size the number of elements to take in each window
+ * @param step the number of elements to move the window forward by on an each step
+ * 
+ * @sample samples.collections.Sequences.Transformations.takeWindows
+ */
@SinceKotlin("1.2")
 public expect fun CharSequence.windowedSequence(size: Int, step: Int): Sequence<String> 

+/**
+ * Returns a sequence of results of applying the given [transform] function to
+ * an each char sequence representing a view over the window of the given [size]
+ * sliding along this char sequence with the given [step].
+ * 
+ * Note that the char sequence passed to the [transform] function is ephemeral and is valid only inside that function.
+ * You should not store it or allow it to escape in some way, unless you made a snapshot of it.
+ * Several last char sequences may have less characters than the given [size].
+ * 
+ * Both [size] and [step] must be positive and can be greater than the number of elements in this char sequence.
+ * @param size the number of elements to take in each window
+ * @param step the number of elements to move the window forward by on an each step
+ * 
+ * @sample samples.collections.Sequences.Transformations.averageWindows
+ */
@SinceKotlin("1.2")
 public expect fun <R> CharSequence.windowedSequence(size: Int, step: Int, transform: (CharSequence) -> R): Sequence<R> 

@@ -141,4 +141,32 @@ class Sequences {
    }


+    class Transformations {
+
+        @Sample
+        fun takeWindows() {
+            val sequence = generateSequence(1) { it + 1 }
+
+            val windows = sequence.windowed(size = 5, step = 1)
+            assertPrints(windows.take(4).toList(), "[[1, 2, 3, 4, 5], [2, 3, 4, 5, 6], [3, 4, 5, 6, 7], [4, 5, 6, 7, 8]]")
+
+            val moreSparseWindows = sequence.windowed(size = 5, step = 3)
+            assertPrints(moreSparseWindows.take(4).toList(), "[[1, 2, 3, 4, 5], [4, 5, 6, 7, 8], [7, 8, 9, 10, 11], [10, 11, 12, 13, 14]]")
+
+            val partialWindows = sequence.take(10).windowed(size = 5, step = 3)
+            assertPrints(partialWindows.toList(), "[[1, 2, 3, 4, 5], [4, 5, 6, 7, 8], [7, 8, 9, 10], [10]]")
+        }
+
+        @Sample
+        fun averageWindows() {
+            val dataPoints = sequenceOf(10, 15, 18, 25, 19, 21, 14, 8, 5)
+
+            val averaged = dataPoints.windowed(size = 4, step = 1) { window -> window.average() }
+            assertPrints(averaged.toList(), "[17.0, 19.25, 20.75, 19.75, 15.5, 12.0, 9.0, 6.5, 5.0]")
+
+            val averagedNoPartialWindows = dataPoints.windowed(size = 4, step = 1).filter { it.size == 4 }.map { it.average() }
+            assertPrints(averagedNoPartialWindows.toList(), "[17.0, 19.25, 20.75, 19.75, 15.5, 12.0]")
+        }
+    }
+
 }
@@ -1819,7 +1819,7 @@ public fun <T> Iterable<T>.chunked(size: Int): List<List<T>> {
 * @return list of results of the [transform] applied to an each list.
 * 
 * Note that the list passed to the [transform] function is ephemeral and is valid only inside that function.
- * You should not store it or allow it escape someway, unless you made a snapshot of it.
+ * You should not store it or allow it to escape in some way, unless you made a snapshot of it.
 * The last list may have less elements than the given [size].
 * 
 * @param size the number of elements to take in each list, must be positive and can be greater than the number of elements in this collection.
@@ -2034,6 +2034,19 @@ public inline fun <T> Collection<T>.plusElement(element: T): List<T> {
    return plus(element)
 }

+/**
+ * Returns a list of snapshots of the window of the given [size]
+ * sliding along this collection with the given [step], where each
+ * snapshot is a list.
+ * 
+ * Several last lists may have less elements than the given [size].
+ * 
+ * Both [size] and [step] must be positive and can be greater than the number of elements in this collection.
+ * @param size the number of elements to take in each window
+ * @param step the number of elements to move the window forward by on an each step
+ * 
+ * @sample samples.collections.Sequences.Transformations.takeWindows
+ */
@SinceKotlin("1.2")
 public fun <T> Iterable<T>.windowed(size: Int, step: Int): List<List<T>> {
    checkWindowSizeStep(size, step)
@@ -2054,6 +2067,21 @@ public fun <T> Iterable<T>.windowed(size: Int, step: Int): List<List<T>> {
    return result
 }

+/**
+ * Returns a list of results of applying the given [transform] function to
+ * an each list representing a view over the window of the given [size]
+ * sliding along this collection with the given [step].
+ * 
+ * Note that the list passed to the [transform] function is ephemeral and is valid only inside that function.
+ * You should not store it or allow it to escape in some way, unless you made a snapshot of it.
+ * Several last lists may have less elements than the given [size].
+ * 
+ * Both [size] and [step] must be positive and can be greater than the number of elements in this collection.
+ * @param size the number of elements to take in each window
+ * @param step the number of elements to move the window forward by on an each step
+ * 
+ * @sample samples.collections.Sequences.Transformations.averageWindows
+ */
@SinceKotlin("1.2")
 public fun <T, R> Iterable<T>.windowed(size: Int, step: Int, transform: (List<T>) -> R): List<R> {
    checkWindowSizeStep(size, step)
@@ -1354,7 +1354,7 @@ public fun <T> Sequence<T>.chunked(size: Int): Sequence<List<T>> {
 * @return sequence of results of the [transform] applied to an each list.
 * 
 * Note that the list passed to the [transform] function is ephemeral and is valid only inside that function.
- * You should not store it or allow it escape someway, unless you made a snapshot of it.
+ * You should not store it or allow it to escape in some way, unless you made a snapshot of it.
 * The last list may have less elements than the given [size].
 * 
 * @param size the number of elements to take in each list, must be positive and can be greater than the number of elements in this sequence.
@@ -1563,11 +1563,39 @@ public inline fun <T> Sequence<T>.plusElement(element: T): Sequence<T> {
    return plus(element)
 }

+/**
+ * Returns a sequence of snapshots of the window of the given [size]
+ * sliding along this sequence with the given [step], where each
+ * snapshot is a list.
+ * 
+ * Several last lists may have less elements than the given [size].
+ * 
+ * Both [size] and [step] must be positive and can be greater than the number of elements in this sequence.
+ * @param size the number of elements to take in each window
+ * @param step the number of elements to move the window forward by on an each step
+ * 
+ * @sample samples.collections.Sequences.Transformations.takeWindows
+ */
@SinceKotlin("1.2")
 public fun <T> Sequence<T>.windowed(size: Int, step: Int): Sequence<List<T>> {
    return windowedSequence(size, step, dropTrailing = false, reuseBuffer = false)
 }

+/**
+ * Returns a sequence of results of applying the given [transform] function to
+ * an each list representing a view over the window of the given [size]
+ * sliding along this sequence with the given [step].
+ * 
+ * Note that the list passed to the [transform] function is ephemeral and is valid only inside that function.
+ * You should not store it or allow it to escape in some way, unless you made a snapshot of it.
+ * Several last lists may have less elements than the given [size].
+ * 
+ * Both [size] and [step] must be positive and can be greater than the number of elements in this sequence.
+ * @param size the number of elements to take in each window
+ * @param step the number of elements to move the window forward by on an each step
+ * 
+ * @sample samples.collections.Sequences.Transformations.averageWindows
+ */
@SinceKotlin("1.2")
 public fun <T, R> Sequence<T>.windowed(size: Int, step: Int, transform: (List<T>) -> R): Sequence<R> {
    return windowedSequence(size, step, dropTrailing = false, reuseBuffer = true).map(transform)
@@ -1131,7 +1131,7 @@ public fun CharSequence.chunked(size: Int): List<String> {
 * @return list of results of the [transform] applied to an each char sequence.
 * 
 * Note that the char sequence passed to the [transform] function is ephemeral and is valid only inside that function.
- * You should not store it or allow it escape someway, unless you made a snapshot of it.
+ * You should not store it or allow it to escape in some way, unless you made a snapshot of it.
 * The last char sequence may have less characters than the given [size].
 * 
 * @param size the number of elements to take in each char sequence, must be positive and can be greater than the number of elements in this char sequence.
@@ -1164,7 +1164,7 @@ public fun CharSequence.chunkedSequence(size: Int): Sequence<String>  {
 * @return sequence of results of the [transform] applied to an each char sequence.
 * 
 * Note that the char sequence passed to the [transform] function is ephemeral and is valid only inside that function.
- * You should not store it or allow it to escape someway, unless you made a snapshot of it.
+ * You should not store it or allow it to escape in some way, unless you made a snapshot of it.
 * The last char sequence may have less characters than the given [size].
 * 
 * @param size the number of elements to take in each char sequence, must be positive and can be greater than the number of elements in this char sequence.
@@ -1243,11 +1243,39 @@ public inline fun String.partition(predicate: (Char) -> Boolean): Pair<String, S
    return Pair(first.toString(), second.toString())
 }

+/**
+ * Returns a list of snapshots of the window of the given [size]
+ * sliding along this char sequence with the given [step], where each
+ * snapshot is a string.
+ * 
+ * Several last strings may have less characters than the given [size].
+ * 
+ * Both [size] and [step] must be positive and can be greater than the number of elements in this char sequence.
+ * @param size the number of elements to take in each window
+ * @param step the number of elements to move the window forward by on an each step
+ * 
+ * @sample samples.collections.Sequences.Transformations.takeWindows
+ */
@SinceKotlin("1.2")
 public fun CharSequence.windowed(size: Int, step: Int): List<String> {
    return windowed(size, step) { it.toString() }
 }

+/**
+ * Returns a list of results of applying the given [transform] function to
+ * an each char sequence representing a view over the window of the given [size]
+ * sliding along this char sequence with the given [step].
+ * 
+ * Note that the char sequence passed to the [transform] function is ephemeral and is valid only inside that function.
+ * You should not store it or allow it to escape in some way, unless you made a snapshot of it.
+ * Several last char sequences may have less characters than the given [size].
+ * 
+ * Both [size] and [step] must be positive and can be greater than the number of elements in this char sequence.
+ * @param size the number of elements to take in each window
+ * @param step the number of elements to move the window forward by on an each step
+ * 
+ * @sample samples.collections.Sequences.Transformations.averageWindows
+ */
@SinceKotlin("1.2")
 public fun <R> CharSequence.windowed(size: Int, step: Int, transform: (CharSequence) -> R): List<R> {
    checkWindowSizeStep(size, step)
@@ -1261,11 +1289,39 @@ public fun <R> CharSequence.windowed(size: Int, step: Int, transform: (CharSeque
    return result
 }

+/**
+ * Returns a sequence of snapshots of the window of the given [size]
+ * sliding along this char sequence with the given [step], where each
+ * snapshot is a string.
+ * 
+ * Several last strings may have less characters than the given [size].
+ * 
+ * Both [size] and [step] must be positive and can be greater than the number of elements in this char sequence.
+ * @param size the number of elements to take in each window
+ * @param step the number of elements to move the window forward by on an each step
+ * 
+ * @sample samples.collections.Sequences.Transformations.takeWindows
+ */
@SinceKotlin("1.2")
 public fun CharSequence.windowedSequence(size: Int, step: Int): Sequence<String>  {
    return windowedSequence(size, step) { it.toString() }
 }

+/**
+ * Returns a sequence of results of applying the given [transform] function to
+ * an each char sequence representing a view over the window of the given [size]
+ * sliding along this char sequence with the given [step].
+ * 
+ * Note that the char sequence passed to the [transform] function is ephemeral and is valid only inside that function.
+ * You should not store it or allow it to escape in some way, unless you made a snapshot of it.
+ * Several last char sequences may have less characters than the given [size].
+ * 
+ * Both [size] and [step] must be positive and can be greater than the number of elements in this char sequence.
+ * @param size the number of elements to take in each window
+ * @param step the number of elements to move the window forward by on an each step
+ * 
+ * @sample samples.collections.Sequences.Transformations.averageWindows
+ */
@SinceKotlin("1.2")
 public fun <R> CharSequence.windowedSequence(size: Int, step: Int, transform: (CharSequence) -> R): Sequence<R>  {
    checkWindowSizeStep(size, step)
@@ -562,8 +562,25 @@ fun generators(): List<GenericFunction> {
    templates add f("windowed(size: Int, step: Int, transform: (List<T>) -> R)") {
        since("1.2")
        only(Iterables, Sequences, CharSequences)
-        typeParam("R")
+        doc { f ->
+            """
+            Returns a ${f.mapResult} of results of applying the given [transform] function to
+            an each ${f.viewResult} representing a view over the window of the given [size]
+            sliding along this ${f.collection} with the given [step].

+            Note that the ${f.viewResult} passed to the [transform] function is ephemeral and is valid only inside that function.
+            You should not store it or allow it to escape in some way, unless you made a snapshot of it.
+            Several last ${f.viewResult.pluralize()} may have less ${f.element.pluralize()} than the given [size].
+
+            Both [size] and [step] must be positive and can be greater than the number of elements in this ${f.collection}.
+            @param size the number of elements to take in each window
+            @param step the number of elements to move the window forward by on an each step
+
+            @sample samples.collections.Sequences.Transformations.averageWindows
+            """
+        }
+
+        typeParam("R")
        returns("List<R>")

        body {
@@ -619,6 +636,21 @@ fun generators(): List<GenericFunction> {
        returns(Sequences) { "Sequence<List<T>>" }
        returns(CharSequences) { "List<String>" }

+        doc { f ->
+            """
+            Returns a ${f.mapResult} of snapshots of the window of the given [size]
+            sliding along this ${f.collection} with the given [step], where each
+            snapshot is ${f.snapshotResult.prefixWithArticle()}.
+
+            Several last ${f.snapshotResult.pluralize()} may have less ${f.element.pluralize()} than the given [size].
+
+            Both [size] and [step] must be positive and can be greater than the number of elements in this ${f.collection}.
+            @param size the number of elements to take in each window
+            @param step the number of elements to move the window forward by on an each step
+
+            @sample samples.collections.Sequences.Transformations.takeWindows
+            """
+        }

        body {
            """
@@ -651,6 +683,23 @@ fun generators(): List<GenericFunction> {
    templates add f("windowedSequence(size: Int, step: Int, transform: (CharSequence) -> R)") {
        since("1.2")
        only(CharSequences)
+        doc { f ->
+            """
+            Returns a sequence of results of applying the given [transform] function to
+            an each ${f.viewResult} representing a view over the window of the given [size]
+            sliding along this ${f.collection} with the given [step].
+
+            Note that the ${f.viewResult} passed to the [transform] function is ephemeral and is valid only inside that function.
+            You should not store it or allow it to escape in some way, unless you made a snapshot of it.
+            Several last ${f.viewResult.pluralize()} may have less ${f.element.pluralize()} than the given [size].
+
+            Both [size] and [step] must be positive and can be greater than the number of elements in this ${f.collection}.
+            @param size the number of elements to take in each window
+            @param step the number of elements to move the window forward by on an each step
+
+            @sample samples.collections.Sequences.Transformations.averageWindows
+            """
+        }
        typeParam("R")
        returns { "Sequence<R> "}

@@ -665,6 +714,21 @@ fun generators(): List<GenericFunction> {
    templates add f("windowedSequence(size: Int, step: Int)") {
        since("1.2")
        only(CharSequences)
+        doc { f ->
+            """
+            Returns a sequence of snapshots of the window of the given [size]
+            sliding along this ${f.collection} with the given [step], where each
+            snapshot is ${f.snapshotResult.prefixWithArticle()}.
+
+            Several last ${f.snapshotResult.pluralize()} may have less ${f.element.pluralize()} than the given [size].
+
+            Both [size] and [step] must be positive and can be greater than the number of elements in this ${f.collection}.
+            @param size the number of elements to take in each window
+            @param step the number of elements to move the window forward by on an each step
+
+            @sample samples.collections.Sequences.Transformations.takeWindows
+            """
+        }
        returns { "Sequence<String> "}

        body(CharSequences) { "return windowedSequence(size, step) { it.toString() }" }
@@ -681,7 +745,7 @@ fun generators(): List<GenericFunction> {
            @return ${f.mapResult} of results of the [transform] applied to an each ${f.viewResult}.

            Note that the ${f.viewResult} passed to the [transform] function is ephemeral and is valid only inside that function.
-            You should not store it or allow it escape someway, unless you made a snapshot of it.
+            You should not store it or allow it to escape in some way, unless you made a snapshot of it.
            The last ${f.viewResult} may have less ${f.element.pluralize()} than the given [size].

            @param size the number of elements to take in each ${f.viewResult}, must be positive and can be greater than the number of elements in this ${f.collection}.
@@ -734,7 +798,7 @@ fun generators(): List<GenericFunction> {
            @return sequence of results of the [transform] applied to an each ${f.viewResult}.

            Note that the ${f.viewResult} passed to the [transform] function is ephemeral and is valid only inside that function.
-            You should not store it or allow it to escape someway, unless you made a snapshot of it.
+            You should not store it or allow it to escape in some way, unless you made a snapshot of it.
            The last ${f.viewResult} may have less ${f.element.pluralize()} than the given [size].

            @param size the number of elements to take in each ${f.viewResult}, must be positive and can be greater than the number of elements in this ${f.collection}.