From 99bd54116e1669fe16861c5789aa48929e51383a Mon Sep 17 00:00:00 2001 From: Ilya Gorbunov Date: Thu, 18 May 2017 08:33:13 +0300 Subject: [PATCH] Docs and samples for 'windowed' function --- .../src/core/generated/_CollectionsJs.kt | 30 +++++++- .../src/core/generated/_SequencesJs.kt | 30 +++++++- .../src/core/generated/_StringsJs.kt | 60 +++++++++++++++- .../common/src/generated/_Collections.kt | 30 +++++++- .../stdlib/common/src/generated/_Sequences.kt | 30 +++++++- .../stdlib/common/src/generated/_Strings.kt | 60 +++++++++++++++- .../test/samples/collections/sequences.kt | 28 ++++++++ .../stdlib/src/generated/_Collections.kt | 30 +++++++- libraries/stdlib/src/generated/_Sequences.kt | 30 +++++++- libraries/stdlib/src/generated/_Strings.kt | 60 +++++++++++++++- .../src/templates/Generators.kt | 70 ++++++++++++++++++- 11 files changed, 443 insertions(+), 15 deletions(-) diff --git a/js/js.libraries/src/core/generated/_CollectionsJs.kt b/js/js.libraries/src/core/generated/_CollectionsJs.kt index cab3f1b5226..4d88f2887af 100644 --- a/js/js.libraries/src/core/generated/_CollectionsJs.kt +++ b/js/js.libraries/src/core/generated/_CollectionsJs.kt @@ -1809,7 +1809,7 @@ public fun Iterable.chunked(size: Int): List> { * @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 Collection.plusElement(element: T): List { 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 Iterable.windowed(size: Int, step: Int): List> { checkWindowSizeStep(size, step) @@ -2044,6 +2057,21 @@ public fun Iterable.windowed(size: Int, step: Int): List> { 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 Iterable.windowed(size: Int, step: Int, transform: (List) -> R): List { checkWindowSizeStep(size, step) diff --git a/js/js.libraries/src/core/generated/_SequencesJs.kt b/js/js.libraries/src/core/generated/_SequencesJs.kt index 1fabbeacff7..8d4d8d09b4e 100644 --- a/js/js.libraries/src/core/generated/_SequencesJs.kt +++ b/js/js.libraries/src/core/generated/_SequencesJs.kt @@ -1332,7 +1332,7 @@ public fun Sequence.chunked(size: Int): Sequence> { * @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 Sequence.plusElement(element: T): Sequence { 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 Sequence.windowed(size: Int, step: Int): Sequence> { 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 Sequence.windowed(size: Int, step: Int, transform: (List) -> R): Sequence { return windowedSequence(size, step, dropTrailing = false, reuseBuffer = true).map(transform) diff --git a/js/js.libraries/src/core/generated/_StringsJs.kt b/js/js.libraries/src/core/generated/_StringsJs.kt index 50b91464962..11642c285e9 100644 --- a/js/js.libraries/src/core/generated/_StringsJs.kt +++ b/js/js.libraries/src/core/generated/_StringsJs.kt @@ -1123,7 +1123,7 @@ public fun CharSequence.chunked(size: Int): List { * @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 { * @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 { 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 CharSequence.windowed(size: Int, step: Int, transform: (CharSequence) -> R): List { checkWindowSizeStep(size, step) @@ -1253,11 +1281,39 @@ public fun 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 { 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 CharSequence.windowedSequence(size: Int, step: Int, transform: (CharSequence) -> R): Sequence { checkWindowSizeStep(size, step) diff --git a/libraries/stdlib/common/src/generated/_Collections.kt b/libraries/stdlib/common/src/generated/_Collections.kt index b018f4522e6..e615ec9ebb0 100644 --- a/libraries/stdlib/common/src/generated/_Collections.kt +++ b/libraries/stdlib/common/src/generated/_Collections.kt @@ -917,7 +917,7 @@ public expect fun Iterable.chunked(size: Int): List> * @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 Iterable.plusElement(element: T): List @kotlin.internal.InlineOnly public expect inline fun Collection.plusElement(element: T): List +/** + * 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 Iterable.windowed(size: Int, step: Int): List> +/** + * 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 Iterable.windowed(size: Int, step: Int, transform: (List) -> R): List diff --git a/libraries/stdlib/common/src/generated/_Sequences.kt b/libraries/stdlib/common/src/generated/_Sequences.kt index d127889d43d..2a86ec73328 100644 --- a/libraries/stdlib/common/src/generated/_Sequences.kt +++ b/libraries/stdlib/common/src/generated/_Sequences.kt @@ -824,7 +824,7 @@ public expect fun Sequence.chunked(size: Int): Sequence> * @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 Sequence.plus(elements: Sequence): Sequence @kotlin.internal.InlineOnly public expect inline fun Sequence.plusElement(element: T): Sequence +/** + * 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 Sequence.windowed(size: Int, step: Int): Sequence> +/** + * 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 Sequence.windowed(size: Int, step: Int, transform: (List) -> R): Sequence diff --git a/libraries/stdlib/common/src/generated/_Strings.kt b/libraries/stdlib/common/src/generated/_Strings.kt index 24ee56e08f8..48fc41ba177 100644 --- a/libraries/stdlib/common/src/generated/_Strings.kt +++ b/libraries/stdlib/common/src/generated/_Strings.kt @@ -657,7 +657,7 @@ public expect fun CharSequence.chunked(size: Int): List * @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 * @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 +/** + * 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 +/** + * 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 CharSequence.windowed(size: Int, step: Int, transform: (CharSequence) -> R): List +/** + * 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 +/** + * 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 CharSequence.windowedSequence(size: Int, step: Int, transform: (CharSequence) -> R): Sequence diff --git a/libraries/stdlib/samples/test/samples/collections/sequences.kt b/libraries/stdlib/samples/test/samples/collections/sequences.kt index 85a5cd8c230..586e48d54be 100644 --- a/libraries/stdlib/samples/test/samples/collections/sequences.kt +++ b/libraries/stdlib/samples/test/samples/collections/sequences.kt @@ -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]") + } + } + } \ No newline at end of file diff --git a/libraries/stdlib/src/generated/_Collections.kt b/libraries/stdlib/src/generated/_Collections.kt index badd7579eac..7ef537aae3d 100644 --- a/libraries/stdlib/src/generated/_Collections.kt +++ b/libraries/stdlib/src/generated/_Collections.kt @@ -1819,7 +1819,7 @@ public fun Iterable.chunked(size: Int): List> { * @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 Collection.plusElement(element: T): List { 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 Iterable.windowed(size: Int, step: Int): List> { checkWindowSizeStep(size, step) @@ -2054,6 +2067,21 @@ public fun Iterable.windowed(size: Int, step: Int): List> { 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 Iterable.windowed(size: Int, step: Int, transform: (List) -> R): List { checkWindowSizeStep(size, step) diff --git a/libraries/stdlib/src/generated/_Sequences.kt b/libraries/stdlib/src/generated/_Sequences.kt index 242ff6def75..20ffba860bc 100644 --- a/libraries/stdlib/src/generated/_Sequences.kt +++ b/libraries/stdlib/src/generated/_Sequences.kt @@ -1354,7 +1354,7 @@ public fun Sequence.chunked(size: Int): Sequence> { * @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 Sequence.plusElement(element: T): Sequence { 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 Sequence.windowed(size: Int, step: Int): Sequence> { 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 Sequence.windowed(size: Int, step: Int, transform: (List) -> R): Sequence { return windowedSequence(size, step, dropTrailing = false, reuseBuffer = true).map(transform) diff --git a/libraries/stdlib/src/generated/_Strings.kt b/libraries/stdlib/src/generated/_Strings.kt index 1315c57a9d1..6a3b512f93d 100644 --- a/libraries/stdlib/src/generated/_Strings.kt +++ b/libraries/stdlib/src/generated/_Strings.kt @@ -1131,7 +1131,7 @@ public fun CharSequence.chunked(size: Int): List { * @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 { * @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 { 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 CharSequence.windowed(size: Int, step: Int, transform: (CharSequence) -> R): List { checkWindowSizeStep(size, step) @@ -1261,11 +1289,39 @@ public fun 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 { 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 CharSequence.windowedSequence(size: Int, step: Int, transform: (CharSequence) -> R): Sequence { checkWindowSizeStep(size, step) diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Generators.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Generators.kt index 4585e34a81a..c19aab71eb9 100644 --- a/libraries/tools/kotlin-stdlib-gen/src/templates/Generators.kt +++ b/libraries/tools/kotlin-stdlib-gen/src/templates/Generators.kt @@ -562,8 +562,25 @@ fun generators(): List { templates add f("windowed(size: Int, step: Int, transform: (List) -> 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") body { @@ -619,6 +636,21 @@ fun generators(): List { returns(Sequences) { "Sequence>" } returns(CharSequences) { "List" } + 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 { 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 "} @@ -665,6 +714,21 @@ fun generators(): List { 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 "} body(CharSequences) { "return windowedSequence(size, step) { it.toString() }" } @@ -681,7 +745,7 @@ fun generators(): List { @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 { @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}.