Float

Built-in type · Written 3.14, -0.5, or 6.02e23

A Float is a number that can have a fractional part. Use one for measurements, prices, averages, and anything else that is not always a whole number; use Int for counting.

A number with a decimal point or an exponent is a Float. Dividing with / always gives one, even when both numbers are whole. And wherever a Float is expected, an Int is accepted and becomes one.

const price = 19.99
const average = 7 / 2                      # → 3.5
const distance: Float = 42                 # → 42.0

print(price.round())                       # → 20
print(average.format(decimal_places: 2))   # → 3.50

A Float holds about 15 significant digits, and like floating-point numbers in every language, it stores most fractions approximately: 0.1 + 0.2 is 0.30000000000000004. Round a result when you show it, rather than comparing two calculated values for exact equality.

A whole Float always keeps its .0 when printed (2.0, not 2), so you can tell it from an Int. Very large and very small values print in scientific notation, such as 1e+16 and 1e-7.

At a glance

Rounding
round()	To the nearest whole number
floor()	Down to a whole number
ceil()	Up to a whole number
truncate()	Toward zero, dropping the fraction
round_to(places)	To a number of decimal places, staying a Float

Showing as text
format(...)	Fixed decimal places, with optional digit grouping
to_string()	The same text print shows

Comparing and limiting
abs()	The distance from zero
clamp(minimum, maximum)	Kept within a range
between?(minimum, maximum)	Whether it is within a range
zero?(), positive?(), negative?()	Its sign

Math
square_root()	The square root
to_radians(), to_degrees()	Converting an angle

Special values
Float.infinity, Float.nan	Infinity and “not a number”
finite?(), infinite?(), nan?()	Checking for them
to_int()	Converting to an Int

Operators

Operator	Meaning	Example
+ - *	Add, subtract, multiply	1.5 * 2 → 3.0
/	Divide	7 / 2 → 3.5
//	Divide, then round down	7.5 // 2 → 3.0
%	The remainder after //	7.5 % 2 → 1.5
**	Raise to a power	2 ** 0.5 → 1.4142135623730951
== != < <= > >=	Compare	2.5 < 3 → true

When either side is a Float, the result is a Float. Dividing by zero raises an error rather than giving infinity.

Rounding

round(): Int

The nearest whole number. A value exactly halfway rounds away from zero.

2.4.round()    # → 2
2.5.round()    # → 3
-2.5.round()   # → -3

Raises when the value is infinity or not a number, or too large for an Int.

floor(): Int

The nearest whole number at or below the value.

2.7.floor()    # → 2
-2.5.floor()   # → -3

Raises when the value is infinity or not a number, or too large for an Int.

ceil(): Int

The nearest whole number at or above the value.

2.1.ceil()    # → 3
-2.5.ceil()   # → -2

Raises when the value is infinity or not a number, or too large for an Int.

truncate(): Int

The whole-number part, with the fraction dropped. This rounds toward zero, so it rounds positive numbers down and negative numbers up.

2.7.truncate()    # → 2
-2.7.truncate()   # → -2

Raises when the value is infinity or not a number, or too large for an Int.

round_to(places: Int): Float

The value rounded to places decimal places. The result is still a number, not text; to show a fixed number of places, use format. A negative places rounds to tens, hundreds, and so on.

3.14159.round_to(2)   # → 3.14
2.675.round_to(2)     # → 2.68
1234.5.round_to(-2)   # → 1200.0

Showing as text

format(decimal_places: Int? = nothing, group_digits: Bool = false): String

The value as text. With decimal_places, it has exactly that many digits after the decimal point, never scientific notation. With group_digits: true, a comma separates every three digits of the whole-number part.

12.5.format(decimal_places: 2)                              # → "12.50"
12.0.format(decimal_places: 0)                              # → "12"
1234567.891.format(decimal_places: 2, group_digits: true)   # → "1,234,567.89"

Raises when decimal_places is not from 0 to 100.

to_string(): String

The value as text, exactly as print shows it.

2.0.to_string()    # → "2.0"
1e16.to_string()   # → "1e+16"

Comparing and limiting

abs(): Float

The distance from zero: the value without its sign.

-2.5.abs()   # → 2.5

clamp(minimum: Float, maximum: Float): Float

The value, kept within minimum to maximum. A value below the range becomes minimum, and a value above it becomes maximum.

12.7.clamp(0, 10)   # → 10.0
-3.0.clamp(0, 10)   # → 0.0
4.2.clamp(0, 10)    # → 4.2

Raises when minimum is greater than maximum.

between?(minimum: Float, maximum: Float): Bool

Whether the value is from minimum to maximum, including both.

3.2.between?(0, 5)   # → true
7.5.between?(0, 5)   # → false

Raises when minimum is greater than maximum.

zero?(): Bool

Whether the value is zero.

0.0.zero?()   # → true

positive?(): Bool

Whether the value is greater than zero.

0.5.positive?()   # → true
0.0.positive?()   # → false

negative?(): Bool

Whether the value is less than zero.

-0.5.negative?()   # → true

Math

square_root(): Float

The square root.

16.0.square_root()   # → 4.0
2.0.square_root()    # → 1.4142135623730951

to_radians(): Float

An angle in degrees, converted to radians. Math’s trigonometry functions take radians.

180.0.to_radians()   # → 3.141592653589793

to_degrees(): Float

An angle in radians, converted to degrees.

Math.pi.to_degrees()   # → 180.0

Special values

Float.infinity: Float

A value larger than every other Float. Write -Float.infinity for negative infinity.

Float.infinity > 1e300   # → true

Float.nan: Float

“Not a number”, the result of a calculation with no meaningful answer. It is not equal to anything, not even itself, so check for it with nan?() rather than ==.

Float.nan == Float.nan   # → false
Float.nan.nan?()         # → true

finite?(): Bool

Whether the value is an ordinary number: neither infinity nor not a number.

1.5.finite?()              # → true
Float.infinity.finite?()   # → false

infinite?(): Bool

Whether the value is infinity or negative infinity.

Float.infinity.infinite?()   # → true

nan?(): Bool

Whether the value is not a number.

Float.nan.nan?()   # → true
1.5.nan?()         # → false

to_int(): Int

The value as an Int, with the fraction dropped. It gives the same result as truncate(); use whichever name says what you mean.

2.7.to_int()   # → 2

Raises when the value is infinity or not a number, or too large for an Int.

Making a Float

A Float can also come from text or from an Int:

"3.75".to_float()        # → 3.75
"abc".to_float_maybe()   # → nothing
3.to_float()             # → 3.0

See String and Int for these methods.