17. More about numbers
Chapter 3 introduced Int and Float: 64-bit integers, binary64 floating point, no integer /, and no mixing of Int and Float. This chapter adds the other four numeric types and shows how to convert between them:
In this chapter you will learn:
- what
Int32,Float32,DecimalandBigIntare and when to reach for them; - how narrow types widen for free and wide types narrow only through a method;
- what the
Exact,LossyandTruncsuffixes in conversion names mean; - exact money arithmetic with
Decimal, and the real names of its rounding modes; Float'sNaN,Infinity,sqrt/floor/ceil/abs,isNaNandapproxEqual;abs,min,max,sign,clamp,floor_divandisqrtin@std/math.
17.1 The six numeric types
| Type | What it is | How to build one |
|---|---|---|
Int | signed 64-bit integer, overflow-checked | literal 42 |
Int32 | signed 32-bit integer, Java's int | typed literal: let n: Int32 = 7 |
BigInt | an integer of any size | BigInt.parse("..."), BigInt.fromInt(7) |
Float | IEEE 754 binary64 | literal 2.5, 1.0 |
Float32 | IEEE 754 binary32, Java's float | typed literal: let f: Float32 = 0.5 |
Decimal | arbitrary-precision base 10 | Decimal.parse("19.99"), 7.toDecimal() |
Day to day, Int and Float are enough. Int32 and Float32 exist mainly for the Java boundary (chapter 21); Decimal is for money; BigInt handles integers past 64 bits. They all obey chapter 3's general rule: different numeric families never convert implicitly.
17.2 Int32 and Float32: the narrow types that match Java
# Int32 and Float32 are mainly for talking to Java; narrow values widen for free, not the other way.
let small: Int32 = 2000000000
let wide: Int = small
print(wide + 1)
print(small + wide)
let narrow: Float32 = 0.1
print(narrow)
print(narrow.toFloat())
let whole: Float = 1
print(whole)2000000001
4000000000
0.1
0.10000000149011612
1.0Line by line:
let small: Int32 = 2000000000: an ordinary integer literal is anInt; write the type on the declaration to get anInt32(same for0.5andFloat32). The literal must fit; if it does not, the compiler reportsSPR-NUM-RANGE(an example comes later in this section).let wide: Int = small: narrow values widen for free. AnInt32goes where anIntis expected with no method call, and aFloat32goes where aFloatis expected the same way. The reverse (Int→Int32,Float→Float32) always needs an explicit method.wide + 1isIntarithmetic and prints2000000001.small + wide: mixingInt32withIntgives the widerInt, printing4000000000.let narrow: Float32 = 0.1:0.1has no exact binary representation, so 32 bits hold the closest value. Printingnarrowgives0.1— the shortest decimal that reads back as the same 32-bit value.narrow.toFloat()widens it exactly to 64-bitFloat, which exposes the stored value:0.10000000149011612.A trace of that value's two shapes:
Step Value in memory Printed let narrow: Float32 = 0.1closest 32-bit float to 0.1 0.1(shortest 32-bit form)narrow.toFloat()the same value in 64 bits 0.10000000149011612(shortest 64-bit form)let whole: Float = 1: an integer literal may go to a floating variable only if it is exactly representable. It prints1.0.
So what type does Float32 arithmetic produce? A bare literal follows the other side:
let a: Float32 = 0.1
print(a + 1.0)
let b: Float32 = 0.1
let c = 1.0
print(b + c)1.1
1.1000000014901161a + 1.0:aisFloat32, so the untyped1.0literal is aFloat32; the arithmetic is 32-bit and prints1.1.b + c:cis aFloatvariable, so the operation widens to 64 bits; the value inbwas never exactly0.1, and the sum prints1.1000000014901161.
Mixing narrow types has one red line — Float32 and Int do not compute together:
Deliberate mistake: Float32 plus Int
let a: Float32 = 0.5
let b = 2
print(a + b)SPR-NUM-MIXED [TYPE] main.spr:3:7: Operator '+' has no implicit conversion between Float32 and Int (expected matching numeric families, actual Float32 and Int)
hint: Convert the Int side: b.toFloatExact().expected matching numeric families means the operands are from different families. Follow the hint and convert b to floating point (b.toFloatExact(), next section), or make a an Int.
Deliberate mistake: a literal that does not fit
let x: Float = 9007199254740993SPR-NUM-RANGE [TYPE] main.spr:1:16: Integer literal 9007199254740993 is not exactly representable as Float (expected Float, actual 9007199254740993)2^53 + 1 is beyond the integers binary64 can represent exactly, and Sprig will not quietly turn it into 2^53. An Int32 literal past 32 bits is the same code.
Overflow the compiler cannot see fails at run time. Save the next two lines as overflow.spr and run sprig run overflow.spr:
let a: Int32 = 2000000000
print(a + a)SPR-RUNTIME-EXCEPTION [RUNTIME] overflow.spr:2:1: Numeric error: Int32 addition overflow
hint: The exact result does not fit in the integer type. Check before the operation, for example 'if value > 0 and total > 9223372036854775807 - value:' for an Int addition, or catch it: import java.lang.ArithmeticException as ArithmeticException, then put the operation in 'try:' with 'catch problem: ArithmeticException:'. See `sprig help numerics`. Run with --stacktrace to see the JVM stack.
1 error(s); run 'sprig explain <code>' for details on a diagnostic code.2000000000 + 2000000000 is 4000000000, which does not fit in Int32. As with Int, Sprig reports an error instead of wrapping around. The hint's second option needs Java's exception type, deferred to chapter 21.
17.3 How conversions are named
Every conversion between number types follows one naming rule: the name says whether information can be lost.
let n = 300
print(n.toInt32Exact())
print(n.toFloatExact())
let f = 2.75
print(f.toIntTrunc())
let a = 3
print(a.compareTo(5))
print("pear".compareTo("apple") > 0)300
300.0
2
-1
truen.toInt32Exact():300is withinInt32, so it succeeds and prints300.n.toFloatExact(): prints300.0. If theIntwere too large for an exactFloat,Exactwould fail at run time rather than round quietly.f.toIntTrunc():2.75drops its fraction and gives2.Truncsays plainly "the fraction is thrown away".a.compareTo(5): every numeric type hascompareTo, its argument must be the receiver's own type, and it returnsInt32:3is less than5, so-1."pear".compareTo("apple") > 0:Stringhas it too, in lexicographic order;true.
The rule table:
| Name | Meaning | Examples |
|---|---|---|
| no suffix | always succeeds | Int32.toInt(), Int32.toFloat(), Float32.toFloat(), value.toDecimal() |
Exact | fails when information would be lost | Int.toFloatExact(), Float.toIntExact(), Int.toInt32Exact() |
Lossy | rounding is allowed | Int.toFloatLossy(), Float.toFloat32Lossy() |
Trunc | the fraction is dropped | Float.toIntTrunc() |
The common conversions:
| From → to | How to write it |
|---|---|
Int32 → Int, Float32 → Float | assignment (widens for free), or .toInt() / .toFloat() |
Int → Int32 | .toInt32Exact(), out-of-range fails |
Int → Float | .toFloatExact() (fails on lost precision) or .toFloatLossy() (rounds) |
Int → Decimal | .toDecimal() |
Float → Int | .toIntExact() (fails on a fraction) or .toIntTrunc() (drops it) |
Float → Float32 | .toFloat32Exact() or .toFloat32Lossy() |
BigInt → Int / Float / Decimal | .toIntExact() / .toFloatExact(), .toFloatLossy() / .toDecimal() |
Decimal → Int / Float | .toIntExact() / .toFloatExact(), .toFloatLossy() |
Write the wrong name and the compiler tells you the right one:
Deliberate mistake: Int has no toFloat()
let n = 3
print(n.toFloat())SPR-NAME-UNRESOLVED [NAME] main.spr:2:7: Type Int has no method 'toFloat'
hint: An Int beyond 2^53 has no exact Float: write value.toFloatExact(), which fails instead of rounding, or value.toFloatLossy(), which rounds.Int.toFloat() and Float.toInt() deliberately do not exist: neither could tell you whether it loses information. The hint names both candidates and their difference — Exact for safety, Lossy when rounding is fine. Likewise Decimal has no static fromInt (write value.toDecimal()), and BigInt uses BigInt.fromInt(value).
17.4 Decimal: the money type
0.1 + 0.2 is 0.30000000000000004 in Float, because binary floating point cannot represent most decimal fractions. Decimal is arbitrary-precision base 10, so addition, subtraction and multiplication are exact:
# Decimal is arbitrary-precision base 10 and BigInt is an arbitrary-size integer; neither mixes with Int or Float.
let price = Decimal.parse("19.99")
let total = price * 3.toDecimal()
print(total)
print(1.toDecimal().divide(3.toDecimal(), 4, "HALF_EVEN"))
let huge = BigInt.parse("123456789012345678901234567890")
print(huge + BigInt.fromInt(1))
print(huge.compareTo(BigInt.fromInt(1)))59.97
0.3333
123456789012345678901234567891
1Decimal.parse("19.99")builds one from text (DecimalandBigInthave no literals).price * 3.toDecimal()is exactly59.97.1.toDecimal().divide(3.toDecimal(), 4, "HALF_EVEN"): division must state how many decimal places and which rounding mode; this one gives0.3333.BigInt.parse("123456789012345678901234567890")is as long as it needs to be;+ BigInt.fromInt(1)gives...891with no overflow.huge.compareTo(BigInt.fromInt(1))returns1, meaninghugeis larger.
The third argument to division is a rounding-mode name, and it must be one of Java's RoundingMode names; the common ones are "HALF_UP" (round half away from zero), "HALF_EVEN" (banker's rounding, ties to the even digit) and "DOWN" (truncate toward zero):
print(Decimal.parse("2.5").divide(1.toDecimal(), 0, "HALF_UP"))
print(Decimal.parse("2.5").divide(1.toDecimal(), 0, "HALF_EVEN"))
print(Decimal.parse("0.30") == Decimal.parse("0.3"))
print(Decimal.parse("0.30").compareTo(Decimal.parse("0.3")))
print(1.toDecimal().divide(3.toDecimal(), 4, "DOWN"))
print(Decimal.parse("19.99") * 3.toDecimal())3
2
true
0
0.3333
59.972.5to zero decimal places:HALF_UPgives3,HALF_EVENgives2(ties to the even digit).Decimal==compares values, not text:0.30 == 0.3istrueandcompareToreturns0."DOWN"truncates to four places and gives0.3333.- Multiplication is exact as above.
Deliberate mistake: dividing Decimal with /
let a = Decimal.parse("1")
let b = Decimal.parse("3")
print(a / b)SPR-NUM-DIVISION [TYPE] main.spr:3:7: Decimal division needs an explicit scale and rounding mode
hint: Use a.divide(b, scale, "HALF_EVEN") or another rounding mode.1/3 has no finite decimal expansion and Sprig will not pick a precision for you. Write a.divide(b, scale, mode) as the hint says.
A wrong mode name is not a compile error — it fails at run time. Save these two lines as modes.spr and run:
let third = 1.toDecimal().divide(3.toDecimal(), 4, "NEAREST")
print(third)SPR-RUNTIME-EXCEPTION [RUNTIME] modes.spr:1:1: Numeric error: Decimal division failed: No enum constant java.math.RoundingMode.NEAREST
hint: Guard the checked arithmetic or use an explicit conversion; see `sprig help numerics`. Run with --stacktrace to see the JVM stack.
1 error(s); run 'sprig explain <code>' for details on a diagnostic code.NEAREST is not a legal name, and the error even recites the Java enum it was looking in. The legal names are exactly Java's RoundingMode constants (HALF_EVEN, HALF_UP, DOWN and the rest).
Coming from another language?
Decimal is Java's BigDecimal and BigInt is BigInteger. Other languages often hide these behind a library; Sprig makes them native types but keeps the "the name states the cost" rule: no implicit Float/Decimal conversion, and no Decimal.fromInt. The Java interop chapter shows toJava() / fromJava() moving between the wrapper types and Java's own.
17.5 BigInt: as large as it needs to be
let big = BigInt.parse("99999999999999999999")
print(big * big)
print(big.divTrunc(BigInt.fromInt(7)))
print(big % BigInt.fromInt(7))
print(big.toFloatLossy())9999999999999999999800000000000000000001
14285714285714285714
1
1.0E20big * big: a 20-digit number squared is a 40-digit number, exactly, with no overflow.+,-and*are all exact.big.divTrunc(BigInt.fromInt(7))andbig % BigInt.fromInt(7): integer division and remainder usedivTruncand%, and a zero divisor fails.big.toFloatLossy(): converting toFloatmay round, so it prints1.0E20in scientific notation.
Converting a BigInt back to Int uses .toIntExact(); when the number is too large it fails at run time with Numeric error: BigInt outside Int range — like every Exact conversion, refusing is better than silently truncating. toDecimal() cannot fail.
17.6 Float's special values and helper methods
Floating point has values beyond ordinary numbers, and a few static helpers (written on the type name Float):
print(Float.sqrt(2.0))
print(Float.floor(-1.5))
print(Float.ceil(-1.5))
print(Float.abs(-2.5))
print(Float.sqrt(-1.0))
print(0.1 + 0.2)
print(1.0 / 0.0)
print(0.0 / 0.0)
print(-0.0 == 0.0)
print((0.1 + 0.2).approxEqual(0.3, 1e-15))
print((0.0 / 0.0).isNaN())
print((1.0 / 0.0).isInfinite())
print(1.0.isFinite())1.4142135623730951
-2.0
-1.0
2.5
NaN
0.30000000000000004
Infinity
NaN
true
true
true
true
trueLine by line:
Float.sqrt(2.0): the square root;1.4142135623730951is the closest binary64 value.Float.floor(-1.5)rounds down to-2.0andFloat.ceil(-1.5)rounds up to-1.0. Both return aFloat(note the.0); for an integer, usetoIntExact()once the value is whole.Float.abs(-2.5)is2.5.Float.sqrt(-1.0)isNaN(Not a Number), not an error — an IEEE 754 rule.0.1 + 0.2is0.30000000000000004: binary floating point's classic error, printed as it is rather than hidden.1.0 / 0.0isInfinityand0.0 / 0.0isNaN; floating division by zero is not an error (only integer division by zero is).-0.0 == 0.0istrue: positive and negative zero compare equal, althoughcompareTodistinguishes them.(0.1 + 0.2).approxEqual(0.3, 1e-15)istrue:approxEqual(value, absolute tolerance)is an explicit near-equality, kinder than==but still not a mathematical proof.(0.0 / 0.0).isNaN(),(1.0 / 0.0).isInfinite()and1.0.isFinite()classify the three special-value families, alltruehere.
NaN compares false to everything, itself included; never search for it with ==, use isNaN().
17.7 @std/math
The small integer helpers live in @std/math (the import was taught in chapter 4):
import "@std/math.spr" as math
print(math.abs(-5))
print(math.min(3, 7))
print(math.max(3, 7))
print(math.sign(-5))
print(math.clamp(12, 0, 10))
print(math.floor_div(-7, 2))
print(math.isqrt(17))5
3
7
-1
10
-4
4math.abs(-5)is5;math.min(3, 7)andmath.max(3, 7)give3and7.math.sign(-5)is-1(negative),0for zero and1for positive.math.clamp(12, 0, 10)limits12to the range0..10inclusive, giving10.math.floor_div(-7, 2)gives-4: floor toward negative infinity. That differs fromdivTrunc(toward zero,-3), so pick deliberately for negative operands — exactly why chapter 3 insists integer division say what it means.math.isqrt(17)gives4: the integer floor of the square root.
Failing @std/math functions use chapter 14's throws Error, so they go straight into try:
import "@std/math.spr" as math
try:
print(math.isqrt(-1))
catch problem: Error:
print("caught: " + problem.message)
try:
print(math.clamp(5, 10, 0))
catch problem: Error:
print("caught: " + problem.message)caught: isqrt input must not be negative
caught: clamp lower bound must not exceed upper boundmath.isqrt(-1)throws anErrorsayingisqrt input must not be negative.math.clamp(5, 10, 0)has a lower bound above its upper bound and throwsclamp lower bound must not exceed upper bound.- Both are caught by
catch problem: Error— standard-library failures travel the sameErrorchannel as yours (Java exceptions do not; chapter 21).
17.8 Summary
- Six numeric types:
Int,Int32,BigInt,Float,Float32,Decimal; families never convert implicitly. - Narrow values widen for free (
Int32→Int,Float32→Float); wide to narrow always writes a method. - Conversion naming: no suffix always succeeds,
Exactfails when information would be lost,Lossyrounds andTruncdrops the fraction. Decimaladds, subtracts and multiplies exactly; division writesdivide(scale, mode)with a JavaRoundingModename;BigIntis unbounded and narrows only throughExact.- Floats have
NaN,Infinityand-0.0; handle them withisNaN,isInfinite,isFiniteandapproxEqual, never==. @std/mathoffersabs,min,max,sign,clamp,floor_divandisqrt, throwingErroron failure.
17.9 Exercises
Exercise 1 (easy) Print 0.1 + 0.2 (Float) and Decimal.parse("0.1") + Decimal.parse("0.2") and compare.
Hint: one carries the binary error, the other is exact base 10.
Answer
print(0.1 + 0.2)
print(Decimal.parse("0.1") + Decimal.parse("0.2"))0.30000000000000004
0.3Exercise 2 Print (-7).divTrunc(2) and math.floor_div(-7, 2) and explain the difference.
Hint: divTrunc rounds toward zero, floor_div toward negative infinity.
Answer
import "@std/math.spr" as math
print((-7).divTrunc(2))
print(math.floor_div(-7, 2))-3
-4Exercise 3 Use math.isqrt on 50 and math.clamp to limit 12 to 0..10.
Hint: isqrt(50) is 7 (7×7=49) and clamp's upper bound 10 pulls 12 down to 10.
Answer
import "@std/math.spr" as math
print(math.isqrt(50))
print(math.clamp(12, 0, 10))7
10Exercise 4 (hard) Convert 12345 to Int32 and to Float (rounding allowed), then truncate 2.5 to an Int.
Hint: Int → Int32 is toInt32Exact(); Int → Float can lose precision, so use toFloatLossy(); Float → Int with a fraction uses toIntTrunc().
Answer
let n = 12345
print(n.toInt32Exact())
print(n.toFloatLossy())
let f = 2.5
print(f.toIntTrunc())12345
12345.0
2Next chapter: Modules, projects and dependencies — splitting code into files and pulling in other people's libraries.
