More detailed Primitive.toChar conversion documentation

core/builtins/native/kotlin/Primitives.kt

@@ -191,7 +191,10 @@ public class Byte private constructor() : Number(), Comparable<Byte> {
     /**
      * Converts this [Byte] value to [Char].
      *
-     * Returns the `Char` with the numeric value equal to this value sign-extended to 16 bits.
+     * If this value is non-negative, the resulting `Char` code is equal to this value.
+     *
+     * The least significant 8 bits of the resulting `Char` code are the same as the bits of this `Byte` value,
+     * whereas the most significant 8 bits are filled with the sign bit of this value.
      */
     public override fun toChar(): Char
     /**
@@ -426,7 +429,8 @@ public class Short private constructor() : Number(), Comparable<Short> {
     /**
      * Converts this [Short] value to [Char].
      *
-     * Returns the `Char` with the numeric value equal to this value.
+     * The resulting `Char` code is equal to this value reinterpreted as an unsigned number,
+     * i.e. it has the same binary representation as this `Short`.
      */
     public override fun toChar(): Char
     /** Returns this value. */
@@ -669,7 +673,10 @@ public class Int private constructor() : Number(), Comparable<Int> {
     /**
      * Converts this [Int] value to [Char].
      *
-     * Returns the `Char` with the numeric value equal to this value truncated to 16 bits.
+     * If this value is in the range of `Char` codes `Char.MIN_VALUE..Char.MAX_VALUE`,
+     * the resulting `Char` code is equal to this value.
+     *
+     * The resulting `Char` code is represented by the least significant 16 bits of this `Int` value.
      */
     public override fun toChar(): Char
     /**
@@ -914,7 +921,10 @@ public class Long private constructor() : Number(), Comparable<Long> {
     /**
      * Converts this [Long] value to [Char].
      *
-     * Returns the `Char` with the numeric value equal to this value truncated to 16 bits.
+     * If this value is in the range of `Char` codes `Char.MIN_VALUE..Char.MAX_VALUE`,
+     * the resulting `Char` code is equal to this value.
+     *
+     * The resulting `Char` code is represented by the least significant 16 bits of this `Long` value.
      */
     public override fun toChar(): Char
     /**

generators/builtins/primitives.kt

@@ -278,39 +278,44 @@ class GeneratePrimitives(out: PrintWriter) : BuiltInsSourceGenerator(out) {
         val thisName = fromIntegral.capitalized
         val otherName = toIntegral.capitalized
 
-        return if (compareByDomainCapacity(toIntegral, fromIntegral) < 0) {
+        return if (toIntegral == PrimitiveType.CHAR) {
-            if (toIntegral == PrimitiveType.CHAR) {
+            if (fromIntegral == PrimitiveType.SHORT) {
                 """
-                 * Returns the `$otherName` with the numeric value equal to this value truncated to ${toIntegral.bitSize} bits.
+                * The resulting `Char` code is equal to this value reinterpreted as an unsigned number,
-                 */
+                * i.e. it has the same binary representation as this `Short`.
+                */
+                """
+            } else if (fromIntegral == PrimitiveType.BYTE) {
+                """
+                * If this value is non-negative, the resulting `Char` code is equal to this value.
+                *
+                * The least significant 8 bits of the resulting `Char` code are the same as the bits of this `Byte` value,
+                * whereas the most significant 8 bits are filled with the sign bit of this value.
+                */
                 """
             } else {
                 """
-                 * If this value is in [$otherName.MIN_VALUE]..[$otherName.MAX_VALUE], the resulting `$otherName` value represents
+                * If this value is in the range of `Char` codes `Char.MIN_VALUE..Char.MAX_VALUE`,
-                 * the same numerical value as this `$thisName`.
+                * the resulting `Char` code is equal to this value.
-                 *
+                *
-                 * The resulting `$otherName` value is represented by the least significant ${toIntegral.bitSize} bits of this `$thisName` value.
+                * The resulting `Char` code is represented by the least significant 16 bits of this `$thisName` value.
-                 */
+                */
                 """
             }
-        } else if (compareByDomainCapacity(toIntegral, fromIntegral) > 0) {
+        } else if (compareByDomainCapacity(toIntegral, fromIntegral) < 0) {
-            if (toIntegral == PrimitiveType.CHAR) {
-                """
-                 * Returns the `$otherName` with the numeric value equal to this value sign-extended to ${toIntegral.bitSize} bits.
-                 */
-                """
-            } else {
-                """
-                 * The resulting `$otherName` value represents the same numerical value as this `$thisName`.
-                 *
-                 * The least significant ${fromIntegral.bitSize} bits of the resulting `$otherName` value are the same as the binary representation of this `$thisName` value,
-                 * whereas the most significant ${toIntegral.bitSize - fromIntegral.bitSize} bits are filled with the bit sign of this value.
-                 */
-                """
-            }
-        } else { // Short -> Char
             """
-             * Returns the `$otherName` with the numeric value equal to this value.
+             * If this value is in [$otherName.MIN_VALUE]..[$otherName.MAX_VALUE], the resulting `$otherName` value represents
+             * the same numerical value as this `$thisName`.
+             *
+             * The resulting `$otherName` value is represented by the least significant ${toIntegral.bitSize} bits of this `$thisName` value.
+             */
+            """
+        } else {
+            """
+             * The resulting `$otherName` value represents the same numerical value as this `$thisName`.
+             *
+             * The least significant ${fromIntegral.bitSize} bits of the resulting `$otherName` value are the same as the binary representation of this `$thisName` value,
+             * whereas the most significant ${toIntegral.bitSize - fromIntegral.bitSize} bits are filled with the bit sign of this value.
              */
             """
         }