Num

Num range

Represents a number that could be either an Int or a Frac.

This is useful for functions that can work on either, for example Num.add, whose type is:

add : Num a, Num a -> Num a

The number 1.5 technically has the type Num (Fraction *), so when you pass two of them to Num.add, the answer you get is 3.0 : Num (Fraction *).

Similarly, the number 0x1 (that is, the integer 1 in hexadecimal notation) technically has the type Num (Integer *), so when you pass two of them to Num.add, the answer you get is 2 : Num (Integer *).

The type Frac a is defined to be an alias for Num (Fraction a), so 3.0 : Num (Fraction *) is the same value as 3.0 : Frac *. Similarly, the type Int a is defined to be an alias for Num (Integer a), so 2 : Num (Integer *) is the same value as 2 : Int *.

In this way, the Num type makes it possible to have 1 + 0x1 return 2 : Int * and 1.5 + 1.5 return 3.0 : Frac.

Number Literals

Number literals without decimal points (like 0, 4 or 360) have the type Num * at first, but usually end up taking on a more specific type based on how they're used.

For example, in (1 + List.len myList), the 1 has the type Num * at first, but because List.len returns a U64, the 1 ends up changing from Num * to the more specific U64, and the expression as a whole ends up having the type U64.

Sometimes number literals don't become more specific. For example, the Num.toStr function has the type Num * -> Str. This means that when calling Num.toStr (5 + 6), the expression (5 + 6) still has the type Num *. When this happens, Num * defaults to being an I64 - so this addition expression would overflow if either 5 or 6 were replaced with a number big enough to cause addition overflow on an I64 value.

If this default of I64 is not big enough for your purposes, you can add an i128 to the end of the number literal, like so:

Num.toStr 5_000_000_000i128

This i128 suffix specifies that you want this number literal to be an I128 instead of a Num *. All the other numeric types have suffixes just like i128; here are some other examples:

215u8 is a 215 value of type U8
76.4f32 is a 76.4 value of type F32
123.45dec is a 123.45 value of type Dec

In practice, these are rarely needed. It's most common to write number literals without any suffix.

Int range

A fixed-size integer - that is, a number with no fractional component.

Integers come in two flavors: signed and unsigned. Signed integers can be negative ("signed" refers to how they can incorporate a minus sign), whereas unsigned integers cannot be negative.

Since integers have a fixed size, the size you choose determines both the range of numbers it can represent, and also how much memory it takes up.

U8 is an an example of an integer. It is an unsigned Int that takes up 8 bits (aka 1 byte) in memory. The U is for Unsigned and the 8 is for 8 bits. Because it has 8 bits to work with, it can store 256 numbers (2^8), and because it is unsigned, its min value is 0. This means the 256 numbers it can store range from 0 to 255.

I8 is a signed integer that takes up 8 bits. The I is for Integer, since integers in mathematics are signed by default. Because it has 8 bits just like U8, it can store 256 numbers (still 2^8), but because it is signed, the range is different. Its 256 numbers range from -128 to 127.

Here are some other examples:

U16 is like U8, except it takes up 16 bits in memory. It can store 65,536 numbers (2^16), ranging from 0 to 65,536.
I16 is like U16, except it is signed. It can still store the same 65,536 numbers (2^16), ranging from -32,768 to 32,767.

This pattern continues up to U128 and I128.

Performance Details

In general, using smaller numeric sizes means your program will use less memory. However, if a mathematical operation results in an answer that is too big or too small to fit in the size available for that answer (which is typically the same size as the inputs), then you'll get an overflow error.

As such, minimizing memory usage without causing overflows involves choosing number sizes based on your knowledge of what numbers you expect your program to encounter at runtime.

Minimizing memory usage does not imply maximum runtime speed! CPUs are typically fastest at performing integer operations on integers that are the same size as that CPU's native machine word size. That means a 64-bit CPU is typically fastest at executing instructions on U64 and I64 values, whereas a 32-bit CPU is typically fastest on U32 and I32 values.

Putting these factors together, here are some reasonable guidelines for optimizing performance through integer size choice:

Start by deciding if this integer should allow negative numbers, and choose signed or unsigned accordingly.
Next, think about the range of numbers you expect this number to hold. Choose the smallest size you will never expect to overflow, no matter the inputs your program receives. (Validating inputs for size, and presenting the user with an error if they are too big, can help guard against overflow.)
Finally, if a particular numeric calculation is running too slowly, you can try experimenting with other number sizes. This rarely makes a meaningful difference, but some processors can operate on different number sizes at different speeds.

All number literals without decimal points are compatible with Int values.

You can optionally put underscores in your Int literals. They have no effect on the number's value, but can make large numbers easier to read.

1_000_000

Integers come in two flavors: signed and unsigned.

Unsigned integers can never be negative. The lowest value they can hold is zero.
Signed integers can be negative.

Integers also come in different sizes. Choosing a size depends on your performance needs and the range of numbers you need to represent. At a high level, the general trade-offs are:

Larger integer sizes can represent a wider range of numbers. If you absolutely need to represent numbers in a certain range, make sure to pick an integer size that can hold them!
Smaller integer sizes take up less memory. These savings rarely matter in variables and function arguments, but the sizes of integers that you use in data structures can add up. This can also affect whether those data structures fit in cache lines, which can be a performance bottleneck.
Certain CPUs work faster on some numeric sizes than others. If the CPU is taking too long to run numeric calculations, you may find a performance improvement by experimenting with numeric sizes that are larger than otherwise necessary. However, in practice, doing this typically degrades overall performance, so be careful to measure properly!

Here are the different fixed size integer types:

Range	Type	Size
`-128`	`I8`	1 Byte
`127`
--------------------------------------------------------	-------	----------
`0`	`U8`	1 Byte
`255`
--------------------------------------------------------	-------	----------
`-32_768`	`I16`	2 Bytes
`32_767`
--------------------------------------------------------	-------	----------
`0`	`U16`	2 Bytes
`65_535`
--------------------------------------------------------	-------	----------
`-2_147_483_648`	`I32`	4 Bytes
`2_147_483_647`
--------------------------------------------------------	-------	----------
`0`	`U32`	4 Bytes
`(over 4 billion) 4_294_967_295`
--------------------------------------------------------	-------	----------
`-9_223_372_036_854_775_808`	`I64`	8 Bytes
`9_223_372_036_854_775_807`
--------------------------------------------------------	-------	----------
`0`	`U64`	8 Bytes
`(over 18 quintillion) 18_446_744_073_709_551_615`
--------------------------------------------------------	-------	----------
`-170_141_183_460_469_231_731_687_303_715_884_105_728`	`I128`	16 Bytes
`170_141_183_460_469_231_731_687_303_715_884_105_727`
--------------------------------------------------------	-------	----------
`(over 340 undecillion) 0`	`U128`	16 Bytes
`340_282_366_920_938_463_463_374_607_431_768_211_455`

If any operation would result in an Int that is either too big or too small to fit in that range (e.g. calling Num.maxI32 + 1), then the operation will overflow. When an overflow occurs, the program will crash.

As such, it's very important to design your code not to exceed these bounds! If you need to do math outside these bounds, consider using a larger numeric size.

Frac range

A fixed-size number with a fractional component.

Roc fractions come in two flavors: fixed-point base-10 and floating-point base-2.

Dec is a 128-bit fixed-point base-10 number. It's a great default choice, especially when precision is important - for example when representing currency. With Dec, 0.1 + 0.2 returns 0.3. Dec has 18 decimal places of precision and a range from -170_141_183_460_469_231_731.687303715884105728 to 170_141_183_460_469_231_731.687303715884105727.
F64 and F32 are floating-point base-2 numbers. They sacrifice precision for lower memory usage and improved performance on some operations. This makes them a good fit for representing graphical coordinates. With F64, 0.1 + 0.2 returns 0.30000000000000004.

If you don't specify a type, Roc will default to using Dec because it's the least error-prone overall. For example, suppose you write this:

wasItPrecise = 0.1 + 0.2 == 0.3

The value of wasItPrecise here will be Bool.true, because Roc uses Dec by default when there are no types specified.

In contrast, suppose we use f32 or f64 for one of these numbers:

wasItPrecise = 0.1f64 + 0.2 == 0.3

Here, wasItPrecise will be Bool.false because the entire calculation will have been done in a base-2 floating point calculation, which causes noticeable precision loss in this case.

The floating-point numbers (F32 and F64) also have three values which are not ordinary finite numbers. They are:

∞ (infinity)
-∞ (negative infinity)
NaN (not a number)

These values are different from ordinary numbers in that they only occur when a floating-point calculation encounters an error. For example:

Dividing a positive F64 by 0.0 returns ∞.
Dividing a negative F64 by 0.0 returns -∞.
Dividing a F64 of 0.0 by 0.0 returns NaN.

These rules come from the IEEE-754 floating point standard. Because almost all modern processors are built to this standard, deviating from these rules has a significant performance cost! Since the most common reason to choose F64 or F32 over Dec is access to hardware-accelerated performance, Roc follows these rules exactly.

There's no literal syntax for these error values, but you can check to see if you ended up with one of them by using #isNaN, #isFinite, and #isInfinite. Whenever a function in this module could return one of these values, that possibility is noted in the function's documentation.

Performance Details

On typical modern CPUs, performance is similar between Dec, F64, and F32 for addition and subtraction. For example, F32 and F64 do addition using a single CPU floating-point addition instruction, which typically takes a few clock cycles to complete. In contrast, Dec does addition using a few CPU integer arithmetic instructions, each of which typically takes only one clock cycle to complete. Exact numbers will vary by CPU, but they should be similar overall.

Dec is significantly slower for multiplication and division. It not only needs to do more arithmetic instructions than F32 and F64 do, but also those instructions typically take more clock cycles to complete.

With Num.sqrt and trigonometry functions like Num.cos, there is an even bigger performance difference. F32 and F64 can do these in a single instruction, whereas Dec needs entire custom procedures - which use loops and conditionals. If you need to do performance-critical trigonometry or square roots, either F64 or F32 is probably a better choice than the usual default choice of Dec, despite the precision problems they bring.

Signed128

Signed64

Signed32

Signed16

Signed8

Unsigned128

Unsigned64

Unsigned32

Unsigned16

Unsigned8

Integer range

I128

I64

I32

I16

I8

A signed 8-bit integer, ranging from -128 to 127

U128

U64

U32

U16

U8

Decimal

Binary64

Binary32

FloatingPoint range

F64

A 64-bit IEEE 754 binary floating-point number.

F64 represents decimal numbers less precisely than Dec does, but operations on it can be faster because CPUs have hardware-level support for F64 but not Dec. There are other tradeoffs between the two, such as:

Dec has a fixed number of digits it can represent before the decimal point, and a fixed number it can represent after the decimal point. In contrast, F64's decimal point can "float"—which conceptually means if you don't need many digits before the decimal point, you can get more digits of precision afterwards (and vice versa).
Dec represents its number internally in base-10, whereas F64 uses base-2. This can lead to imprecise answers like 0.1 + 0.2 returning 0.3 for Dec and 0.30000000000000004 for F64. This is not a bug; rather, it's a consequence of F64's base-2 representation.
Dec always gives a precise answer (or an error), whereas F64 can lose precision. For example, increasing a very large F64 number (using addition, perhaps) can result in the whole number portion being incorrect. 1234567890123456789 + 100 correctly results in a number ending in 889 for Dec, but results in a number ending 800 in F64 due to precision loss.

F32

A 32-bit IEEE 754 binary floating-point number.

This works just like F64 (see its docs for a comparison with Dec) except it's smaller. That in turn means it takes up less memory, but can store smaller numbers (and becomes imprecise more easily than F64 does).

Dec

A decimal number.

Dec is a more precise way to represent decimal numbers (like currency) than F32 and F64 are, because Dec is represented in memory as base-10. In contrast, F64 and F32 are base-2 in memory, which can lead to decimal precision loss even when doing addition and subtraction. For example, when using F64, 0.1 + 0.2 returns 0.30000000000000004, whereas when using Dec, 0.1 + 0.2 returns 0.3.

Under the hood, a Dec is an I128, and operations on it perform base-10 fixed-point arithmetic with 18 decimal places of precision.

This means a Dec can represent whole numbers up to slightly over 170 quintillion, along with 18 decimal places. (To be precise, it can store numbers between -170_141_183_460_469_231_731.687303715884105728 and 170_141_183_460_469_231_731.687303715884105727.) Why 18 decimal places? It's the highest number of decimal places where you can still convert any U64 to a Dec without losing information.

There are some use cases where F64 and F32 can be better choices than Dec despite their issues with base-10 numbers. For example, in graphical applications they can be a better choice for representing coordinates because they take up less memory, certain relevant calculations run faster (see performance details, below), and base-10 generally isn't as big a concern when dealing with screen coordinates as it is when dealing with currency.

Another scenario where F64 can be a better choice than Dec is when representing extremely small numbers. The smallest positive F64 that can be represented without precision loss is 2^(−1074), which is about 5 * 10^(-324). Here is that number next to the smallest Dec that can be represented:

Smallest F64: 0.000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000005
Smallest Dec: 0.000000000000000001

This is because floating-point numbers like F64 can gain more digits of precision after the . when they aren't using as many digits before the . - and this applies the most if the digit before . is 0. So whereas Dec always has 18 digits after the ., the number of digits after the . that F32 can F64 can represent without precision loss depends on what comes before it.

Performance Details

CPUs have dedicated instructions for many F32 and F64 operations, but none for Dec. Internally, Dec is represented as a 128-bit integer and uses multiple instructions to perform fractional operations. This gives F32 and F64 performance advantages for many operations.

Here's a comparison of about how long Dec takes to perform a given operation compared to F64, based on benchmarks on an M1 CPU:

add 0.6x
sub 0.6x
mul 15x
div 55x
sin 3.9x
cos 3.6x
tan 2.3x
asin 1.8x
acos 1.7x
atan 1.7x

Keep in mind that arithmetic instructions are basically the fastest thing a CPU does, so (for example) a network request that takes 10 milliseconds to complete would go on this list as about 10000000x. So these performance differences might be more or less noticeable than the base-10 representation differences depending on the use case.

e : Frac *

Euler's number (e)

pi : Frac *

Archimedes' constant (π)

tau : Frac *

Circle constant (τ)

toStr : Num * -> Str

Convert a number to a Str.

Num.toStr 42

Only Frac values will include a decimal point, and they will always include one.

Num.toStr 4.2
Num.toStr 4.0

When this function is given a non-finite F64 or F32 value, the returned string will be "NaN", "∞", or "-∞".

intCast : Int a -> Int b

Convert an Int to a new Int of the expected type:

# Casts a U8 to a U16
x : U16
x = Num.intCast 255u8

In the case of downsizing, information is lost:

# returns 0, as the bits were truncated.
x : U8
x = Num.intCast 256u16