Add missing api: radix overloads, mathContext and scale overloads, orNull overloads

Move string-to-number conversions and their tests near to existing ones

Add documentation and copyrights.

libraries/stdlib/src/kotlin/text/StringNumberConversions.kt

@@ -340,6 +340,105 @@ public fun String.toFloatOrNull(): Float? = screenFloatValue(this, java.lang.Flo
 @kotlin.jvm.JvmVersion
 public fun String.toDoubleOrNull(): Double? = screenFloatValue(this, java.lang.Double::parseDouble)
 
+/**
+ * Parses the string as a [java.math.BigInteger] number and returns the result.
+ * @throws NumberFormatException if the string is not a valid representation of a number.
+ */
+@SinceKotlin("1.2")
+@kotlin.jvm.JvmVersion
+@kotlin.internal.InlineOnly
+public inline fun String.toBigInteger(): java.math.BigInteger =
+        java.math.BigInteger(this)
+
+/**
+ * Parses the string as a [java.math.BigInteger] number and returns the result.
+ * @throws NumberFormatException if the string is not a valid representation of a number.
+ * @throws IllegalArgumentException when [radix] is not a valid radix for string to number conversion.
+ */
+@SinceKotlin("1.2")
+@kotlin.jvm.JvmVersion
+@kotlin.internal.InlineOnly
+public inline fun String.toBigInteger(radix: Int): java.math.BigInteger =
+        java.math.BigInteger(this, checkRadix(radix))
+
+/**
+ * Parses the string as a [java.math.BigInteger] number and returns the result
+ * or `null` if the string is not a valid representation of a number.
+ */
+@SinceKotlin("1.2")
+@kotlin.jvm.JvmVersion
+public fun String.toBigIntegerOrNull(): java.math.BigInteger? = toBigIntegerOrNull(10)
+
+/**
+ * Parses the string as a [java.math.BigInteger] number and returns the result
+ * or `null` if the string is not a valid representation of a number.
+ *
+ * @throws IllegalArgumentException when [radix] is not a valid radix for string to number conversion.
+ */
+@SinceKotlin("1.2")
+@kotlin.jvm.JvmVersion
+public fun String.toBigIntegerOrNull(radix: Int): java.math.BigInteger? {
+    checkRadix(radix)
+    val length = this.length
+    when (length) {
+        0 -> return null
+        1 -> if (digitOf(this[0], radix) < 0) return null
+        else -> {
+            val start = if (this[0] == '-') 1 else 0
+            for (index in start until length) {
+                if (digitOf(this[index], radix) < 0)
+                    return null
+            }
+        }
+    }
+    return toBigInteger(radix)
+}
+
+
+/**
+ * Parses the string as a [java.math.BigDecimal] number and returns the result.
+ * @throws NumberFormatException if the string is not a valid representation of a number.
+ */
+@SinceKotlin("1.2")
+@kotlin.jvm.JvmVersion
+@kotlin.internal.InlineOnly
+public inline fun String.toBigDecimal(): java.math.BigDecimal =
+        java.math.BigDecimal(this)
+
+/**
+ * Parses the string as a [java.math.BigDecimal] number and returns the result.
+ * @throws NumberFormatException if the string is not a valid representation of a number.
+ *
+ * @param mathContext specifies the precision and the rounding mode.
+ * @throws ArithmeticException if the rounding is needed, but the rounding mode is [java.math.RoundingMode.UNNECESSARY].
+ */
+@SinceKotlin("1.2")
+@kotlin.jvm.JvmVersion
+@kotlin.internal.InlineOnly
+public inline fun String.toBigDecimal(mathContext: java.math.MathContext): java.math.BigDecimal =
+        java.math.BigDecimal(this, mathContext)
+
+/**
+ * Parses the string as a [java.math.BigDecimal] number and returns the result
+ * or `null` if the string is not a valid representation of a number.
+ */
+@SinceKotlin("1.2")
+@kotlin.jvm.JvmVersion
+public fun String.toBigDecimalOrNull(): java.math.BigDecimal? =
+        screenFloatValue(this) { it.toBigDecimal() }
+
+/**
+ * Parses the string as a [java.math.BigDecimal] number and returns the result
+ * or `null` if the string is not a valid representation of a number.
+ *
+ * @param mathContext specifies the precision and the rounding mode.
+ * @throws ArithmeticException if the rounding is needed, but the rounding mode is [java.math.RoundingMode.UNNECESSARY].
+ */
+@SinceKotlin("1.2")
+@kotlin.jvm.JvmVersion
+public fun String.toBigDecimalOrNull(mathContext: java.math.MathContext): java.math.BigDecimal? =
+        screenFloatValue(this) { it.toBigDecimal(mathContext) }
+
 /**
  * Recommended floating point number validation RegEx from the javadoc of `java.lang.Double.valueOf(String)`
  */

libraries/stdlib/src/kotlin/util/BigDecimals.kt

@@ -1,3 +1,19 @@
+/*
+ * Copyright 2010-2017 JetBrains s.r.o.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 @file:kotlin.jvm.JvmMultifileClass
 @file:kotlin.jvm.JvmName("MathKt")
 @file:kotlin.jvm.JvmVersion
@@ -5,6 +21,7 @@
 package kotlin
 
 import java.math.BigDecimal
+import java.math.MathContext
 import java.math.RoundingMode
 
 /**
@@ -67,31 +84,74 @@ public inline operator fun BigDecimal.inc(): BigDecimal = this.add(BigDecimal.ON
 @kotlin.internal.InlineOnly
 public inline operator fun BigDecimal.dec(): BigDecimal = this.subtract(BigDecimal.ONE)
 
-
+/**
-@SinceKotlin("1.2")
+ * Returns the value of this [Int] number as a [BigDecimal].
-@kotlin.internal.InlineOnly
+ */
-public inline fun String.toBigDecimal(): BigDecimal = BigDecimal(this)
-
 @SinceKotlin("1.2")
 @kotlin.internal.InlineOnly
 public inline fun Int.toBigDecimal(): BigDecimal = BigDecimal(this)
 
+
+/**
+ * Returns the value of this [Int] number as a [BigDecimal].
+ * @param mathContext specifies the precision and the rounding mode.
+ */
+@SinceKotlin("1.2")
+@kotlin.internal.InlineOnly
+public inline fun Int.toBigDecimal(mathContext: MathContext): BigDecimal = BigDecimal(this, mathContext)
+
+/**
+ * Returns the value of this [Long] number as a [BigDecimal].
+ */
 @SinceKotlin("1.2")
 @kotlin.internal.InlineOnly
 public inline fun Long.toBigDecimal(): BigDecimal = BigDecimal(this)
 
-/*
+/**
- * JDK documentation recommends using `BigDecimal(String)` instead of `BigDecimal(double)`
+ * Returns the value of this [Long] number as a [BigDecimal].
- * For more details consult http://docs.oracle.com/javase/7/docs/api/java/math/BigDecimal.html
+ * @param mathContext specifies the precision and the rounding mode.
+ */
+@SinceKotlin("1.2")
+@kotlin.internal.InlineOnly
+public inline fun Long.toBigDecimal(mathContext: MathContext): BigDecimal = BigDecimal(this, mathContext)
+
+
+/**
+ * Returns the value of this [Float] number as a [BigDecimal].
+ *
+ * The number is converted to a string and then the string is converted to a [BigDecimal].
  */
 @SinceKotlin("1.2")
 @kotlin.internal.InlineOnly
 public inline fun Float.toBigDecimal(): BigDecimal = BigDecimal(this.toString())
 
-/*
+/**
- * JDK documentation recommends using `BigDecimal(String)` instead of `BigDecimal(double)`
+ * Returns the value of this [Float] number as a [BigDecimal].
- * For more details consult http://docs.oracle.com/javase/7/docs/api/java/math/BigDecimal.html
+ *
+ * The number is converted to a string and then the string is converted to a [BigDecimal].
+ *
+ * @param mathContext specifies the precision and the rounding mode.
+ */
+@SinceKotlin("1.2")
+@kotlin.internal.InlineOnly
+public inline fun Float.toBigDecimal(mathContext: MathContext): BigDecimal = BigDecimal(this.toString(), mathContext)
+
+/**
+ * Returns the value of this [Double] number as a [BigDecimal].
+ *
+ * The number is converted to a string and then the string is converted to a [BigDecimal].
  */
 @SinceKotlin("1.2")
 @kotlin.internal.InlineOnly
 public inline fun Double.toBigDecimal(): BigDecimal = BigDecimal(this.toString())
+
+/**
+ * Returns the value of this [Double] number as a [BigDecimal].
+ *
+ * The number is converted to a string and then the string is converted to a [BigDecimal].
+ *
+ * @param mathContext specifies the precision and the rounding mode.
+ */
+@SinceKotlin("1.2")
+@kotlin.internal.InlineOnly
+public inline fun Double.toBigDecimal(mathContext: MathContext): BigDecimal = BigDecimal(this.toString(), mathContext)

libraries/stdlib/src/kotlin/util/BigIntegers.kt

@@ -1,3 +1,19 @@
+/*
+ * Copyright 2010-2017 JetBrains s.r.o.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 @file:kotlin.jvm.JvmMultifileClass
 @file:kotlin.jvm.JvmName("MathKt")
 @file:kotlin.jvm.JvmVersion
@@ -6,6 +22,7 @@ package kotlin
 
 import java.math.BigInteger
 import java.math.BigDecimal
+import java.math.MathContext
 
 /**
  * Enables the use of the `+` operator for [BigInteger] instances.
@@ -58,45 +75,67 @@ public inline operator fun BigInteger.inc(): BigInteger = this.add(BigInteger.ON
 @kotlin.internal.InlineOnly
 public inline operator fun BigInteger.dec(): BigInteger = this.subtract(BigInteger.ONE)
 
-
+/** Inverts the bits including the sign bit in this value. */
 @SinceKotlin("1.2")
 @kotlin.internal.InlineOnly
 public inline fun BigInteger.inv(): BigInteger = this.not()
 
+/** Performs a bitwise AND operation between the two values. */
 @SinceKotlin("1.2")
 @kotlin.internal.InlineOnly
 public inline infix fun BigInteger.and(other: BigInteger): BigInteger = this.and(other)
 
+/** Performs a bitwise OR operation between the two values. */
 @SinceKotlin("1.2")
 @kotlin.internal.InlineOnly
 public inline infix fun BigInteger.or(other: BigInteger): BigInteger = this.or(other)
 
+/** Performs a bitwise XOR operation between the two values. */
 @SinceKotlin("1.2")
 @kotlin.internal.InlineOnly
 public inline infix fun BigInteger.xor(other: BigInteger): BigInteger = this.xor(other)
 
+/** Shifts this value left by [bits]. */
 @SinceKotlin("1.2")
 @kotlin.internal.InlineOnly
 public inline infix fun BigInteger.shl(n: Int): BigInteger = this.shiftLeft(n)
 
+/** Shifts this value right by [bits], filling the leftmost bits with copies of the sign bit. */
 @SinceKotlin("1.2")
 @kotlin.internal.InlineOnly
 public inline infix fun BigInteger.shr(n: Int): BigInteger = this.shiftRight(n)
 
 
-@SinceKotlin("1.2")
+/**
-@kotlin.internal.InlineOnly
+ * Returns the value of this [Int] number as a [BigInteger].
-public inline fun String.toBigInteger(): BigInteger = BigInteger(this)
+ */
-
 @SinceKotlin("1.2")
 @kotlin.internal.InlineOnly
 public inline fun Int.toBigInteger(): BigInteger = BigInteger.valueOf(this.toLong())
 
+/**
+ * Returns the value of this [Long] number as a [BigInteger].
+ */
 @SinceKotlin("1.2")
 @kotlin.internal.InlineOnly
 public inline fun Long.toBigInteger(): BigInteger = BigInteger.valueOf(this)
 
-
+/**
+ * Returns the value of this [BigInteger] number as a [BigDecimal].
+ */
 @SinceKotlin("1.2")
 @kotlin.internal.InlineOnly
 public inline fun BigInteger.toBigDecimal(): BigDecimal = BigDecimal(this)
+
+/**
+ * Returns the value of this [BigInteger] number as a [BigDecimal]
+ * scaled according to the specified [scale] and rounded according to the settings specified with [mathContext].
+ *
+ * @param scale the scale of the resulting [BigDecimal], i.e. number of decimal places of the fractional part.
+ * By default 0.
+ */
+@SinceKotlin("1.2")
+@kotlin.internal.InlineOnly
+public inline fun BigInteger.toBigDecimal(scale: Int = 0, mathContext: MathContext = MathContext.UNLIMITED): BigDecimal =
+        BigDecimal(this, scale, mathContext)
+

libraries/stdlib/test/numbers/MathJVMTest.kt

@@ -6,6 +6,8 @@ import java.math.BigDecimal
 
 import kotlin.test.*
 import org.junit.Test
+import java.math.MathContext
+import java.math.RoundingMode
 
 class MathTest {
     @Test fun testBigInteger() {
@@ -29,15 +31,33 @@ class MathTest {
         assertEquals(BigInteger("1"), a xor b)
         assertEquals(BigInteger("4"), a shl 1)
         assertEquals(BigInteger("1"), a shr 1)
+        assertEquals(BigInteger("0"), a shr 2)
         assertEquals(BigInteger("-4"), -a shl 1)
         assertEquals(BigInteger("-1"), -a shr 1)
+        assertEquals(BigInteger("-1"), -a shr 2)
 
-        assertEquals(BigInteger("2"), "2".toBigInteger())
-        assertEquals(BigInteger("-3"), "-3".toBigInteger())
         assertEquals(BigInteger("2"),  2.toBigInteger())
         assertEquals(BigInteger("-3"), -3L.toBigInteger())
 
         assertEquals(BigDecimal("2"), a.toBigDecimal())
+        assertEquals(BigDecimal("0.02"), a.toBigDecimal(2))
+        assertEquals(BigDecimal("2E+2"), a.toBigDecimal(-2))
+        assertEquals(BigDecimal("2.6E+3"), BigInteger("253").toBigDecimal(-1, MathContext(2, RoundingMode.UP)))
+        assertEquals(BigDecimal("2.6E+2"), BigInteger("253").toBigDecimal(mathContext = MathContext(2, RoundingMode.UP)))
+        assertEquals(BigDecimal("3"), BigInteger("253").toBigDecimal(2, MathContext(1, RoundingMode.UP)))
+
+
+
+        var c = 2.toBigInteger()
+        assertEquals(BigInteger("2"), c++)
+        assertEquals(BigInteger("3"), c)
+        assertEquals(BigInteger("4"), ++c)
+        assertEquals(BigInteger("4"), c)
+
+        assertEquals(BigInteger("4"), c--)
+        assertEquals(BigInteger("3"), c)
+        assertEquals(BigInteger("2"), --c)
+        assertEquals(BigInteger("2"), c)
     }
 
     @Test fun testBigDecimal() {
@@ -56,29 +76,21 @@ class MathTest {
         assertEquals(BigDecimal("3"), a.inc())
         assertEquals(BigDecimal("1"), a.dec())
 
-        assertEquals(BigDecimal("2.5"), "2.5".toBigDecimal())
-        assertEquals(BigDecimal("-3"), "-3".toBigDecimal())
         assertEquals(BigDecimal("2"),  2.toBigDecimal())
         assertEquals(BigDecimal("-3"), -3L.toBigDecimal())
         assertEquals(BigDecimal("2.0"), 2f.toBigDecimal())
         assertEquals(BigDecimal("0.5"),  0.5.toBigDecimal())
+
+        var c = "1.5".toBigDecimal()
+        assertEquals(BigDecimal("1.5"), c++)
+        assertEquals(BigDecimal("2.5"), c)
+        assertEquals(BigDecimal("3.5"), ++c)
+        assertEquals(BigDecimal("3.5"), c)
+        assertEquals(BigDecimal("3.5"), c--)
+        assertEquals(BigDecimal("2.5"), c)
+        assertEquals(BigDecimal("1.5"), --c)
+        assertEquals(BigDecimal("1.5"), c)
     }
 
-    @Test fun mutatingBigNumbers() {
-        var a = 2.toBigInteger()
-        var b = "1.5".toBigDecimal()
-
-        a++
-        b++
-
-        assertEquals(BigInteger("3"), a)
-        assertEquals(BigDecimal("2.5"), b)
-
-        --a
-        --b
-
-        assertEquals(BigInteger("2"), a)
-        assertEquals(BigDecimal("1.5"), b)
-    }
 }
 

libraries/stdlib/test/text/StringNumberConversionTest.kt

@@ -224,6 +224,66 @@ class StringNumberConversionTest {
         assertFailsWith<IllegalArgumentException>("Expected to fail with radix 37") { 37L.toString(radix = 37) }
         assertFailsWith<IllegalArgumentException>("Expected to fail with radix 1") { 1L.toString(radix = 1) }
     }
+
+    @kotlin.jvm.JvmVersion
+    @Test fun toBigInteger() {
+        compareConversion(String::toBigInteger, String::toBigIntegerOrNull) {
+            assertProduces("0", java.math.BigInteger.ZERO)
+            assertProduces("1", java.math.BigInteger.ONE)
+            assertProduces("-1", java.math.BigInteger.ONE.negate())
+            assertProduces("100000000000000000000", java.math.BigInteger("100000000000000000000"))
+            assertFailsOrNull("")
+            assertFailsOrNull("-")
+            assertFailsOrNull("a")
+            assertFailsOrNull("-x")
+            assertFailsOrNull("1000 000")
+        }
+
+        compareConversionWithRadix(String::toBigInteger, String::toBigIntegerOrNull) {
+            assertProduces(16, "ABCDEF90ABCDEF9012345678", java.math.BigInteger("ABCDEF90ABCDEF9012345678", 16))
+            assertProduces(36, "HazelnutHazelnut", java.math.BigInteger.valueOf(1356099454469L).let { it.multiply(java.math.BigInteger.valueOf(36).pow(8)).add(it) })
+
+            assertFailsOrNull(16, "EFG")
+            assertFailsOrNull(10, "-1A")
+            assertFailsOrNull(2, "-")
+            assertFailsOrNull(3, "")
+
+            assertFailsWith<IllegalArgumentException>("Expected to fail with radix 37") { "37".toBigInteger(radix = 37) }
+            assertFailsWith<IllegalArgumentException>("Expected to fail with radix 1") { "1".toBigIntegerOrNull(radix = 1) }
+        }
+    }
+
+    @kotlin.jvm.JvmVersion
+    @Test fun toBigDecimal() {
+        fun bd(value: String) = java.math.BigDecimal(value)
+        compareConversion(String::toBigDecimal, String::toBigDecimalOrNull) {
+
+            assertProduces("-77", bd("-77"))
+            assertProduces("-77.0", bd("-77.0"))
+            assertProduces("77.", bd("77"))
+            assertProduces("123456789012345678901234567890.123456789", bd("123456789012345678901234567890.123456789"))
+            assertProduces("-1.77", bd("-1.77"))
+            assertProduces("+.77", bd("0.77"))
+            assertProduces("7.7e1", bd("77"))
+            assertProduces("+770e-1", bd("77.0"))
+
+            assertFailsOrNull("7..7")
+            assertFailsOrNull("\t-77 \n")
+            assertFailsOrNull("007 not a number")
+            assertFailsOrNull("")
+            assertFailsOrNull("   ")
+        }
+
+        var mc = java.math.MathContext(3, java.math.RoundingMode.UP)
+        compareConversion( { it.toBigDecimal(mc) }, { it.toBigDecimalOrNull(mc) }) {
+            assertProduces("1.991", bd("2.00"))
+
+            mc = java.math.MathContext(1, java.math.RoundingMode.UNNECESSARY)
+
+            assertFailsWith<ArithmeticException> { "2.991".toBigDecimal(mc) }
+            assertFailsWith<ArithmeticException> { "2.991".toBigDecimalOrNull(mc) }
+        }
+    }
 }