Range
| Description: | Describes a range of values from a starting value to an ending value, with an optional stride. |
| Annotation: | range |
| Literal Syntax: | <start_value>..<end_value> or <start_value>..<second_value>..<end_value>. E.g., 1..10. |
| Casts: | seq (see Lists of numbers with seq) |
| See also: | Types of Data - Ranges |
Additional Language Notes
Ranges are inclusive by default.
Examples:
- Values from 1 to 5 inclusive:
1..5 # => ╭───┬───╮ # => │ 0 │ 1 │ # => │ 1 │ 2 │ # => │ 2 │ 3 │ # => │ 3 │ 4 │ # => │ 4 │ 5 │ # => ╰───┴───╯..=spells the inclusive form out, as Rust does.1..=5is the same range as1..5. The=goes only on the last.., so1..3..=9and..=3are ranges, but1..=3..9is not. Nushell reads that word as the name of an external command.(1..=5) == (1..5) # => true 1..3..=9 | each {} | to nuon # => [1, 3, 5, 7, 9]In many programming languages, the step (or interval) is specified. Nushell's range is inspired by more functional languages, where the second value is literally the second value that should be generated. The step is then automatically calculated as the distance between the first and second values.
Example - Values from 1 to 10, striding with 2 (only odds):
1..3..10 # => ╭───┬───╮ # => │ 0 │ 1 │ # => │ 1 │ 3 │ # => │ 2 │ 5 │ # => │ 3 │ 7 │ # => │ 4 │ 9 │ # => ╰───┴───╯The second value sets the direction too, so a second value below the start counts down. The step form also works with an exclusive end:
10..8..0 | each {} | to nuon # => [10, 8, 6, 4, 2, 0] 1..3..<9 | each {} | to nuon # => [1, 3, 5, 7]Exclusive range - You can also use
..<to have values up to, but not including, the range end.Values from 1 to 5 (exclusive):
1..<5 # => ╭───┬───╮ # => │ 0 │ 1 │ # => │ 1 │ 2 │ # => │ 2 │ 3 │ # => │ 3 │ 4 │ # => ╰───┴───╯Range values can be floats:
(1.0)..(1.2)..(2.2) # => ╭───┬──────╮ # => │ 0 │ 1.00 │ # => │ 1 │ 1.20 │ # => │ 2 │ 1.40 │ # => │ 3 │ 1.60 │ # => │ 4 │ 1.80 │ # => │ 5 │ 2.00 │ # => │ 6 │ 2.20 │ # => ╰───┴──────╯Note: Parentheses (subexpressions) are not required in this example; they are simply used for readability.
If any of the values is a float, the whole range is a float range.
1..2.5starts at1.0:1..2.5 | each {} | to nuon # => [1.0, 2.0]The start, second and end values can be variables or subexpressions, not just literals:
let start = 2 let end = 5 $start..$end | each {} | to nuon # => [2, 3, 4, 5] let list = [a b c] 0..<($list | length) | each {} | to nuon # => [0, 1, 2]A negative start works where an expression begins (
-2..0), but not as a command argument, where a word that starts with-is read as a flag:[a b c d e] | slice -2.. # => Error: nu::parser::unknown_flag # => # => × The `slice` command doesn't have flag `-2`. # => ╭─[repl_entry #1:1:22] # => 1 │ [a b c d e] | slice -2.. # => · ┬ # => · ╰── unknown flag # => ╰──── # => help: Use `--help` to see available flagsPut the number in parentheses, or pass it in a variable:
[a b c d e] | slice (-2).. | to nuon # => [d, e]The start, second and end values must be numbers. A range of strings or dates is a parse error:
("a")..("z") # => Error: nu::parser::operator_unsupported_type # => # => × The '..' operator does not work on values of type 'string'. # => ╭─[repl_entry #1:1:1] # => 1 │ ("a")..("z") # => · ──┬───┬ # => · │ ╰── does not support 'string' # => · ╰── string # => ╰────Without the parentheses,
'a'..'z'isn't a range at all. A quoted word runs to its last quote, so it is the single stringa'..'z(see Quotes inside a quoted word). For a sequence of letters, useseq char, and for dates useseq date.seq charincludes both ends, and counts down when the start comes after the end. Each bound must be a single ASCII character, and anything else is an error. The characters follow ASCII order, so a run from uppercase to lowercase picks up the punctuation in between:seq char e a | str join # => edcba seq char Y b | str join # => YZ[\]^_`ab seq char é z # => Error: nu::shell::error # => # => × seq char only accepts individual ASCII characters as parameters # => ╭─[repl_entry #1:1:10] # => 1 │ seq char é z # => · ┬ # => · ╰── input should be a single ASCII character # => ╰────When no second value is given, the step is
1(or-1when counting down). The exception is a float range whose start and end are less than1apart. Its step is based on the order of magnitude of the difference:0.1..0.3 # => ╭───┬──────╮ # => │ 0 │ 0.10 │ # => │ 1 │ 0.20 │ # => │ 2 │ 0.30 │ # => ╰───┴──────╯Ranges can also work backward:
5..1 # => ╭───┬───╮ # => │ 0 │ 5 │ # => │ 1 │ 4 │ # => │ 2 │ 3 │ # => │ 3 │ 2 │ # => │ 4 │ 1 │ # => ╰───┴───╯The start value is optional. The default start value is
0.(..5) == (0..5) # => trueThe end value is also optional. The default end value is infinite, so
1..is an infinite range starting at 1:1.. | describe # => rangeNote: If you enter
1..by itself at the prompt, Nushell starts listing its values. Interrupt the generation using Ctrl+C.Ranges are lazy, meaning they do not generate their values until needed. You can use a range with no specified end point and combine it with a command that takes only the first n elements. For example, you could generate the numbers from 1 to 5 using:
1.. | take 5 # => ╭───┬───╮ # => │ 0 │ 1 │ # => │ 1 │ 2 │ # => │ 2 │ 3 │ # => │ 3 │ 4 │ # => │ 4 │ 5 │ # => ╰───┴───╯Conversion - A range may be converted to a
listusing:1..5 | each {||} | describe # => list<int> (stream)A range stays a
rangewhen it is assigned to a variable or passed throughcollect. Most filter commands, such aseach,takeandappend, produce a list from it.
Range errors
Some ranges parse but can't produce any values. Nushell reports them when the range is evaluated, not when it is parsed, so a bad range inside an if branch that never runs causes no error. Each one fails with the same error, which underlines either the value at fault or the whole range:
1..1..5
# => Error: nu::shell::range_to_countable
# =>
# => × Can't convert range to countable values
# => ╭─[repl_entry #1:1:4]
# => 1 │ 1..1..5
# => · ┬
# => · ╰── can't convert to countable values
# => ╰────These ranges fail:
- The second value equals the start, as in
1..1..5. The step would be zero. - The second value is on the other side of the start from the end, as in
1..2..-5or5..1..10. Counting would never reach the end. - A float range has equal start and end and no second value, as in
1.0..1.0or1..1.0. An int range with equal bounds is fine:1..1yields[1]. - A float range starts at
inf,-inforNaN(inf..5), has a second value that isn't finite (1..inf..5), or ends atNaN(1..2..NaN). An end ofinfis allowed and makes an endless range, like1...