More docs around ranges

Author: josevalim

lib/elixir/lib/enum.ex

@@ -2601,11 +2601,14 @@ defmodule Enum do
       iex> Enum.slice(1..30, -5..-1)
       [26, 27, 28, 29, 30]
 
-      # last five elements (mixed positive and negative indexes)
-      iex> Enum.slice(1..30, 25..-1)
+  For ranges where `start > stop`, you need to explicit
+  mark them as increasing:
+
+      iex> Enum.slice(1..30, 25..-1//1)
       [26, 27, 28, 29, 30]
 
-      # out of bounds
+  If values are out of bounds, it returns an empty list:
+
       iex> Enum.slice(1..10, 11..20)
       []
 
@@ -2617,6 +2620,7 @@ defmodule Enum do
   @doc since: "1.6.0"
   @spec slice(t, Range.t()) :: list
   def slice(enumerable, first..last//step = index_range) do
+    # TODO: Deprecate negative steps on Elixir v1.16
     # TODO: There are two features we can add to slicing ranges:
     # 1. We can allow the step to be any positive number
     # 2. We can allow slice and reverse at the same time. However, we can't

lib/elixir/lib/kernel.ex

@@ -3641,6 +3641,8 @@ defmodule Kernel do
   to last, albeit this behaviour is deprecated. Instead prefer to
   explicitly list the step with `first..last//-1`.
 
+  See the `Range` module for more information.
+
   ## Examples
 
       iex> 0 in 1..3
@@ -3666,7 +3668,7 @@ defmodule Kernel do
   end
 
   defp range(_context, first, last) when is_integer(first) and is_integer(last) do
-    # TODO: Deprecate inferring a range with step of -1 on Elixir v1.16
+    # TODO: Deprecate inferring a range with step of -1 on Elixir v1.17
     step = if first <= last, do: 1, else: -1
     {:%{}, [], [__struct__: Elixir.Range, first: first, last: last, step: step]}
   end
@@ -3676,18 +3678,20 @@ defmodule Kernel do
   end
 
   defp range(:guard, first, last) do
-    # TODO: Deprecate me inside guard when sides are not integers on Elixir v1.16
+    # TODO: Deprecate me inside guard when sides are not integers on Elixir v1.17
     {:%{}, [], [__struct__: Elixir.Range, first: first, last: last, step: nil]}
   end
 
   defp range(:match, first, last) do
-    # TODO: Deprecate me inside match in all occasions (including literals) on Elixir v1.16
+    # TODO: Deprecate me inside match in all occasions (including literals) on Elixir v1.17
     {:%{}, [], [__struct__: Elixir.Range, first: first, last: last]}
   end
 
   @doc """
   Creates a range from `first` to `last` with `step`.
 
+  See the `Range` module for more information.
+
   ## Examples
 
       iex> 0 in 1..3//1

lib/elixir/lib/range.ex

@@ -1,11 +1,12 @@
 defmodule Range do
   @moduledoc """
-  Ranges represent a sequence of one or many, ascending
+  Ranges represent a sequence of zero, one or many, ascending
   or descending, consecutive integers.
 
-  Ranges are always inclusive and they may have custom
-  steps. The most common form of creating and matching
-  on ranges is via the `../2` and `..///3` macros,
+  Ranges are always inclusive and they may have custom steps.
+  The most common form of creating and matching on ranges is
+  via the `start..stop` and `start..stop//step` notations,
+  defined respectively as the `../2` and `..///3` macros
   auto-imported from `Kernel`:
 
       iex> Enum.to_list(1..3)
@@ -15,6 +16,44 @@ defmodule Range do
       iex> Enum.to_list(3..1//-1)
       [3, 2, 1]
 
+  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)
+      []
+
+  When defining a range without steps, the step will be
+  defined based on the start and stop position of the
+  range, If `start >= stop`, it will be an increasing range
+  with step of 1. Otherwise, it is a decreasing range.
+  Note however implicitly decreasing ranges are deprecated.
+  Therefore, if you need a decreasing range from `3` to `1`,
+  prefer to write `3..1//-1` instead.
+
+  ## Definition
+
+  An increasing range `first..last//step` is a range from
+  `first` to `last` increasing by `step` where 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 all 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 `10 >= v and v >= 0`.
+
+  ## Representation
+
   Internally, ranges are represented as structs:
 
       iex> range = 1..9//2
@@ -62,6 +101,14 @@ defmodule Range do
   @doc """
   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 more than last, the range will be decreasing from first
+  to last, albeit this behaviour is deprecated. Instead prefer to
+  explicitly list the step `new/3`.
+
   ## Examples
 
       iex> Range.new(-100, 100)
@@ -70,7 +117,7 @@ defmodule Range do
   """
   @spec new(integer, integer) :: t
   def new(first, last) when is_integer(first) and is_integer(last) do
-    # TODO: Deprecate inferring a range with step of -1 on Elixir v1.16
+    # TODO: Deprecate inferring a range with step of -1 on Elixir v1.17
     step = if first <= last, do: 1, else: -1
     %Range{first: first, last: last, step: step}
   end

lib/elixir/lib/string.ex

@@ -2052,19 +2052,24 @@ defmodule String do
       iex> String.slice("elixir", 1..10)
       "lixir"
 
-      iex> String.slice("elixir", 10..3)
-      ""
-
       iex> String.slice("elixir", -4..-1)
       "ixir"
 
-      iex> String.slice("elixir", 2..-1)
+      iex> String.slice("elixir", -4..6)
       "ixir"
 
-      iex> String.slice("elixir", -4..6)
+  For ranges where `start > stop`, you need to explicit
+  mark them as increasing:
+
+      iex> String.slice("elixir", 2..-1//1)
       "ixir"
 
-      iex> String.slice("elixir", -1..-4)
+      iex> String.slice("elixir", 1..-2//1)
+      "lixi"
+
+  If values are out of bounds, it returns an empty string:
+
+      iex> String.slice("elixir", 10..3)
       ""
 
       iex> String.slice("elixir", -10..-7)
@@ -2079,6 +2084,7 @@ defmodule String do
   """
   @spec slice(t, Range.t()) :: t
   def slice(string, first..last//step = range) when is_binary(string) do
+    # TODO: Deprecate negative steps on Elixir v1.16
     # TODO: There are two features we can add to slicing ranges:
     # 1. We can allow the step to be any positive number
     # 2. We can allow slice and reverse at the same time. However, we can't