math

tuprolog.math

Arbitrary-precision numbers, as used by numeric terms.

Logic numbers never overflow nor lose digits: tuprolog.core.Integer terms hold a BigInteger, and tuprolog.core.Real terms a BigDecimal (a decimal number, not a binary floating-point one). This package exposes these JVM types, with MathContext and RoundingMode (the settings of decimal arithmetic) and some constants, and converts them from and to Python numbers: big_integer and python_integer (for ints), big_decimal and python_decimal (for floats and decimal.Decimals), jvm_rounding_mode (for the rounding modes of Python's decimal).

Examples:

>>> from tuprolog.math import big_decimal, big_integer, python_decimal, python_integer
>>> python_integer(big_integer(2**100)) == 2**100
True
>>> python_decimal(big_decimal("0.1"))
Decimal('0.1')

See Also

tuprolog.core.integer and tuprolog.core.real, building numeric terms.

BigInteger module-attribute

BigInteger = _ktmath.BigInteger

An immutable integer of arbitrary precision, as used by tuprolog.core.Integer terms.

Build them with big_integer (and convert them back with python_integer), or BigInteger.of. Members include arithmetic (plus, minus, times, div, rem, pow, ...), comparison (compareTo), and toString(radix).

Examples:

>>> from tuprolog.math import big_decimal, big_integer
>>> big_integer(6).times(big_integer(7))
42

Note

The JVM class org.gciatto.kt.math.BigInteger, a multi-platform port of Java's java.math.BigInteger.

BigDecimal module-attribute

BigDecimal = _ktmath.BigDecimal

An immutable decimal number of arbitrary precision, as used by tuprolog.core.Real terms.

Build them with big_decimal (and convert them back with python_decimal), or BigDecimal.of. Members include arithmetic (plus, minus, times, div, ..., optionally taking a MathContext), comparison (compareTo), getScale(), getPrecision(), and stripTrailingZeros().

Examples:

>>> from tuprolog.math import big_decimal, big_integer
>>> big_decimal("2.5").plus(big_decimal("1.25"))
3.75

Note

The JVM class org.gciatto.kt.math.BigDecimal, a multi-platform port of Java's java.math.BigDecimal.

MathContext module-attribute

MathContext = _ktmath.MathContext

The settings of arithmetic on BigDecimals: a precision (the number of significant digits, 0 for unlimited) and a RoundingMode, as MathContext(precision, rounding_mode).

The constants MathContext.UNLIMITED, DECIMAL32, DECIMAL64 and DECIMAL128 give common settings.

Examples:

>>> from tuprolog.math import big_decimal, big_integer
>>> big_decimal(1).div(big_decimal(3), MathContext(5, RoundingMode.HALF_UP))
0.33333

Note

The JVM class org.gciatto.kt.math.MathContext, a port of Java's java.math.MathContext.

RoundingMode module-attribute

RoundingMode = _ktmath.RoundingMode

How to round decimal numbers when digits must be discarded, an enumeration: UP, DOWN, CEILING, FLOOR, HALF_UP, HALF_DOWN, HALF_EVEN, UNNECESSARY (raising an error when rounding is needed).

jvm_rounding_mode converts the rounding modes of Python's decimal module into these.

Note

The JVM class org.gciatto.kt.math.RoundingMode, a port of Java's java.math.RoundingMode.

BIG_INTEGER_MAX_LONG module-attribute

BIG_INTEGER_MAX_LONG = BigInteger.of(_MAX_LONG)

The largest 64-bit signed integer, 2^63 - 1, as a BigInteger.

BIG_INTEGER_MIN_LONG module-attribute

BIG_INTEGER_MIN_LONG = BigInteger.of(_MIN_LONG)

The smallest 64-bit signed integer, -2^63, as a BigInteger.

BIG_INTEGER_ZERO module-attribute

BIG_INTEGER_ZERO = BigInteger.ZERO

The integer 0, as a BigInteger.

BIG_INTEGER_TEN module-attribute

BIG_INTEGER_TEN = BigInteger.TEN

The integer 10, as a BigInteger.

BIG_INTEGER_ONE module-attribute

BIG_INTEGER_ONE = BigInteger.ONE

The integer 1, as a BigInteger.

BIG_INTEGER_NEGATIVE_ONE module-attribute

BIG_INTEGER_NEGATIVE_ONE = BigInteger.NEGATIVE_ONE

The integer -1, as a BigInteger.

BIG_INTEGER_TWO module-attribute

BIG_INTEGER_TWO = BigInteger.TWO

The integer 2, as a BigInteger.

BIG_DECIMAL_ZERO module-attribute

BIG_DECIMAL_ZERO = BigDecimal.ZERO

The number 0, as a BigDecimal.

BIG_DECIMAL_ONE module-attribute

BIG_DECIMAL_ONE = BigDecimal.ONE

The number 1, as a BigDecimal.

BIG_DECIMAL_ONE_HALF module-attribute

BIG_DECIMAL_ONE_HALF = BigDecimal.ONE_HALF

The number 0.5, as a BigDecimal.

BIG_DECIMAL_ONE_TENTH module-attribute

BIG_DECIMAL_ONE_TENTH = BigDecimal.ONE_TENTH

The number 0.1, as a BigDecimal.

BIG_DECIMAL_E module-attribute

BIG_DECIMAL_E = BigDecimal.E

Euler's number e (2.71828...), as a BigDecimal with many digits.

BIG_DECIMAL_PI module-attribute

BIG_DECIMAL_PI = BigDecimal.PI

The number pi (3.14159...), as a BigDecimal with many digits.

big_integer

big_integer(
    value: str | int | BigInteger, radix: int | None = None
) -> BigInteger

Converts a Python integer, or a string of digits, into a BigInteger.

Parameters:

Name	Type	Description	Default
value	str | int | BigInteger	the value: an int (booleans count as 0 and 1), a string of digits (in base 10, or with a prefix such as 0x, unless radix is given), or a BigInteger (returned as it is).	required
radix	int | None	the base of the digits in value, which must be a string then. If None, base 10.	None

Returns:

Type	Description
BigInteger	The BigInteger.

Raises:

Type	Description
TypeError	if value has another type (e.g. a float), or radix is given with a non-string value.

Examples:

>>> big_integer(42), big_integer("-123456789012345678901234567890"), big_integer("ff", 16)
(42, -123456789012345678901234567890, 255)

python_integer

python_integer(value: BigInteger) -> int

Converts a BigInteger into a Python int, without loss of precision.

Parameters:

Name	Type	Description	Default
value	BigInteger	the BigInteger.	required

Returns:

Type	Description
int	The int.

Examples:

>>> python_integer(big_integer(2**70)) == 2**70
True

jvm_rounding_mode

jvm_rounding_mode(mode: str) -> RoundingMode

Converts a rounding mode of Python's decimal module into a RoundingMode.

Parameters:

Name	Type	Description	Default
mode	str	one of decimal.ROUND_UP, ROUND_DOWN, ROUND_CEILING, ROUND_FLOOR, ROUND_HALF_UP, ROUND_HALF_DOWN, ROUND_HALF_EVEN.	required

Returns:

Type	Description
RoundingMode	The corresponding RoundingMode.

Raises:

Type	Description
ValueError	if mode is decimal.ROUND_05UP (which has no JVM counterpart), or is not a rounding mode.

Examples:

>>> import decimal
>>> jvm_rounding_mode(decimal.ROUND_HALF_EVEN)
HALF_EVEN

big_decimal

big_decimal(
    value: str | float | Decimal,
    precision: int | None = 0,
    rounding: RoundingMode = HALF_UP,
) -> BigDecimal

Converts a Python number, or a string, into a BigDecimal.

Trailing zeros are dropped (e.g. "1.50" gives 1.5, and "1E+2" gives 100).

Parameters:

Name	Type	Description	Default
value	str | float | Decimal	the value: a string (e.g. "3.14", "1e-3"), a float (converted exactly, with all the digits of its binary value, unless precision limits them), a decimal.Decimal, an int, or a BigInteger.	required
precision	int | None	the number of significant digits to keep: 0 for all of them (the default), or None for the precision of the current decimal context.	0
rounding	RoundingMode	how to round when digits are discarded, as a RoundingMode or a rounding mode of Python's decimal module (e.g. decimal.ROUND_HALF_EVEN); None for the rounding of the current decimal context.	HALF_UP

Returns:

Type	Description
BigDecimal	The BigDecimal.

Raises:

Type	Description
TypeError	if value, precision, or rounding have another type.
ValueError	if rounding is a Python rounding mode with no JVM counterpart.

Examples:

>>> big_decimal("1.50"), big_decimal(0.1, precision=3), big_decimal("1E+2")
(1.5, 0.1, 100)
>>> big_decimal(0.1)
0.1000000000000000055511151231257827021181583404541015625
>>> import decimal
>>> big_decimal("2.5", precision=1), big_decimal("2.5", 1, decimal.ROUND_HALF_EVEN)
(3, 2)

python_decimal

python_decimal(value: BigDecimal) -> Decimal

Converts a BigDecimal into a decimal.Decimal, without loss of precision.

Parameters:

Name	Type	Description	Default
value	BigDecimal	the BigDecimal.	required

Returns:

Type	Description
Decimal	The decimal.Decimal.

Examples:

>>> python_decimal(big_decimal("3.14"))
Decimal('3.14')