Straighten Char-to-code and Char-to-digit conversions out #KT-23451

2020-12-08 11:51:16 +03:00
parent 79e426270c
commit 662787b12b
17 changed files with 575 additions and 14 deletions
@@ -0,0 +1,50 @@
+/*
+ * Copyright 2010-2020 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.
+ */
+
+package kotlin
+
+
+/**
+ * Creates a Char with the specified [code], or throws an exception if the [code] is out of `Char.MIN_VALUE.code..Char.MAX_VALUE.code`.
+ *
+ * If the program that calls this function is written in a way that only valid [code] is passed as the argument,
+ * using the overload that takes a [UShort] argument is preferable (`Char(intValue.toUShort())`).
+ * That overload doesn't check validity of the argument, and may improve program performance when the function is called routinely inside a loop.
+ *
+ * @sample samples.text.Chars.charFromCode
+ */
+@OptIn(ExperimentalUnsignedTypes::class)
+@ExperimentalStdlibApi
+@SinceKotlin("1.4")
+@kotlin.internal.InlineOnly
+public inline fun Char(code: Int): Char {
+    if (code < Char.MIN_VALUE.code || code > Char.MAX_VALUE.code) {
+        throw IllegalArgumentException("Invalid Char code: $code")
+    }
+    return Char(code.toUShort())
+}
+
+/**
+ * Creates a Char with the specified [code].
+ *
+ * @sample samples.text.Chars.charFromCode
+ */
+@OptIn(ExperimentalUnsignedTypes::class)
+@ExperimentalStdlibApi
+@SinceKotlin("1.4")
+@Suppress("NO_ACTUAL_FOR_EXPECT")
+public expect fun Char(code: UShort): Char
+
+/**
+ * Returns the code of this Char.
+ *
+ * Code of a Char is the value it was constructed with, and the UTF-16 code unit corresponding to this Char.
+ *
+ * @sample samples.text.Chars.code
+ */
+@ExperimentalStdlibApi
+@SinceKotlin("1.4")
+@kotlin.internal.InlineOnly
+public inline val Char.code: Int get() = this.toInt()
@@ -8,6 +8,127 @@

 package kotlin.text

+/**
+ * Returns the numeric value of the decimal digit that this Char represents.
+ * Throws an exception if this Char is not a valid decimal digit.
+ *
+ * A Char is considered to represent a decimal digit if the Char is one of the ASCII decimal digits '0' through '9'.
+ * In this case, `this.code - '0'.code` is returned.
+ *
+ * @sample samples.text.Chars.digitToInt
+ */
+@ExperimentalStdlibApi
+@SinceKotlin("1.4")
+public fun Char.digitToInt(): Int {
+    if (this in '0'..'9') {
+        return this - '0'
+    }
+    throw IllegalArgumentException("Char $this is not a decimal digit")
+}
+
+/**
+ * Returns the numeric value of the digit that this Char represents in the specified [radix].
+ * Throws an exception if the [radix] is not in the range `2..36` or if this Char is not a valid digit in the specified [radix].
+ *
+ * A Char is considered to represent a digit in the specified [radix] if at least one of the following is true:
+ *  - The Char is one of the ASCII decimal digits '0' through '9' and its [code] is less than `radix + '0'.code`. In this case, `this.code - '0'.code` is returned.
+ *  - The Char is one of the uppercase Latin letters 'A' through 'Z' and its [code] is less than `radix + 'A'.code - 10`. In this case, `this.code - 'A'.code + 10` is returned.
+ *  - The Char is one of the lowercase Latin letters 'a' through 'z' and its [code] is less than `radix + 'a'.code - 10`. In this case, `this.code - 'a'.code + 10` is returned.
+ *
+ * @sample samples.text.Chars.digitToInt
+ */
+@ExperimentalStdlibApi
+@SinceKotlin("1.4")
+public fun Char.digitToInt(radix: Int): Int {
+    return digitToIntOrNull(radix) ?: throw IllegalArgumentException("Char $this is not a digit in the given radix=$radix")
+}
+
+/**
+ *
+ * Returns the numeric value of the decimal digit that this Char represents, or `null` if this Char is not a valid decimal digit.
+ *
+ * A Char is considered to represent a decimal digit if the Char is one of the ASCII decimal digits '0' through '9'.
+ * In this case, `this.code - '0'.code` is returned.
+ *
+ * @sample samples.text.Chars.digitToIntOrNull
+ */
+@ExperimentalStdlibApi
+@SinceKotlin("1.4")
+public fun Char.digitToIntOrNull(): Int? {
+    if (this in '0'..'9') {
+        return this - '0'
+    }
+    return null
+}
+
+/**
+ * Returns the numeric value of the digit that this Char represents in the specified [radix], or `null` if this Char is not a valid digit in the specified [radix].
+ * Throws an exception if the [radix] is not in the range `2..36`.
+ *
+ * A Char is considered to represent a digit in the specified [radix] if at least one of the following is true:
+ *  - The Char is one of the ASCII decimal digits '0' through '9' and its [code] is less than `radix + '0'.code`. In this case, `this.code - '0'.code` is returned.
+ *  - The Char is one of the uppercase Latin letters 'A' through 'Z' and its [code] is less than `radix + 'A'.code - 10`. In this case, `this.code - 'A'.code + 10` is returned.
+ *  - The Char is one of the lowercase Latin letters 'a' through 'z' and its [code] is less than `radix + 'a'.code - 10`. In this case, `this.code - 'a'.code + 10` is returned.
+ *
+ * @sample samples.text.Chars.digitToIntOrNull
+ */
+@ExperimentalStdlibApi
+@SinceKotlin("1.4")
+public fun Char.digitToIntOrNull(radix: Int): Int? {
+    if (radix !in 2..36) {
+        throw IllegalArgumentException("Invalid radix: $radix. Valid radix values are in range 2..36")
+    }
+    if (this in '0'..'9') {
+        val digit = this - '0'
+        return if (digit < radix) digit else null
+    }
+    val a = if (this <= 'Z') 'A' else 'a'
+    val digit = 10 + (this - a)
+    return if (digit in 10 until radix) digit else null
+}
+
+/**
+ * Returns the Char that represents this decimal digit.
+ * Throws an exception if this value is not in the range `0..9`.
+ *
+ * If this value is in `0..9`, the decimal digit Char with code `'0'.code + this` is returned.
+ *
+ * @sample samples.text.Chars.digitToChar
+ */
+@ExperimentalStdlibApi
+@SinceKotlin("1.4")
+public fun Int.digitToChar(): Char {
+    if (this in 0..9) {
+        return '0' + this
+    }
+    throw IllegalArgumentException("Int $this is not a decimal digit")
+}
+
+/**
+ * Returns the Char that represents this numeric digit value in the specified [radix].
+ * Throws an exception if the [radix] is not in the range `2..36` or if this value is not in the range `0 until radix`.
+ *
+ * If this value is less than `10`, the decimal digit Char with code `'0'.code + this` is returned.
+ * Otherwise, the uppercase Latin letter with code `'A'.code + this - 10` is returned.
+ *
+ * @sample samples.text.Chars.digitToChar
+ */
+@ExperimentalStdlibApi
+@SinceKotlin("1.4")
+public fun Int.digitToChar(radix: Int): Char {
+    if (radix !in 2..36) {
+        throw IllegalArgumentException("Invalid radix: $radix. Valid radix values are in range 2..36")
+    }
+    if (this < 0 || this >= radix) {
+        throw IllegalArgumentException("Digit $this does not represent a valid digit in radix $radix")
+    }
+    return if (this < 10) {
+        '0' + this
+    } else {
+        'A' + this - 10
+    }
+}
+
 /**
 * Converts this character to lower case using Unicode mapping rules of the invariant locale.
 */