Float
| Description: | Numbers with some fractional component |
| Annotation: | float |
| Literal syntax: | A decimal numeric value including a decimal place. E.g., 1.5, 2.0, -15.333 |
| Casts: | into float |
| See also: | Types of Data - Floats |
Additional language notes
Floats are internally represented as IEEE-754 floats with 64 bit precision.
Scientific notation is supported in literals, e.g.
1e3or1.5e-3. Theecan also be uppercase:1E-2is0.01. An exponent too large for a float doesn't cause an error. The literal becomesinf, so1e400isinf.The digits before or after the decimal point can be left out:
.5is0.5,5.is5.0and-.5is-0.5. Underscores separate digits anywhere in a float literal, as in1_000.000_1.A float is always displayed with a decimal point, even when it has no fractional part. The
/operator always returns a float, even when both operands are integers (use//for integer division).Floats and integers can be compared with each other.
10 / 2 # => 5.0 1e3 # => 1000.0 0.1 + 0.2 # => 0.30000000000000004 2.0 == 2 # => trueAn int combined with a float by
+,-,*,/,//,modor**gives a float, even when the result is a whole number:[(1 + 1.5) (2 * 2.0) (7 // 2.0) (7 mod 2.0) (2 ** 2.0)] | to nuon # => [2.5, 4.0, 3.0, 1.0, 4.0]into inttruncates the fractional part. To round instead, usemath round,math floorormath ceil, described under Rounding.The other
mathcommands, such asmath sqrtandmath stddev, are described in Working with Numbers.
Rounding
math floor rounds down, math ceil rounds up, and math round rounds to the nearest whole number. A value exactly halfway rounds away from zero. All three return an int:
[-1.5 1.5 2.5] | each {|x| {x: $x, floor: ($x | math floor), ceil: ($x | math ceil), round: ($x | math round)} }
# => ╭───┬───────┬───────┬──────┬───────╮
# => │ # │ x │ floor │ ceil │ round │
# => ├───┼───────┼───────┼──────┼───────┤
# => │ 0 │ -1.50 │ -2 │ -1 │ -2 │
# => │ 1 │ 1.50 │ 1 │ 2 │ 2 │
# => │ 2 │ 2.50 │ 2 │ 3 │ 3 │
# => ╰───┴───────┴───────┴──────┴───────╯math round --precision (-p) keeps that many decimal places and returns a float. A negative precision rounds to tens, hundreds and so on:
[1.555 2.333] | math round --precision 2 | to nuon
# => [1.56, 2.33]
1234.5 | math round --precision -2
# => 1200.0The rounding works on the stored binary value, so a decimal that a float can't hold exactly may round the other way: 1.005 | math round -p 2 is 1.0.
The three commands accept other input too:
- An int comes back unchanged.
- A list or range of numbers gives a list, as in
1.5..3.5 | math ceil, which is[2, 3, 4]. - A file size or duration also comes back unchanged, since it is already a whole number of bytes or nanoseconds.
math round --precisionrejects them. - A record has every field rounded, and each field must be a number, file size or duration. To round only some fields, name them as cell paths after the command:
{a: 1.26, b: 2.5} | math round -p 1 ais{a: 1.3, b: 2.5}.
A table is not accepted. Round a column with update instead:
[[item price]; [a 1.25] [b 2.5]] | update price { math round } | to nuon
# => [[item, price]; [a, 1], [b, 3]]Infinity and NaN
The words inf and NaN are float literals for infinity and "not a number". Write -inf for negative infinity. nan is accepted as another spelling of NaN, and Nushell prints it as NaN. No other spelling is a float. Nan, Inf and infinity are bare-word strings:
[inf -inf nan NaN Nan Inf infinity] | to nuon
# => [inf, -inf, NaN, NaN, "Nan", "Inf", "infinity"]into float is more lenient with text. 'infinity' | into float returns inf.
These values also come out of float arithmetic. A result too large for a float becomes inf, so 1e308 * 10 is inf, and inf - inf is NaN. Division by zero is an error, even for floats, so 1.0 / 0 and 0.0 / 0.0 fail with nu::shell::division_by_zero instead of returning inf or NaN.
Comparisons follow IEEE-754. inf == inf is true, and NaN is not equal to anything, itself included:
NaN == NaN
# => false
NaN in [NaN]
# => falseOther places where they behave differently from ordinary floats:
sortputsNaNafter every other number:[3 NaN 1 inf -inf] | sortis[-inf, 1, 3, inf, NaN].to nuonwritesinf,-infandNaN, whichfrom nuonreads back as floats. JSON has no such values, soto jsonwrites each of them asnull.- Converting to an int doesn't fail.
inf | into intis the largest int,9223372036854775807, andNaN | into intis0.math floorandmath ceildo the same, whilemath roundrejects them with "cannot round non-finite number". - A range can't start at
inf,-inforNaN. See Range.
Converting to float
into float accepts these input types:
| Input | Result |
|---|---|
int | The same number as a float. Above 2^53 not every int has an exact float, so 9007199254740993 becomes 9007199254740992.0. |
bool | 1.0 for true, 0.0 for false |
string | The number the text holds (see below) |
float | The value unchanged |
Durations and file sizes aren't accepted. Divide by a unit to get a float that counts that unit:
90sec / 1min
# => 1.5
1500B / 1kB
# => 1.5A string can hold a decimal number with an optional sign, fraction and exponent, such as "-1.5e3". Leading and trailing whitespace is ignored. inf, infinity and NaN are accepted in any case, with an optional sign. Unlike into int, into float doesn't read 0x, 0o or 0b prefixes. Neither command accepts _ separators. Text that isn't a number is an error:
"abc" | into float
# => Error: nu::shell::cant_convert
# =>
# => × Can't convert to float.
# => ╭─[repl_entry #1:1:1]
# => 1 │ "abc" | into float
# => · ──┬──
# => · ╰── can't convert string to float
# => ╰────
# => help: invalid float literalA comma is read as a decimal point, so "1,5" | into float is 1.5. A comma that groups thousands is read the same way, so "1,000" | into float is 1.0, while "1,000" | into int is 1000 with an English locale. A string with both a comma and a dot is an error:
"1,000.5" | into float
# => Error: nu::shell::cant_convert::ambiguity
# =>
# => × Ambiguity in conversion
# => ╭─[repl_entry #1:1:1]
# => 1 │ "1,000.5" | into float
# => · ────┬────
# => · ╰── input contains both `,` and `.`
# => ╰────Remove the separators first when the text groups thousands: "1,000.5" | str replace --all "," "" | into float is 1000.5.
A list is converted item by item, so [1 "2" true] | into float is [1.0, 2.0, 1.0]. For a table or record, name the columns to convert as cell paths after the command. Without them, a record or a table row is rejected:
[[a b]; ["1.5" x]] | into float a | to nuon
# => [[a, b]; [1.5, x]]