Class Natural

java.lang.Object
java.lang.Number
org.episteme.core.mathematics.numbers.integers.Natural
All Implemented Interfaces:
Serializable, Comparable<Natural>, AbelianMonoid<Natural>, Magma<Natural>, Monoid<Natural>, Semiring<Natural>, Set<Natural>
public abstract class Natural extends Number implements Semiring<Natural>, Comparable<Natural>
Abstract base class for natural numbers (â„• = {0, 1, 2, ...}).

Natural numbers form a semiring under addition and multiplication. This class provides a smart factory that automatically chooses the most efficient backing implementation:

    Since:
    1.0
    Author:
    Silvere Martin-Michiellot, Gemini AI (Google DeepMind)
    See Also:

    • Field Details

      • ZERO

        public static final Natural ZERO
        The natural number 0

      • ONE

        public static final Natural ONE
        The natural number 1

    • Method Details

      • of

        public static Natural of(int value)
        Creates a natural number from an int value.
        Parameters:
        value - the value (must be non-negative)
        Returns:
        the Natural instance
        Throws:
        IllegalArgumentException - if value is negative

      • of

        public static Natural of(long value)
        Creates a natural number from a long value. Automatically selects optimal backing implementation.
        Parameters:
        value - the value (must be non-negative)
        Returns:
        the Natural instance
        Throws:
        IllegalArgumentException - if value is negative

      • of

        public static Natural of(BigInteger value)
        Creates a natural number from a BigInteger. Automatically selects optimal backing implementation.
        Parameters:
        value - the value (must be non-negative)
        Returns:
        the Natural instance
        Throws:
        IllegalArgumentException - if value is negative or null

      • add

        public abstract Natural add(Natural other)
        Adds another natural number.
        Parameters:
        other - the addend
        Returns:
        this + other

      • subtract

        public abstract Natural subtract(Natural other)
        Subtracts another natural number.
        Parameters:
        other - the subtrahend
        Returns:
        this - other
        Throws:
        ArithmeticException - if the result would be negative

      • multiply

        public abstract Natural multiply(Natural other)
        Multiplies by another natural number.
        Parameters:
        other - the multiplicand
        Returns:
        this × other

      • divide

        public abstract Natural divide(Natural other)
        Divides by another natural number (integer division).
        Parameters:
        other - the divisor
        Returns:
        this ÷ other (rounded down)
        Throws:
        ArithmeticException - if other is zero

      • modulo

        public abstract Natural modulo(Natural other)
        Computes this modulo another natural number.
        Parameters:
        other - the modulus
        Returns:
        this mod other
        Throws:
        ArithmeticException - if other is zero

      • isZero

        public abstract boolean isZero()
        Returns true if this natural number is zero.

      • isOne

        public abstract boolean isOne()
        Returns true if this natural number is one.

      • longValue

        public abstract long longValue()
        Converts this natural number to a long.
        Specified by:
        longValue in class Number
        Returns:
        the long value
        Throws:
        ArithmeticException - if the value doesn't fit in a long

      • bigIntegerValue

        public abstract BigInteger bigIntegerValue()
        Converts this natural number to a BigInteger.
        Returns:
        the BigInteger value (never null)

      • toBigInteger

        public BigInteger toBigInteger()
        Alias for bigIntegerValue() for compatibility.
        Returns:
        the BigInteger value (never null)

      • equals

        public abstract boolean equals(Object obj)
        Overrides:
        equals in class Object

      • hashCode

        public abstract int hashCode()
        Overrides:
        hashCode in class Object

      • toString

        public abstract String toString()
        Overrides:
        toString in class Object

      • compareTo

        public abstract int compareTo(Natural other)
        Specified by:
        compareTo in interface Comparable<Natural>