azalea/kotlin-fork
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Introduce kotlin-stdlib-generator dsl block for specifying sample reference

Browse Source
This commit is contained in:
Ilya Gorbunov
2018-04-20 22:11:23 +03:00
parent 5dd7ff4d7f
commit 908d2d6975
12 changed files with 126 additions and 92 deletions
Download Patch File Download Diff File Expand all files Collapse all files
libraries/stdlib/common/src/generated/_Ranges.kt
+25
View File
@@ -704,6 +704,7 @@ public infix fun Short.until(to: Short): IntRange {
* Ensures that this value is not less than the specified [minimumValue].
*
* @return this value if it's greater than or equal to the [minimumValue] or the [minimumValue] otherwise.
*
* @sample samples.comparisons.ComparableOps.coerceAtLeastComparable
*/
public fun <T: Comparable<T>> T.coerceAtLeast(minimumValue: T): T {
@@ -714,6 +715,7 @@ public fun <T: Comparable<T>> T.coerceAtLeast(minimumValue: T): T {
* Ensures that this value is not less than the specified [minimumValue].
*
* @return this value if it's greater than or equal to the [minimumValue] or the [minimumValue] otherwise.
*
* @sample samples.comparisons.ComparableOps.coerceAtLeast
*/
public fun Byte.coerceAtLeast(minimumValue: Byte): Byte {
@@ -724,6 +726,7 @@ public fun Byte.coerceAtLeast(minimumValue: Byte): Byte {
* Ensures that this value is not less than the specified [minimumValue].
*
* @return this value if it's greater than or equal to the [minimumValue] or the [minimumValue] otherwise.
*
* @sample samples.comparisons.ComparableOps.coerceAtLeast
*/
public fun Short.coerceAtLeast(minimumValue: Short): Short {
@@ -734,6 +737,7 @@ public fun Short.coerceAtLeast(minimumValue: Short): Short {
* Ensures that this value is not less than the specified [minimumValue].
*
* @return this value if it's greater than or equal to the [minimumValue] or the [minimumValue] otherwise.
*
* @sample samples.comparisons.ComparableOps.coerceAtLeast
*/
public fun Int.coerceAtLeast(minimumValue: Int): Int {
@@ -744,6 +748,7 @@ public fun Int.coerceAtLeast(minimumValue: Int): Int {
* Ensures that this value is not less than the specified [minimumValue].
*
* @return this value if it's greater than or equal to the [minimumValue] or the [minimumValue] otherwise.
*
* @sample samples.comparisons.ComparableOps.coerceAtLeast
*/
public fun Long.coerceAtLeast(minimumValue: Long): Long {
@@ -754,6 +759,7 @@ public fun Long.coerceAtLeast(minimumValue: Long): Long {
* Ensures that this value is not less than the specified [minimumValue].
*
* @return this value if it's greater than or equal to the [minimumValue] or the [minimumValue] otherwise.
*
* @sample samples.comparisons.ComparableOps.coerceAtLeast
*/
public fun Float.coerceAtLeast(minimumValue: Float): Float {
@@ -764,6 +770,7 @@ public fun Float.coerceAtLeast(minimumValue: Float): Float {
* Ensures that this value is not less than the specified [minimumValue].
*
* @return this value if it's greater than or equal to the [minimumValue] or the [minimumValue] otherwise.
*
* @sample samples.comparisons.ComparableOps.coerceAtLeast
*/
public fun Double.coerceAtLeast(minimumValue: Double): Double {
@@ -774,6 +781,7 @@ public fun Double.coerceAtLeast(minimumValue: Double): Double {
* Ensures that this value is not greater than the specified [maximumValue].
*
* @return this value if it's less than or equal to the [maximumValue] or the [maximumValue] otherwise.
*
* @sample samples.comparisons.ComparableOps.coerceAtMostComparable
*/
public fun <T: Comparable<T>> T.coerceAtMost(maximumValue: T): T {
@@ -784,6 +792,7 @@ public fun <T: Comparable<T>> T.coerceAtMost(maximumValue: T): T {
* Ensures that this value is not greater than the specified [maximumValue].
*
* @return this value if it's less than or equal to the [maximumValue] or the [maximumValue] otherwise.
*
* @sample samples.comparisons.ComparableOps.coerceAtMost
*/
public fun Byte.coerceAtMost(maximumValue: Byte): Byte {
@@ -794,6 +803,7 @@ public fun Byte.coerceAtMost(maximumValue: Byte): Byte {
* Ensures that this value is not greater than the specified [maximumValue].
*
* @return this value if it's less than or equal to the [maximumValue] or the [maximumValue] otherwise.
*
* @sample samples.comparisons.ComparableOps.coerceAtMost
*/
public fun Short.coerceAtMost(maximumValue: Short): Short {
@@ -804,6 +814,7 @@ public fun Short.coerceAtMost(maximumValue: Short): Short {
* Ensures that this value is not greater than the specified [maximumValue].
*
* @return this value if it's less than or equal to the [maximumValue] or the [maximumValue] otherwise.
*
* @sample samples.comparisons.ComparableOps.coerceAtMost
*/
public fun Int.coerceAtMost(maximumValue: Int): Int {
@@ -814,6 +825,7 @@ public fun Int.coerceAtMost(maximumValue: Int): Int {
* Ensures that this value is not greater than the specified [maximumValue].
*
* @return this value if it's less than or equal to the [maximumValue] or the [maximumValue] otherwise.
*
* @sample samples.comparisons.ComparableOps.coerceAtMost
*/
public fun Long.coerceAtMost(maximumValue: Long): Long {
@@ -824,6 +836,7 @@ public fun Long.coerceAtMost(maximumValue: Long): Long {
* Ensures that this value is not greater than the specified [maximumValue].
*
* @return this value if it's less than or equal to the [maximumValue] or the [maximumValue] otherwise.
*
* @sample samples.comparisons.ComparableOps.coerceAtMost
*/
public fun Float.coerceAtMost(maximumValue: Float): Float {
@@ -834,6 +847,7 @@ public fun Float.coerceAtMost(maximumValue: Float): Float {
* Ensures that this value is not greater than the specified [maximumValue].
*
* @return this value if it's less than or equal to the [maximumValue] or the [maximumValue] otherwise.
*
* @sample samples.comparisons.ComparableOps.coerceAtMost
*/
public fun Double.coerceAtMost(maximumValue: Double): Double {
@@ -844,6 +858,7 @@ public fun Double.coerceAtMost(maximumValue: Double): Double {
* Ensures that this value lies in the specified range [minimumValue]..[maximumValue].
*
* @return this value if it's in the range, or [minimumValue] if this value is less than [minimumValue], or [maximumValue] if this value is greater than [maximumValue].
*
* @sample samples.comparisons.ComparableOps.coerceInComparable
*/
public fun <T: Comparable<T>> T.coerceIn(minimumValue: T?, maximumValue: T?): T {
@@ -863,6 +878,7 @@ public fun <T: Comparable<T>> T.coerceIn(minimumValue: T?, maximumValue: T?): T
* Ensures that this value lies in the specified range [minimumValue]..[maximumValue].
*
* @return this value if it's in the range, or [minimumValue] if this value is less than [minimumValue], or [maximumValue] if this value is greater than [maximumValue].
*
* @sample samples.comparisons.ComparableOps.coerceIn
*/
public fun Byte.coerceIn(minimumValue: Byte, maximumValue: Byte): Byte {
@@ -876,6 +892,7 @@ public fun Byte.coerceIn(minimumValue: Byte, maximumValue: Byte): Byte {
* Ensures that this value lies in the specified range [minimumValue]..[maximumValue].
*
* @return this value if it's in the range, or [minimumValue] if this value is less than [minimumValue], or [maximumValue] if this value is greater than [maximumValue].
*
* @sample samples.comparisons.ComparableOps.coerceIn
*/
public fun Short.coerceIn(minimumValue: Short, maximumValue: Short): Short {
@@ -889,6 +906,7 @@ public fun Short.coerceIn(minimumValue: Short, maximumValue: Short): Short {
* Ensures that this value lies in the specified range [minimumValue]..[maximumValue].
*
* @return this value if it's in the range, or [minimumValue] if this value is less than [minimumValue], or [maximumValue] if this value is greater than [maximumValue].
*
* @sample samples.comparisons.ComparableOps.coerceIn
*/
public fun Int.coerceIn(minimumValue: Int, maximumValue: Int): Int {
@@ -902,6 +920,7 @@ public fun Int.coerceIn(minimumValue: Int, maximumValue: Int): Int {
* Ensures that this value lies in the specified range [minimumValue]..[maximumValue].
*
* @return this value if it's in the range, or [minimumValue] if this value is less than [minimumValue], or [maximumValue] if this value is greater than [maximumValue].
*
* @sample samples.comparisons.ComparableOps.coerceIn
*/
public fun Long.coerceIn(minimumValue: Long, maximumValue: Long): Long {
@@ -915,6 +934,7 @@ public fun Long.coerceIn(minimumValue: Long, maximumValue: Long): Long {
* Ensures that this value lies in the specified range [minimumValue]..[maximumValue].
*
* @return this value if it's in the range, or [minimumValue] if this value is less than [minimumValue], or [maximumValue] if this value is greater than [maximumValue].
*
* @sample samples.comparisons.ComparableOps.coerceIn
*/
public fun Float.coerceIn(minimumValue: Float, maximumValue: Float): Float {
@@ -928,6 +948,7 @@ public fun Float.coerceIn(minimumValue: Float, maximumValue: Float): Float {
* Ensures that this value lies in the specified range [minimumValue]..[maximumValue].
*
* @return this value if it's in the range, or [minimumValue] if this value is less than [minimumValue], or [maximumValue] if this value is greater than [maximumValue].
*
* @sample samples.comparisons.ComparableOps.coerceIn
*/
public fun Double.coerceIn(minimumValue: Double, maximumValue: Double): Double {
@@ -941,6 +962,7 @@ public fun Double.coerceIn(minimumValue: Double, maximumValue: Double): Double {
* Ensures that this value lies in the specified [range].
*
* @return this value if it's in the [range], or `range.start` if this value is less than `range.start`, or `range.endInclusive` if this value is greater than `range.endInclusive`.
*
* @sample samples.comparisons.ComparableOps.coerceInFloatingPointRange
*/
@SinceKotlin("1.1")
@@ -959,6 +981,7 @@ public fun <T: Comparable<T>> T.coerceIn(range: ClosedFloatingPointRange<T>): T
* Ensures that this value lies in the specified [range].
*
* @return this value if it's in the [range], or `range.start` if this value is less than `range.start`, or `range.endInclusive` if this value is greater than `range.endInclusive`.
*
* @sample samples.comparisons.ComparableOps.coerceInComparable
*/
public fun <T: Comparable<T>> T.coerceIn(range: ClosedRange<T>): T {
@@ -977,6 +1000,7 @@ public fun <T: Comparable<T>> T.coerceIn(range: ClosedRange<T>): T {
* Ensures that this value lies in the specified [range].
*
* @return this value if it's in the [range], or `range.start` if this value is less than `range.start`, or `range.endInclusive` if this value is greater than `range.endInclusive`.
*
* @sample samples.comparisons.ComparableOps.coerceIn
*/
public fun Int.coerceIn(range: ClosedRange<Int>): Int {
@@ -995,6 +1019,7 @@ public fun Int.coerceIn(range: ClosedRange<Int>): Int {
* Ensures that this value lies in the specified [range].
*
* @return this value if it's in the [range], or `range.start` if this value is less than `range.start`, or `range.endInclusive` if this value is greater than `range.endInclusive`.
*
* @sample samples.comparisons.ComparableOps.coerceIn
*/
public fun Long.coerceIn(range: ClosedRange<Long>): Long {
libraries/stdlib/common/src/generated/_Sequences.kt
+8
View File
@@ -332,6 +332,8 @@ public inline fun <T> Sequence<T>.singleOrNull(predicate: (T) -> Boolean): T? {
/**
* Returns a sequence containing all elements except first [n] elements.
*
* @sample samples.collections.Collections.Transformations.drop
*
* The operation is _intermediate_ and _stateless_.
*/
@@ -346,6 +348,8 @@ public fun <T> Sequence<T>.drop(n: Int): Sequence<T> {
/**
* Returns a sequence containing all elements except first elements that satisfy the given [predicate].
*
* @sample samples.collections.Collections.Transformations.drop
*
* The operation is _intermediate_ and _stateless_.
*/
@@ -459,6 +463,8 @@ public inline fun <T, C : MutableCollection<in T>> Sequence<T>.filterTo(destinat
/**
* Returns a sequence containing first [n] elements.
*
* @sample samples.collections.Collections.Transformations.take
*
* The operation is _intermediate_ and _stateless_.
*/
@@ -473,6 +479,8 @@ public fun <T> Sequence<T>.take(n: Int): Sequence<T> {
/**
* Returns a sequence containing first elements satisfying the given [predicate].
*
* @sample samples.collections.Collections.Transformations.take
*
* The operation is _intermediate_ and _stateless_.
*/
libraries/stdlib/common/src/generated/_Strings.kt
+32
View File
@@ -220,6 +220,8 @@ public inline fun CharSequence.singleOrNull(predicate: (Char) -> Boolean): Char?
/**
* Returns a subsequence of this char sequence with the first [n] characters removed.
*
* @sample samples.collections.Collections.Transformations.drop
*/
public fun CharSequence.drop(n: Int): CharSequence {
require(n >= 0) { "Requested character count $n is less than zero." }
@@ -228,6 +230,8 @@ public fun CharSequence.drop(n: Int): CharSequence {
/**
* Returns a string with the first [n] characters removed.
*
* @sample samples.collections.Collections.Transformations.drop
*/
public fun String.drop(n: Int): String {
require(n >= 0) { "Requested character count $n is less than zero." }
@@ -236,6 +240,8 @@ public fun String.drop(n: Int): String {
/**
* Returns a subsequence of this char sequence with the last [n] characters removed.
*
* @sample samples.collections.Collections.Transformations.drop
*/
public fun CharSequence.dropLast(n: Int): CharSequence {
require(n >= 0) { "Requested character count $n is less than zero." }
@@ -244,6 +250,8 @@ public fun CharSequence.dropLast(n: Int): CharSequence {
/**
* Returns a string with the last [n] characters removed.
*
* @sample samples.collections.Collections.Transformations.drop
*/
public fun String.dropLast(n: Int): String {
require(n >= 0) { "Requested character count $n is less than zero." }
@@ -252,6 +260,8 @@ public fun String.dropLast(n: Int): String {
/**
* Returns a subsequence of this char sequence containing all characters except last characters that satisfy the given [predicate].
*
* @sample samples.collections.Collections.Transformations.drop
*/
public inline fun CharSequence.dropLastWhile(predicate: (Char) -> Boolean): CharSequence {
for (index in lastIndex downTo 0)
@@ -262,6 +272,8 @@ public inline fun CharSequence.dropLastWhile(predicate: (Char) -> Boolean): Char
/**
* Returns a string containing all characters except last characters that satisfy the given [predicate].
*
* @sample samples.collections.Collections.Transformations.drop
*/
public inline fun String.dropLastWhile(predicate: (Char) -> Boolean): String {
for (index in lastIndex downTo 0)
@@ -272,6 +284,8 @@ public inline fun String.dropLastWhile(predicate: (Char) -> Boolean): String {
/**
* Returns a subsequence of this char sequence containing all characters except first characters that satisfy the given [predicate].
*
* @sample samples.collections.Collections.Transformations.drop
*/
public inline fun CharSequence.dropWhile(predicate: (Char) -> Boolean): CharSequence {
for (index in this.indices)
@@ -282,6 +296,8 @@ public inline fun CharSequence.dropWhile(predicate: (Char) -> Boolean): CharSequ
/**
* Returns a string containing all characters except first characters that satisfy the given [predicate].
*
* @sample samples.collections.Collections.Transformations.drop
*/
public inline fun String.dropWhile(predicate: (Char) -> Boolean): String {
for (index in this.indices)
@@ -406,6 +422,8 @@ public inline fun String.slice(indices: Iterable<Int>): String {
/**
* Returns a subsequence of this char sequence containing the first [n] characters from this char sequence, or the entire char sequence if this char sequence is shorter.
*
* @sample samples.collections.Collections.Transformations.take
*/
public fun CharSequence.take(n: Int): CharSequence {
require(n >= 0) { "Requested character count $n is less than zero." }
@@ -414,6 +432,8 @@ public fun CharSequence.take(n: Int): CharSequence {
/**
* Returns a string containing the first [n] characters from this string, or the entire string if this string is shorter.
*
* @sample samples.collections.Collections.Transformations.take
*/
public fun String.take(n: Int): String {
require(n >= 0) { "Requested character count $n is less than zero." }
@@ -422,6 +442,8 @@ public fun String.take(n: Int): String {
/**
* Returns a subsequence of this char sequence containing the last [n] characters from this char sequence, or the entire char sequence if this char sequence is shorter.
*
* @sample samples.collections.Collections.Transformations.take
*/
public fun CharSequence.takeLast(n: Int): CharSequence {
require(n >= 0) { "Requested character count $n is less than zero." }
@@ -431,6 +453,8 @@ public fun CharSequence.takeLast(n: Int): CharSequence {
/**
* Returns a string containing the last [n] characters from this string, or the entire string if this string is shorter.
*
* @sample samples.collections.Collections.Transformations.take
*/
public fun String.takeLast(n: Int): String {
require(n >= 0) { "Requested character count $n is less than zero." }
@@ -440,6 +464,8 @@ public fun String.takeLast(n: Int): String {
/**
* Returns a subsequence of this char sequence containing last characters that satisfy the given [predicate].
*
* @sample samples.collections.Collections.Transformations.take
*/
public inline fun CharSequence.takeLastWhile(predicate: (Char) -> Boolean): CharSequence {
for (index in lastIndex downTo 0) {
@@ -452,6 +478,8 @@ public inline fun CharSequence.takeLastWhile(predicate: (Char) -> Boolean): Char
/**
* Returns a string containing last characters that satisfy the given [predicate].
*
* @sample samples.collections.Collections.Transformations.take
*/
public inline fun String.takeLastWhile(predicate: (Char) -> Boolean): String {
for (index in lastIndex downTo 0) {
@@ -464,6 +492,8 @@ public inline fun String.takeLastWhile(predicate: (Char) -> Boolean): String {
/**
* Returns a subsequence of this char sequence containing the first characters that satisfy the given [predicate].
*
* @sample samples.collections.Collections.Transformations.take
*/
public inline fun CharSequence.takeWhile(predicate: (Char) -> Boolean): CharSequence {
for (index in 0 until length)
@@ -475,6 +505,8 @@ public inline fun CharSequence.takeWhile(predicate: (Char) -> Boolean): CharSequ
/**
* Returns a string containing the first characters that satisfy the given [predicate].
*
* @sample samples.collections.Collections.Transformations.take
*/
public inline fun String.takeWhile(predicate: (Char) -> Boolean): String {
for (index in 0 until length)
libraries/tools/kotlin-stdlib-gen/src/templates/Aggregates.kt
+5 -10
View File
@@ -37,10 +37,9 @@ object Aggregates : TemplateGroupBase() {
doc {
"""
Returns `true` if all ${f.element.pluralize()} match the given [predicate].
@sample samples.collections.Collections.Aggregates.all
"""
}
sample("samples.collections.Collections.Aggregates.all")
returns("Boolean")
body {
"""
@@ -64,10 +63,9 @@ object Aggregates : TemplateGroupBase() {
doc {
"""
Returns `true` if no ${f.element.pluralize()} match the given [predicate].
@sample samples.collections.Collections.Aggregates.noneWithPredicate
"""
}
sample("samples.collections.Collections.Aggregates.noneWithPredicate")
returns("Boolean")
body {
"""
@@ -89,10 +87,9 @@ object Aggregates : TemplateGroupBase() {
doc {
"""
Returns `true` if the ${f.collection} has no ${f.element.pluralize()}.
@sample samples.collections.Collections.Aggregates.none
"""
}
sample("samples.collections.Collections.Aggregates.none")
returns("Boolean")
body {
"return !iterator().hasNext()"
@@ -119,10 +116,9 @@ object Aggregates : TemplateGroupBase() {
doc {
"""
Returns `true` if at least one ${f.element} matches the given [predicate].
@sample samples.collections.Collections.Aggregates.anyWithPredicate
"""
}
sample("samples.collections.Collections.Aggregates.anyWithPredicate")
returns("Boolean")
body {
"""
@@ -144,10 +140,9 @@ object Aggregates : TemplateGroupBase() {
doc {
"""
Returns `true` if ${f.collection} has at least one ${f.element}.
@sample samples.collections.Collections.Aggregates.any
"""
}
sample("samples.collections.Collections.Aggregates.any")
returns("Boolean")
body {
"return iterator().hasNext()"
libraries/tools/kotlin-stdlib-gen/src/templates/Arrays.kt
+2 -4
View File
@@ -118,10 +118,9 @@ object ArrayOps : TemplateGroupBase() {
doc {
"""
Returns a string representation of the contents of the specified array as if it is [List].
@sample samples.collections.Arrays.ContentOperations.contentToString
"""
}
sample("samples.collections.Arrays.ContentOperations.contentToString")
returns("String")
on(Platform.JVM) {
inlineOnly()
@@ -144,10 +143,9 @@ object ArrayOps : TemplateGroupBase() {
If any of arrays contains itself on any nesting level that reference
is rendered as `"[...]"` to prevent recursion.
@sample samples.collections.Arrays.ContentOperations.contentDeepToString
"""
}
sample("samples.collections.Arrays.ContentOperations.contentDeepToString")
returns("String")
on(Platform.JVM) {
inlineOnly()
libraries/tools/kotlin-stdlib-gen/src/templates/Comparables.kt
+5 -5
View File
@@ -36,9 +36,9 @@ object ComparableOps : TemplateGroupBase() {
Ensures that this value is not less than the specified [minimumValue].
@return this value if it's greater than or equal to the [minimumValue] or the [minimumValue] otherwise.
@sample samples.comparisons.ComparableOps.coerceAtLeast${if (f == Generic) "Comparable" else ""}
"""
}
sample("samples.comparisons.ComparableOps.coerceAtLeast${if (f == Generic) "Comparable" else ""}")
body {
"""
return if (this < minimumValue) minimumValue else this
@@ -58,9 +58,9 @@ object ComparableOps : TemplateGroupBase() {
Ensures that this value is not greater than the specified [maximumValue].
@return this value if it's less than or equal to the [maximumValue] or the [maximumValue] otherwise.
@sample samples.comparisons.ComparableOps.coerceAtMost${if (f == Generic) "Comparable" else ""}
"""
}
sample("samples.comparisons.ComparableOps.coerceAtMost${if (f == Generic) "Comparable" else ""}")
body {
"""
return if (this > maximumValue) maximumValue else this
@@ -80,9 +80,9 @@ object ComparableOps : TemplateGroupBase() {
Ensures that this value lies in the specified [range].
@return this value if it's in the [range], or `range.start` if this value is less than `range.start`, or `range.endInclusive` if this value is greater than `range.endInclusive`.
@sample samples.comparisons.ComparableOps.coerceIn${if (f == Generic) "Comparable" else ""}
"""
}
sample("samples.comparisons.ComparableOps.coerceIn${if (f == Generic) "Comparable" else ""}")
body(Generic) {
"""
if (range is ClosedFloatingPointRange) {
@@ -123,9 +123,9 @@ object ComparableOps : TemplateGroupBase() {
Ensures that this value lies in the specified [range].
@return this value if it's in the [range], or `range.start` if this value is less than `range.start`, or `range.endInclusive` if this value is greater than `range.endInclusive`.
@sample samples.comparisons.ComparableOps.coerceInFloatingPointRange
"""
}
sample("samples.comparisons.ComparableOps.coerceInFloatingPointRange")
body(Generic) {
"""
if (range.isEmpty()) throw IllegalArgumentException("Cannot coerce value to an empty range: ${'$'}range.")
@@ -384,9 +384,9 @@ object ComparableOps : TemplateGroupBase() {
Ensures that this value lies in the specified range [minimumValue]..[maximumValue].
@return this value if it's in the range, or [minimumValue] if this value is less than [minimumValue], or [maximumValue] if this value is greater than [maximumValue].
@sample samples.comparisons.ComparableOps.coerceIn${if (f == Generic) "Comparable" else ""}
"""
}
sample("samples.comparisons.ComparableOps.coerceIn${if (f == Generic) "Comparable" else ""}")
body(Primitives) {
"""
if (minimumValue > maximumValue) throw IllegalArgumentException("Cannot coerce value to an empty range: maximum ${'$'}maximumValue is less than minimum ${'$'}minimumValue.")
libraries/tools/kotlin-stdlib-gen/src/templates/Filtering.kt
+9 -17
View File
@@ -51,10 +51,9 @@ object Filtering : TemplateGroupBase() {
doc {
"""
Returns a list containing all elements except first [n] elements.
@sample samples.collections.Collections.Transformations.drop
"""
}
sample("samples.collections.Collections.Transformations.drop")
returns("List<T>")
body {
"""
@@ -138,10 +137,9 @@ object Filtering : TemplateGroupBase() {
doc {
"""
Returns a list containing first [n] elements.
@sample samples.collections.Collections.Transformations.take
"""
}
sample("samples.collections.Collections.Transformations.take")
returns("List<T>")
body {
"""
@@ -219,10 +217,9 @@ object Filtering : TemplateGroupBase() {
doc {
"""
Returns a list containing all elements except last [n] elements.
@sample samples.collections.Collections.Transformations.drop
"""
}
sample("samples.collections.Collections.Transformations.drop")
returns("List<T>")
body {
"""
@@ -249,10 +246,9 @@ object Filtering : TemplateGroupBase() {
doc {
"""
Returns a list containing last [n] elements.
@sample samples.collections.Collections.Transformations.take
"""
}
sample("samples.collections.Collections.Transformations.take")
returns("List<T>")
specialFor(Strings, CharSequences) {
@@ -316,10 +312,9 @@ object Filtering : TemplateGroupBase() {
doc {
"""
Returns a list containing all elements except first elements that satisfy the given [predicate].
@sample samples.collections.Collections.Transformations.drop
"""
}
sample("samples.collections.Collections.Transformations.drop")
returns("List<T>")
body {
"""
@@ -373,10 +368,9 @@ object Filtering : TemplateGroupBase() {
doc {
"""
Returns a list containing first elements satisfying the given [predicate].
@sample samples.collections.Collections.Transformations.take
"""
"""
}
sample("samples.collections.Collections.Transformations.take")
returns("List<T>")
body {
"""
@@ -424,10 +418,9 @@ object Filtering : TemplateGroupBase() {
doc {
"""
Returns a list containing all elements except last elements that satisfy the given [predicate].
@sample samples.collections.Collections.Transformations.drop
"""
}
sample("samples.collections.Collections.Transformations.drop")
returns("List<T>")
body {
@@ -481,10 +474,9 @@ object Filtering : TemplateGroupBase() {
doc {
"""
Returns a list containing last elements satisfying the given [predicate].
@sample samples.collections.Collections.Transformations.take
"""
}
sample("samples.collections.Collections.Transformations.take")
returns("List<T>")
body {
libraries/tools/kotlin-stdlib-gen/src/templates/Generators.kt
+20 -40
View File
@@ -631,10 +631,9 @@ object Generators : TemplateGroupBase() {
@param step the number of elements to move the window forward by on an each step, by default 1
@param partialWindows controls whether or not to keep partial windows in the end if any,
by default `false` which means partial windows won't be preserved
@sample samples.collections.Sequences.Transformations.averageWindows
"""
}
sample("samples.collections.Sequences.Transformations.averageWindows")
typeParam("R")
returns("List<R>")
@@ -711,10 +710,9 @@ object Generators : TemplateGroupBase() {
@param step the number of elements to move the window forward by on an each step, by default 1
@param partialWindows controls whether or not to keep partial windows in the end if any,
by default `false` which means partial windows won't be preserved
@sample samples.collections.Sequences.Transformations.takeWindows
"""
}
sample("samples.collections.Sequences.Transformations.takeWindows")
body {
"""
@@ -765,10 +763,9 @@ object Generators : TemplateGroupBase() {
@param step the number of elements to move the window forward by on an each step, by default 1
@param partialWindows controls whether or not to keep partial windows in the end if any,
by default `false` which means partial windows won't be preserved
@sample samples.collections.Sequences.Transformations.averageWindows
"""
}
sample("samples.collections.Sequences.Transformations.averageWindows")
typeParam("R")
returns("Sequence<R>")
@@ -798,10 +795,9 @@ object Generators : TemplateGroupBase() {
@param step the number of elements to move the window forward by on an each step, by default 1
@param partialWindows controls whether or not to keep partial windows in the end if any,
by default `false` which means partial windows won't be preserved
@sample samples.collections.Sequences.Transformations.takeWindows
"""
}
sample("samples.collections.Sequences.Transformations.takeWindows")
returns("Sequence<String>")
body(CharSequences) { "return windowedSequence(size, step, partialWindows) { it.toString() }" }
@@ -823,10 +819,9 @@ object Generators : TemplateGroupBase() {
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}.
@sample samples.text.Strings.chunkedTransform
"""
}
sample("samples.text.Strings.chunkedTransform")
typeParam("R")
returns("List<R>")
@@ -851,10 +846,9 @@ object Generators : TemplateGroupBase() {
The last ${f.snapshotResult} in the resulting ${f.mapResult} may have less ${f.element.pluralize()} than the given [size].
@param size the number of elements to take in each ${f.snapshotResult}, must be positive and can be greater than the number of elements in this ${f.collection}.
@sample samples.collections.Collections.Transformations.chunked
"""
}
sample("samples.collections.Collections.Transformations.chunked")
specialFor(Iterables) { returns("List<List<T>>") }
specialFor(Sequences) { returns("Sequence<List<T>>") }
specialFor(CharSequences) { returns("List<String>") }
@@ -880,10 +874,9 @@ object Generators : TemplateGroupBase() {
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}.
@sample samples.text.Strings.chunkedTransformToSequence
"""
}
sample("samples.text.Strings.chunkedTransformToSequence")
typeParam("R")
returns("Sequence<R>")
@@ -906,10 +899,9 @@ object Generators : TemplateGroupBase() {
The last ${f.snapshotResult} in the resulting sequence may have less ${f.element.pluralize()} than the given [size].
@param size the number of elements to take in each ${f.snapshotResult}, must be positive and can be greater than the number of elements in this ${f.collection}.
@sample samples.collections.Collections.Transformations.chunked
"""
}
sample("samples.collections.Collections.Transformations.chunked")
returns("Sequence<String>")
body(CharSequences) { "return chunkedSequence(size) { it.toString() }" }
@@ -926,10 +918,9 @@ object Generators : TemplateGroupBase() {
to an each pair of two adjacent ${f.element.pluralize()} in this ${f.collection}.
The returned ${f.mapResult} is empty if this ${f.collection} contains less than two ${f.element.pluralize()}.
@sample samples.collections.Collections.Transformations.zipWithNextToFindDeltas
"""
}
sample("samples.collections.Collections.Transformations.zipWithNextToFindDeltas")
returns("List<R>")
inline()
body {
@@ -988,10 +979,9 @@ object Generators : TemplateGroupBase() {
Returns a ${f.mapResult} of pairs of each two adjacent ${f.element.pluralize()} in this ${f.collection}.
The returned ${f.mapResult} is empty if this ${f.collection} contains less than two ${f.element.pluralize()}.
@sample samples.collections.Collections.Transformations.zipWithNext
"""
}
sample("samples.collections.Collections.Transformations.zipWithNext")
sequenceClassification(intermediate, stateless)
specialFor(Sequences) { returns("Sequence<Pair<T, T>>") }
body {
@@ -1007,10 +997,9 @@ object Generators : TemplateGroupBase() {
Returns a list of values built from the elements of `this` ${f.collection} and the [other] collection with the same index
using the provided [transform] function applied to each pair of elements.
The returned list has length of the shortest collection.
@sample samples.collections.Iterables.Operations.zipIterableWithTransform
"""
}
sample("samples.collections.Iterables.Operations.zipIterableWithTransform")
typeParam("R")
typeParam("V")
returns("List<V>")
@@ -1048,10 +1037,9 @@ object Generators : TemplateGroupBase() {
Returns a list of values built from the elements of `this` ${f.collection} and the [other] array with the same index
using the provided [transform] function applied to each pair of elements.
The returned list has length of the shortest collection.
@sample samples.collections.Iterables.Operations.zipIterableWithTransform
"""
}
sample("samples.collections.Iterables.Operations.zipIterableWithTransform")
typeParam("R")
typeParam("V")
returns("List<V>")
@@ -1089,10 +1077,9 @@ object Generators : TemplateGroupBase() {
Returns a list of values built from the elements of `this` array and the [other] array with the same index
using the provided [transform] function applied to each pair of elements.
The returned list has length of the shortest array.
@sample samples.collections.Iterables.Operations.zipIterableWithTransform
"""
}
sample("samples.collections.Iterables.Operations.zipIterableWithTransform")
typeParam("V")
returns("List<V>")
inline()
@@ -1116,10 +1103,9 @@ object Generators : TemplateGroupBase() {
Returns a sequence of values built from the elements of `this` sequence and the [other] sequence with the same index
using the provided [transform] function applied to each pair of elements.
The resulting sequence ends as soon as the shortest input sequence ends.
@sample samples.collections.Sequences.Transformations.zipWithTransform
"""
}
sample("samples.collections.Sequences.Transformations.zipWithTransform")
sequenceClassification(intermediate, stateless)
typeParam("R")
typeParam("V")
@@ -1139,10 +1125,9 @@ object Generators : TemplateGroupBase() {
Returns a list of values built from the characters of `this` and the [other] char sequences with the same index
using the provided [transform] function applied to each pair of characters.
The returned list has length of the shortest char sequence.
@sample samples.text.Strings.zipWithTransform
"""
}
sample("samples.text.Strings.zipWithTransform")
typeParam("V")
returns("List<V>")
inline()
@@ -1168,10 +1153,9 @@ object Generators : TemplateGroupBase() {
"""
Returns a list of pairs built from the elements of `this` collection and [other] ${f.collection} with the same index.
The returned list has length of the shortest collection.
@sample samples.collections.Iterables.Operations.zipIterable
"""
}
sample("samples.collections.Iterables.Operations.zipIterable")
typeParam("R")
returns("List<Pair<T, R>>")
body {
@@ -1189,10 +1173,9 @@ object Generators : TemplateGroupBase() {
"""
Returns a list of pairs built from the characters of `this` and the [other] char sequences with the same index
The returned list has length of the shortest char sequence.
@sample samples.text.Strings.zip
"""
}
sample("samples.text.Strings.zip")
returns("List<Pair<Char, Char>>")
body {
"""
@@ -1209,10 +1192,9 @@ object Generators : TemplateGroupBase() {
"""
Returns a list of pairs built from the elements of `this` ${f.collection} and the [other] array with the same index.
The returned list has length of the shortest collection.
@sample samples.collections.Iterables.Operations.zipIterable
"""
}
sample("samples.collections.Iterables.Operations.zipIterable")
typeParam("R")
returns("List<Pair<T, R>>")
body {
@@ -1230,10 +1212,9 @@ object Generators : TemplateGroupBase() {
"""
Returns a list of pairs built from the elements of `this` array and the [other] array with the same index.
The returned list has length of the shortest collection.
@sample samples.collections.Iterables.Operations.zipIterable
"""
}
sample("samples.collections.Iterables.Operations.zipIterable")
returns("List<Pair<T, T>>")
body {
"""
@@ -1250,10 +1231,9 @@ object Generators : TemplateGroupBase() {
"""
Returns a sequence of values built from the elements of `this` sequence and the [other] sequence with the same index.
The resulting sequence ends as soon as the shortest input sequence ends.
@sample samples.collections.Sequences.Transformations.zip
"""
}
sample("samples.collections.Sequences.Transformations.zip")
sequenceClassification(intermediate, stateless)
typeParam("R")
returns("Sequence<Pair<T, R>>")
libraries/tools/kotlin-stdlib-gen/src/templates/Mapping.kt
+5 -10
View File
@@ -326,10 +326,9 @@ object Mapping : TemplateGroupBase() {
applied to each ${f.element} and returns a map where each group key is associated with a list of corresponding ${f.element.pluralize()}.
The returned map preserves the entry iteration order of the keys produced from the original ${f.collection}.
@sample samples.collections.Collections.Transformations.groupBy
"""
}
sample("samples.collections.Collections.Transformations.groupBy")
sequenceClassification(terminal)
typeParam("K")
returns("Map<K, List<T>>")
@@ -350,10 +349,9 @@ object Mapping : TemplateGroupBase() {
applied to each ${f.element} and puts to the [destination] map each group key associated with a list of corresponding ${f.element.pluralize()}.
@return The [destination] map.
@sample samples.collections.Collections.Transformations.groupBy
"""
}
sample("samples.collections.Collections.Transformations.groupBy")
sequenceClassification(terminal)
returns("M")
body {
@@ -380,10 +378,9 @@ object Mapping : TemplateGroupBase() {
and returns a map where each group key is associated with a list of corresponding values.
The returned map preserves the entry iteration order of the keys produced from the original ${f.collection}.
@sample samples.collections.Collections.Transformations.groupByKeysAndValues
"""
}
sample("samples.collections.Collections.Transformations.groupByKeysAndValues")
sequenceClassification(terminal)
typeParam("K")
typeParam("V")
@@ -408,10 +405,9 @@ object Mapping : TemplateGroupBase() {
and puts to the [destination] map each group key associated with a list of corresponding values.
@return The [destination] map.
@sample samples.collections.Collections.Transformations.groupByKeysAndValues
"""
}
sample("samples.collections.Collections.Transformations.groupByKeysAndValues")
sequenceClassification(terminal)
returns("M")
body {
@@ -441,10 +437,9 @@ object Mapping : TemplateGroupBase() {
"""
Creates a [Grouping] source from ${f.collection.prefixWithArticle()} to be used later with one of group-and-fold operations
using the specified [keySelector] function to extract a key from each ${f.element}.
@sample samples.collections.Collections.Transformations.groupingByEachCount
"""
}
sample("samples.collections.Collections.Transformations.groupingByEachCount")
body {
"""
libraries/tools/kotlin-stdlib-gen/src/templates/Sequence.kt
+3 -2
View File
@@ -52,10 +52,11 @@ object SequenceOps : TemplateGroupBase() {
doc {
"""
Creates a [Sequence] instance that wraps the original ${f.collection} returning its ${f.element.pluralize()} when being iterated.
${if (f in listOf(ArraysOfPrimitives, ArraysOfObjects, Iterables)) "@sample samples.collections.Sequences.Building.sequenceFrom${f.doc.collection.capitalize()}" else ""}
"""
}
if (f in listOf(ArraysOfPrimitives, ArraysOfObjects, Iterables))
sample("samples.collections.Sequences.Building.sequenceFrom${f.doc.collection.capitalize()}")
returns("Sequence<T>")
body {
"""
libraries/tools/kotlin-stdlib-gen/src/templates/Strings.kt
+2 -4
View File
@@ -30,10 +30,9 @@ object StringJoinOps : TemplateGroupBase() {
If the collection could be huge, you can specify a non-negative value of [limit], in which case only the first [limit]
elements will be appended, followed by the [truncated] string (which defaults to "...").
@sample samples.collections.Collections.Transformations.joinTo
"""
}
sample("samples.collections.Collections.Transformations.joinTo")
sequenceClassification(terminal)
typeParam("A : Appendable")
returns("A")
@@ -81,10 +80,9 @@ object StringJoinOps : TemplateGroupBase() {
If the collection could be huge, you can specify a non-negative value of [limit], in which case only the first [limit]
elements will be appended, followed by the [truncated] string (which defaults to "...").
@sample samples.collections.Collections.Transformations.joinToString
"""
}
sample("samples.collections.Collections.Transformations.joinToString")
sequenceClassification(terminal)
returns("String")
libraries/tools/kotlin-stdlib-gen/src/templates/dsl/MemberBuilder.kt
+10
View File
@@ -55,6 +55,8 @@ class MemberBuilder(
var doc: String? = null; private set
val samples = mutableListOf<String>()
val sequenceClassification = mutableListOf<SequenceClass>()
var deprecate: Deprecation? = null; private set
var since: String? = null; private set
@@ -129,6 +131,10 @@ class MemberBuilder(
@Deprecated("Use specialFor", ReplaceWith("specialFor(*fs) { doc(valueBuilder) }"))
fun doc(vararg fs: Family, valueBuilder: DocExtensions.() -> String) = specialFor(*fs) { doc(valueBuilder) }
fun sample(sampleRef: String) {
samples += sampleRef
}
fun body(valueBuilder: () -> String) {
body = valueBuilder()
}
@@ -299,6 +305,10 @@ class MemberBuilder(
StringReader(methodDoc.trim()).forEachLine { line ->
builder.append(" * ").append(line.trim()).append("\n")
}
if (samples.any()) {
builder.append(" * \n")
samples.forEach { builder.append(" * @sample $it\n")}
}
if (family == Sequences && sequenceClassification.isNotEmpty()) {
builder.append(" *\n")
builder.append(" * The operation is ${sequenceClassification.joinToString(" and ") { "_${it}_" }}.\n")