types/org.kotools.types.number/Decimal/Companion/parse

parse

Returns a Decimal representing the number described by value, or throws NumberFormatException if value doesn't represent a decimal number.

A valid decimal representation is defined as:

decimal = [sign] digit {digit} ['.' digit {digit}]
sign    = "+" | "-"
digit   = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"

(grammar written in Wirth-style EBNF, where [] denotes optionality and {} denotes repetition)

Leading zeros, leading plus sign, and trailing fractional zeros are ignored when interpreting value. As a result, calling this function with 3.14, +03.140, and 3.14000 produces the same decimal.

Calling from Kotlin

Here's an example of calling this function from Kotlin code:

fun parsesTo(input: String, expected: String) {
    check(Decimal.parse(input).toString() == expected)
    check(Decimal.parseOrNull(input).toString() == expected)
}

fun parsingFailsWith(input: String) {
    val exception: Throwable? = runCatching { Decimal.parse(input) }
        .exceptionOrNull()
    check(exception is NumberFormatException)
    check(Decimal.parseOrNull(input) == null)
}

// Parsing normalizes zero:
parsesTo(input = "0", expected = "0")
parsesTo(input = "+0", expected = "0")
parsesTo(input = "-0", expected = "0")
parsesTo(input = "0.0", expected = "0")
parsesTo(input = "-0.0", expected = "0")

// Parsing removes leading plus sign:
parsesTo(input = "+3.14", expected = "3.14")

// Parsing removes leading zeros:
parsesTo(input = "00042", expected = "42")
parsesTo(input = "-00042", expected = "-42")

// Parsing removes trailing fractional zeros:
parsesTo(input = "3.10", expected = "3.1")
parsesTo(input = "5.00", expected = "5")

// Parsing preserves canonical representation:
parsesTo(input = "3.14", expected = "3.14")
parsesTo(input = "-2.5", expected = "-2.5")
parsesTo(input = "0.001", expected = "0.001")

// Parsing fails with non-decimal string:
parsingFailsWith("")
parsingFailsWith("+")
parsingFailsWith("-")
parsingFailsWith(".")
parsingFailsWith(".5")
parsingFailsWith("3.")
parsingFailsWith("1.2.3")
parsingFailsWith("1.5E3")
parsingFailsWith("12a")

Calling from Java

Here's an example of calling this function from Java code:

final BiConsumer<String, String> parsesTo = (input, expected) -> {
    final boolean check = String.valueOf(Decimal.parse(input))
            .equals(expected);
    if (!check) throw new IllegalStateException("Check failed.");
};

final Consumer<String> parsingFailsWith = (input) -> {
    try {
        Decimal.parse(input);
        throw new IllegalStateException("Check failed.");
    } catch (NumberFormatException ignored) {
    }
};

// Parsing normalizes zero:
parsesTo.accept("0", "0");
parsesTo.accept("+0", "0");
parsesTo.accept("-0", "0");
parsesTo.accept("0.0", "0");
parsesTo.accept("-0.0", "0");

// Parsing removes leading plus sign:
parsesTo.accept("+3.14", "3.14");

// Parsing removes leading zeros:
parsesTo.accept("00042", "42");
parsesTo.accept("-00042", "-42");

// Parsing removes trailing fractional zeros:
parsesTo.accept("3.10", "3.1");
parsesTo.accept("5.00", "5");

// Parsing preserves canonical representation:
parsesTo.accept("3.14", "3.14");
parsesTo.accept("-2.5", "-2.5");
parsesTo.accept("0.001", "0.001");

// Parsing fails with non-decimal string:
parsingFailsWith.accept("");
parsingFailsWith.accept("+");
parsingFailsWith.accept("-");
parsingFailsWith.accept(".");
parsingFailsWith.accept(".5");
parsingFailsWith.accept("3.");
parsingFailsWith.accept("1.2.3");
parsingFailsWith.accept("1.5E3");
parsingFailsWith.accept("12a");

See the parseOrNull function for returning null instead of throwing an exception in case of invalid value.