Toit
Libraries
bignum
binary
bitmap
ble
bytes
core
crypto
device
encoding
esp32
expect
fixed-point
flash
font
gpio
i2c
i2s
icons
io
line-wrap
log
math
monitor
net
pulse-counter
reader
reader-writer
rmt
serial
spi
statistics
system
tls
uart
uuid
writer
zlib

Class num

extends Object implements Comparable
A number.
This is an abstract super class for int and float.
See also https://docs.toit.io/language/math.

Class summary

parse data/Data -> num
Parses the given data as a number.
parse data/Data [--on-error] -> num
Deprecated. Use parse data [--if-error] instead.
parse data/Data [--if-error] -> num
Variant of parse data.

Statics

parse data/Data -> num
Parses the given data as a number.
Tries to parse the data as an integer first, and if that fails, as a float.
See int.parse and float.parse.
parse data/Data [--on-error] -> num
Deprecated. Use parse data [--if-error] instead.
parse data/Data [--if-error] -> num
Variant of parse data.
If the data can't be parsed correctly, returns the result of calling the if-error block.

Methods

abs -> num
The absolute value of this number.
The number -9223372036854775808 (0x8000_0000_0000_0000 or int.MIN) does not have an absolute counterpart.
Examples

2.abs       // => 2
(-2).abs    // => 2
2.0.abs     // => 2.0
(-2.0).abs  // => 2.0
(-0.0).abs  // => 0.0

int.MIN.abs            // => -9223372036854775808
float.NAN.abs          // => float.NAN
(-float.INFINITY).abs  // => float.NAN
compare-to other/num -> int
Compares this number to the other.
Uses the truncated division for the modulo computation. The sign of the result is thus always the same as the one of the divisor (the first operand).
Returns 1 if this number is greater than the other.
Returns 0 if this number is equal to the other.
Returns -1 if this number is less than the other.
Returns -1 if the other is NaN (float.NAN).
Returns 0 if both this number and the other are NaN (float.NAN).
Return 1 if this number is NaN and the other is not NaN.
Contrary to < this comparison handles 0.0 and -0.0, such that 0.0.compare-to -0.0 returns 1.
Examples

2.compare-to 1  // => 1
1.compare-to 1  // => 0
1.compare-to 2  // => -1

(-0.0).compare-to 0.0 // => -1

2.compare-to float.NAN // => -1

float.INFINITY.compare-to 3               // => 1
float.INFINITY.compare-to float.INFINITY  // => 0
3.compare-to float.INFINITY               // => -1
compare-to other/num [--if-equal] -> int
Variant of compare-to other.
Calls if-equal if this number is equal to other.
Examples
In the example, MyTime implements a lexicographical ordering of seconds and nanoseconds using compare-to other [--if-equal] to move on to nanoseconds when the seconds component is equal.

class MyTime:
  seconds/int
  nanoseconds/int

  constructor .seconds .nanoseconds:

  compare-to other/MyTime -> int:
    return seconds.compare-to other.seconds --if-equal=:
      nanoseconds.compare-to other.nanoseconds
operator - -> any
Negates this number.
The following numbers are not changed by negation:
Examples

-(2)                      // => -2
-(-13)                    // => 13
-(-9223372036854775808)  // => -9223372036854775808

-(1.0)      // => -1.0
-(-3.2)     // => 3.2
-float.NAN  // => float.NAN
operator - other/num -> any
Subtracts this number from the other.
Overflows if this number and the other are integers and the result is outside the 64-bit integer range ([int.MIN, int.MAX]).
Returns NaN (float.NAN) if either this number of the other is NaN.
Returns infinity (float.INFINITY) if either this number or the other is infinity and the other is a scalar.
Examples

46 - 2          // => 44
1.0 - 3.0       // => -2.0
1 - 1.1         // => -0.10000000000000008882
int.MAX - (-1)  // => -9223372036854775808
int.MIN - 1     // => 9223372036854775807

1 - float.NAN          // => float.NAN
float.NAN - 1          // => float.NAN
float.NAN - float.NAN  // => float.NAN

float.INFINITY - 1               // => float.INFINITY
float.INFINITY - float.INFINITY  // => float.NAN
operator * other/num -> any
Multiplies this number with the other.
Overflows if this number and the other are integers and the result is outside the 64-bit integer range ([int.MIN, int.MAX]).
Returns NaN (float.NAN) if either this number of the other is NaN.
Returns infinity (float.INFINITY) if either this number or the other is infinity and the other is not NaN.
Returns NaN if both this numbers and the other are infinity (float.INFINITY).
Examples

7 * 9         // => 63
-12 * 3       // => -36
2.0 * 3.0     // => 6.0
2 * 1.1       // => 2.2000000000000001776
-1 * int.MAX  // => -9223372036854775807
-1 * int.MIN  // => -9223372036854775808

1 * float.NAN          // => float.NAN
float.NAN * 1          // => float.NAN
float.NAN * float.NAN  // => float.NAN

float.INFINITY * 1                // => float.INFINITY
float.INFINITY * float.INFINITY   // => float.INFINITY
-1 * float.INFINITY               // => -float.INFINITY
float.INFINITY * -float.INFINITY  // => -float.INFINITY
operator / other/num -> any
Divides this number by the other.
Returns NaN (float.NAN) if either this number of the other is NaN.
Returns infinity (float.INFINITY) for division by zero if either this number or the other is a float.
Returns infinity (float.INFINITY) if this number is infinity and the other is a scalar.
Returns 0.0 if either this number is a scalar and the other is infinity (float.INFINITY).
Returns NaN (float.NAN) if both this number and the other are either infinity (float.INFINITY).
Errors
The other must not be 0 when this number is an int.
Examples

46 / 2    // => 23
2.0 / 4.0 // => 0.5
-1 / 3.0  // => -0.33333333333333331483

2 / 0     // Error.
2.0 / 0   // => float.INFINITY
2 / 0.0   // => float.INFINITY
2 / -0.0   // => -float.INFINITY

1 / float.NAN          // => float.NAN
float.NAN / 1          // => float.NAN
float.NAN / float.NAN  // => float.NAN

float.INFINITY / 2               // => float.INFINITY
float.INFINITY / float.INFINITY  // => float.NAN
operator % other/num -> any
Takes this number modulo the other.
Uses the truncated division for the modulo computation. The sign of the result is thus always the same as the one of the divisor (the first operand).
Returns NaN (float.NAN) if this number or the other is a float and the other is equal to 0.0.
Returns NaN (float.NAN) if either this number or the other is a NaN.
Errors
The other must not be 0 when this number is an int.
Examples

5 % 3    // => 2
-5 % 3   // => -2
5 % -3   // => 2
-5 % -3  // => -2
6 % 1.5  // => 0.0
5.2 % 3  // => 2.2000000000000001776

5 % 0    // => Error.
2.0 % 0  // => float.NAN
2 % 0.0  // => float.NAN

1 % float.NAN          // => float.NAN
float.NAN % 1          // => float.NAN
float.NAN % float.NAN  // => float.NAN
operator + other/num -> any
Sums this number with the other.
Overflows if this number and the other are integers and the result is outside the 64-bit integer range ([int.MIN, int.MAX]).
Returns NaN (float.NAN) if either this number of the other is NaN.
Returns infinity (float.INFINITY) if either this number or the other is infinity and the other is a scalar.
Returns NaN when summing positive and negative infinity (float.INFINITY).
Examples

1 + 1           // => 2
1.0 + 1.0       // => 2.0
1 + 1.1         // => 2.1000000000000000888
int.MAX + 1     // => -9223372036854775808
int.MIN + (-1)  // => 9223372036854775807

1 + float.NAN          // => float.NAN
float.NAN + 1          // => float.NAN
float.NAN + float.NAN  // => float.NAN

float.INFINITY + 1                  // => float.INFINITY
float.INFINITY + -float.INFINITY    // => float.NAN
operator < other/num -> bool
Whether this number is less than the other.
Returns false if this number or the other is a NaN (float.NAN)
Examples

1 < 1  // => false
1 < 2  // => true
2 < 1  // => false

12.3 < 12.3  // => false
0.0 < 12.3   // => true
1.2 < 0.0    // => false
0.0 < -0.0   // => false
-0.0 < 0.0   // => false

12 < 123.0    // => true
12.34 < 123   // => true
1234 < 123.0  // => false
1.2 < 1       // => false

float.NAN < float.NAN  // => false
1 < float.NAN          // => false
float.NAN < 1.0        // => false

float.MAX-FINITE < float.INFINITY  // => true
float.NAN < float.INFINITY  // => false
float.INFINITY < float.NAN  // => false
operator <= other/num -> bool
Whether this number is less than or equal to the other.
Returns false if this number or the other is a NaN (float.NAN).
Examples

1 <= 1  // => true
1 <= 2  // => true
2 <= 1  // => false

12.3 <= 12.3  // => true
0.0 <= 12.3   // => true
1.2 <= 0.0    // => false
0.0 <= -0.0   // => true

12 <= 123.0    // => true
12.34 <= 123   // => true
32.0 <= 32     // => true
32 <= 32.0     // => true
1234 <= 123.0  // => false
1.2 <= 1       // => false

float.NAN <= float.NAN  // => false
1 <= float.NAN          // => false
float.NAN <= 1.0        // => false

float.MAX-FINITE <= float.INFINITY  // => true
float.NAN <= float.INFINITY  // => false
float.INFINITY <= float.NAN  // => false
operator == other/num -> bool
Whether this number is equal to the other.
Returns false if this number or the other is a NaN (float.NAN).
Examples

1 == 1  // => true
1 == 2  // => false
2 == 1  // => false

12.3 == 12.3  // => true
0.0 == 12.3   // => false
1.2 == 0.0    // => false
0.0 == -0.0   // => true

123 == 123.0     // => true
1.0 == 1         // => true

float.NAN == float.NAN  // => false
1 == float.NAN          // => false
float.NAN == 1.0        // => false

float.INFINITY == float.INFINITY  // => true
operator > other/num -> bool
Whether this number is greater than the other.
Returns false if this number or the other is a NaN (float.NAN).
Examples

1 > 1  // => false
1 > 2  // => false
2 > 1  // => true

12.3 > 12.3  // => false
0.0 > 12.3   // => false
1.2 > 0.0    // => true
-0.0 > 0.0   // => false

12 > 123.0    // => false
12.34 > 123   // => false
32.0 > 32     // => false
32 > 32.0     // => false
1234 > 123.0  // => true
1.2 > 1       // => true

float.NAN > float.NAN  // => false
1 > float.NAN          // => false
float.NAN > 1.0        // => false

float.MAX-FINITE > float.INFINITY  // => false
float.NAN > float.INFINITY  // => false
float.INFINITY > float.NAN  // => false
operator >= other/num -> bool
Whether this number is greater than or equal to the other.
Returns false if this number or the other is a NaN (float.NAN).
Examples

1 >= 1  // => true
1 >= 2  // => false
2 >= 1  // => true

12.3 >= 12.3  // => true
0.0 >= 12.3   // => false
1.2 >= 0.0    // => true
-0.0 >= 0.0   // => true

12 >= 123.0    // => false
12.34 >= 123   // => false
32.0 >= 32     // => true
32 >= 32.0     // => true
1234 >= 123.0  // => true
1.2 >= 1       // => true

float.NAN >= float.NAN  // => false
1 >= float.NAN          // => false
float.NAN >= 1.0        // => false

float.MAX-FINITE >= float.INFINITY  // => false
float.NAN >= float.INFINITY  // => false
float.INFINITY >= float.NAN  // => false
sign -> int
The sign of this number.
Returns -1 if this number is negative (including -0.0).
Returns 0 if this number is 0.
Returns 1 if this number is positive.
Returns 1 if this number is a NaN (float.NAN).
Examples

(-500).sign // => -1
(-1).sign   // => -1
0.sign      // => 0
1.sign      // => 1
100.sign    // => 1

(-2.0).sign  // => -1
(-0.0).sign  // => -1
0.0.sign     // => 0
(3.123).sign // => 1

float.INFINITY.sign    // => 1
(-float.INFINITY).sign // => -1
float.NAN.sign         // => 1
(-float.NAN).sign      // => 1
sqrt -> float
Takes the square root of this number.
Returns NaN (float.NAN) for negative numbers (including -0.0).
Examples

4.sqrt     // => 2
25.0.sqrt  // => 5
2.sqrt     // => 1.4142135623730951455
(-4).sqrt  // => float.NAN
to-float -> float
Converts this number to a floating point number.
For very large integers, the conversion may be to the nearest floating point number.
Examples

2.to-float   // => 2.0
2.1.to-float // => 2.1

9223372036854775807.to-float  // => 9223372036854775808.0
to-int -> int
Converts this number to an integer.
Errors
This number must be inside the 64-bit integer range ([int.MIN, int.MAX]).
This number must be a valid number and not a NaN (float.NAN).
Examples

42.to-int  // => 42

(100.0).to-int   // => 100
(-1.123).to-int  // => -1

float.MAX-FINITE.to-int  // Error.
float.INFINITY.to-int    // Error.
float.NAN.to-int         // Error.
to-string -> string
Converts this number to a well-defined string.