Add docs for LinRange. Change linspace deprecation to suggest LinRange?

[dlfivefifty]

At the moment linspace suggests using range. It is a bit more natural to use LinRange as a replacement.

However, LinRange does not have any documentation.

julia> linspace(1,5,10)
┌ Warning: `linspace(start, stop, length::Integer)` is deprecated, use `range(start, stop=stop, length=length)` instead.
│   caller = top-level scope
└ @ Core :0
1.0:0.4444444444444444:5.0

julia> LinRange(1,5,10)
10-element LinRange{Float64}:
 1.0,1.44444,1.88889,2.33333,2.77778,3.22222,3.66667,4.11111,4.55556,5.0

help?> LinRange
search: LinRange

  No documentation found.

  Base.LinRange is of type UnionAll.

  Summary
  ≡≡≡≡≡≡≡≡≡

  struct UnionAll <: Type{T}

  Fields
  ≡≡≡≡≡≡≡≡

  var  :: TypeVar
  body :: Any

  Supertype Hierarchy
  ≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡

  UnionAll <: Type{T} <: Any

[dlfivefifty]

The first item is a dup of #26919

[mbauman]

This is a little more awkward than ideal to provide a non-breaking stepping stone. In 1.0 we can make stop a positional argument, making the replacement range(1, 5, length=10).

Note that range(1, stop=5, length=10) on 0.7 and linspace on 0.6 do not produce a LinRange object. They return a StepRangeLen. I don't recall whether that choice was made for performance, accuracy, or both.

[dlfivefifty]

What’s the difference between LinRange and StepRangeLen ?

[mbauman]

They're just two different implementations of a range — they compute their values differently. Refreshing my memory: LinRange is a simpler implementation that supports a wider variety of types. StepRangeLen uses higher precision arithmetic to get floating point results that are likely closer to what you intend and are more consistent with the colon syntax, but it doesn't support as many types and is a bit slower in exchange.

Compare the values produced by collect(0:0.1:10) vs collect(range(0, stop=10, length=101)) vs collect(LinRange(0, 10, 101)).

[dlfivefifty]

Ok, so I think my suggestion is correct then: I think a user currently using linspace would almost always want the faster implementation.

[mbauman]

LinRange is now documented, range now supports a stop positional arg, and we're well past deprecations. :)