Docs and samples for 'chunked' function

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

@@ -898,9 +898,32 @@ public expect fun <T : Any> Iterable<T?>.requireNoNulls(): Iterable<T>
  */
 public expect fun <T : Any> List<T?>.requireNoNulls(): List<T>
 
+/**
+ * Splits this collection into a list of lists each not exceeding the given [size].
+ * 
+ * The last list in the resulting 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.
+ * 
+ * @sample samples.collections.Collections.Transformations.chunked
+ */
 @SinceKotlin("1.2")
 public expect fun <T> Iterable<T>.chunked(size: Int): List<List<T>>
 
+/**
+ * Splits this collection into several lists each not exceeding the given [size]
+ * and applies the given [transform] function to an each.
+ * 
+ * @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.
+ * 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.
+ * 
+ * @sample samples.text.Strings.chunkedTransform
+ */
 @SinceKotlin("1.2")
 public expect fun <T, R> Iterable<T>.chunked(size: Int, transform: (List<T>) -> R): List<R>
 

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

@@ -803,9 +803,36 @@ public expect inline fun <T> Sequence<T>.sumByDouble(selector: (T) -> Double): D
  */
 public expect fun <T : Any> Sequence<T?>.requireNoNulls(): Sequence<T>
 
+/**
+ * Splits this sequence into a sequence of lists each not exceeding the given [size].
+ * 
+ * The last list in the resulting sequence 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.
+ * 
+ * @sample samples.collections.Collections.Transformations.chunked
+ *
+ * The operation is _intermediate_ and _stateful_.
+ */
 @SinceKotlin("1.2")
 public expect fun <T> Sequence<T>.chunked(size: Int): Sequence<List<T>>
 
+/**
+ * Splits this sequence into several lists each not exceeding the given [size]
+ * and applies the given [transform] function to an each.
+ * 
+ * @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.
+ * 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.
+ * 
+ * @sample samples.text.Strings.chunkedTransform
+ *
+ * The operation is _intermediate_ and _stateful_.
+ */
 @SinceKotlin("1.2")
 public expect fun <T, R> Sequence<T>.chunked(size: Int, transform: (List<T>) -> R): Sequence<R>
 

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

@@ -638,15 +638,61 @@ public expect inline fun CharSequence.sumBy(selector: (Char) -> Int): Int
  */
 public expect inline fun CharSequence.sumByDouble(selector: (Char) -> Double): Double
 
+/**
+ * Splits this char sequence into a list of strings each not exceeding the given [size].
+ * 
+ * The last string in the resulting list may have less characters than the given [size].
+ * 
+ * @param size the number of elements to take in each string, must be positive and can be greater than the number of elements in this char sequence.
+ * 
+ * @sample samples.collections.Collections.Transformations.chunked
+ */
 @SinceKotlin("1.2")
 public expect fun CharSequence.chunked(size: Int): List<String>
 
+/**
+ * Splits this char sequence into several char sequences each not exceeding the given [size]
+ * and applies the given [transform] function to an each.
+ * 
+ * @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.
+ * 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.
+ * 
+ * @sample samples.text.Strings.chunkedTransform
+ */
 @SinceKotlin("1.2")
 public expect fun <R> CharSequence.chunked(size: Int, transform: (CharSequence) -> R): List<R>
 
+/**
+ * Splits this char sequence into a sequence of strings each not exceeding the given [size].
+ * 
+ * The last string in the resulting sequence may have less characters than the given [size].
+ * 
+ * @param size the number of elements to take in each string, must be positive and can be greater than the number of elements in this char sequence.
+ * 
+ * @sample samples.collections.Collections.Transformations.chunked
+ */
 @SinceKotlin("1.2")
 public expect fun CharSequence.chunkedSequence(size: Int): Sequence<String> 
 
+/**
+ * Splits this char sequence into several char sequences each not exceeding the given [size]
+ * and applies the given [transform] function to an each.
+ * 
+ * @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.
+ * 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.
+ * 
+ * @sample samples.text.Strings.chunkedTransformToSequence
+ */
 @SinceKotlin("1.2")
 public expect fun <R> CharSequence.chunkedSequence(size: Int, transform: (CharSequence) -> R): Sequence<R> 
 

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

@@ -71,6 +71,15 @@ class Collections {
             assertPrints(moreFrequencies, "{o=1, t=4, f=2, s=2, e=2, n=1}")
         }
 
+        @Sample
+        fun chunked() {
+            val words = "one two three four five six seven eight nine ten".split(' ')
+            val chunks = words.chunked(3)
+
+            assertPrints(chunks, "[[one, two, three], [four, five, six], [seven, eight, nine], [ten]]")
+        }
+
+
         @Sample
         fun pairwise() {
             val letters = ('a'..'f').toList()

libraries/stdlib/samples/test/samples/text/strings.kt

@@ -50,5 +50,25 @@ class Strings {
         assertPrints(withoutMargin2, "XYZ\nfoo\nbar")
     }
 
+    @Sample
+    fun chunkedTransform() {
+        val codonTable = mapOf("ATT" to "Isoleucine", "CAA" to "Glutamine", "CGC" to "Arginine", "GGC" to "Glycine")
+        val dnaFragment = "ATTCGCGGCCGCCAA"
+
+        val proteins = dnaFragment.chunked(3) { codon: CharSequence -> codonTable[codon.toString()] ?: error("Unknown codon") }
+
+        assertPrints(proteins, "[Isoleucine, Arginine, Glycine, Arginine, Glutamine]")
+    }
+
+    @Sample
+    fun chunkedTransformToSequence() {
+        val codonTable = mapOf("ATT" to "Isoleucine", "CAA" to "Glutamine", "CGC" to "Arginine", "GGC" to "Glycine")
+        val dnaFragment = "ATTCGCGGCCGCCAACGG"
+
+        val proteins = dnaFragment.chunkedSequence(3) { codon: CharSequence -> codonTable[codon.toString()] ?: error("Unknown codon") }
+
+        // sequence is evaluated lazily, so that unknown codon is not reached
+        assertPrints(proteins.take(5).toList(), "[Isoleucine, Arginine, Glycine, Arginine, Glutamine]")
+    }
 
 }

libraries/stdlib/src/generated/_Collections.kt

@@ -1798,11 +1798,34 @@ public fun <T : Any> List<T?>.requireNoNulls(): List<T> {
     return this as List<T>
 }
 
+/**
+ * Splits this collection into a list of lists each not exceeding the given [size].
+ * 
+ * The last list in the resulting 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.
+ * 
+ * @sample samples.collections.Collections.Transformations.chunked
+ */
 @SinceKotlin("1.2")
 public fun <T> Iterable<T>.chunked(size: Int): List<List<T>> {
     return windowed(size, size)
 }
 
+/**
+ * Splits this collection into several lists each not exceeding the given [size]
+ * and applies the given [transform] function to an each.
+ * 
+ * @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.
+ * 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.
+ * 
+ * @sample samples.text.Strings.chunkedTransform
+ */
 @SinceKotlin("1.2")
 public fun <T, R> Iterable<T>.chunked(size: Int, transform: (List<T>) -> R): List<R> {
     return windowed(size, size, transform)

libraries/stdlib/src/generated/_Sequences.kt

@@ -1331,11 +1331,38 @@ public fun <T : Any> Sequence<T?>.requireNoNulls(): Sequence<T> {
     return map { it ?: throw IllegalArgumentException("null element found in $this.") }
 }
 
+/**
+ * Splits this sequence into a sequence of lists each not exceeding the given [size].
+ * 
+ * The last list in the resulting sequence 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.
+ * 
+ * @sample samples.collections.Collections.Transformations.chunked
+ *
+ * The operation is _intermediate_ and _stateful_.
+ */
 @SinceKotlin("1.2")
 public fun <T> Sequence<T>.chunked(size: Int): Sequence<List<T>> {
     return windowed(size, size)
 }
 
+/**
+ * Splits this sequence into several lists each not exceeding the given [size]
+ * and applies the given [transform] function to an each.
+ * 
+ * @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.
+ * 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.
+ * 
+ * @sample samples.text.Strings.chunkedTransform
+ *
+ * The operation is _intermediate_ and _stateful_.
+ */
 @SinceKotlin("1.2")
 public fun <T, R> Sequence<T>.chunked(size: Int, transform: (List<T>) -> R): Sequence<R> {
     return windowed(size, size, transform)

libraries/stdlib/src/generated/_Strings.kt

@@ -1110,21 +1110,67 @@ public inline fun CharSequence.sumByDouble(selector: (Char) -> Double): Double {
     return sum
 }
 
+/**
+ * Splits this char sequence into a list of strings each not exceeding the given [size].
+ * 
+ * The last string in the resulting list may have less characters than the given [size].
+ * 
+ * @param size the number of elements to take in each string, must be positive and can be greater than the number of elements in this char sequence.
+ * 
+ * @sample samples.collections.Collections.Transformations.chunked
+ */
 @SinceKotlin("1.2")
 public fun CharSequence.chunked(size: Int): List<String> {
     return windowed(size, size)
 }
 
+/**
+ * Splits this char sequence into several char sequences each not exceeding the given [size]
+ * and applies the given [transform] function to an each.
+ * 
+ * @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.
+ * 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.
+ * 
+ * @sample samples.text.Strings.chunkedTransform
+ */
 @SinceKotlin("1.2")
 public fun <R> CharSequence.chunked(size: Int, transform: (CharSequence) -> R): List<R> {
     return windowed(size, size, transform)
 }
 
+/**
+ * Splits this char sequence into a sequence of strings each not exceeding the given [size].
+ * 
+ * The last string in the resulting sequence may have less characters than the given [size].
+ * 
+ * @param size the number of elements to take in each string, must be positive and can be greater than the number of elements in this char sequence.
+ * 
+ * @sample samples.collections.Collections.Transformations.chunked
+ */
 @SinceKotlin("1.2")
 public fun CharSequence.chunkedSequence(size: Int): Sequence<String>  {
     return chunkedSequence(size) { it.toString() }
 }
 
+/**
+ * Splits this char sequence into several char sequences each not exceeding the given [size]
+ * and applies the given [transform] function to an each.
+ * 
+ * @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.
+ * 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.
+ * 
+ * @sample samples.text.Strings.chunkedTransformToSequence
+ */
 @SinceKotlin("1.2")
 public fun <R> CharSequence.chunkedSequence(size: Int, transform: (CharSequence) -> R): Sequence<R>  {
     return windowedSequence(size, size, transform)