Integer

Integer vs Int

The Integer type is the default integer type provided by Kotools Types, designed to replace Kotlin integer types (Byte, Short, Int and Long) where correctness matters.

This type intentionally avoids names like BigInteger or BigInt, as its behavior is part of its contract and not an implementation detail.

On JVM, this type coexists with java.lang.Integer. In Kotlin, developers typically use Int, so this rarely causes confusion in practice.

Motivations

Integer overflow

Problem: Adding, subtracting or multiplying Kotlin integer types can lead to an overflow, which produces unexpected behavior.

val x = 9223372036854775807
val y = 10
check(x + y == -9223372036854775799) // instead of 9223372036854775817
check(-x - y == 9223372036854775799) // instead of -9223372036854775817
check(x * y == -10L) // instead of 92233720368547758070

Solution: The Integer type can add, subtract or multiply integers without producing an overflow.

val x: Integer = Integer.fromLong(9223372036854775807)
val y: Integer = Integer.fromLong(10)
check(x + y == Integer.parse("9223372036854775817"))
check(-x - y == Integer.parse("-9223372036854775817"))
check(x * y == Integer.parse("92233720368547758070"))

Division by zero

Problem: Performing division and remainder operations by zero on Kotlin integer types have different behavior per platform: throw an ArithmeticException on JVM and Native platforms, and return 0 on JS platform.

// JVM and Native platforms
val quotient: Result<Int> = runCatching { 12 / 0 }
val remainder: Result<Int> = runCatching { 12 % 0 }
check(quotient.exceptionOrNull() is ArithmeticException)
check(remainder.exceptionOrNull() is ArithmeticException)

// JS platform
check(12 / 0 == 0)
check(12 % 0 == 0)

Solution: Division and remainder operations on Integer type take a NonZeroInteger divisor, which rejects zero at construction. This makes dividing by zero unrepresentable: these operations can never throw or return null because of a zero divisor.

val exception: Throwable? = runCatching { NonZeroInteger.fromLong(0) }
    .exceptionOrNull()
check(exception is IllegalArgumentException)

Euclidean division

Problem: Performing a remainder operation on Kotlin integer types with a negative dividend returns a negative result, which differs from the mathematical definition of the remainder.

check(-7 % 2 == -1) // instead of 1

Solution: Division and remainder operations on Integer type follow Euclidean semantics: the remainder is always non-negative (0 ≤ r < |b|).

val x: Integer = Integer.fromLong(-7)
val y: NonZeroInteger = NonZeroInteger.fromLong(2)

val quotient: Integer = x / y
val remainder: NonNegativeInteger = x % y

check(quotient == Integer.fromLong(-4))
check(remainder == NonNegativeInteger.fromLong(1))
check(x == quotient * y.toInteger() + remainder.toInteger())

This guarantee covers both halves of the Euclidean division theorem, each encoded directly in the signature of div and rem rather than asserted in documentation prose: the divisor can never be zero, because both functions require a NonZeroInteger, and the remainder can never be negative, because rem returns a NonNegativeInteger instead of an Integer.

Key features

• Creations: Create from Kotlin integer types or decimal string (see fromLong and parse).

• Comparisons: Compare integers using structural equality (x == y, x != y) and ordering operators (x < y, x <= y, x > y, x >= y).

• Arithmetic operations: Add (x + y), subtract (x - y), multiply (x * y), divide (x / y), compute remainders (x % y), and negate (-x) integers without overflow.

• Conversions: Convert to its decimal string representation (see Integer.toString) or to a Long (see toLong).