diff --git a/core/builtins/native/kotlin/Primitives.kt b/core/builtins/native/kotlin/Primitives.kt index e6a49bbfb61..f02e102e67f 100644 --- a/core/builtins/native/kotlin/Primitives.kt +++ b/core/builtins/native/kotlin/Primitives.kt @@ -117,35 +117,59 @@ public class Byte private constructor() : Number(), Comparable { /** Multiplies this value by the other value. */ public operator fun times(other: Double): Double - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ public operator fun div(other: Byte): Int - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ public operator fun div(other: Short): Int - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ public operator fun div(other: Int): Int - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ public operator fun div(other: Long): Long /** Divides this value by the other value. */ public operator fun div(other: Float): Float /** Divides this value by the other value. */ public operator fun div(other: Double): Double - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Byte): Int - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Short): Int - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Int): Int - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Long): Long - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Float): Float - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Double): Double @@ -329,35 +353,59 @@ public class Short private constructor() : Number(), Comparable { /** Multiplies this value by the other value. */ public operator fun times(other: Double): Double - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ public operator fun div(other: Byte): Int - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ public operator fun div(other: Short): Int - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ public operator fun div(other: Int): Int - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ public operator fun div(other: Long): Long /** Divides this value by the other value. */ public operator fun div(other: Float): Float /** Divides this value by the other value. */ public operator fun div(other: Double): Double - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Byte): Int - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Short): Int - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Int): Int - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Long): Long - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Float): Float - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Double): Double @@ -539,35 +587,59 @@ public class Int private constructor() : Number(), Comparable { /** Multiplies this value by the other value. */ public operator fun times(other: Double): Double - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ public operator fun div(other: Byte): Int - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ public operator fun div(other: Short): Int - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ public operator fun div(other: Int): Int - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ public operator fun div(other: Long): Long /** Divides this value by the other value. */ public operator fun div(other: Float): Float /** Divides this value by the other value. */ public operator fun div(other: Double): Double - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Byte): Int - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Short): Int - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Int): Int - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Long): Long - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Float): Float - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Double): Double @@ -786,35 +858,59 @@ public class Long private constructor() : Number(), Comparable { /** Multiplies this value by the other value. */ public operator fun times(other: Double): Double - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ public operator fun div(other: Byte): Long - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ public operator fun div(other: Short): Long - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ public operator fun div(other: Int): Long - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ public operator fun div(other: Long): Long /** Divides this value by the other value. */ public operator fun div(other: Float): Float /** Divides this value by the other value. */ public operator fun div(other: Double): Double - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Byte): Long - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Short): Long - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Int): Long - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Long): Long - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Float): Float - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Double): Double @@ -1063,22 +1159,46 @@ public class Float private constructor() : Number(), Comparable { /** Divides this value by the other value. */ public operator fun div(other: Double): Double - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Byte): Float - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Short): Float - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Int): Float - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Long): Float - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Float): Float - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Double): Double @@ -1276,22 +1396,46 @@ public class Double private constructor() : Number(), Comparable { /** Divides this value by the other value. */ public operator fun div(other: Double): Double - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Byte): Double - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Short): Double - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Int): Double - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Long): Double - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Float): Double - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Double): Double diff --git a/generators/builtins/common.kt b/generators/builtins/common.kt index b29833829d0..16a2f3ccc56 100644 --- a/generators/builtins/common.kt +++ b/generators/builtins/common.kt @@ -6,6 +6,7 @@ package org.jetbrains.kotlin.generators.builtins import org.jetbrains.kotlin.generators.builtins.ProgressionKind.* +import java.io.PrintWriter enum class PrimitiveType(val byteSize: Int) { BYTE(1), @@ -65,3 +66,15 @@ fun hashLong(v: String) = "($v xor ($v ushr 32))" fun convert(v: String, from: UnsignedType, to: UnsignedType) = if (from == to) v else "$v.to${to.capitalized}()" fun convert(v: String, from: PrimitiveType, to: PrimitiveType) = if (from == to) v else "$v.to${to.capitalized}()" + + +fun PrintWriter.printDoc(documentation: String, indent: String) { + val docLines = documentation.lines() + if (docLines.size == 1) { + this.println("$indent/** $documentation */") + } else { + this.println("$indent/**") + docLines.forEach { this.println("$indent * $it") } + this.println("$indent */") + } +} \ No newline at end of file diff --git a/generators/builtins/primitives.kt b/generators/builtins/primitives.kt index 70784958b87..b7cb54be412 100644 --- a/generators/builtins/primitives.kt +++ b/generators/builtins/primitives.kt @@ -8,16 +8,17 @@ package org.jetbrains.kotlin.generators.builtins.numbers import org.jetbrains.kotlin.generators.builtins.PrimitiveType import org.jetbrains.kotlin.generators.builtins.convert import org.jetbrains.kotlin.generators.builtins.generateBuiltIns.BuiltInsSourceGenerator +import org.jetbrains.kotlin.generators.builtins.printDoc import java.io.PrintWriter class GeneratePrimitives(out: PrintWriter) : BuiltInsSourceGenerator(out) { companion object { - internal val binaryOperators: Map = mapOf( - "plus" to "Adds the other value to this value.", - "minus" to "Subtracts the other value from this value.", - "times" to "Multiplies this value by the other value.", - "div" to "Divides this value by the other value.", - "rem" to "Calculates the remainder of dividing this value by the other value." + internal val binaryOperators: List = listOf( + "plus", + "minus", + "times", + "div", + "rem", ) internal val unaryOperators: Map = mapOf( "inc" to "Increments this value.", @@ -45,6 +46,37 @@ class GeneratePrimitives(out: PrintWriter) : BuiltInsSourceGenerator(out) { * The shift distance actually used is therefore always in the range `0..${kind.bitSize - 1}`. """ } + + internal fun binaryOperatorDoc(operator: String, operand1: PrimitiveType, operand2: PrimitiveType): String = when (operator) { + "plus" -> "Adds the other value to this value." + "minus" -> "Subtracts the other value from this value." + "times" -> "Multiplies this value by the other value." + "div" -> { + if (operand1.isIntegral && operand2.isIntegral) + "Divides this value by the other value, truncating the result to an integer that is closer to zero." + else + "Divides this value by the other value." + } + "floorDiv" -> + "Divides this value by the other value, flooring the result to an integer that is closer to negative infinity." + "rem" -> { + """ + Calculates the remainder of truncating division of this value by the other value. + + The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + """.trimIndent() + } + "mod" -> { + """ + Calculates the remainder of flooring division of this value by the other value. + + The result is either zero or has the same sign as the _divisor_ and has the absolute value less than the absolute value of the divisor. + """.trimIndent() + if (operand1.isFloatingPoint) + "\n\n" + "If the result cannot be represented exactly, it is rounded to the nearest representable number. In this case the absolute value of the result can be less than or _equal to_ the absolute value of the divisor." + else "" + } + else -> error("No documentation for operator $operator") + } } private val typeDescriptions: Map = mapOf( PrimitiveType.DOUBLE to "double-precision 64-bit IEEE 754 floating point number", @@ -173,16 +205,16 @@ class GeneratePrimitives(out: PrintWriter) : BuiltInsSourceGenerator(out) { } private fun generateBinaryOperators(thisKind: PrimitiveType) { - for ((name, doc) in binaryOperators) { - generateOperator(name, doc, thisKind) + for (name in binaryOperators) { + generateOperator(name, thisKind) } } - private fun generateOperator(name: String, doc: String, thisKind: PrimitiveType) { + private fun generateOperator(name: String, thisKind: PrimitiveType) { for (otherKind in PrimitiveType.onlyNumeric) { val returnType = getOperatorReturnType(thisKind, otherKind) - out.println(" /** $doc */") + out.printDoc(binaryOperatorDoc(name, thisKind, otherKind), " ") when (name) { "rem" -> out.println(" @SinceKotlin(\"1.1\")") @@ -427,6 +459,7 @@ class GenerateFloorDivMod(out: PrintWriter) : BuiltInsSourceGenerator(out) { private fun generateFloorDiv(thisKind: PrimitiveType, otherKind: PrimitiveType) { val returnType = getOperatorReturnType(thisKind, otherKind) val returnTypeName = returnType.capitalized + out.printDoc(GeneratePrimitives.binaryOperatorDoc("floorDiv", thisKind, otherKind), "") out.println("""@SinceKotlin("1.5")""") out.println("@kotlin.internal.InlineOnly") val declaration = "public inline fun ${thisKind.capitalized}.floorDiv(other: ${otherKind.capitalized}): $returnTypeName" @@ -451,6 +484,7 @@ class GenerateFloorDivMod(out: PrintWriter) : BuiltInsSourceGenerator(out) { private fun generateMod(thisKind: PrimitiveType, otherKind: PrimitiveType) { val operationType = getOperatorReturnType(thisKind, otherKind) val returnType = otherKind + out.printDoc(GeneratePrimitives.binaryOperatorDoc("mod", thisKind, otherKind),"") out.println("""@SinceKotlin("1.5")""") out.println("@kotlin.internal.InlineOnly") val declaration = "public inline fun ${thisKind.capitalized}.mod(other: ${otherKind.capitalized}): ${returnType.capitalized}" @@ -475,6 +509,7 @@ class GenerateFloorDivMod(out: PrintWriter) : BuiltInsSourceGenerator(out) { private fun generateFpMod(thisKind: PrimitiveType, otherKind: PrimitiveType) { val operationType = getOperatorReturnType(thisKind, otherKind) + out.printDoc(GeneratePrimitives.binaryOperatorDoc("mod", thisKind, otherKind), "") out.println("""@SinceKotlin("1.5")""") out.println("@kotlin.internal.InlineOnly") val declaration = "public inline fun ${thisKind.capitalized}.mod(other: ${otherKind.capitalized}): ${operationType.capitalized}" diff --git a/generators/builtins/unsignedTypes.kt b/generators/builtins/unsignedTypes.kt index 0947f253492..84435646e58 100644 --- a/generators/builtins/unsignedTypes.kt +++ b/generators/builtins/unsignedTypes.kt @@ -6,9 +6,7 @@ package org.jetbrains.kotlin.generators.builtins.unsigned -import org.jetbrains.kotlin.generators.builtins.PrimitiveType -import org.jetbrains.kotlin.generators.builtins.UnsignedType -import org.jetbrains.kotlin.generators.builtins.convert +import org.jetbrains.kotlin.generators.builtins.* import org.jetbrains.kotlin.generators.builtins.generateBuiltIns.BuiltInsSourceGenerator import org.jetbrains.kotlin.generators.builtins.numbers.GeneratePrimitives import java.io.File @@ -37,6 +35,32 @@ class UnsignedTypeGenerator(val type: UnsignedType, out: PrintWriter) : BuiltIns val className = type.capitalized val storageType = type.asSigned.capitalized + internal fun binaryOperatorDoc(operator: String, operand1: UnsignedType, operand2: UnsignedType): String = when (operator) { + "floorDiv" -> + """ + Divides this value by the other value, flooring the result to an integer that is closer to negative infinity. + + For unsigned types, the results of flooring division and truncating division are the same. + """.trimIndent() + "rem" -> { + """ + Calculates the remainder of truncating division of this value by the other value. + + The result is always less than the divisor. + """.trimIndent() + } + "mod" -> { + """ + Calculates the remainder of flooring division of this value by the other value. + + The result is always less than the divisor. + + For unsigned types, the remainders of flooring division and truncating division are the same. + """.trimIndent() + } + else -> GeneratePrimitives.binaryOperatorDoc(operator, operand1.asSigned, operand2.asSigned) + } + override fun generateBody() { out.println("import kotlin.experimental.*") @@ -124,18 +148,18 @@ class UnsignedTypeGenerator(val type: UnsignedType, out: PrintWriter) : BuiltIns } private fun generateBinaryOperators() { - for ((name, doc) in GeneratePrimitives.binaryOperators) { - generateOperator(name, doc) + for (name in GeneratePrimitives.binaryOperators) { + generateOperator(name) } - generateFloorDivMod("floorDiv", "TODO") - generateFloorDivMod("mod", "TODO") + generateFloorDivMod("floorDiv") + generateFloorDivMod("mod") } - private fun generateOperator(name: String, doc: String) { + private fun generateOperator(name: String) { for (otherType in UnsignedType.values()) { val returnType = getOperatorReturnType(type, otherType) - out.println(" /** $doc */") + out.printDoc(binaryOperatorDoc(name, type, otherType), " ") out.println(" @kotlin.internal.InlineOnly") out.print(" public inline operator fun $name(other: ${otherType.capitalized}): ${returnType.capitalized} = ") if (type == otherType && type == returnType) { @@ -152,12 +176,12 @@ class UnsignedTypeGenerator(val type: UnsignedType, out: PrintWriter) : BuiltIns out.println() } - private fun generateFloorDivMod(name: String, doc: String) { + private fun generateFloorDivMod(name: String) { for (otherType in UnsignedType.values()) { val operationType = getOperatorReturnType(type, otherType) val returnType = if (name == "mod") otherType else operationType - out.println(" /** $doc */") + out.printDoc(binaryOperatorDoc(name, type, otherType), " ") out.println(" @kotlin.internal.InlineOnly") out.print(" public inline fun $name(other: ${otherType.capitalized}): ${returnType.capitalized} = ") if (type == otherType && type == operationType) { diff --git a/libraries/stdlib/js-ir/builtins/Primitives.kt b/libraries/stdlib/js-ir/builtins/Primitives.kt index 9269673392a..8a193c07c8a 100644 --- a/libraries/stdlib/js-ir/builtins/Primitives.kt +++ b/libraries/stdlib/js-ir/builtins/Primitives.kt @@ -1,5 +1,5 @@ /* - * Copyright 2010-2020 JetBrains s.r.o. and Kotlin Programming Language contributors. + * Copyright 2010-2021 JetBrains s.r.o. and Kotlin Programming Language contributors. * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file. */ @@ -118,35 +118,59 @@ public class Byte private constructor() : Number(), Comparable { /** Multiplies this value by the other value. */ public operator fun times(other: Double): Double - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ public operator fun div(other: Byte): Int - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ public operator fun div(other: Short): Int - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ public operator fun div(other: Int): Int - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ public operator fun div(other: Long): Long /** Divides this value by the other value. */ public operator fun div(other: Float): Float /** Divides this value by the other value. */ public operator fun div(other: Double): Double - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Byte): Int - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Short): Int - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Int): Int - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Long): Long - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Float): Float - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Double): Double @@ -334,35 +358,59 @@ public class Short private constructor() : Number(), Comparable { /** Multiplies this value by the other value. */ public operator fun times(other: Double): Double - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ public operator fun div(other: Byte): Int - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ public operator fun div(other: Short): Int - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ public operator fun div(other: Int): Int - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ public operator fun div(other: Long): Long /** Divides this value by the other value. */ public operator fun div(other: Float): Float /** Divides this value by the other value. */ public operator fun div(other: Double): Double - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Byte): Int - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Short): Int - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Int): Int - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Long): Long - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Float): Float - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Double): Double @@ -548,35 +596,59 @@ public class Int private constructor() : Number(), Comparable { /** Multiplies this value by the other value. */ public operator fun times(other: Double): Double - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ public operator fun div(other: Byte): Int - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ public operator fun div(other: Short): Int - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ public operator fun div(other: Int): Int - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ public operator fun div(other: Long): Long /** Divides this value by the other value. */ public operator fun div(other: Float): Float /** Divides this value by the other value. */ public operator fun div(other: Double): Double - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Byte): Int - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Short): Int - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Int): Int - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Long): Long - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Float): Float - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Double): Double @@ -828,22 +900,46 @@ public class Float private constructor() : Number(), Comparable { /** Divides this value by the other value. */ public operator fun div(other: Double): Double - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Byte): Float - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Short): Float - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Int): Float - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Long): Float - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Float): Float - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Double): Double @@ -1046,22 +1142,46 @@ public class Double private constructor() : Number(), Comparable { /** Divides this value by the other value. */ public operator fun div(other: Double): Double - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Byte): Double - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Short): Double - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Int): Double - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Long): Double - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Float): Double - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Double): Double diff --git a/libraries/stdlib/js-ir/runtime/long.kt b/libraries/stdlib/js-ir/runtime/long.kt index 5a3f49ceee5..3c3ce7f6788 100644 --- a/libraries/stdlib/js-ir/runtime/long.kt +++ b/libraries/stdlib/js-ir/runtime/long.kt @@ -1,5 +1,5 @@ /* - * Copyright 2010-2020 JetBrains s.r.o. and Kotlin Programming Language contributors. + * Copyright 2010-2021 JetBrains s.r.o. and Kotlin Programming Language contributors. * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file. */ @@ -135,16 +135,16 @@ public class Long internal constructor( /** Multiplies this value by the other value. */ public inline operator fun times(other: Double): Double = toDouble() * other - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ public inline operator fun div(other: Byte): Long = div(other.toLong()) - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ public inline operator fun div(other: Short): Long = div(other.toLong()) - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ public inline operator fun div(other: Int): Long = div(other.toLong()) - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ public operator fun div(other: Long): Long = divide(other) /** Divides this value by the other value. */ @@ -153,27 +153,51 @@ public class Long internal constructor( /** Divides this value by the other value. */ public inline operator fun div(other: Double): Double = toDouble() / other - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public inline operator fun rem(other: Byte): Long = rem(other.toLong()) - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public inline operator fun rem(other: Short): Long = rem(other.toLong()) - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public inline operator fun rem(other: Int): Long = rem(other.toLong()) - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public operator fun rem(other: Long): Long = modulo(other) - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public inline operator fun rem(other: Float): Float = toFloat() % other - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is either zero or has the same sign as the _dividend_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.1") public inline operator fun rem(other: Double): Double = toDouble() % other diff --git a/libraries/stdlib/src/kotlin/util/FloorDivMod.kt b/libraries/stdlib/src/kotlin/util/FloorDivMod.kt index 42764c4d3f2..9fda3e02376 100644 --- a/libraries/stdlib/src/kotlin/util/FloorDivMod.kt +++ b/libraries/stdlib/src/kotlin/util/FloorDivMod.kt @@ -11,106 +11,167 @@ package kotlin import kotlin.math.sign +/** Divides this value by the other value, flooring the result to an integer that is closer to negative infinity. */ @SinceKotlin("1.5") @kotlin.internal.InlineOnly public inline fun Byte.floorDiv(other: Byte): Int = this.toInt().floorDiv(other.toInt()) +/** + * Calculates the remainder of flooring division of this value by the other value. + * + * The result is either zero or has the same sign as the _divisor_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.5") @kotlin.internal.InlineOnly public inline fun Byte.mod(other: Byte): Byte = this.toInt().mod(other.toInt()).toByte() +/** Divides this value by the other value, flooring the result to an integer that is closer to negative infinity. */ @SinceKotlin("1.5") @kotlin.internal.InlineOnly public inline fun Byte.floorDiv(other: Short): Int = this.toInt().floorDiv(other.toInt()) +/** + * Calculates the remainder of flooring division of this value by the other value. + * + * The result is either zero or has the same sign as the _divisor_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.5") @kotlin.internal.InlineOnly public inline fun Byte.mod(other: Short): Short = this.toInt().mod(other.toInt()).toShort() +/** Divides this value by the other value, flooring the result to an integer that is closer to negative infinity. */ @SinceKotlin("1.5") @kotlin.internal.InlineOnly public inline fun Byte.floorDiv(other: Int): Int = this.toInt().floorDiv(other) +/** + * Calculates the remainder of flooring division of this value by the other value. + * + * The result is either zero or has the same sign as the _divisor_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.5") @kotlin.internal.InlineOnly public inline fun Byte.mod(other: Int): Int = this.toInt().mod(other) +/** Divides this value by the other value, flooring the result to an integer that is closer to negative infinity. */ @SinceKotlin("1.5") @kotlin.internal.InlineOnly public inline fun Byte.floorDiv(other: Long): Long = this.toLong().floorDiv(other) +/** + * Calculates the remainder of flooring division of this value by the other value. + * + * The result is either zero or has the same sign as the _divisor_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.5") @kotlin.internal.InlineOnly public inline fun Byte.mod(other: Long): Long = this.toLong().mod(other) +/** Divides this value by the other value, flooring the result to an integer that is closer to negative infinity. */ @SinceKotlin("1.5") @kotlin.internal.InlineOnly public inline fun Short.floorDiv(other: Byte): Int = this.toInt().floorDiv(other.toInt()) +/** + * Calculates the remainder of flooring division of this value by the other value. + * + * The result is either zero or has the same sign as the _divisor_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.5") @kotlin.internal.InlineOnly public inline fun Short.mod(other: Byte): Byte = this.toInt().mod(other.toInt()).toByte() +/** Divides this value by the other value, flooring the result to an integer that is closer to negative infinity. */ @SinceKotlin("1.5") @kotlin.internal.InlineOnly public inline fun Short.floorDiv(other: Short): Int = this.toInt().floorDiv(other.toInt()) +/** + * Calculates the remainder of flooring division of this value by the other value. + * + * The result is either zero or has the same sign as the _divisor_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.5") @kotlin.internal.InlineOnly public inline fun Short.mod(other: Short): Short = this.toInt().mod(other.toInt()).toShort() +/** Divides this value by the other value, flooring the result to an integer that is closer to negative infinity. */ @SinceKotlin("1.5") @kotlin.internal.InlineOnly public inline fun Short.floorDiv(other: Int): Int = this.toInt().floorDiv(other) +/** + * Calculates the remainder of flooring division of this value by the other value. + * + * The result is either zero or has the same sign as the _divisor_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.5") @kotlin.internal.InlineOnly public inline fun Short.mod(other: Int): Int = this.toInt().mod(other) +/** Divides this value by the other value, flooring the result to an integer that is closer to negative infinity. */ @SinceKotlin("1.5") @kotlin.internal.InlineOnly public inline fun Short.floorDiv(other: Long): Long = this.toLong().floorDiv(other) +/** + * Calculates the remainder of flooring division of this value by the other value. + * + * The result is either zero or has the same sign as the _divisor_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.5") @kotlin.internal.InlineOnly public inline fun Short.mod(other: Long): Long = this.toLong().mod(other) +/** Divides this value by the other value, flooring the result to an integer that is closer to negative infinity. */ @SinceKotlin("1.5") @kotlin.internal.InlineOnly public inline fun Int.floorDiv(other: Byte): Int = this.floorDiv(other.toInt()) +/** + * Calculates the remainder of flooring division of this value by the other value. + * + * The result is either zero or has the same sign as the _divisor_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.5") @kotlin.internal.InlineOnly public inline fun Int.mod(other: Byte): Byte = this.mod(other.toInt()).toByte() +/** Divides this value by the other value, flooring the result to an integer that is closer to negative infinity. */ @SinceKotlin("1.5") @kotlin.internal.InlineOnly public inline fun Int.floorDiv(other: Short): Int = this.floorDiv(other.toInt()) +/** + * Calculates the remainder of flooring division of this value by the other value. + * + * The result is either zero or has the same sign as the _divisor_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.5") @kotlin.internal.InlineOnly public inline fun Int.mod(other: Short): Short = this.mod(other.toInt()).toShort() +/** Divides this value by the other value, flooring the result to an integer that is closer to negative infinity. */ @SinceKotlin("1.5") @kotlin.internal.InlineOnly public inline fun Int.floorDiv(other: Int): Int { @@ -119,6 +180,11 @@ public inline fun Int.floorDiv(other: Int): Int { return q } +/** + * Calculates the remainder of flooring division of this value by the other value. + * + * The result is either zero or has the same sign as the _divisor_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.5") @kotlin.internal.InlineOnly public inline fun Int.mod(other: Int): Int { @@ -126,46 +192,71 @@ public inline fun Int.mod(other: Int): Int { return r + (other and (((r xor other) and (r or -r)) shr 31)) } +/** Divides this value by the other value, flooring the result to an integer that is closer to negative infinity. */ @SinceKotlin("1.5") @kotlin.internal.InlineOnly public inline fun Int.floorDiv(other: Long): Long = this.toLong().floorDiv(other) +/** + * Calculates the remainder of flooring division of this value by the other value. + * + * The result is either zero or has the same sign as the _divisor_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.5") @kotlin.internal.InlineOnly public inline fun Int.mod(other: Long): Long = this.toLong().mod(other) +/** Divides this value by the other value, flooring the result to an integer that is closer to negative infinity. */ @SinceKotlin("1.5") @kotlin.internal.InlineOnly public inline fun Long.floorDiv(other: Byte): Long = this.floorDiv(other.toLong()) +/** + * Calculates the remainder of flooring division of this value by the other value. + * + * The result is either zero or has the same sign as the _divisor_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.5") @kotlin.internal.InlineOnly public inline fun Long.mod(other: Byte): Byte = this.mod(other.toLong()).toByte() +/** Divides this value by the other value, flooring the result to an integer that is closer to negative infinity. */ @SinceKotlin("1.5") @kotlin.internal.InlineOnly public inline fun Long.floorDiv(other: Short): Long = this.floorDiv(other.toLong()) +/** + * Calculates the remainder of flooring division of this value by the other value. + * + * The result is either zero or has the same sign as the _divisor_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.5") @kotlin.internal.InlineOnly public inline fun Long.mod(other: Short): Short = this.mod(other.toLong()).toShort() +/** Divides this value by the other value, flooring the result to an integer that is closer to negative infinity. */ @SinceKotlin("1.5") @kotlin.internal.InlineOnly public inline fun Long.floorDiv(other: Int): Long = this.floorDiv(other.toLong()) +/** + * Calculates the remainder of flooring division of this value by the other value. + * + * The result is either zero or has the same sign as the _divisor_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.5") @kotlin.internal.InlineOnly public inline fun Long.mod(other: Int): Int = this.mod(other.toLong()).toInt() +/** Divides this value by the other value, flooring the result to an integer that is closer to negative infinity. */ @SinceKotlin("1.5") @kotlin.internal.InlineOnly public inline fun Long.floorDiv(other: Long): Long { @@ -174,6 +265,11 @@ public inline fun Long.floorDiv(other: Long): Long { return q } +/** + * Calculates the remainder of flooring division of this value by the other value. + * + * The result is either zero or has the same sign as the _divisor_ and has the absolute value less than the absolute value of the divisor. + */ @SinceKotlin("1.5") @kotlin.internal.InlineOnly public inline fun Long.mod(other: Long): Long { @@ -181,6 +277,13 @@ public inline fun Long.mod(other: Long): Long { return r + (other and (((r xor other) and (r or -r)) shr 63)) } +/** + * Calculates the remainder of flooring division of this value by the other value. + * + * The result is either zero or has the same sign as the _divisor_ and has the absolute value less than the absolute value of the divisor. + * + * If the result cannot be represented exactly, it is rounded to the nearest representable number. In this case the absolute value of the result can be less than or _equal to_ the absolute value of the divisor. + */ @SinceKotlin("1.5") @kotlin.internal.InlineOnly public inline fun Float.mod(other: Float): Float { @@ -188,16 +291,37 @@ public inline fun Float.mod(other: Float): Float { return if (r != 0.0.toFloat() && r.sign != other.sign) r + other else r } +/** + * Calculates the remainder of flooring division of this value by the other value. + * + * The result is either zero or has the same sign as the _divisor_ and has the absolute value less than the absolute value of the divisor. + * + * If the result cannot be represented exactly, it is rounded to the nearest representable number. In this case the absolute value of the result can be less than or _equal to_ the absolute value of the divisor. + */ @SinceKotlin("1.5") @kotlin.internal.InlineOnly public inline fun Float.mod(other: Double): Double = this.toDouble().mod(other) +/** + * Calculates the remainder of flooring division of this value by the other value. + * + * The result is either zero or has the same sign as the _divisor_ and has the absolute value less than the absolute value of the divisor. + * + * If the result cannot be represented exactly, it is rounded to the nearest representable number. In this case the absolute value of the result can be less than or _equal to_ the absolute value of the divisor. + */ @SinceKotlin("1.5") @kotlin.internal.InlineOnly public inline fun Double.mod(other: Float): Double = this.mod(other.toDouble()) +/** + * Calculates the remainder of flooring division of this value by the other value. + * + * The result is either zero or has the same sign as the _divisor_ and has the absolute value less than the absolute value of the divisor. + * + * If the result cannot be represented exactly, it is rounded to the nearest representable number. In this case the absolute value of the result can be less than or _equal to_ the absolute value of the divisor. + */ @SinceKotlin("1.5") @kotlin.internal.InlineOnly public inline fun Double.mod(other: Double): Double { diff --git a/libraries/stdlib/unsigned/src/kotlin/UByte.kt b/libraries/stdlib/unsigned/src/kotlin/UByte.kt index 7ccee99f568..62db4e7b744 100644 --- a/libraries/stdlib/unsigned/src/kotlin/UByte.kt +++ b/libraries/stdlib/unsigned/src/kotlin/UByte.kt @@ -109,55 +109,111 @@ public value class UByte @PublishedApi internal constructor(@PublishedApi intern @kotlin.internal.InlineOnly public inline operator fun times(other: ULong): ULong = this.toULong().times(other) - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ @kotlin.internal.InlineOnly public inline operator fun div(other: UByte): UInt = this.toUInt().div(other.toUInt()) - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ @kotlin.internal.InlineOnly public inline operator fun div(other: UShort): UInt = this.toUInt().div(other.toUInt()) - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ @kotlin.internal.InlineOnly public inline operator fun div(other: UInt): UInt = this.toUInt().div(other) - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ @kotlin.internal.InlineOnly public inline operator fun div(other: ULong): ULong = this.toULong().div(other) - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is always less than the divisor. + */ @kotlin.internal.InlineOnly public inline operator fun rem(other: UByte): UInt = this.toUInt().rem(other.toUInt()) - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is always less than the divisor. + */ @kotlin.internal.InlineOnly public inline operator fun rem(other: UShort): UInt = this.toUInt().rem(other.toUInt()) - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is always less than the divisor. + */ @kotlin.internal.InlineOnly public inline operator fun rem(other: UInt): UInt = this.toUInt().rem(other) - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is always less than the divisor. + */ @kotlin.internal.InlineOnly public inline operator fun rem(other: ULong): ULong = this.toULong().rem(other) - /** TODO */ + /** + * Divides this value by the other value, flooring the result to an integer that is closer to negative infinity. + * + * For unsigned types, the results of flooring division and truncating division are the same. + */ @kotlin.internal.InlineOnly public inline fun floorDiv(other: UByte): UInt = this.toUInt().floorDiv(other.toUInt()) - /** TODO */ + /** + * Divides this value by the other value, flooring the result to an integer that is closer to negative infinity. + * + * For unsigned types, the results of flooring division and truncating division are the same. + */ @kotlin.internal.InlineOnly public inline fun floorDiv(other: UShort): UInt = this.toUInt().floorDiv(other.toUInt()) - /** TODO */ + /** + * Divides this value by the other value, flooring the result to an integer that is closer to negative infinity. + * + * For unsigned types, the results of flooring division and truncating division are the same. + */ @kotlin.internal.InlineOnly public inline fun floorDiv(other: UInt): UInt = this.toUInt().floorDiv(other) - /** TODO */ + /** + * Divides this value by the other value, flooring the result to an integer that is closer to negative infinity. + * + * For unsigned types, the results of flooring division and truncating division are the same. + */ @kotlin.internal.InlineOnly public inline fun floorDiv(other: ULong): ULong = this.toULong().floorDiv(other) - /** TODO */ + /** + * Calculates the remainder of flooring division of this value by the other value. + * + * The result is always less than the divisor. + * + * For unsigned types, the remainders of flooring division and truncating division are the same. + */ @kotlin.internal.InlineOnly public inline fun mod(other: UByte): UByte = this.toUInt().mod(other.toUInt()).toUByte() - /** TODO */ + /** + * Calculates the remainder of flooring division of this value by the other value. + * + * The result is always less than the divisor. + * + * For unsigned types, the remainders of flooring division and truncating division are the same. + */ @kotlin.internal.InlineOnly public inline fun mod(other: UShort): UShort = this.toUInt().mod(other.toUInt()).toUShort() - /** TODO */ + /** + * Calculates the remainder of flooring division of this value by the other value. + * + * The result is always less than the divisor. + * + * For unsigned types, the remainders of flooring division and truncating division are the same. + */ @kotlin.internal.InlineOnly public inline fun mod(other: UInt): UInt = this.toUInt().mod(other) - /** TODO */ + /** + * Calculates the remainder of flooring division of this value by the other value. + * + * The result is always less than the divisor. + * + * For unsigned types, the remainders of flooring division and truncating division are the same. + */ @kotlin.internal.InlineOnly public inline fun mod(other: ULong): ULong = this.toULong().mod(other) diff --git a/libraries/stdlib/unsigned/src/kotlin/UInt.kt b/libraries/stdlib/unsigned/src/kotlin/UInt.kt index 28a7505f199..4bec305eff9 100644 --- a/libraries/stdlib/unsigned/src/kotlin/UInt.kt +++ b/libraries/stdlib/unsigned/src/kotlin/UInt.kt @@ -109,55 +109,111 @@ public value class UInt @PublishedApi internal constructor(@PublishedApi interna @kotlin.internal.InlineOnly public inline operator fun times(other: ULong): ULong = this.toULong().times(other) - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ @kotlin.internal.InlineOnly public inline operator fun div(other: UByte): UInt = this.div(other.toUInt()) - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ @kotlin.internal.InlineOnly public inline operator fun div(other: UShort): UInt = this.div(other.toUInt()) - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ @kotlin.internal.InlineOnly public inline operator fun div(other: UInt): UInt = uintDivide(this, other) - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ @kotlin.internal.InlineOnly public inline operator fun div(other: ULong): ULong = this.toULong().div(other) - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is always less than the divisor. + */ @kotlin.internal.InlineOnly public inline operator fun rem(other: UByte): UInt = this.rem(other.toUInt()) - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is always less than the divisor. + */ @kotlin.internal.InlineOnly public inline operator fun rem(other: UShort): UInt = this.rem(other.toUInt()) - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is always less than the divisor. + */ @kotlin.internal.InlineOnly public inline operator fun rem(other: UInt): UInt = uintRemainder(this, other) - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is always less than the divisor. + */ @kotlin.internal.InlineOnly public inline operator fun rem(other: ULong): ULong = this.toULong().rem(other) - /** TODO */ + /** + * Divides this value by the other value, flooring the result to an integer that is closer to negative infinity. + * + * For unsigned types, the results of flooring division and truncating division are the same. + */ @kotlin.internal.InlineOnly public inline fun floorDiv(other: UByte): UInt = this.floorDiv(other.toUInt()) - /** TODO */ + /** + * Divides this value by the other value, flooring the result to an integer that is closer to negative infinity. + * + * For unsigned types, the results of flooring division and truncating division are the same. + */ @kotlin.internal.InlineOnly public inline fun floorDiv(other: UShort): UInt = this.floorDiv(other.toUInt()) - /** TODO */ + /** + * Divides this value by the other value, flooring the result to an integer that is closer to negative infinity. + * + * For unsigned types, the results of flooring division and truncating division are the same. + */ @kotlin.internal.InlineOnly public inline fun floorDiv(other: UInt): UInt = div(other) - /** TODO */ + /** + * Divides this value by the other value, flooring the result to an integer that is closer to negative infinity. + * + * For unsigned types, the results of flooring division and truncating division are the same. + */ @kotlin.internal.InlineOnly public inline fun floorDiv(other: ULong): ULong = this.toULong().floorDiv(other) - /** TODO */ + /** + * Calculates the remainder of flooring division of this value by the other value. + * + * The result is always less than the divisor. + * + * For unsigned types, the remainders of flooring division and truncating division are the same. + */ @kotlin.internal.InlineOnly public inline fun mod(other: UByte): UByte = this.mod(other.toUInt()).toUByte() - /** TODO */ + /** + * Calculates the remainder of flooring division of this value by the other value. + * + * The result is always less than the divisor. + * + * For unsigned types, the remainders of flooring division and truncating division are the same. + */ @kotlin.internal.InlineOnly public inline fun mod(other: UShort): UShort = this.mod(other.toUInt()).toUShort() - /** TODO */ + /** + * Calculates the remainder of flooring division of this value by the other value. + * + * The result is always less than the divisor. + * + * For unsigned types, the remainders of flooring division and truncating division are the same. + */ @kotlin.internal.InlineOnly public inline fun mod(other: UInt): UInt = rem(other) - /** TODO */ + /** + * Calculates the remainder of flooring division of this value by the other value. + * + * The result is always less than the divisor. + * + * For unsigned types, the remainders of flooring division and truncating division are the same. + */ @kotlin.internal.InlineOnly public inline fun mod(other: ULong): ULong = this.toULong().mod(other) diff --git a/libraries/stdlib/unsigned/src/kotlin/ULong.kt b/libraries/stdlib/unsigned/src/kotlin/ULong.kt index 79ab77044f3..3218db0003b 100644 --- a/libraries/stdlib/unsigned/src/kotlin/ULong.kt +++ b/libraries/stdlib/unsigned/src/kotlin/ULong.kt @@ -109,55 +109,111 @@ public value class ULong @PublishedApi internal constructor(@PublishedApi intern @kotlin.internal.InlineOnly public inline operator fun times(other: ULong): ULong = ULong(this.data.times(other.data)) - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ @kotlin.internal.InlineOnly public inline operator fun div(other: UByte): ULong = this.div(other.toULong()) - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ @kotlin.internal.InlineOnly public inline operator fun div(other: UShort): ULong = this.div(other.toULong()) - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ @kotlin.internal.InlineOnly public inline operator fun div(other: UInt): ULong = this.div(other.toULong()) - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ @kotlin.internal.InlineOnly public inline operator fun div(other: ULong): ULong = ulongDivide(this, other) - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is always less than the divisor. + */ @kotlin.internal.InlineOnly public inline operator fun rem(other: UByte): ULong = this.rem(other.toULong()) - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is always less than the divisor. + */ @kotlin.internal.InlineOnly public inline operator fun rem(other: UShort): ULong = this.rem(other.toULong()) - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is always less than the divisor. + */ @kotlin.internal.InlineOnly public inline operator fun rem(other: UInt): ULong = this.rem(other.toULong()) - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is always less than the divisor. + */ @kotlin.internal.InlineOnly public inline operator fun rem(other: ULong): ULong = ulongRemainder(this, other) - /** TODO */ + /** + * Divides this value by the other value, flooring the result to an integer that is closer to negative infinity. + * + * For unsigned types, the results of flooring division and truncating division are the same. + */ @kotlin.internal.InlineOnly public inline fun floorDiv(other: UByte): ULong = this.floorDiv(other.toULong()) - /** TODO */ + /** + * Divides this value by the other value, flooring the result to an integer that is closer to negative infinity. + * + * For unsigned types, the results of flooring division and truncating division are the same. + */ @kotlin.internal.InlineOnly public inline fun floorDiv(other: UShort): ULong = this.floorDiv(other.toULong()) - /** TODO */ + /** + * Divides this value by the other value, flooring the result to an integer that is closer to negative infinity. + * + * For unsigned types, the results of flooring division and truncating division are the same. + */ @kotlin.internal.InlineOnly public inline fun floorDiv(other: UInt): ULong = this.floorDiv(other.toULong()) - /** TODO */ + /** + * Divides this value by the other value, flooring the result to an integer that is closer to negative infinity. + * + * For unsigned types, the results of flooring division and truncating division are the same. + */ @kotlin.internal.InlineOnly public inline fun floorDiv(other: ULong): ULong = div(other) - /** TODO */ + /** + * Calculates the remainder of flooring division of this value by the other value. + * + * The result is always less than the divisor. + * + * For unsigned types, the remainders of flooring division and truncating division are the same. + */ @kotlin.internal.InlineOnly public inline fun mod(other: UByte): UByte = this.mod(other.toULong()).toUByte() - /** TODO */ + /** + * Calculates the remainder of flooring division of this value by the other value. + * + * The result is always less than the divisor. + * + * For unsigned types, the remainders of flooring division and truncating division are the same. + */ @kotlin.internal.InlineOnly public inline fun mod(other: UShort): UShort = this.mod(other.toULong()).toUShort() - /** TODO */ + /** + * Calculates the remainder of flooring division of this value by the other value. + * + * The result is always less than the divisor. + * + * For unsigned types, the remainders of flooring division and truncating division are the same. + */ @kotlin.internal.InlineOnly public inline fun mod(other: UInt): UInt = this.mod(other.toULong()).toUInt() - /** TODO */ + /** + * Calculates the remainder of flooring division of this value by the other value. + * + * The result is always less than the divisor. + * + * For unsigned types, the remainders of flooring division and truncating division are the same. + */ @kotlin.internal.InlineOnly public inline fun mod(other: ULong): ULong = rem(other) diff --git a/libraries/stdlib/unsigned/src/kotlin/UShort.kt b/libraries/stdlib/unsigned/src/kotlin/UShort.kt index 33d57aa8a1b..ce35c09670f 100644 --- a/libraries/stdlib/unsigned/src/kotlin/UShort.kt +++ b/libraries/stdlib/unsigned/src/kotlin/UShort.kt @@ -109,55 +109,111 @@ public value class UShort @PublishedApi internal constructor(@PublishedApi inter @kotlin.internal.InlineOnly public inline operator fun times(other: ULong): ULong = this.toULong().times(other) - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ @kotlin.internal.InlineOnly public inline operator fun div(other: UByte): UInt = this.toUInt().div(other.toUInt()) - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ @kotlin.internal.InlineOnly public inline operator fun div(other: UShort): UInt = this.toUInt().div(other.toUInt()) - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ @kotlin.internal.InlineOnly public inline operator fun div(other: UInt): UInt = this.toUInt().div(other) - /** Divides this value by the other value. */ + /** Divides this value by the other value, truncating the result to an integer that is closer to zero. */ @kotlin.internal.InlineOnly public inline operator fun div(other: ULong): ULong = this.toULong().div(other) - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is always less than the divisor. + */ @kotlin.internal.InlineOnly public inline operator fun rem(other: UByte): UInt = this.toUInt().rem(other.toUInt()) - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is always less than the divisor. + */ @kotlin.internal.InlineOnly public inline operator fun rem(other: UShort): UInt = this.toUInt().rem(other.toUInt()) - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is always less than the divisor. + */ @kotlin.internal.InlineOnly public inline operator fun rem(other: UInt): UInt = this.toUInt().rem(other) - /** Calculates the remainder of dividing this value by the other value. */ + /** + * Calculates the remainder of truncating division of this value by the other value. + * + * The result is always less than the divisor. + */ @kotlin.internal.InlineOnly public inline operator fun rem(other: ULong): ULong = this.toULong().rem(other) - /** TODO */ + /** + * Divides this value by the other value, flooring the result to an integer that is closer to negative infinity. + * + * For unsigned types, the results of flooring division and truncating division are the same. + */ @kotlin.internal.InlineOnly public inline fun floorDiv(other: UByte): UInt = this.toUInt().floorDiv(other.toUInt()) - /** TODO */ + /** + * Divides this value by the other value, flooring the result to an integer that is closer to negative infinity. + * + * For unsigned types, the results of flooring division and truncating division are the same. + */ @kotlin.internal.InlineOnly public inline fun floorDiv(other: UShort): UInt = this.toUInt().floorDiv(other.toUInt()) - /** TODO */ + /** + * Divides this value by the other value, flooring the result to an integer that is closer to negative infinity. + * + * For unsigned types, the results of flooring division and truncating division are the same. + */ @kotlin.internal.InlineOnly public inline fun floorDiv(other: UInt): UInt = this.toUInt().floorDiv(other) - /** TODO */ + /** + * Divides this value by the other value, flooring the result to an integer that is closer to negative infinity. + * + * For unsigned types, the results of flooring division and truncating division are the same. + */ @kotlin.internal.InlineOnly public inline fun floorDiv(other: ULong): ULong = this.toULong().floorDiv(other) - /** TODO */ + /** + * Calculates the remainder of flooring division of this value by the other value. + * + * The result is always less than the divisor. + * + * For unsigned types, the remainders of flooring division and truncating division are the same. + */ @kotlin.internal.InlineOnly public inline fun mod(other: UByte): UByte = this.toUInt().mod(other.toUInt()).toUByte() - /** TODO */ + /** + * Calculates the remainder of flooring division of this value by the other value. + * + * The result is always less than the divisor. + * + * For unsigned types, the remainders of flooring division and truncating division are the same. + */ @kotlin.internal.InlineOnly public inline fun mod(other: UShort): UShort = this.toUInt().mod(other.toUInt()).toUShort() - /** TODO */ + /** + * Calculates the remainder of flooring division of this value by the other value. + * + * The result is always less than the divisor. + * + * For unsigned types, the remainders of flooring division and truncating division are the same. + */ @kotlin.internal.InlineOnly public inline fun mod(other: UInt): UInt = this.toUInt().mod(other) - /** TODO */ + /** + * Calculates the remainder of flooring division of this value by the other value. + * + * The result is always less than the divisor. + * + * For unsigned types, the remainders of flooring division and truncating division are the same. + */ @kotlin.internal.InlineOnly public inline fun mod(other: ULong): ULong = this.toULong().mod(other)