# View Source Range (Elixir v1.14.0)

Ranges represent a sequence of zero, one or many, ascending or descending integers with a common difference called step.

The most common form of creating and matching on ranges is
via the `first..last`

and `first..last//step`

notations, auto-imported from `Kernel`

:

```
iex> 1 in 1..10
true
iex> 5 in 1..10
true
iex> 10 in 1..10
true
```

Ranges are always inclusive in Elixir. When a step is defined, integers will only belong to the range if they match the step:

```
iex> 5 in 1..10//2
true
iex> 4 in 1..10//2
false
```

When defining a range without a step, the step will be
defined based on the first and last position of the
range, If `first >= last`

, it will be an increasing range
with a step of 1. Otherwise, it is a decreasing range.
Note however implicit decreasing ranges are deprecated.
Therefore, if you need a decreasing range from `3`

to `1`

,
prefer to write `3..1//-1`

instead.

`../0`

can also be used as a shortcut to create the range `0..-1//1`

,
also known as the full-slice range:

```
iex> ..
0..-1//1
```

##
use-cases

Use cases

Ranges typically have two uses in Elixir: as a collection or to represent a slice of another data structure.

###
ranges-as-collections

Ranges as collections

Ranges in Elixir are enumerables and therefore can be used
with the `Enum`

module:

```
iex> Enum.to_list(1..3)
[1, 2, 3]
iex> Enum.to_list(3..1//-1)
[3, 2, 1]
iex> Enum.to_list(1..5//2)
[1, 3, 5]
```

Ranges may also have a single element:

```
iex> Enum.to_list(1..1)
[1]
iex> Enum.to_list(1..1//2)
[1]
```

Or even no elements at all:

```
iex> Enum.to_list(10..0//1)
[]
iex> Enum.to_list(0..10//-1)
[]
```

The full-slice range, returned by `../0`

, is an empty collection:

```
iex> Enum.to_list(..)
[]
```

###
ranges-as-slices

Ranges as slices

Ranges are also frequently used to slice collections. You can slice strings or any enumerable:

```
iex> String.slice("elixir", 1..4)
"lixi"
iex> Enum.slice([0, 1, 2, 3, 4, 5], 1..4)
[1, 2, 3, 4]
```

In those cases, the first and last values of the range are mapped to positions in the collections.

If a negative number is given, it maps to a position from the back:

```
iex> String.slice("elixir", 1..-2//1)
"lixi"
iex> Enum.slice([0, 1, 2, 3, 4, 5], 1..-2//1)
[1, 2, 3, 4]
```

The range `0..-1//1`

, returned by `../0`

, returns the
collection as is, which is why it is called the full-slice
range:

```
iex> String.slice("elixir", ..)
"elixir"
iex> Enum.slice([0, 1, 2, 3, 4, 5], ..)
[0, 1, 2, 3, 4, 5]
```

##
definition

Definition

An increasing range `first..last//step`

is a range from `first`

to `last`

increasing by `step`

where `step`

must be a positive
integer and all values `v`

must be `first <= v and v <= last`

.
Therefore, a range `10..0//1`

is an empty range because there
is no value `v`

that is `10 <= v and v <= 0`

.

Similarly, a decreasing range `first..last//step`

is a range
from `first`

to `last`

decreasing by `step`

where `step`

must
be a negative integer and values `v`

must be `first >= v and v >= last`

.
Therefore, a range `0..10//-1`

is an empty range because there
is no value `v`

that is `0 >= v and v >= 10`

.

##
representation

Representation

Internally, ranges are represented as structs:

```
iex> range = 1..9//2
1..9//2
iex> first..last//step = range
iex> first
1
iex> last
9
iex> step
2
iex> range.step
2
```

You can access the range fields (`first`

, `last`

, and `step`

)
directly but you should not modify nor create ranges by hand.
Instead use the proper operators or `new/2`

and `new/3`

.

Ranges implement the `Enumerable`

protocol with memory
efficient versions of all `Enumerable`

callbacks:

```
iex> range = 1..10
1..10
iex> Enum.reduce(range, 0, fn i, acc -> i * i + acc end)
385
iex> Enum.count(range)
10
iex> Enum.member?(range, 11)
false
iex> Enum.member?(range, 8)
true
```

Such function calls are efficient memory-wise no matter the
size of the range. The implementation of the `Enumerable`

protocol uses logic based solely on the endpoints and does
not materialize the whole list of integers.

# Link to this section Summary

## Functions

Checks if two ranges are disjoint.

Creates a new range.

Creates a new range with `step`

.

Shifts a range by the given number of steps.

Returns the size of `range`

.

# Link to this section Types

@type limit() :: integer()

@type step() :: pos_integer() | neg_integer()

@type t(first, last) :: %Range{first: first, last: last, step: step()}

# Link to this section Functions

Checks if two ranges are disjoint.

##
examples

Examples

```
iex> Range.disjoint?(1..5, 6..9)
true
iex> Range.disjoint?(5..1, 6..9)
true
iex> Range.disjoint?(1..5, 5..9)
false
iex> Range.disjoint?(1..5, 2..7)
false
```

Steps are also considered when computing the ranges to be disjoint:

```
iex> Range.disjoint?(1..10//2, 2..10//2)
true
# First element in common in all below is 29
iex> Range.disjoint?(2..100//3, 9..100//5)
false
iex> Range.disjoint?(101..2//-3, 99..9//-5)
false
iex> Range.disjoint?(1..100//14, 8..100//21)
false
iex> Range.disjoint?(57..-1//-14, 8..100//21)
false
iex> Range.disjoint?(1..100//14, 51..8//-21)
false
# If 29 is out of range
iex> Range.disjoint?(1..28//14, 8..28//21)
true
iex> Range.disjoint?(2..28//3, 9..28//5)
true
```

Creates a new range.

If `first`

is less than `last`

, the range will be increasing from
`first`

to `last`

. If `first`

is equal to `last`

, the range will contain
one element, which is the number itself.

If `first`

is greater than `last`

, the range will be decreasing from `first`

to `last`

, albeit this behaviour is deprecated. Therefore, it is advised to
explicitly list the step with `new/3`

.

##
examples

Examples

```
iex> Range.new(-100, 100)
-100..100
```

Creates a new range with `step`

.

##
examples

Examples

```
iex> Range.new(-100, 100, 2)
-100..100//2
```

Shifts a range by the given number of steps.

##
examples

Examples

```
iex> Range.shift(0..10, 1)
1..11
iex> Range.shift(0..10, 2)
2..12
iex> Range.shift(0..10//2, 2)
4..14//2
```

Returns the size of `range`

.

##
examples

Examples

```
iex> Range.size(1..10)
10
iex> Range.size(1..10//2)
5
iex> Range.size(1..10//3)
4
iex> Range.size(1..10//-1)
0
iex> Range.size(10..1)
10
iex> Range.size(10..1//-1)
10
iex> Range.size(10..1//-2)
5
iex> Range.size(10..1//-3)
4
iex> Range.size(10..1//1)
0
```