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

2018-04-20 22:11:23 +03:00
parent 5dd7ff4d7f
commit 908d2d6975
12 changed files with 126 additions and 92 deletions
@@ -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 {
@@ -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_.
 */
@@ -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)