diff --git a/generators/builtins/common.kt b/generators/builtins/common.kt index 94a8dd96e92..211673daead 100644 --- a/generators/builtins/common.kt +++ b/generators/builtins/common.kt @@ -48,6 +48,7 @@ enum class UnsignedType { val asSigned: PrimitiveType = PrimitiveType.valueOf(name.substring(1)) val byteSize = (1 shl ordinal) + val bitSize = byteSize * 8 val mask = "0x${List(byteSize) { "FF" }.chunked(2).joinToString("_") { it.joinToString("") }}" } diff --git a/generators/builtins/unsignedTypes.kt b/generators/builtins/unsignedTypes.kt index 27b23c016f5..9db3b685927 100644 --- a/generators/builtins/unsignedTypes.kt +++ b/generators/builtins/unsignedTypes.kt @@ -199,9 +199,37 @@ class UnsignedTypeGenerator(val type: UnsignedType, out: PrintWriter) : BuiltIns out.println() } + private fun lsb(count: Int) = "least significant $count bits" + private fun msb(count: Int) = "most significant $count bits" + private fun generateMemberConversions() { for (otherType in UnsignedType.values()) { val signed = otherType.asSigned.capitalized + + out.println(" /**\n * Converts this [$className] value to [$signed].\n *") + when { + otherType < type -> { + out.println(" * If this value is less than or equals to [$signed.MAX_VALUE], the resulting `$signed` value represents") + out.println(" * the same numerical value as this `$className`.") + out.println(" *") + out.println(" * The resulting `$signed` value is represented by the ${lsb(otherType.bitSize)} of this `$className` value.") + out.println(" * Note that the resulting `$signed` value may be negative.") + } + otherType == type -> { + out.println(" * If this value is less than or equals to [$signed.MAX_VALUE], the resulting `$signed` value represents") + out.println(" * the same numerical value as this `$className`. Otherwise the result is negative.") + out.println(" *") + out.println(" * The resulting `$signed` value has the same binary representation as this `$className` value.") + } + else -> { + out.println(" * The resulting `$signed` value represents the same numerical value as this `$className`.") + out.println(" *") + out.println(" * The ${lsb(type.bitSize)} of the resulting `$signed` value are the same as the binary representation of this `$className` value,") + out.println(" * whereas the ${msb(otherType.bitSize - type.bitSize)} are filled with zeros.") + } + } + out.println(" */") + out.println(" @kotlin.internal.InlineOnly") out.print(" public inline fun to$signed(): $signed = ") out.println(when { @@ -214,6 +242,28 @@ class UnsignedTypeGenerator(val type: UnsignedType, out: PrintWriter) : BuiltIns for (otherType in UnsignedType.values()) { val name = otherType.capitalized + + if (type == otherType) + out.println(" /** Returns this value. */") + else { + out.println(" /**\n * Converts this [$className] value to [$name].\n *") + when { + otherType < type -> { + out.println(" * If this value is less than or equals to [$name.MAX_VALUE], the resulting `$name` value represents") + out.println(" * the same numerical value as this `$className`.") + out.println(" *") + out.println(" * The resulting `$name` value is represented by the ${lsb(otherType.bitSize)} of this `$className` value.") + } + else -> { + out.println(" * The resulting `$name` value represents the same numerical value as this `$className`.") + out.println(" *") + out.println(" * The ${lsb(type.bitSize)} of the resulting `$name` value are the same as the binary representation of this `$className` value,") + out.println(" * whereas the ${msb(otherType.bitSize - type.bitSize)} are filled with zeros.") + } + } + out.println(" */") + } + out.println(" @kotlin.internal.InlineOnly") out.print(" public inline fun to$name(): $name = ") out.println(when { @@ -228,6 +278,17 @@ class UnsignedTypeGenerator(val type: UnsignedType, out: PrintWriter) : BuiltIns private fun generateFloatingConversions() { for (otherType in PrimitiveType.floatingPoint) { val otherName = otherType.capitalized + + out.println(" /**\n * Converts this [$className] value to [$otherName].\n *") + if (type == UnsignedType.ULONG || type == UnsignedType.UINT && otherType == PrimitiveType.FLOAT) { + out.println(" * The resulting value is the closest `$otherName` to this `$className` value.") + out.println(" * In case when this `$className` value is exactly between two `$otherName`s,") + out.println(" * the one with zero at least significant bit of mantissa is selected.") + } else { + out.println(" * The resulting `$otherName` value represents the same numerical value as this `$className`.") + } + out.println(" */") + out.println(" @kotlin.internal.InlineOnly") out.print(" public inline fun to$otherName(): $otherName = ") when (type) { @@ -244,6 +305,28 @@ class UnsignedTypeGenerator(val type: UnsignedType, out: PrintWriter) : BuiltIns for (otherType in UnsignedType.values()) { val otherSigned = otherType.asSigned.capitalized val thisSigned = type.asSigned.capitalized + + out.println("/**\n * Converts this [$otherSigned] value to [$className].\n *") + when { + otherType < type -> { + out.println(" * If this value is positive, the resulting `$className` value represents the same numerical value as this `$otherSigned`.") + out.println(" *") + out.println(" * The ${lsb(otherType.bitSize)} of the resulting `$className` value are the same as the binary representation of this `$otherSigned` value,") + out.println(" * whereas the ${msb(type.bitSize - otherType.bitSize)} are filled with the sign bit of this value.") + } + otherType == type -> { + out.println(" * If this value is positive, the resulting `$className` value represents the same numerical value as this `$otherSigned`.") + out.println(" *") + out.println(" * The resulting `$className` value has the same binary representation as this `$otherSigned` value.") + } + else -> { + out.println(" * If this value is positive and less than or equals to [$className.MAX_VALUE], the resulting `$className` value represents") + out.println(" * the same numerical value as this `$otherSigned`.") + out.println(" *") + out.println(" * The resulting `$className` value is represented by the ${lsb(type.bitSize)} of this `$otherSigned` value.") + } + } + out.println(" */") out.println("@SinceKotlin(\"1.3\")") out.println("@ExperimentalUnsignedTypes") out.println("@kotlin.internal.InlineOnly") @@ -257,6 +340,17 @@ class UnsignedTypeGenerator(val type: UnsignedType, out: PrintWriter) : BuiltIns for (otherType in PrimitiveType.floatingPoint) { val otherName = otherType.capitalized + + out.println( + """ + /** + * Converts this [$otherName] value to [$className]. + * + * The fractional part, if any, is rounded down. + * Returns zero if this `$otherName` value is negative or `NaN`, [$className.MAX_VALUE] if it's bigger than `$className.MAX_VALUE`. + */ + """.trimIndent() + ) out.println("@SinceKotlin(\"1.3\")") out.println("@ExperimentalUnsignedTypes") out.println("@kotlin.internal.InlineOnly") diff --git a/libraries/stdlib/unsigned/src/kotlin/UByte.kt b/libraries/stdlib/unsigned/src/kotlin/UByte.kt index af8c8cbad19..37c3fd6bc4e 100644 --- a/libraries/stdlib/unsigned/src/kotlin/UByte.kt +++ b/libraries/stdlib/unsigned/src/kotlin/UByte.kt @@ -158,26 +158,93 @@ public inline class UByte @PublishedApi internal constructor(@PublishedApi inter @kotlin.internal.InlineOnly public inline fun inv(): UByte = UByte(data.inv()) + /** + * Converts this [UByte] value to [Byte]. + * + * If this value is less than or equals to [Byte.MAX_VALUE], the resulting `Byte` value represents + * the same numerical value as this `UByte`. Otherwise the result is negative. + * + * The resulting `Byte` value has the same binary representation as this `UByte` value. + */ @kotlin.internal.InlineOnly public inline fun toByte(): Byte = data + /** + * Converts this [UByte] value to [Short]. + * + * The resulting `Short` value represents the same numerical value as this `UByte`. + * + * The least significant 8 bits of the resulting `Short` value are the same as the binary representation of this `UByte` value, + * whereas the most significant 8 bits are filled with zeros. + */ @kotlin.internal.InlineOnly public inline fun toShort(): Short = data.toShort() and 0xFF + /** + * Converts this [UByte] value to [Int]. + * + * The resulting `Int` value represents the same numerical value as this `UByte`. + * + * The least significant 8 bits of the resulting `Int` value are the same as the binary representation of this `UByte` value, + * whereas the most significant 24 bits are filled with zeros. + */ @kotlin.internal.InlineOnly public inline fun toInt(): Int = data.toInt() and 0xFF + /** + * Converts this [UByte] value to [Long]. + * + * The resulting `Long` value represents the same numerical value as this `UByte`. + * + * The least significant 8 bits of the resulting `Long` value are the same as the binary representation of this `UByte` value, + * whereas the most significant 56 bits are filled with zeros. + */ @kotlin.internal.InlineOnly public inline fun toLong(): Long = data.toLong() and 0xFF + /** Returns this value. */ @kotlin.internal.InlineOnly public inline fun toUByte(): UByte = this + /** + * Converts this [UByte] value to [UShort]. + * + * The resulting `UShort` value represents the same numerical value as this `UByte`. + * + * The least significant 8 bits of the resulting `UShort` value are the same as the binary representation of this `UByte` value, + * whereas the most significant 8 bits are filled with zeros. + */ @kotlin.internal.InlineOnly public inline fun toUShort(): UShort = UShort(data.toShort() and 0xFF) + /** + * Converts this [UByte] value to [UInt]. + * + * The resulting `UInt` value represents the same numerical value as this `UByte`. + * + * The least significant 8 bits of the resulting `UInt` value are the same as the binary representation of this `UByte` value, + * whereas the most significant 24 bits are filled with zeros. + */ @kotlin.internal.InlineOnly public inline fun toUInt(): UInt = UInt(data.toInt() and 0xFF) + /** + * Converts this [UByte] value to [ULong]. + * + * The resulting `ULong` value represents the same numerical value as this `UByte`. + * + * The least significant 8 bits of the resulting `ULong` value are the same as the binary representation of this `UByte` value, + * whereas the most significant 56 bits are filled with zeros. + */ @kotlin.internal.InlineOnly public inline fun toULong(): ULong = ULong(data.toLong() and 0xFF) + /** + * Converts this [UByte] value to [Float]. + * + * The resulting `Float` value represents the same numerical value as this `UByte`. + */ @kotlin.internal.InlineOnly public inline fun toFloat(): Float = this.toInt().toFloat() + /** + * Converts this [UByte] value to [Double]. + * + * The resulting `Double` value represents the same numerical value as this `UByte`. + */ @kotlin.internal.InlineOnly public inline fun toDouble(): Double = this.toInt().toDouble() @@ -185,27 +252,70 @@ public inline class UByte @PublishedApi internal constructor(@PublishedApi inter } +/** + * Converts this [Byte] value to [UByte]. + * + * If this value is positive, the resulting `UByte` value represents the same numerical value as this `Byte`. + * + * The resulting `UByte` value has the same binary representation as this `Byte` value. + */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @kotlin.internal.InlineOnly public inline fun Byte.toUByte(): UByte = UByte(this) +/** + * Converts this [Short] value to [UByte]. + * + * If this value is positive and less than or equals to [UByte.MAX_VALUE], the resulting `UByte` value represents + * the same numerical value as this `Short`. + * + * The resulting `UByte` value is represented by the least significant 8 bits of this `Short` value. + */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @kotlin.internal.InlineOnly public inline fun Short.toUByte(): UByte = UByte(this.toByte()) +/** + * Converts this [Int] value to [UByte]. + * + * If this value is positive and less than or equals to [UByte.MAX_VALUE], the resulting `UByte` value represents + * the same numerical value as this `Int`. + * + * The resulting `UByte` value is represented by the least significant 8 bits of this `Int` value. + */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @kotlin.internal.InlineOnly public inline fun Int.toUByte(): UByte = UByte(this.toByte()) +/** + * Converts this [Long] value to [UByte]. + * + * If this value is positive and less than or equals to [UByte.MAX_VALUE], the resulting `UByte` value represents + * the same numerical value as this `Long`. + * + * The resulting `UByte` value is represented by the least significant 8 bits of this `Long` value. + */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @kotlin.internal.InlineOnly public inline fun Long.toUByte(): UByte = UByte(this.toByte()) +/** + * Converts this [Float] value to [UByte]. + * + * The fractional part, if any, is rounded down. + * Returns zero if this `Float` value is negative or `NaN`, [UByte.MAX_VALUE] if it's bigger than `UByte.MAX_VALUE`. + */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @kotlin.internal.InlineOnly public inline fun Float.toUByte(): UByte = doubleToUByte(this.toDouble()) +/** + * Converts this [Double] value to [UByte]. + * + * The fractional part, if any, is rounded down. + * Returns zero if this `Double` value is negative or `NaN`, [UByte.MAX_VALUE] if it's bigger than `UByte.MAX_VALUE`. + */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @kotlin.internal.InlineOnly diff --git a/libraries/stdlib/unsigned/src/kotlin/UInt.kt b/libraries/stdlib/unsigned/src/kotlin/UInt.kt index a82edb94549..a0357bf6758 100644 --- a/libraries/stdlib/unsigned/src/kotlin/UInt.kt +++ b/libraries/stdlib/unsigned/src/kotlin/UInt.kt @@ -164,26 +164,97 @@ public inline class UInt @PublishedApi internal constructor(@PublishedApi intern @kotlin.internal.InlineOnly public inline fun inv(): UInt = UInt(data.inv()) + /** + * Converts this [UInt] value to [Byte]. + * + * If this value is less than or equals to [Byte.MAX_VALUE], the resulting `Byte` value represents + * the same numerical value as this `UInt`. + * + * The resulting `Byte` value is represented by the least significant 8 bits of this `UInt` value. + * Note that the resulting `Byte` value may be negative. + */ @kotlin.internal.InlineOnly public inline fun toByte(): Byte = data.toByte() + /** + * Converts this [UInt] value to [Short]. + * + * If this value is less than or equals to [Short.MAX_VALUE], the resulting `Short` value represents + * the same numerical value as this `UInt`. + * + * The resulting `Short` value is represented by the least significant 16 bits of this `UInt` value. + * Note that the resulting `Short` value may be negative. + */ @kotlin.internal.InlineOnly public inline fun toShort(): Short = data.toShort() + /** + * Converts this [UInt] value to [Int]. + * + * If this value is less than or equals to [Int.MAX_VALUE], the resulting `Int` value represents + * the same numerical value as this `UInt`. Otherwise the result is negative. + * + * The resulting `Int` value has the same binary representation as this `UInt` value. + */ @kotlin.internal.InlineOnly public inline fun toInt(): Int = data + /** + * Converts this [UInt] value to [Long]. + * + * The resulting `Long` value represents the same numerical value as this `UInt`. + * + * The least significant 32 bits of the resulting `Long` value are the same as the binary representation of this `UInt` value, + * whereas the most significant 32 bits are filled with zeros. + */ @kotlin.internal.InlineOnly public inline fun toLong(): Long = data.toLong() and 0xFFFF_FFFF + /** + * Converts this [UInt] value to [UByte]. + * + * If this value is less than or equals to [UByte.MAX_VALUE], the resulting `UByte` value represents + * the same numerical value as this `UInt`. + * + * The resulting `UByte` value is represented by the least significant 8 bits of this `UInt` value. + */ @kotlin.internal.InlineOnly public inline fun toUByte(): UByte = data.toUByte() + /** + * Converts this [UInt] value to [UShort]. + * + * If this value is less than or equals to [UShort.MAX_VALUE], the resulting `UShort` value represents + * the same numerical value as this `UInt`. + * + * The resulting `UShort` value is represented by the least significant 16 bits of this `UInt` value. + */ @kotlin.internal.InlineOnly public inline fun toUShort(): UShort = data.toUShort() + /** Returns this value. */ @kotlin.internal.InlineOnly public inline fun toUInt(): UInt = this + /** + * Converts this [UInt] value to [ULong]. + * + * The resulting `ULong` value represents the same numerical value as this `UInt`. + * + * The least significant 32 bits of the resulting `ULong` value are the same as the binary representation of this `UInt` value, + * whereas the most significant 32 bits are filled with zeros. + */ @kotlin.internal.InlineOnly public inline fun toULong(): ULong = ULong(data.toLong() and 0xFFFF_FFFF) + /** + * Converts this [UInt] value to [Float]. + * + * The resulting value is the closest `Float` to this `UInt` value. + * In case when this `UInt` value is exactly between two `Float`s, + * the one with zero at least significant bit of mantissa is selected. + */ @kotlin.internal.InlineOnly public inline fun toFloat(): Float = this.toDouble().toFloat() + /** + * Converts this [UInt] value to [Double]. + * + * The resulting `Double` value represents the same numerical value as this `UInt`. + */ @kotlin.internal.InlineOnly public inline fun toDouble(): Double = uintToDouble(data) @@ -191,27 +262,70 @@ public inline class UInt @PublishedApi internal constructor(@PublishedApi intern } +/** + * Converts this [Byte] value to [UInt]. + * + * If this value is positive, the resulting `UInt` value represents the same numerical value as this `Byte`. + * + * The least significant 8 bits of the resulting `UInt` value are the same as the binary representation of this `Byte` value, + * whereas the most significant 24 bits are filled with the sign bit of this value. + */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @kotlin.internal.InlineOnly public inline fun Byte.toUInt(): UInt = UInt(this.toInt()) +/** + * Converts this [Short] value to [UInt]. + * + * If this value is positive, the resulting `UInt` value represents the same numerical value as this `Short`. + * + * The least significant 16 bits of the resulting `UInt` value are the same as the binary representation of this `Short` value, + * whereas the most significant 16 bits are filled with the sign bit of this value. + */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @kotlin.internal.InlineOnly public inline fun Short.toUInt(): UInt = UInt(this.toInt()) +/** + * Converts this [Int] value to [UInt]. + * + * If this value is positive, the resulting `UInt` value represents the same numerical value as this `Int`. + * + * The resulting `UInt` value has the same binary representation as this `Int` value. + */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @kotlin.internal.InlineOnly public inline fun Int.toUInt(): UInt = UInt(this) +/** + * Converts this [Long] value to [UInt]. + * + * If this value is positive and less than or equals to [UInt.MAX_VALUE], the resulting `UInt` value represents + * the same numerical value as this `Long`. + * + * The resulting `UInt` value is represented by the least significant 32 bits of this `Long` value. + */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @kotlin.internal.InlineOnly public inline fun Long.toUInt(): UInt = UInt(this.toInt()) +/** + * Converts this [Float] value to [UInt]. + * + * The fractional part, if any, is rounded down. + * Returns zero if this `Float` value is negative or `NaN`, [UInt.MAX_VALUE] if it's bigger than `UInt.MAX_VALUE`. + */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @kotlin.internal.InlineOnly public inline fun Float.toUInt(): UInt = doubleToUInt(this.toDouble()) +/** + * Converts this [Double] value to [UInt]. + * + * The fractional part, if any, is rounded down. + * Returns zero if this `Double` value is negative or `NaN`, [UInt.MAX_VALUE] if it's bigger than `UInt.MAX_VALUE`. + */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @kotlin.internal.InlineOnly diff --git a/libraries/stdlib/unsigned/src/kotlin/ULong.kt b/libraries/stdlib/unsigned/src/kotlin/ULong.kt index fee6fe66539..445d116520f 100644 --- a/libraries/stdlib/unsigned/src/kotlin/ULong.kt +++ b/libraries/stdlib/unsigned/src/kotlin/ULong.kt @@ -164,26 +164,100 @@ public inline class ULong @PublishedApi internal constructor(@PublishedApi inter @kotlin.internal.InlineOnly public inline fun inv(): ULong = ULong(data.inv()) + /** + * Converts this [ULong] value to [Byte]. + * + * If this value is less than or equals to [Byte.MAX_VALUE], the resulting `Byte` value represents + * the same numerical value as this `ULong`. + * + * The resulting `Byte` value is represented by the least significant 8 bits of this `ULong` value. + * Note that the resulting `Byte` value may be negative. + */ @kotlin.internal.InlineOnly public inline fun toByte(): Byte = data.toByte() + /** + * Converts this [ULong] value to [Short]. + * + * If this value is less than or equals to [Short.MAX_VALUE], the resulting `Short` value represents + * the same numerical value as this `ULong`. + * + * The resulting `Short` value is represented by the least significant 16 bits of this `ULong` value. + * Note that the resulting `Short` value may be negative. + */ @kotlin.internal.InlineOnly public inline fun toShort(): Short = data.toShort() + /** + * Converts this [ULong] value to [Int]. + * + * If this value is less than or equals to [Int.MAX_VALUE], the resulting `Int` value represents + * the same numerical value as this `ULong`. + * + * The resulting `Int` value is represented by the least significant 32 bits of this `ULong` value. + * Note that the resulting `Int` value may be negative. + */ @kotlin.internal.InlineOnly public inline fun toInt(): Int = data.toInt() + /** + * Converts this [ULong] value to [Long]. + * + * If this value is less than or equals to [Long.MAX_VALUE], the resulting `Long` value represents + * the same numerical value as this `ULong`. Otherwise the result is negative. + * + * The resulting `Long` value has the same binary representation as this `ULong` value. + */ @kotlin.internal.InlineOnly public inline fun toLong(): Long = data + /** + * Converts this [ULong] value to [UByte]. + * + * If this value is less than or equals to [UByte.MAX_VALUE], the resulting `UByte` value represents + * the same numerical value as this `ULong`. + * + * The resulting `UByte` value is represented by the least significant 8 bits of this `ULong` value. + */ @kotlin.internal.InlineOnly public inline fun toUByte(): UByte = data.toUByte() + /** + * Converts this [ULong] value to [UShort]. + * + * If this value is less than or equals to [UShort.MAX_VALUE], the resulting `UShort` value represents + * the same numerical value as this `ULong`. + * + * The resulting `UShort` value is represented by the least significant 16 bits of this `ULong` value. + */ @kotlin.internal.InlineOnly public inline fun toUShort(): UShort = data.toUShort() + /** + * Converts this [ULong] value to [UInt]. + * + * If this value is less than or equals to [UInt.MAX_VALUE], the resulting `UInt` value represents + * the same numerical value as this `ULong`. + * + * The resulting `UInt` value is represented by the least significant 32 bits of this `ULong` value. + */ @kotlin.internal.InlineOnly public inline fun toUInt(): UInt = data.toUInt() + /** Returns this value. */ @kotlin.internal.InlineOnly public inline fun toULong(): ULong = this + /** + * Converts this [ULong] value to [Float]. + * + * The resulting value is the closest `Float` to this `ULong` value. + * In case when this `ULong` value is exactly between two `Float`s, + * the one with zero at least significant bit of mantissa is selected. + */ @kotlin.internal.InlineOnly public inline fun toFloat(): Float = this.toDouble().toFloat() + /** + * Converts this [ULong] value to [Double]. + * + * The resulting value is the closest `Double` to this `ULong` value. + * In case when this `ULong` value is exactly between two `Double`s, + * the one with zero at least significant bit of mantissa is selected. + */ @kotlin.internal.InlineOnly public inline fun toDouble(): Double = ulongToDouble(data) @@ -191,27 +265,70 @@ public inline class ULong @PublishedApi internal constructor(@PublishedApi inter } +/** + * Converts this [Byte] value to [ULong]. + * + * If this value is positive, the resulting `ULong` value represents the same numerical value as this `Byte`. + * + * The least significant 8 bits of the resulting `ULong` value are the same as the binary representation of this `Byte` value, + * whereas the most significant 56 bits are filled with the sign bit of this value. + */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @kotlin.internal.InlineOnly public inline fun Byte.toULong(): ULong = ULong(this.toLong()) +/** + * Converts this [Short] value to [ULong]. + * + * If this value is positive, the resulting `ULong` value represents the same numerical value as this `Short`. + * + * The least significant 16 bits of the resulting `ULong` value are the same as the binary representation of this `Short` value, + * whereas the most significant 48 bits are filled with the sign bit of this value. + */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @kotlin.internal.InlineOnly public inline fun Short.toULong(): ULong = ULong(this.toLong()) +/** + * Converts this [Int] value to [ULong]. + * + * If this value is positive, the resulting `ULong` value represents the same numerical value as this `Int`. + * + * The least significant 32 bits of the resulting `ULong` value are the same as the binary representation of this `Int` value, + * whereas the most significant 32 bits are filled with the sign bit of this value. + */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @kotlin.internal.InlineOnly public inline fun Int.toULong(): ULong = ULong(this.toLong()) +/** + * Converts this [Long] value to [ULong]. + * + * If this value is positive, the resulting `ULong` value represents the same numerical value as this `Long`. + * + * The resulting `ULong` value has the same binary representation as this `Long` value. + */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @kotlin.internal.InlineOnly public inline fun Long.toULong(): ULong = ULong(this) +/** + * Converts this [Float] value to [ULong]. + * + * The fractional part, if any, is rounded down. + * Returns zero if this `Float` value is negative or `NaN`, [ULong.MAX_VALUE] if it's bigger than `ULong.MAX_VALUE`. + */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @kotlin.internal.InlineOnly public inline fun Float.toULong(): ULong = doubleToULong(this.toDouble()) +/** + * Converts this [Double] value to [ULong]. + * + * The fractional part, if any, is rounded down. + * Returns zero if this `Double` value is negative or `NaN`, [ULong.MAX_VALUE] if it's bigger than `ULong.MAX_VALUE`. + */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @kotlin.internal.InlineOnly diff --git a/libraries/stdlib/unsigned/src/kotlin/UShort.kt b/libraries/stdlib/unsigned/src/kotlin/UShort.kt index be98314c7da..f0a2c00094e 100644 --- a/libraries/stdlib/unsigned/src/kotlin/UShort.kt +++ b/libraries/stdlib/unsigned/src/kotlin/UShort.kt @@ -158,26 +158,94 @@ public inline class UShort @PublishedApi internal constructor(@PublishedApi inte @kotlin.internal.InlineOnly public inline fun inv(): UShort = UShort(data.inv()) + /** + * Converts this [UShort] value to [Byte]. + * + * If this value is less than or equals to [Byte.MAX_VALUE], the resulting `Byte` value represents + * the same numerical value as this `UShort`. + * + * The resulting `Byte` value is represented by the least significant 8 bits of this `UShort` value. + * Note that the resulting `Byte` value may be negative. + */ @kotlin.internal.InlineOnly public inline fun toByte(): Byte = data.toByte() + /** + * Converts this [UShort] value to [Short]. + * + * If this value is less than or equals to [Short.MAX_VALUE], the resulting `Short` value represents + * the same numerical value as this `UShort`. Otherwise the result is negative. + * + * The resulting `Short` value has the same binary representation as this `UShort` value. + */ @kotlin.internal.InlineOnly public inline fun toShort(): Short = data + /** + * Converts this [UShort] value to [Int]. + * + * The resulting `Int` value represents the same numerical value as this `UShort`. + * + * The least significant 16 bits of the resulting `Int` value are the same as the binary representation of this `UShort` value, + * whereas the most significant 16 bits are filled with zeros. + */ @kotlin.internal.InlineOnly public inline fun toInt(): Int = data.toInt() and 0xFFFF + /** + * Converts this [UShort] value to [Long]. + * + * The resulting `Long` value represents the same numerical value as this `UShort`. + * + * The least significant 16 bits of the resulting `Long` value are the same as the binary representation of this `UShort` value, + * whereas the most significant 48 bits are filled with zeros. + */ @kotlin.internal.InlineOnly public inline fun toLong(): Long = data.toLong() and 0xFFFF + /** + * Converts this [UShort] value to [UByte]. + * + * If this value is less than or equals to [UByte.MAX_VALUE], the resulting `UByte` value represents + * the same numerical value as this `UShort`. + * + * The resulting `UByte` value is represented by the least significant 8 bits of this `UShort` value. + */ @kotlin.internal.InlineOnly public inline fun toUByte(): UByte = data.toUByte() + /** Returns this value. */ @kotlin.internal.InlineOnly public inline fun toUShort(): UShort = this + /** + * Converts this [UShort] value to [UInt]. + * + * The resulting `UInt` value represents the same numerical value as this `UShort`. + * + * The least significant 16 bits of the resulting `UInt` value are the same as the binary representation of this `UShort` value, + * whereas the most significant 16 bits are filled with zeros. + */ @kotlin.internal.InlineOnly public inline fun toUInt(): UInt = UInt(data.toInt() and 0xFFFF) + /** + * Converts this [UShort] value to [ULong]. + * + * The resulting `ULong` value represents the same numerical value as this `UShort`. + * + * The least significant 16 bits of the resulting `ULong` value are the same as the binary representation of this `UShort` value, + * whereas the most significant 48 bits are filled with zeros. + */ @kotlin.internal.InlineOnly public inline fun toULong(): ULong = ULong(data.toLong() and 0xFFFF) + /** + * Converts this [UShort] value to [Float]. + * + * The resulting `Float` value represents the same numerical value as this `UShort`. + */ @kotlin.internal.InlineOnly public inline fun toFloat(): Float = this.toInt().toFloat() + /** + * Converts this [UShort] value to [Double]. + * + * The resulting `Double` value represents the same numerical value as this `UShort`. + */ @kotlin.internal.InlineOnly public inline fun toDouble(): Double = this.toInt().toDouble() @@ -185,27 +253,70 @@ public inline class UShort @PublishedApi internal constructor(@PublishedApi inte } +/** + * Converts this [Byte] value to [UShort]. + * + * If this value is positive, the resulting `UShort` value represents the same numerical value as this `Byte`. + * + * The least significant 8 bits of the resulting `UShort` value are the same as the binary representation of this `Byte` value, + * whereas the most significant 8 bits are filled with the sign bit of this value. + */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @kotlin.internal.InlineOnly public inline fun Byte.toUShort(): UShort = UShort(this.toShort()) +/** + * Converts this [Short] value to [UShort]. + * + * If this value is positive, the resulting `UShort` value represents the same numerical value as this `Short`. + * + * The resulting `UShort` value has the same binary representation as this `Short` value. + */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @kotlin.internal.InlineOnly public inline fun Short.toUShort(): UShort = UShort(this) +/** + * Converts this [Int] value to [UShort]. + * + * If this value is positive and less than or equals to [UShort.MAX_VALUE], the resulting `UShort` value represents + * the same numerical value as this `Int`. + * + * The resulting `UShort` value is represented by the least significant 16 bits of this `Int` value. + */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @kotlin.internal.InlineOnly public inline fun Int.toUShort(): UShort = UShort(this.toShort()) +/** + * Converts this [Long] value to [UShort]. + * + * If this value is positive and less than or equals to [UShort.MAX_VALUE], the resulting `UShort` value represents + * the same numerical value as this `Long`. + * + * The resulting `UShort` value is represented by the least significant 16 bits of this `Long` value. + */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @kotlin.internal.InlineOnly public inline fun Long.toUShort(): UShort = UShort(this.toShort()) +/** + * Converts this [Float] value to [UShort]. + * + * The fractional part, if any, is rounded down. + * Returns zero if this `Float` value is negative or `NaN`, [UShort.MAX_VALUE] if it's bigger than `UShort.MAX_VALUE`. + */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @kotlin.internal.InlineOnly public inline fun Float.toUShort(): UShort = doubleToUShort(this.toDouble()) +/** + * Converts this [Double] value to [UShort]. + * + * The fractional part, if any, is rounded down. + * Returns zero if this `Double` value is negative or `NaN`, [UShort.MAX_VALUE] if it's bigger than `UShort.MAX_VALUE`. + */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @kotlin.internal.InlineOnly