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

Unify stdlib docs with common stdlib (#2245)

Browse Source 
* Update collection interface declarations

* Unify math docs: remove excess 'actual' word

* Unify print/println/readLine docs

* Unify annotations docs

* Correct parameter reference in copyInto docs

* Unify array extension docs

* Unify AbstractMutableMap docs

* Unify docs of primitives and string extensions

* Unify coroutine intrinsic docs

* Unify Regex docs
This commit is contained in:
ilya-g
2018-10-22 15:04:12 +03:00
committed by Nikolay Igotti
parent a628e3e56a
commit ec9b057e5a
19 changed files with 327 additions and 164 deletions
Download Patch File Download Diff File Expand all files Collapse all files
runtime/src/main/kotlin/kotlin/Annotations.kt
+9 -1
View File
@@ -118,7 +118,15 @@ public annotation class SinceKotlin(val version: String)
public annotation class DslMarker
/**
* Specifies that this part of internal API is effectively public exposed by using in public inline function
* When applied to a class or a member with internal visibility allows to use it from public inline functions and
* makes it effectively public.
*
* Public inline functions cannot use non-public API, since if they are inlined, those non-public API references
* would violate access restrictions at a call site (http://kotlinlang.org/docs/reference/inline-functions.html#public-inline-restrictions).
*
* To overcome this restriction an `internal` declaration can be annotated with the `@PublishedApi` annotation:
* - this allows to call that declaration from public inline functions;
* - the declaration becomes effectively public, and this should be considered with respect to binary compatibility maintaining.
*/
@Target(AnnotationTarget.CLASS, AnnotationTarget.CONSTRUCTOR, AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY)
@Retention(AnnotationRetention.BINARY)
runtime/src/main/kotlin/kotlin/Boolean.kt
+4 -2
View File
@@ -22,13 +22,15 @@ public class Boolean private constructor(
external public operator fun not(): Boolean
/**
* Performs a logical `and` operation between this Boolean and the [other] one.
* Performs a logical `and` operation between this Boolean and the [other] one. Unlike the `&&` operator,
* this function does not perform short-circuit evaluation. Both `this` and [other] will always be evaluated.
*/
@SymbolName("Kotlin_Boolean_and_Boolean")
external public infix fun and(other: Boolean): Boolean
/**
* Performs a logical `or` operation between this Boolean and the [other] one.
* Performs a logical `or` operation between this Boolean and the [other] one. Unlike the `||` operator,
* this function does not perform short-circuit evaluation. Both `this` and [other] will always be evaluated.
*/
@SymbolName("Kotlin_Boolean_or_Boolean")
external public infix fun or(other: Boolean): Boolean
runtime/src/main/kotlin/kotlin/Char.kt
+3 -2
View File
@@ -12,8 +12,9 @@ public class Char private constructor(
private val value: kotlin.native.internal.ShortValue) : Comparable<Char> {
/**
* Compares this value with the specified value for order.
* Returns zero if this value is equal to the specified other value, a negative number if its less than other,
* or a positive number if its greater than other.
*
* Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
* or a positive number if it's greater than other.
*/
@SymbolName("Kotlin_Char_compareTo_Char")
external public override fun compareTo(other: Char): Int
runtime/src/main/kotlin/kotlin/Primitives.kt
+80 -80
View File
@@ -38,43 +38,43 @@ public final class Byte private constructor(private val value: kotlin.native.int
/**
* Compares this value with the specified value for order.
* Returns zero if this value is equal to the specified other value, a negative number if its less than other,
* or a positive number if its greater than other.
* Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
* or a positive number if it's greater than other.
*/
@SymbolName("Kotlin_Byte_compareTo_Byte")
external public override operator fun compareTo(other: Byte): Int
/**
* Compares this value with the specified value for order.
* Returns zero if this value is equal to the specified other value, a negative number if its less than other,
* or a positive number if its greater than other.
* Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
* or a positive number if it's greater than other.
*/
@SymbolName("Kotlin_Byte_compareTo_Short")
external public operator fun compareTo(other: Short): Int
/**
* Compares this value with the specified value for order.
* Returns zero if this value is equal to the specified other value, a negative number if its less than other,
* or a positive number if its greater than other.
* Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
* or a positive number if it's greater than other.
*/
@SymbolName("Kotlin_Byte_compareTo_Int")
external public operator fun compareTo(other: Int): Int
/**
* Compares this value with the specified value for order.
* Returns zero if this value is equal to the specified other value, a negative number if its less than other,
* or a positive number if its greater than other.
* Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
* or a positive number if it's greater than other.
*/
@SymbolName("Kotlin_Byte_compareTo_Long")
external public operator fun compareTo(other: Long): Int
/**
* Compares this value with the specified value for order.
* Returns zero if this value is equal to the specified other value, a negative number if its less than other,
* or a positive number if its greater than other.
* Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
* or a positive number if it's greater than other.
*/
@SymbolName("Kotlin_Byte_compareTo_Float")
external public operator fun compareTo(other: Float): Int
/**
* Compares this value with the specified value for order.
* Returns zero if this value is equal to the specified other value, a negative number if its less than other,
* or a positive number if its greater than other.
* Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
* or a positive number if it's greater than other.
*/
@SymbolName("Kotlin_Byte_compareTo_Double")
external public operator fun compareTo(other: Double): Int
@@ -263,43 +263,43 @@ public final class Short private constructor(private val value: kotlin.native.in
/**
* Compares this value with the specified value for order.
* Returns zero if this value is equal to the specified other value, a negative number if its less than other,
* or a positive number if its greater than other.
* Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
* or a positive number if it's greater than other.
*/
@SymbolName("Kotlin_Short_compareTo_Byte")
external public operator fun compareTo(other: Byte): Int
/**
* Compares this value with the specified value for order.
* Returns zero if this value is equal to the specified other value, a negative number if its less than other,
* or a positive number if its greater than other.
* Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
* or a positive number if it's greater than other.
*/
@SymbolName("Kotlin_Short_compareTo_Short")
external public override operator fun compareTo(other: Short): Int
/**
* Compares this value with the specified value for order.
* Returns zero if this value is equal to the specified other value, a negative number if its less than other,
* or a positive number if its greater than other.
* Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
* or a positive number if it's greater than other.
*/
@SymbolName("Kotlin_Short_compareTo_Int")
external public operator fun compareTo(other: Int): Int
/**
* Compares this value with the specified value for order.
* Returns zero if this value is equal to the specified other value, a negative number if its less than other,
* or a positive number if its greater than other.
* Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
* or a positive number if it's greater than other.
*/
@SymbolName("Kotlin_Short_compareTo_Long")
external public operator fun compareTo(other: Long): Int
/**
* Compares this value with the specified value for order.
* Returns zero if this value is equal to the specified other value, a negative number if its less than other,
* or a positive number if its greater than other.
* Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
* or a positive number if it's greater than other.
*/
@SymbolName("Kotlin_Short_compareTo_Float")
external public operator fun compareTo(other: Float): Int
/**
* Compares this value with the specified value for order.
* Returns zero if this value is equal to the specified other value, a negative number if its less than other,
* or a positive number if its greater than other.
* Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
* or a positive number if it's greater than other.
*/
@SymbolName("Kotlin_Short_compareTo_Double")
external public operator fun compareTo(other: Double): Int
@@ -488,43 +488,43 @@ public final class Int private constructor(private val value: kotlin.native.inte
/**
* Compares this value with the specified value for order.
* Returns zero if this value is equal to the specified other value, a negative number if its less than other,
* or a positive number if its greater than other.
* Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
* or a positive number if it's greater than other.
*/
@SymbolName("Kotlin_Int_compareTo_Byte")
external public operator fun compareTo(other: Byte): Int
/**
* Compares this value with the specified value for order.
* Returns zero if this value is equal to the specified other value, a negative number if its less than other,
* or a positive number if its greater than other.
* Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
* or a positive number if it's greater than other.
*/
@SymbolName("Kotlin_Int_compareTo_Short")
external public operator fun compareTo(other: Short): Int
/**
* Compares this value with the specified value for order.
* Returns zero if this value is equal to the specified other value, a negative number if its less than other,
* or a positive number if its greater than other.
* Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
* or a positive number if it's greater than other.
*/
@SymbolName("Kotlin_Int_compareTo_Int")
external public override operator fun compareTo(other: Int): Int
/**
* Compares this value with the specified value for order.
* Returns zero if this value is equal to the specified other value, a negative number if its less than other,
* or a positive number if its greater than other.
* Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
* or a positive number if it's greater than other.
*/
@SymbolName("Kotlin_Int_compareTo_Long")
external public operator fun compareTo(other: Long): Int
/**
* Compares this value with the specified value for order.
* Returns zero if this value is equal to the specified other value, a negative number if its less than other,
* or a positive number if its greater than other.
* Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
* or a positive number if it's greater than other.
*/
@SymbolName("Kotlin_Int_compareTo_Float")
external public operator fun compareTo(other: Float): Int
/**
* Compares this value with the specified value for order.
* Returns zero if this value is equal to the specified other value, a negative number if its less than other,
* or a positive number if its greater than other.
* Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
* or a positive number if it's greater than other.
*/
@SymbolName("Kotlin_Int_compareTo_Double")
external public operator fun compareTo(other: Double): Int
@@ -637,13 +637,13 @@ public final class Int private constructor(private val value: kotlin.native.inte
@SymbolName("Kotlin_Int_unaryMinus")
external public operator fun unaryMinus(): Int
/** Shifts this value left by [bits]. */
/** Shifts this value left by the [bitCount] number of bits. */
@SymbolName("Kotlin_Int_shl_Int")
external public infix fun shl(bitCount: Int): Int
/** Shifts this value right by [bits], filling the leftmost bits with copies of the sign bit. */
/** Shifts this value right by the [bitCount] number of bits, filling the leftmost bits with copies of the sign bit. */
@SymbolName("Kotlin_Int_shr_Int")
external public infix fun shr(bitCount: Int): Int
/** Shifts this value right by [bits], filling the leftmost bits with zeros. */
/** Shifts this value right by the [bitCount] number of bits, filling the leftmost bits with zeros. */
@SymbolName("Kotlin_Int_ushr_Int")
external public infix fun ushr(bitCount: Int): Int
/** Performs a bitwise AND operation between the two values. */
@@ -655,7 +655,7 @@ public final class Int private constructor(private val value: kotlin.native.inte
/** Performs a bitwise XOR operation between the two values. */
@SymbolName("Kotlin_Int_xor_Int")
external public infix fun xor(other: Int): Int
/** Inverts the bits in this value/ */
/** Inverts the bits in this value. */
@SymbolName("Kotlin_Int_inv")
external public fun inv(): Int
@@ -735,43 +735,43 @@ public final class Long private constructor(private val value: kotlin.native.int
/**
* Compares this value with the specified value for order.
* Returns zero if this value is equal to the specified other value, a negative number if its less than other,
* or a positive number if its greater than other.
* Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
* or a positive number if it's greater than other.
*/
@SymbolName("Kotlin_Long_compareTo_Byte")
external public operator fun compareTo(other: Byte): Int
/**
* Compares this value with the specified value for order.
* Returns zero if this value is equal to the specified other value, a negative number if its less than other,
* or a positive number if its greater than other.
* Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
* or a positive number if it's greater than other.
*/
@SymbolName("Kotlin_Long_compareTo_Short")
external public operator fun compareTo(other: Short): Int
/**
* Compares this value with the specified value for order.
* Returns zero if this value is equal to the specified other value, a negative number if its less than other,
* or a positive number if its greater than other.
* Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
* or a positive number if it's greater than other.
*/
@SymbolName("Kotlin_Long_compareTo_Int")
external public operator fun compareTo(other: Int): Int
/**
* Compares this value with the specified value for order.
* Returns zero if this value is equal to the specified other value, a negative number if its less than other,
* or a positive number if its greater than other.
* Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
* or a positive number if it's greater than other.
*/
@SymbolName("Kotlin_Long_compareTo_Long")
external public override operator fun compareTo(other: Long): Int
/**
* Compares this value with the specified value for order.
* Returns zero if this value is equal to the specified other value, a negative number if its less than other,
* or a positive number if its greater than other.
* Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
* or a positive number if it's greater than other.
*/
@SymbolName("Kotlin_Long_compareTo_Float")
external public operator fun compareTo(other: Float): Int
/**
* Compares this value with the specified value for order.
* Returns zero if this value is equal to the specified other value, a negative number if its less than other,
* or a positive number if its greater than other.
* Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
* or a positive number if it's greater than other.
*/
@SymbolName("Kotlin_Long_compareTo_Double")
external public operator fun compareTo(other: Double): Int
@@ -901,13 +901,13 @@ public final class Long private constructor(private val value: kotlin.native.int
return LongRange(this, other.toLong())
}
/** Shifts this value left by [bits]. */
/** Shifts this value left by the [bitCount] number of bits. */
@SymbolName("Kotlin_Long_shl_Int")
external public infix fun shl(bitCount: Int): Long
/** Shifts this value right by [bits], filling the leftmost bits with copies of the sign bit. */
/** Shifts this value right by the [bitCount] number of bits, filling the leftmost bits with copies of the sign bit. */
@SymbolName("Kotlin_Long_shr_Int")
external public infix fun shr(bitCount: Int): Long
/** Shifts this value right by [bits], filling the leftmost bits with zeros. */
/** Shifts this value right by the [bitCount] number of bits, filling the leftmost bits with zeros. */
@SymbolName("Kotlin_Long_ushr_Int")
external public infix fun ushr(bitCount: Int): Long
/** Performs a bitwise AND operation between the two values. */
@@ -919,7 +919,7 @@ public final class Long private constructor(private val value: kotlin.native.int
/** Performs a bitwise XOR operation between the two values. */
@SymbolName("Kotlin_Long_xor_Long")
external public infix fun xor(other: Long): Long
/** Inverts the bits in this value/ */
/** Inverts the bits in this value. */
@SymbolName("Kotlin_Long_inv")
external public fun inv(): Long
@@ -987,32 +987,32 @@ public final class Float private constructor(private val value: kotlin.native.in
/**
* Compares this value with the specified value for order.
* Returns zero if this value is equal to the specified other value, a negative number if its less than other,
* or a positive number if its greater than other.
* Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
* or a positive number if it's greater than other.
*/
public operator fun compareTo(other: Byte): Int = compareTo(other.toFloat())
/**
* Compares this value with the specified value for order.
* Returns zero if this value is equal to the specified other value, a negative number if its less than other,
* or a positive number if its greater than other.
* Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
* or a positive number if it's greater than other.
*/
public operator fun compareTo(other: Short): Int = compareTo(other.toFloat())
/**
* Compares this value with the specified value for order.
* Returns zero if this value is equal to the specified other value, a negative number if its less than other,
* or a positive number if its greater than other.
* Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
* or a positive number if it's greater than other.
*/
public operator fun compareTo(other: Int): Int = compareTo(other.toFloat())
/**
* Compares this value with the specified value for order.
* Returns zero if this value is equal to the specified other value, a negative number if its less than other,
* or a positive number if its greater than other.
* Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
* or a positive number if it's greater than other.
*/
public operator fun compareTo(other: Long): Int = compareTo(other.toFloat())
/**
* Compares this value with the specified value for order.
* Returns zero if this value is equal to the specified other value, a negative number if its less than other,
* or a positive number if its greater than other.
* Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
* or a positive number if it's greater than other.
*/
public override operator fun compareTo(other: Float): Int {
// if any of values in NaN both comparisons return false
@@ -1028,8 +1028,8 @@ public final class Float private constructor(private val value: kotlin.native.in
/**
* Compares this value with the specified value for order.
* Returns zero if this value is equal to the specified other value, a negative number if its less than other,
* or a positive number if its greater than other.
* Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
* or a positive number if it's greater than other.
*/
public operator fun compareTo(other: Double): Int = - other.compareTo(this)
@@ -1206,43 +1206,43 @@ public final class Double private constructor(private val value: kotlin.native.i
/**
* Compares this value with the specified value for order.
* Returns zero if this value is equal to the specified other value, a negative number if its less than other,
* or a positive number if its greater than other.
* Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
* or a positive number if it's greater than other.
*/
public operator fun compareTo(other: Byte): Int = compareTo(other.toDouble())
/**
* Compares this value with the specified value for order.
* Returns zero if this value is equal to the specified other value, a negative number if its less than other,
* or a positive number if its greater than other.
* Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
* or a positive number if it's greater than other.
*/
public operator fun compareTo(other: Short): Int = compareTo(other.toDouble())
/**
* Compares this value with the specified value for order.
* Returns zero if this value is equal to the specified other value, a negative number if its less than other,
* or a positive number if its greater than other.
* Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
* or a positive number if it's greater than other.
*/
public operator fun compareTo(other: Int): Int = compareTo(other.toDouble())
/**
* Compares this value with the specified value for order.
* Returns zero if this value is equal to the specified other value, a negative number if its less than other,
* or a positive number if its greater than other.
* Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
* or a positive number if it's greater than other.
*/
public operator fun compareTo(other: Long): Int = compareTo(other.toDouble())
/**
* Compares this value with the specified value for order.
* Returns zero if this value is equal to the specified other value, a negative number if its less than other,
* or a positive number if its greater than other.
* Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
* or a positive number if it's greater than other.
*/
public operator fun compareTo(other: Float): Int = compareTo(other.toDouble())
/**
* Compares this value with the specified value for order.
* Returns zero if this value is equal to the specified other value, a negative number if its less than other,
* or a positive number if its greater than other.
* Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
* or a positive number if it's greater than other.
*/
public override operator fun compareTo(other: Double): Int {
// if any of values in NaN both comparisons return false
runtime/src/main/kotlin/kotlin/annotation/Annotations.kt
+4 -2
View File
@@ -5,6 +5,8 @@
package kotlin.annotation
import kotlin.annotation.AnnotationTarget.*
/**
* Contains the list of code elements which are the possible annotation targets
*/
@@ -59,8 +61,8 @@ public enum class AnnotationRetention {
/**
* This meta-annotation indicates the kinds of code elements which are possible targets of an annotation.
*
* If the target meta-annotation is not present on an annotation declaration, the annotation
* is applicable to any code element, except type parameters, type usages, expressions, and files.
* If the target meta-annotation is not present on an annotation declaration, the annotation is applicable to the following elements:
* [CLASS], [PROPERTY], [FIELD], [LOCAL_VARIABLE], [VALUE_PARAMETER], [CONSTRUCTOR], [FUNCTION], [PROPERTY_GETTER], [PROPERTY_SETTER].
*
* @property allowedTargets list of allowed annotation targets
*/
runtime/src/main/kotlin/kotlin/collections/Arrays.kt
+99 -20
View File
@@ -89,6 +89,12 @@ public actual inline fun CharArray.copyOf(): CharArray {
/**
* Returns new array which is a copy of the original array, resized to the given [newSize].
* The copy is either truncated or padded at the end with `null` values if necessary.
*
* - If [newSize] is less than the size of the original array, the copy array is truncated to the [newSize].
* - If [newSize] is greater than the size of the original array, the extra elements in the copy array are filled with `null` values.
*
* @sample samples.collections.Arrays.CopyOfOperations.resizingCopyOf
*/
@kotlin.internal.InlineOnly
public actual inline fun <T> Array<T>.copyOf(newSize: Int): Array<T?> {
@@ -97,6 +103,12 @@ public actual inline fun <T> Array<T>.copyOf(newSize: Int): Array<T?> {
/**
* Returns new array which is a copy of the original array, resized to the given [newSize].
* The copy is either truncated or padded at the end with zero values if necessary.
*
* - If [newSize] is less than the size of the original array, the copy array is truncated to the [newSize].
* - If [newSize] is greater than the size of the original array, the extra elements in the copy array are filled with zero values.
*
* @sample samples.collections.Arrays.CopyOfOperations.resizedPrimitiveCopyOf
*/
@kotlin.internal.InlineOnly
public actual inline fun ByteArray.copyOf(newSize: Int): ByteArray {
@@ -105,6 +117,12 @@ public actual inline fun ByteArray.copyOf(newSize: Int): ByteArray {
/**
* Returns new array which is a copy of the original array, resized to the given [newSize].
* The copy is either truncated or padded at the end with zero values if necessary.
*
* - If [newSize] is less than the size of the original array, the copy array is truncated to the [newSize].
* - If [newSize] is greater than the size of the original array, the extra elements in the copy array are filled with zero values.
*
* @sample samples.collections.Arrays.CopyOfOperations.resizedPrimitiveCopyOf
*/
@kotlin.internal.InlineOnly
public actual inline fun ShortArray.copyOf(newSize: Int): ShortArray {
@@ -113,6 +131,12 @@ public actual inline fun ShortArray.copyOf(newSize: Int): ShortArray {
/**
* Returns new array which is a copy of the original array, resized to the given [newSize].
* The copy is either truncated or padded at the end with zero values if necessary.
*
* - If [newSize] is less than the size of the original array, the copy array is truncated to the [newSize].
* - If [newSize] is greater than the size of the original array, the extra elements in the copy array are filled with zero values.
*
* @sample samples.collections.Arrays.CopyOfOperations.resizedPrimitiveCopyOf
*/
@kotlin.internal.InlineOnly
public actual inline fun IntArray.copyOf(newSize: Int): IntArray {
@@ -121,6 +145,12 @@ public actual inline fun IntArray.copyOf(newSize: Int): IntArray {
/**
* Returns new array which is a copy of the original array, resized to the given [newSize].
* The copy is either truncated or padded at the end with zero values if necessary.
*
* - If [newSize] is less than the size of the original array, the copy array is truncated to the [newSize].
* - If [newSize] is greater than the size of the original array, the extra elements in the copy array are filled with zero values.
*
* @sample samples.collections.Arrays.CopyOfOperations.resizedPrimitiveCopyOf
*/
@kotlin.internal.InlineOnly
public actual inline fun LongArray.copyOf(newSize: Int): LongArray {
@@ -129,6 +159,12 @@ public actual inline fun LongArray.copyOf(newSize: Int): LongArray {
/**
* Returns new array which is a copy of the original array, resized to the given [newSize].
* The copy is either truncated or padded at the end with zero values if necessary.
*
* - If [newSize] is less than the size of the original array, the copy array is truncated to the [newSize].
* - If [newSize] is greater than the size of the original array, the extra elements in the copy array are filled with zero values.
*
* @sample samples.collections.Arrays.CopyOfOperations.resizedPrimitiveCopyOf
*/
@kotlin.internal.InlineOnly
public actual inline fun FloatArray.copyOf(newSize: Int): FloatArray {
@@ -137,6 +173,12 @@ public actual inline fun FloatArray.copyOf(newSize: Int): FloatArray {
/**
* Returns new array which is a copy of the original array, resized to the given [newSize].
* The copy is either truncated or padded at the end with zero values if necessary.
*
* - If [newSize] is less than the size of the original array, the copy array is truncated to the [newSize].
* - If [newSize] is greater than the size of the original array, the extra elements in the copy array are filled with zero values.
*
* @sample samples.collections.Arrays.CopyOfOperations.resizedPrimitiveCopyOf
*/
@kotlin.internal.InlineOnly
public actual inline fun DoubleArray.copyOf(newSize: Int): DoubleArray {
@@ -145,6 +187,12 @@ public actual inline fun DoubleArray.copyOf(newSize: Int): DoubleArray {
/**
* Returns new array which is a copy of the original array, resized to the given [newSize].
* The copy is either truncated or padded at the end with `false` values if necessary.
*
* - If [newSize] is less than the size of the original array, the copy array is truncated to the [newSize].
* - If [newSize] is greater than the size of the original array, the extra elements in the copy array are filled with `false` values.
*
* @sample samples.collections.Arrays.CopyOfOperations.resizedPrimitiveCopyOf
*/
@kotlin.internal.InlineOnly
public actual inline fun BooleanArray.copyOf(newSize: Int): BooleanArray {
@@ -153,6 +201,12 @@ public actual inline fun BooleanArray.copyOf(newSize: Int): BooleanArray {
/**
* Returns new array which is a copy of the original array, resized to the given [newSize].
* The copy is either truncated or padded at the end with null char (`\u0000`) values if necessary.
*
* - If [newSize] is less than the size of the original array, the copy array is truncated to the [newSize].
* - If [newSize] is greater than the size of the original array, the extra elements in the copy array are filled with null char (`\u0000`) values.
*
* @sample samples.collections.Arrays.CopyOfOperations.resizedPrimitiveCopyOf
*/
@kotlin.internal.InlineOnly
public actual inline fun CharArray.copyOf(newSize: Int): CharArray {
@@ -167,7 +221,10 @@ public actual inline fun CharArray.copyOf(newSize: Int): CharArray {
}
/**
* Returns new array which is a copy of range of original array.
* Returns a new array which is a copy of the specified range of the original array.
*
* @param fromIndex the start of the range (inclusive), must be in `0..array.size`
* @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size`
*/
// TODO: The method may check input or return Array<T?>.
// Now we check its input (fromIndex <= toIndex < size).
@@ -179,7 +236,10 @@ public actual inline fun <T> Array<T>.copyOfRange(fromIndex: Int, toIndex: Int):
}
/**
* Returns new array which is a copy of range of original array.
* Returns a new array which is a copy of the specified range of the original array.
*
* @param fromIndex the start of the range (inclusive), must be in `0..array.size`
* @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size`
*/
@kotlin.internal.InlineOnly
public actual inline fun ByteArray.copyOfRange(fromIndex: Int, toIndex: Int): ByteArray {
@@ -188,7 +248,10 @@ public actual inline fun ByteArray.copyOfRange(fromIndex: Int, toIndex: Int): By
}
/**
* Returns new array which is a copy of range of original array.
* Returns a new array which is a copy of the specified range of the original array.
*
* @param fromIndex the start of the range (inclusive), must be in `0..array.size`
* @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size`
*/
@kotlin.internal.InlineOnly
public actual inline fun ShortArray.copyOfRange(fromIndex: Int, toIndex: Int): ShortArray {
@@ -197,7 +260,10 @@ public actual inline fun ShortArray.copyOfRange(fromIndex: Int, toIndex: Int): S
}
/**
* Returns new array which is a copy of range of original array.
* Returns a new array which is a copy of the specified range of the original array.
*
* @param fromIndex the start of the range (inclusive), must be in `0..array.size`
* @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size`
*/
@kotlin.internal.InlineOnly
public actual inline fun IntArray.copyOfRange(fromIndex: Int, toIndex: Int): IntArray {
@@ -206,7 +272,10 @@ public actual inline fun IntArray.copyOfRange(fromIndex: Int, toIndex: Int): Int
}
/**
* Returns new array which is a copy of range of original array.
* Returns a new array which is a copy of the specified range of the original array.
*
* @param fromIndex the start of the range (inclusive), must be in `0..array.size`
* @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size`
*/
@kotlin.internal.InlineOnly
public actual inline fun LongArray.copyOfRange(fromIndex: Int, toIndex: Int): LongArray {
@@ -215,7 +284,10 @@ public actual inline fun LongArray.copyOfRange(fromIndex: Int, toIndex: Int): Lo
}
/**
* Returns new array which is a copy of range of original array.
* Returns a new array which is a copy of the specified range of the original array.
*
* @param fromIndex the start of the range (inclusive), must be in `0..array.size`
* @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size`
*/
@kotlin.internal.InlineOnly
public actual inline fun FloatArray.copyOfRange(fromIndex: Int, toIndex: Int): FloatArray {
@@ -224,7 +296,10 @@ public actual inline fun FloatArray.copyOfRange(fromIndex: Int, toIndex: Int): F
}
/**
* Returns new array which is a copy of range of original array.
* Returns a new array which is a copy of the specified range of the original array.
*
* @param fromIndex the start of the range (inclusive), must be in `0..array.size`
* @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size`
*/
@kotlin.internal.InlineOnly
public actual inline fun DoubleArray.copyOfRange(fromIndex: Int, toIndex: Int): DoubleArray {
@@ -233,7 +308,10 @@ public actual inline fun DoubleArray.copyOfRange(fromIndex: Int, toIndex: Int):
}
/**
* Returns new array which is a copy of range of original array.
* Returns a new array which is a copy of the specified range of the original array.
*
* @param fromIndex the start of the range (inclusive), must be in `0..array.size`
* @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size`
*/
@kotlin.internal.InlineOnly
public actual inline fun BooleanArray.copyOfRange(fromIndex: Int, toIndex: Int): BooleanArray {
@@ -242,7 +320,10 @@ public actual inline fun BooleanArray.copyOfRange(fromIndex: Int, toIndex: Int):
}
/**
* Returns new array which is a copy of range of original array.
* Returns a new array which is a copy of the specified range of the original array.
*
* @param fromIndex the start of the range (inclusive), must be in `0..array.size`
* @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size`
*/
@kotlin.internal.InlineOnly
public actual inline fun CharArray.copyOfRange(fromIndex: Int, toIndex: Int): CharArray {
@@ -259,8 +340,6 @@ public actual fun <T> Array<out T>.sortWith(comparator: Comparator<in T>): Unit
/**
* Sorts the array in-place according to the natural order of its elements.
*
* @throws ClassCastException if any element of the array is not [Comparable].
*/
public actual fun <T: Comparable<T>> Array<out T>.sort(): Unit {
if (size > 1) sortArrayComparable(this)
@@ -615,7 +694,7 @@ public inline fun <T> Array<out T>.subarrayContentToString(offset: Int, length:
* @param endIndex the end (exclusive) of the subrange to copy, size of this array by default.
*
* @throws IndexOutOfBoundsException or [IllegalArgumentException] when [startIndex] or [endIndex] is out of range of this array indices or when `startIndex > endIndex`.
* @throws IndexOutOfBoundsException when the subrange doesn't fit into the [destination] array starting at the specified [destinationIndex],
* @throws IndexOutOfBoundsException when the subrange doesn't fit into the [destination] array starting at the specified [destinationOffset],
* or when that index is out of the [destination] array indices range.
*
* @return the [destination] array.
@@ -637,7 +716,7 @@ public actual fun <T> Array<out T>.copyInto(destination: Array<T>, destinationOf
* @param endIndex the end (exclusive) of the subrange to copy, size of this array by default.
*
* @throws IndexOutOfBoundsException or [IllegalArgumentException] when [startIndex] or [endIndex] is out of range of this array indices or when `startIndex > endIndex`.
* @throws IndexOutOfBoundsException when the subrange doesn't fit into the [destination] array starting at the specified [destinationIndex],
* @throws IndexOutOfBoundsException when the subrange doesn't fit into the [destination] array starting at the specified [destinationOffset],
* or when that index is out of the [destination] array indices range.
*
* @return the [destination] array.
@@ -659,7 +738,7 @@ public actual fun ByteArray.copyInto(destination: ByteArray, destinationOffset:
* @param endIndex the end (exclusive) of the subrange to copy, size of this array by default.
*
* @throws IndexOutOfBoundsException or [IllegalArgumentException] when [startIndex] or [endIndex] is out of range of this array indices or when `startIndex > endIndex`.
* @throws IndexOutOfBoundsException when the subrange doesn't fit into the [destination] array starting at the specified [destinationIndex],
* @throws IndexOutOfBoundsException when the subrange doesn't fit into the [destination] array starting at the specified [destinationOffset],
* or when that index is out of the [destination] array indices range.
*
* @return the [destination] array.
@@ -681,7 +760,7 @@ public actual fun ShortArray.copyInto(destination: ShortArray, destinationOffset
* @param endIndex the end (exclusive) of the subrange to copy, size of this array by default.
*
* @throws IndexOutOfBoundsException or [IllegalArgumentException] when [startIndex] or [endIndex] is out of range of this array indices or when `startIndex > endIndex`.
* @throws IndexOutOfBoundsException when the subrange doesn't fit into the [destination] array starting at the specified [destinationIndex],
* @throws IndexOutOfBoundsException when the subrange doesn't fit into the [destination] array starting at the specified [destinationOffset],
* or when that index is out of the [destination] array indices range.
*
* @return the [destination] array.
@@ -703,7 +782,7 @@ public actual fun IntArray.copyInto(destination: IntArray, destinationOffset: In
* @param endIndex the end (exclusive) of the subrange to copy, size of this array by default.
*
* @throws IndexOutOfBoundsException or [IllegalArgumentException] when [startIndex] or [endIndex] is out of range of this array indices or when `startIndex > endIndex`.
* @throws IndexOutOfBoundsException when the subrange doesn't fit into the [destination] array starting at the specified [destinationIndex],
* @throws IndexOutOfBoundsException when the subrange doesn't fit into the [destination] array starting at the specified [destinationOffset],
* or when that index is out of the [destination] array indices range.
*
* @return the [destination] array.
@@ -725,7 +804,7 @@ public actual fun LongArray.copyInto(destination: LongArray, destinationOffset:
* @param endIndex the end (exclusive) of the subrange to copy, size of this array by default.
*
* @throws IndexOutOfBoundsException or [IllegalArgumentException] when [startIndex] or [endIndex] is out of range of this array indices or when `startIndex > endIndex`.
* @throws IndexOutOfBoundsException when the subrange doesn't fit into the [destination] array starting at the specified [destinationIndex],
* @throws IndexOutOfBoundsException when the subrange doesn't fit into the [destination] array starting at the specified [destinationOffset],
* or when that index is out of the [destination] array indices range.
*
* @return the [destination] array.
@@ -747,7 +826,7 @@ public actual fun FloatArray.copyInto(destination: FloatArray, destinationOffset
* @param endIndex the end (exclusive) of the subrange to copy, size of this array by default.
*
* @throws IndexOutOfBoundsException or [IllegalArgumentException] when [startIndex] or [endIndex] is out of range of this array indices or when `startIndex > endIndex`.
* @throws IndexOutOfBoundsException when the subrange doesn't fit into the [destination] array starting at the specified [destinationIndex],
* @throws IndexOutOfBoundsException when the subrange doesn't fit into the [destination] array starting at the specified [destinationOffset],
* or when that index is out of the [destination] array indices range.
*
* @return the [destination] array.
@@ -769,7 +848,7 @@ public actual fun DoubleArray.copyInto(destination: DoubleArray, destinationOffs
* @param endIndex the end (exclusive) of the subrange to copy, size of this array by default.
*
* @throws IndexOutOfBoundsException or [IllegalArgumentException] when [startIndex] or [endIndex] is out of range of this array indices or when `startIndex > endIndex`.
* @throws IndexOutOfBoundsException when the subrange doesn't fit into the [destination] array starting at the specified [destinationIndex],
* @throws IndexOutOfBoundsException when the subrange doesn't fit into the [destination] array starting at the specified [destinationOffset],
* or when that index is out of the [destination] array indices range.
*
* @return the [destination] array.
@@ -791,7 +870,7 @@ public actual fun BooleanArray.copyInto(destination: BooleanArray, destinationOf
* @param endIndex the end (exclusive) of the subrange to copy, size of this array by default.
*
* @throws IndexOutOfBoundsException or [IllegalArgumentException] when [startIndex] or [endIndex] is out of range of this array indices or when `startIndex > endIndex`.
* @throws IndexOutOfBoundsException when the subrange doesn't fit into the [destination] array starting at the specified [destinationIndex],
* @throws IndexOutOfBoundsException when the subrange doesn't fit into the [destination] array starting at the specified [destinationOffset],
* or when that index is out of the [destination] array indices range.
*
* @return the [destination] array.
runtime/src/main/kotlin/kotlin/collections/Collection.kt
+4 -2
View File
@@ -8,7 +8,7 @@ package kotlin.collections
/**
* A generic collection of elements. Methods in this interface support only read-only access to the collection;
* read/write access is supported through the [MutableCollection] interface.
* @param E the type of elements contained in the collection.
* @param E the type of elements contained in the collection. The collection is covariant on its element type.
*/
public interface Collection<out E> : Iterable<E> {
// Query Operations
@@ -37,6 +37,8 @@ public interface Collection<out E> : Iterable<E> {
/**
* A generic collection of elements that supports adding and removing elements.
*
* @param E the type of elements contained in the collection. The mutable collection is invariant on its element type.
*/
public interface MutableCollection<E> : Collection<E>, MutableIterable<E> {
// Query Operations
@@ -61,7 +63,7 @@ public interface MutableCollection<E> : Collection<E>, MutableIterable<E> {
// Bulk Modification Operations
/**
* Adds all of the elements in the specified collection to this collection.
* Adds all of the elements of the specified collection to this collection.
*
* @return `true` if any of the specified elements was added to the collection, `false` if the collection was not modified.
*/
runtime/src/main/kotlin/kotlin/collections/Collections.kt
+3 -2
View File
@@ -21,7 +21,7 @@ internal actual fun <T> Array<out T>.copyToArrayOfAny(isVarargs: Boolean): Array
/**
* Classes that inherit from this interface can be represented as a sequence of elements that can
* be iterated over.
* @param T the type of element being iterated over.
* @param T the type of element being iterated over. The iterator is covariant on its element type.
*/
public interface Iterable<out T> {
/**
@@ -33,10 +33,11 @@ public interface Iterable<out T> {
/**
* Classes that inherit from this interface can be represented as a sequence of elements that can
* be iterated over and that supports removing elements during iteration.
* @param T the type of element being iterated over. The mutable iterator is invariant on its element type.
*/
public interface MutableIterable<out T> : Iterable<T> {
/**
* Returns an iterator over the elementrs of this sequence that supports removing elements during iteration.
* Returns an iterator over the elements of this sequence that supports removing elements during iteration.
*/
override fun iterator(): MutableIterator<T>
}
runtime/src/main/kotlin/kotlin/collections/List.kt
+23 -6
View File
@@ -6,10 +6,10 @@
package kotlin.collections
/**
* A generic ordered collection of elements. Methods in this interface support only read-only access to the list;
* read/write access is supported through the [MutableList] interface.
* @param E the type of elements contained in the list.
*/
* A generic ordered collection of elements. Methods in this interface support only read-only access to the list;
* read/write access is supported through the [MutableList] interface.
* @param E the type of elements contained in the list. The list is covariant on its element type.
*/
public interface List<out E> : Collection<E> {
// Query Operations
override val size: Int
@@ -54,28 +54,44 @@ public interface List<out E> : Collection<E> {
/**
* Returns a view of the portion of this list between the specified [fromIndex] (inclusive) and [toIndex] (exclusive).
* The returned list is backed by this list, so non-structural changes in the returned list are reflected in this list, and vice-versa.
*
* Structural changes in the base list make the behavior of the view undefined.
*/
public fun subList(fromIndex: Int, toIndex: Int): List<E>
}
/**
* A generic ordered collection of elements that supports adding and removing elements.
* @param E the type of elements contained in the list.
* @param E the type of elements contained in the list. The mutable list is invariant on its element type.
*/
public interface MutableList<E> : List<E>, MutableCollection<E> {
// Modification Operations
/**
* Adds the specified element to the end of this list.
*
* @return `true` because the list is always modified as the result of this operation.
*/
override fun add(element: E): Boolean
override fun remove(element: E): Boolean
// Bulk Modification Operations
/**
* Adds all of the elements of the specified collection to the end of this list.
*
* The elements are appended in the order they appear in the [elements] collection.
*
* @return `true` if the list was changed as the result of the operation.
*/
override fun addAll(elements: Collection<E>): Boolean
/**
* Inserts all of the elements in the specified collection [elements] into this list at the specified [index].
* Inserts all of the elements of the specified collection [elements] into this list at the specified [index].
*
* @return `true` if the list was changed as the result of the operation.
*/
public fun addAll(index: Int, elements: Collection<E>): Boolean
override fun removeAll(elements: Collection<E>): Boolean
override fun retainAll(elements: Collection<E>): Boolean
override fun clear(): Unit
@@ -102,6 +118,7 @@ public interface MutableList<E> : List<E>, MutableCollection<E> {
// List Iterators
override fun listIterator(): MutableListIterator<E>
override fun listIterator(index: Int): MutableListIterator<E>
// View
runtime/src/main/kotlin/kotlin/collections/Map.kt
+20 -8
View File
@@ -10,8 +10,9 @@ package kotlin.collections
* the value corresponding to each key. Map keys are unique; the map holds only one value for each key.
* Methods in this interface support only read-only access to the map; read-write access is supported through
* the [MutableMap] interface.
* @param K the type of map keys.
* @param V the type of map values.
* @param K the type of map keys. The map is invariant on its key type, as it
* can accept key as a parameter (of [containsKey] for example) and return it in [keys] set.
* @param V the type of map values. The map is covariant on its value type.
*/
public interface Map<K, out V> {
// Query Operations
@@ -42,17 +43,17 @@ public interface Map<K, out V> {
// Views
/**
* Returns a [Set] of all keys in this map.
* Returns a read-only [Set] of all keys in this map.
*/
public val keys: Set<K>
/**
* Returns a [Collection] of all values in this map. Note that this collection may contain duplicate values.
* Returns a read-only [Collection] of all values in this map. Note that this collection may contain duplicate values.
*/
public val values: Collection<V>
/**
* Returns a [Set] of all key/value pairs in this map.
* Returns a read-only [Set] of all key/value pairs in this map.
*/
public val entries: Set<Map.Entry<K, V>>
@@ -75,8 +76,8 @@ public interface Map<K, out V> {
/**
* A modifiable collection that holds pairs of objects (keys and values) and supports efficiently retrieving
* the value corresponding to each key. Map keys are unique; the map holds only one value for each key.
* @param K the type of map keys.
* @param V the type of map values.
* @param K the type of map keys. The map is invariant on its key type.
* @param V the type of map values. The mutable map is invariant on its value type.
*/
public interface MutableMap<K, V> : Map<K, V> {
// Modification Operations
@@ -106,14 +107,25 @@ public interface MutableMap<K, V> : Map<K, V> {
public fun clear(): Unit
// Views
/**
* Returns a [MutableSet] of all keys in this map.
*/
override val keys: MutableSet<K>
/**
* Returns a [MutableCollection] of all values in this map. Note that this collection may contain duplicate values.
*/
override val values: MutableCollection<V>
/**
* Returns a [MutableSet] of all key/value pairs in this map.
*/
override val entries: MutableSet<MutableMap.MutableEntry<K, V>>
/**
* Represents a key/value pair held by a [MutableMap].
*/
public interface MutableEntry<K,V>: Map.Entry<K, V> {
public interface MutableEntry<K, V> : Map.Entry<K, V> {
/**
* Changes the value associated with the key of this entry.
*
runtime/src/main/kotlin/kotlin/collections/MutableCollections.kt
+2 -2
View File
@@ -46,12 +46,12 @@ actual abstract class AbstractMutableMap<K, V> protected actual constructor() :
actual abstract override fun put(key: K, value: V): V?
/**
* Returns a [Set] of all keys in this map.
* Returns a [MutableSet] of all keys in this map.
*/
abstract override val keys: MutableSet<K>
/**
* Returns a [Collection] of all values in this map.
* Returns a [MutableCollection] of all values in this map. Note that this collection may contain duplicate values.
*/
abstract override val values: MutableCollection<V>
}
runtime/src/main/kotlin/kotlin/collections/Set.kt
+5 -2
View File
@@ -9,11 +9,12 @@ package kotlin.collections
* A generic unordered collection of elements that does not support duplicate elements.
* Methods in this interface support only read-only access to the set;
* read/write access is supported through the [MutableSet] interface.
* @param E the type of elements contained in the set.
* @param E the type of elements contained in the set. The set is covariant on its element type.
*/
public interface Set<out E> : Collection<E> {
// Query Operations
override val size: Int
override fun isEmpty(): Boolean
override fun contains(element: @UnsafeVariance E): Boolean
override fun iterator(): Iterator<E>
@@ -25,7 +26,7 @@ public interface Set<out E> : Collection<E> {
/**
* A generic unordered collection of elements that does not support duplicate elements, and supports
* adding and removing elements.
* @param E the type of elements contained in the set.
* @param E the type of elements contained in the set. The mutable set is invariant on its element type.
*/
public interface MutableSet<E> : Set<E>, MutableCollection<E> {
// Query Operations
@@ -33,10 +34,12 @@ public interface MutableSet<E> : Set<E>, MutableCollection<E> {
// Modification Operations
override fun add(element: E): Boolean
override fun remove(element: E): Boolean
// Bulk Modification Operations
override fun addAll(elements: Collection<E>): Boolean
override fun removeAll(elements: Collection<E>): Boolean
override fun retainAll(elements: Collection<E>): Boolean
override fun clear(): Unit
runtime/src/main/kotlin/kotlin/coroutines/intrinsics/IntrinsicsNative.kt
+12 -2
View File
@@ -13,7 +13,12 @@ import kotlin.native.internal.*
* Starts unintercepted coroutine without receiver and with result type [T] and executes it until its first suspension.
* Returns the result of the coroutine or throws its exception if it does not suspend or [COROUTINE_SUSPENDED] if it suspends.
* In the later case, the [completion] continuation is invoked when coroutine completes with result or exception.
* This function is designed to be used from inside of [suspendCoroutineOrReturn] to resume the execution of suspended
*
* The coroutine is started directly in the invoker's thread without going through the [ContinuationInterceptor] that might
* be present in the completion's [CoroutineContext]. It is invoker's responsibility to ensure that the proper invocation
* context is established.
*
* This function is designed to be used from inside of [suspendCoroutineUninterceptedOrReturn] to resume the execution of suspended
* coroutine using a reference to the suspending function.
*/
@Suppress("UNCHECKED_CAST")
@@ -26,7 +31,12 @@ public actual inline fun <T> (suspend () -> T).startCoroutineUninterceptedOrRetu
* Starts unintercepted coroutine with receiver type [R] and result type [T] and executes it until its first suspension.
* Returns the result of the coroutine or throws its exception if it does not suspend or [COROUTINE_SUSPENDED] if it suspends.
* In the later case, the [completion] continuation is invoked when coroutine completes with result or exception.
* This function is designed to be used from inside of [suspendCoroutineOrReturn] to resume the execution of suspended
*
* The coroutine is started directly in the invoker's thread without going through the [ContinuationInterceptor] that might
* be present in the completion's [CoroutineContext]. It is invoker's responsibility to ensure that the proper invocation
* context is established.
*
* This function is designed to be used from inside of [suspendCoroutineUninterceptedOrReturn] to resume the execution of suspended
* coroutine using a reference to the suspending function.
*/
@Suppress("UNCHECKED_CAST")
runtime/src/main/kotlin/kotlin/io/Console.kt
+4 -4
View File
@@ -14,23 +14,23 @@ public actual fun print(message: Any?) {
print(message.toString())
}
/** Prints the given [message] and newline to the standard output stream. */
/** Prints the given [message] and the line separator to the standard output stream. */
@SymbolName("Kotlin_io_Console_println")
external public fun println(message: String)
/** Prints the given [message] and newline to the standard output stream. */
/** Prints the given [message] and the line separator to the standard output stream. */
public actual fun println(message: Any?) {
println(message.toString())
}
/** Prints newline to the standard output stream. */
/** Prints the line separator to the standard output stream. */
@SymbolName("Kotlin_io_Console_println0")
external public actual fun println()
/**
* Reads a line of input from the standard input stream.
*
* @return the line read or `null` if the input is empty.
* @return the line read or `null` if the input stream is redirected to a file and the end of file has been reached.
*/
@SymbolName("Kotlin_io_Console_readLine")
external public fun readLine(): String?
runtime/src/main/kotlin/kotlin/math/math.kt
+12 -12
View File
@@ -201,14 +201,14 @@ external public actual fun exp(x: Double): Double
/**
* Computes `exp(x) - 1`.
*
* This actual function can be implemented to produce more precise result for [x] near zero.
* This function can be implemented to produce more precise result for [x] near zero.
*
* Special cases:
* - `expm1(NaN)` is `NaN`
* - `expm1(+Inf)` is `+Inf`
* - `expm1(-Inf)` is `-1.0`
*
* @see [exp] actual function.
* @see [exp] function.
*/
@SinceKotlin("1.2")
@SymbolName("Kotlin_math_expm1")
@@ -224,7 +224,7 @@ external public actual fun expm1(x: Double): Double
* - `log(+Inf, b)` is `+Inf` for `b > 1` and `-Inf` for `b < 1`
* - `log(0.0, b)` is `-Inf` for `b > 1` and `+Inf` for `b > 1`
*
* See also logarithm actual functions for common fixed bases: [ln], [log10] and [log2].
* See also logarithm functions for common fixed bases: [ln], [log10] and [log2].
*/
@SinceKotlin("1.2")
public actual fun log(x: Double, base: Double): Double {
@@ -266,7 +266,7 @@ external public actual fun log2(x: Double): Double
/**
* Computes `ln(x + 1)`.
*
* This actual function can be implemented to produce more precise result for [x] near zero.
* This function can be implemented to produce more precise result for [x] near zero.
*
* Special cases:
* - `ln1p(NaN)` is `NaN`
@@ -274,8 +274,8 @@ external public actual fun log2(x: Double): Double
* - `ln1p(-1.0)` is `-Inf`
* - `ln1p(+Inf)` is `+Inf`
*
* @see [ln] actual function
* @see [expm1] actual function
* @see [ln] function
* @see [expm1] function
*/
@SinceKotlin("1.2")
@SymbolName("Kotlin_math_ln1p")
@@ -750,14 +750,14 @@ external public actual fun exp(x: Float): Float
/**
* Computes `exp(x) - 1`.
*
* This actual function can be implemented to produce more precise result for [x] near zero.
* This function can be implemented to produce more precise result for [x] near zero.
*
* Special cases:
* - `expm1(NaN)` is `NaN`
* - `expm1(+Inf)` is `+Inf`
* - `expm1(-Inf)` is `-1.0`
*
* @see [exp] actual function.
* @see [exp] function.
*/
@SinceKotlin("1.2")
@SymbolName("Kotlin_math_expm1f")
@@ -773,7 +773,7 @@ external public actual fun expm1(x: Float): Float
* - `log(+Inf, b)` is `+Inf` for `b > 1` and `-Inf` for `b < 1`
* - `log(0.0, b)` is `-Inf` for `b > 1` and `+Inf` for `b > 1`
*
* See also logarithm actual functions for common fixed bases: [ln], [log10] and [log2].
* See also logarithm functions for common fixed bases: [ln], [log10] and [log2].
*/
@SinceKotlin("1.2")
public actual fun log(x: Float, base: Float): Float {
@@ -815,7 +815,7 @@ external public actual fun log2(x: Float): Float
/**
* Computes `ln(a + 1)`.
*
* This actual function can be implemented to produce more precise result for [x] near zero.
* This function can be implemented to produce more precise result for [x] near zero.
*
* Special cases:
* - `ln1p(NaN)` is `NaN`
@@ -823,8 +823,8 @@ external public actual fun log2(x: Float): Float
* - `ln1p(-1.0)` is `-Inf`
* - `ln1p(+Inf)` is `+Inf`
*
* @see [ln] actual function
* @see [expm1] actual function
* @see [ln] function
* @see [expm1] function
*/
@SinceKotlin("1.2")
@SymbolName("Kotlin_math_ln1pf")
runtime/src/main/kotlin/kotlin/native/internal/Strings.kt
+4 -6
View File
@@ -84,7 +84,7 @@ public actual fun String.replaceFirst(oldValue: String, newValue: String, ignore
* Returns a copy of this string having its first letter lowercased, or the original string,
* if it's empty or already starts with a lower case letter.
*
* @sample samples.text.Strings.decaptialize
* @sample samples.text.Strings.decapitalize
*/
public actual fun String.decapitalize(): String {
return if (isNotEmpty() && this[0].isUpperCase()) substring(0, 1).toLowerCase() + substring(1) else this
@@ -106,9 +106,7 @@ public actual inline fun String.substring(startIndex: Int, endIndex: Int): Strin
subSequence(startIndex, endIndex) as String
/**
* Returns the substring of this string starting at the [startIndex].
*
* @param startIndex the start index (inclusive).
* Returns a substring of this string that starts at the specified [startIndex] and continues to the end of the string.
*/
@kotlin.internal.InlineOnly
public actual inline fun String.substring(startIndex: Int): String =
@@ -171,7 +169,7 @@ external public actual fun String.toUpperCase(): String
external public actual inline fun String.toLowerCase(): String
/**
* Returns an array containing all characters of the specified string.
* Returns a new character array containing the characters from this string.
*/
@SymbolName("Kotlin_String_toCharArray")
external public fun String.toCharArray() : CharArray
@@ -180,7 +178,7 @@ external public fun String.toCharArray() : CharArray
* Returns a copy of this string having its first letter uppercased, or the original string,
* if it's empty or already starts with an upper case letter.
*
* @sample samples.text.Strings.captialize
* @sample samples.text.Strings.capitalize
*/
public actual fun String.capitalize(): String {
return if (isNotEmpty() && this[0].isLowerCase()) substring(0, 1).toUpperCase() + substring(1) else this
runtime/src/main/kotlin/kotlin/ranges/Ranges.kt
+1 -1
View File
@@ -114,7 +114,7 @@ private class ClosedFloatRange (
}
/**
* Creates a range from this [Float] value to the specified [other] value.
* Creates a range from this [Float] value to the specified [that] value.
*
* Numbers are compared with the ends of this range according to IEEE-754.
*/
runtime/src/main/kotlin/kotlin/text/Regex.kt
+26 -10
View File
@@ -28,6 +28,7 @@ actual public enum class RegexOption(override val value: Int, override val mask:
/**
* Enables multiline mode.
*
* In multiline mode the expressions `^` and `$` match just after or just before,
* respectively, a line terminator or the end of the input sequence.
*/
@@ -35,6 +36,7 @@ actual public enum class RegexOption(override val value: Int, override val mask:
/**
* Enables literal parsing of the pattern.
*
* Metacharacters or escape sequences in the input sequence will be given no special meaning.
*/
LITERAL(Pattern.LITERAL),
@@ -64,9 +66,8 @@ actual public enum class RegexOption(override val value: Int, override val mask:
actual data class MatchGroup(actual val value: String, val range: IntRange)
/**
* Represents an immutable regular expression.
*
* For pattern syntax reference see [Pattern]
* Represents a compiled regular expression.
* Provides functions to match strings in text with a pattern, replace the found occurrences and split text around matches.
*/
actual public class Regex internal constructor(internal val nativePattern: Pattern) {
@@ -94,15 +95,21 @@ actual public class Regex internal constructor(internal val nativePattern: Patte
actual val options: Set<RegexOption> = fromInt(nativePattern.flags)
actual companion object {
/** Returns a literal regex for the specified [literal] string. */
/**
* Returns a regular expression that matches the specified [literal] string literally.
* No characters of that string will have special meaning when searching for an occurrence of the regular expression.
*/
actual fun fromLiteral(literal: String): Regex = Regex(literal, RegexOption.LITERAL)
/** Returns a literal pattern for the specified [literal] string. */
/**
* Returns a regular expression pattern string that matches the specified [literal] string literally.
* No characters of that string will have special meaning when searching for an occurrence of the regular expression.
*/
actual fun escape(literal: String): String = Pattern.quote(literal)
/**
* Returns a replacement string for the given one that has all backslashes
* and dollar signs escaped.
* Returns a literal replacement expression for the specified [literal] string.
* No characters of that string will have special meaning when it is used as a replacement string in [Regex.replace] function.
*/
actual fun escapeReplacement(literal: String): String {
if (!literal.contains('\\') && !literal.contains('$'))
@@ -248,7 +255,7 @@ actual public class Regex internal constructor(internal val nativePattern: Patte
/**
* Replaces the first occurrence of this regular expression in the specified [input] string with specified [replacement] expression.
*
* @param replacement A replacement expression that can include substitutions. See [Matcher.appendReplacement] for details.
* @param replacement A replacement expression that can include substitutions.
*/
actual fun replaceFirst(input: CharSequence, replacement: String): String
= replaceFirst(input) { match -> processReplacement(match, replacement) }
@@ -282,7 +289,12 @@ actual public class Regex internal constructor(internal val nativePattern: Patte
return result
}
/** Returns the string representation of this regular expression, namely the [pattern] of this regular expression. */
/**
* Returns the string representation of this regular expression, namely the [pattern] of this regular expression.
*
* Note that another regular expression constructed from the same pattern string may have different [options]
* and may match strings differently.
*/
override fun toString(): String = nativePattern.toString()
// Native specific =================================================================================================
@@ -291,7 +303,11 @@ actual public class Regex internal constructor(internal val nativePattern: Patte
/** Indicates whether the regular expression can find at least one match in the specified [input] starting with [index]. */
fun containsMatchIn(input: CharSequence, index: Int): Boolean = find(input, index) != null
/** Replaces the first occurrence of this regular expression in the specified [input] string with specified using specified transfromation */
/**
* Replaces the first occurrence of this regular expression in the specified [input] string with the result of calling
* the given function [transform] that takes a [MatchResult] representing the occurrence and returns a string to be used as a
* replacement for that occurrence.
*/
fun replaceFirst(input: CharSequence, transform: (MatchResult) -> CharSequence): String {
val match = find(input) ?: return input.toString()
val length = input.length
runtime/src/main/kotlin/kotlin/text/StringNumberConversions.kt
+12
View File
@@ -9,6 +9,8 @@ import kotlin.native.internal.FloatingPointParser
/**
* Returns a string representation of this [Byte] value in the specified [radix].
*
* @throws IllegalArgumentException when [radix] is not a valid radix for number to string conversion.
*/
@SinceKotlin("1.1")
@kotlin.internal.InlineOnly
@@ -16,6 +18,8 @@ public actual inline fun Byte.toString(radix: Int): String = this.toInt().toStri
/**
* Returns a string representation of this [Short] value in the specified [radix].
*
* @throws IllegalArgumentException when [radix] is not a valid radix for number to string conversion.
*/
@SinceKotlin("1.1")
@kotlin.internal.InlineOnly
@@ -27,6 +31,8 @@ external internal fun intToString(value: Int, radix: Int): String
/**
* Returns a string representation of this [Int] value in the specified [radix].
*
* @throws IllegalArgumentException when [radix] is not a valid radix for number to string conversion.
*/
@SinceKotlin("1.1")
@kotlin.internal.InlineOnly
@@ -38,6 +44,8 @@ external internal fun longToString(value: Long, radix: Int): String
/**
* Returns a string representation of this [Long] value in the specified [radix].
*
* @throws IllegalArgumentException when [radix] is not a valid radix for number to string conversion.
*/
@SinceKotlin("1.1")
@kotlin.internal.InlineOnly
@@ -59,6 +67,7 @@ public actual inline fun String.toByte(): Byte = toByteOrNull() ?: throw NumberF
/**
* Parses the string as a signed [Byte] number and returns the result.
* @throws NumberFormatException if the string is not a valid representation of a number.
* @throws IllegalArgumentException when [radix] is not a valid radix for string to number conversion.
*/
@SinceKotlin("1.1")
@kotlin.internal.InlineOnly
@@ -74,6 +83,7 @@ public actual inline fun String.toShort(): Short = toShortOrNull() ?: throw Numb
/**
* Parses the string as a [Short] number and returns the result.
* @throws NumberFormatException if the string is not a valid representation of a number.
* @throws IllegalArgumentException when [radix] is not a valid radix for string to number conversion.
*/
@SinceKotlin("1.1")
@kotlin.internal.InlineOnly
@@ -89,6 +99,7 @@ public actual inline fun String.toInt(): Int = toIntOrNull() ?: throw NumberForm
/**
* Parses the string as an [Int] number and returns the result.
* @throws NumberFormatException if the string is not a valid representation of a number.
* @throws IllegalArgumentException when [radix] is not a valid radix for string to number conversion.
*/
@SinceKotlin("1.1")
@kotlin.internal.InlineOnly
@@ -104,6 +115,7 @@ public actual inline fun String.toLong(): Long = toLongOrNull() ?: throw NumberF
/**
* Parses the string as a [Long] number and returns the result.
* @throws NumberFormatException if the string is not a valid representation of a number.
* @throws IllegalArgumentException when [radix] is not a valid radix for string to number conversion.
*/
@SinceKotlin("1.1")
@kotlin.internal.InlineOnly