← Index

x/num/decimal

Arbitrary-precision decimal floating-point, homed on the Decimal class.

Literal syntax: 1.5d, -0.001d, 3d, 1.5e-8d. The generic operators

dispatch decimal operands through the type ops; mixed operands

resolve by the from-relation, and a double widens EXACTLY.

• • • % are exact; / sqrt ln exp log10 round half-even to

(Decimal precision). The transcendentals are series, not libm –

correct to the last digit; the series run in fixed point, so a

34-digit ln costs about a tenth of a second, not ten.

Exact integer helpers

Construction

Rounding

Arithmetic

dec-add

dec-sub

dec-mul

dec-div

dec-mod

Comparison

dec-lt

dec-eq

Roots and powers

Logarithms and the exponential

Conversion

Predicates

ensure-dec

Type registration

dec-exp-digits

dec-exp-sign

dec-frac

dec-first-frac

dec-int

dec-sign

Operator Overrides

decimal-type

number?

Test whether a value is any numeric type (now including decimals).

Parameters:

• x : ANY — Value to test

Returns: BOOL — True if x is a number

Examples:

(number? 1.5d) => #t

real?

Test whether a value is a real number (now including decimals).

Parameters:

• x : ANY — Value to test

Returns: BOOL — True if x is a real number

Examples:

(real? 1.5d) => #t

Class Decimal

(Decimal type)

The decimal type handle, for Convert and Type.

Returns: ATOM — The DECIMAL type handle

(Decimal decimal? x)

Test whether a value is an arbitrary-precision decimal.

Parameters:

• x : ANY — Value to test

Returns: BOOL — True if x is a decimal

Examples:

(list (Decimal decimal? 1.5d) (Decimal decimal? 1.5)) => (#t #f)

(Decimal precision)

The significant digits division and sqrt round to.

Returns: INTEGER — Current precision

(Decimal precision! n)

Set the significant digits division and sqrt round to. Addition, subtraction and multiplication stay exact and are unaffected.

Parameters:

• n : INTEGER — Significant digits, at least 1

Returns: INTEGER — The new precision

(Decimal from x)

Construct a decimal from any convertible value, through the conversion catalogue. A float converts EXACTLY; a rational rounds to the current precision. Raises a label ‘type when nothing converts.

Parameters:

• x : ANY — An int, bigint, float, rational, numeric string, or decimal (identity)

Returns: DECIMAL — Decimal instance

(Decimal make sig exp)

Construct the decimal sig * 10^exp directly, without going through text.

Parameters:

• sig : INTEGER — Significand (int or bigint)
• exp : INTEGER — Power-of-ten exponent

Returns: DECIMAL — Decimal instance

(Decimal significand x)

The decimal’s significand, with trailing zeros already stripped.

Parameters:

• x : DECIMAL — Decimal value

Returns: INTEGER — Significand as an exact integer

Examples:

(Decimal significand 1.250d) => 125

(Decimal exponent x)

The decimal’s power-of-ten exponent.

Parameters:

• x : DECIMAL — Decimal value

Returns: INTEGER — Exponent

Examples:

(Decimal exponent 1.25d) => -2

(Decimal ->int x)

Convert a decimal to an exact integer by truncation toward zero.

Parameters:

• x : DECIMAL — Decimal value

Returns: INTEGER — Truncated integer value

Examples:

(Decimal ->int -2.75d) => -2

(Decimal ->str x)

The decimal’s text, without the d suffix that write adds for round-tripping.

Parameters:

• x : DECIMAL — Decimal value

Returns: STRING — Decimal text

Examples:

(Decimal ->str 1.5d) => "1.5"

(Decimal ->float x)

Convert a decimal to the nearest IEEE 754 double. Lossy by definition; the rounding is strtod’s.

Parameters:

• x : DECIMAL — Decimal value

Returns: FLOAT — Nearest double

Examples:

(Decimal ->float 0.5d) => 0.5

(Decimal + a b)

Add two decimals, exactly (other numerics promote).

Parameters:

• a : NUMBER — First operand
• b : NUMBER — Second operand

Returns: DECIMAL — Sum

Examples:

(Decimal + 0.1d 0.2d) => 0.3d

(Decimal - a b)

Subtract two decimals, exactly (other numerics promote).

Parameters:

• a : NUMBER — First operand
• b : NUMBER — Second operand

Returns: DECIMAL — Difference

Examples:

(Decimal - 1 0.25d) => 0.75d

(Decimal * a b)

Multiply two decimals, exactly (other numerics promote).

Parameters:

• a : NUMBER — First operand
• b : NUMBER — Second operand

Returns: DECIMAL — Product

Examples:

(Decimal * 1.5d 1.5d) => 2.25d

(Decimal / a b)

Divide two decimals, rounded half-even to the current precision (other numerics promote).

Parameters:

• a : NUMBER — Dividend
• b : NUMBER — Divisor

Returns: DECIMAL — Quotient

Examples:

(Decimal / 1 4) => 0.25d

(Decimal % a b)

Truncating remainder of decimal division, exactly (other numerics promote).

Parameters:

• a : NUMBER — Dividend
• b : NUMBER — Divisor

Returns: DECIMAL — Remainder, with the dividend’s sign

Examples:

(Decimal % 7.5d 2) => 1.5d

(Decimal < a b)

Test whether a is less than b (other numerics promote).

Parameters:

• a : NUMBER — Left operand
• b : NUMBER — Right operand

Returns: BOOL — True if a < b

Examples:

(Decimal < 0.1d 0.2d) => #t

(Decimal = a b)

Test whether a equals b (other numerics promote).

Parameters:

• a : NUMBER — Left operand
• b : NUMBER — Right operand

Returns: BOOL — True if a equals b

Examples:

(Decimal = 0.5d 0.50d) => #t

(Decimal compare a b)

Three-way comparison of two decimals (other numerics promote).

Parameters:

• a : NUMBER — Left operand
• b : NUMBER — Right operand

Returns: INTEGER — -1 if a < b, 0 if equal, 1 if a > b

Examples:

(Decimal compare 1.5d 2) => -1

(Decimal neg x)

Negate a decimal.

Parameters:

• x : NUMBER — Decimal value

Returns: DECIMAL — The negated value

Examples:

(Decimal neg 1.5d) => -1.5d

(Decimal abs x)

The absolute value of a decimal.

Parameters:

• x : NUMBER — Decimal value

Returns: DECIMAL — Magnitude

Examples:

(Decimal abs -1.5d) => 1.5d

(Decimal zero? x)

Test whether a decimal is zero.

Parameters:

• x : NUMBER — Decimal value

Returns: BOOL — True if x is zero

Examples:

(list (Decimal zero? 0.0d) (Decimal zero? 1d)) => (#t #f)

(Decimal round x places)

Round a decimal to a number of decimal places, half-even.

Parameters:

• x : NUMBER — Decimal value
• places : INTEGER — Decimal places to keep; negative rounds to tens, hundreds, …

Returns: DECIMAL — Rounded value

(Decimal rescale x exp)

Restate a decimal at a given exponent, rounding half-even when that drops digits. The exponent-facing form of round, for a caller that thinks in scales.

Parameters:

• x : NUMBER — Decimal value
• exp : INTEGER — Target power-of-ten exponent

Returns: DECIMAL — Value at the requested exponent

Examples:

(Decimal rescale 1.234d -2) => 1.23d

(Decimal trunc x)

Truncate a decimal toward zero, as an integral decimal.

Parameters:

• x : NUMBER — Decimal value

Returns: DECIMAL — Integer part

Examples:

(Decimal trunc -2.7d) => -2d

(Decimal floor x)

The largest integral decimal not greater than x.

Parameters:

• x : NUMBER — Decimal value

Returns: DECIMAL — Floor of x

Examples:

(Decimal floor -2.5d) => -3d

(Decimal ceil x)

The smallest integral decimal not less than x.

Parameters:

• x : NUMBER — Decimal value

Returns: DECIMAL — Ceiling of x

Examples:

(Decimal ceil 2.1d) => 3d

(Decimal sqrt x)

The square root of a decimal, rounded half-even to the current precision.

Parameters:

• x : NUMBER — Non-negative decimal

Returns: DECIMAL — Square root of x

Examples:

(Decimal sqrt 2.25d) => 1.5d

(Decimal pow x n)

Raise a decimal to an integer power. A non-negative exponent is exact; a negative one divides once, at the current precision.

Parameters:

• x : NUMBER — Base
• n : INTEGER — Integer exponent

Returns: DECIMAL — x raised to the power n

Examples:

(Decimal pow 1.5d 2) => 2.25d

(Decimal exp x)

Raise e to a power, to the current precision.

Parameters:

• x : NUMBER — Exponent

Returns: DECIMAL — e raised to the power x

(Decimal ln x)

The natural logarithm of a decimal, to the current precision. Raises a label ‘value for zero or a negative.

Parameters:

• x : NUMBER — Positive decimal

Returns: DECIMAL — Natural logarithm of x

(Decimal log10 x)

The base-10 logarithm of a decimal, to the current precision. An exact power of ten answers its exponent exactly. Raises a label ‘value for zero or a negative.

Parameters:

• x : NUMBER — Positive decimal

Returns: DECIMAL — log10(x)