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

parse

Returns an Integer representing the number described by value, or throws NumberFormatException if the value doesn't represent an integer.

A valid integer representation is defined as:

integer = [sign] 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 and plus sign are ignored when interpreting value. As a result, calling this function with 123 and +000123 produces the same integer.

Calling from Kotlin

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

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

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

    check(Integer.parseOrNull(input) == null)
}

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

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

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

// Parsing preserves canonical representation:
parsesTo(input = "42", expected = "42")
parsesTo(input = "-42", expected = "-42")

// Parsing fails with noninteger string:
parsingFailsWith("")
parsingFailsWith("+")
parsingFailsWith("-")
parsingFailsWith("12a")
parsingFailsWith("3.14")
parsingFailsWith(" 42")

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(Integer.parse(input))
            .equals(expected);
    if (!check) throw new IllegalStateException("Check failed.");
};

final Consumer<String> parsingFailsWith = (input) -> {
    try {
        Integer.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("000", "0");
parsesTo.accept("+000", "0");
parsesTo.accept("-000", "0");

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

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

// Parsing preserves canonical representation:
parsesTo.accept("42", "42");
parsesTo.accept("-42", "-42");

// Parsing fails with noninteger string:
parsingFailsWith.accept("");
parsingFailsWith.accept("+");
parsingFailsWith.accept("-");
parsingFailsWith.accept("12a");
parsingFailsWith.accept("3.14");
parsingFailsWith.accept(" 42");

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

Since

5.2.0