docstrings

base/slicearray.jl

@@ -15,7 +15,7 @@ An `AbstractArray` of slices into a parent array over specified dimension(s),
 returning views that select all the data from the other dimension(s).
 
 These should typically be constructed by [`eachslice`](@ref), [`eachcol`](@ref) or
-[`eachrow`](@ref).
+[`eachrow`](@ref). [`ColumnSlices`](@ref) and [`RowSlices`](@ref) are special cases.
 
 [`parent(s::Slices)`](@ref) will return the parent array.
 """
@@ -85,7 +85,9 @@ the ordering of the dimensions will match those in `dims`. If `drop = false`, th
 `Slices` will have the same dimensionality as the underlying array, with inner
 dimensions having size 1.
 
-See also [`eachrow`](@ref), [`eachcol`](@ref), [`mapslices`](@ref) and [`selectdim`](@ref).
+For matrices, the case `dims = 1` is [`eachrow`](@ref), and `dims = 2` is [`eachcol`](@ref). 
+
+See also [`mapslices`](@ref), [`selectdim`](@ref).
 
 !!! compat "Julia 1.1"
      This function requires at least Julia 1.1.
@@ -103,7 +105,7 @@ julia> m = [1 2 3; 4 5 6; 7 8 9]
  7  8  9
 
 julia> s = eachslice(m, dims=1)
-3-element RowSlices{Matrix{Int64}, Tuple{Base.OneTo{Int64}}, SubArray{Int64, 1, Matrix{Int64}, Tuple{Int64, Base.Slice{Base.OneTo{Int64}}}, true}}:
+3-element eachrow(::Matrix{Int64}) of 3-element slices with eltype Int64:
  [1, 2, 3]
  [4, 5, 6]
  [7, 8, 9]
@@ -115,10 +117,15 @@ julia> s[1]
  3
 
 julia> eachslice(m, dims=1, drop=false)
-3×1 Slices{Matrix{Int64}, Tuple{Int64, Colon}, Tuple{Base.OneTo{Int64}, Base.OneTo{Int64}}, SubArray{Int64, 1, Matrix{Int64}, Tuple{Int64, Base.Slice{Base.OneTo{Int64}}}, true}, 2}:
+3×1 eachslice(::Matrix{Int64}, dims = 1, drop = false) of 3-element slices with eltype Int64:
  [1, 2, 3]
  [4, 5, 6]
  [7, 8, 9]
+
+julia> eachslice(Any[pi, 2pi], dims=1)  # eachrow would produce vector slices
+2-element eachslice(::Vector{Any}, dims = 1) of 0-dimensional slices with eltype Any:
+ fill(π)
+ fill(6.283185307179586)
 ```
 """
 @inline function eachslice(A; dims, drop=true)
@@ -142,20 +149,29 @@ See also [`eachcol`](@ref), [`eachslice`](@ref) and [`mapslices`](@ref).
 # Example
 
 ```jldoctest
-julia> a = [1 2; 3 4]
-2×2 Matrix{Int64}:
- 1  2
- 3  4
+julia> a = [1 2 3; 40 50 60]
+2×3 Matrix{Int64}:
+  1   2   3
+ 40  50  60
 
 julia> s = eachrow(a)
-2-element RowSlices{Matrix{Int64}, Tuple{Base.OneTo{Int64}}, SubArray{Int64, 1, Matrix{Int64}, Tuple{Int64, Base.Slice{Base.OneTo{Int64}}}, true}}:
- [1, 2]
- [3, 4]
+2-element eachrow(::Matrix{Int64}) of 3-element slices with eltype Int64:
+ [1, 2, 3]
+ [40, 50, 60]
 
 julia> s[1]
-2-element view(::Matrix{Int64}, 1, :) with eltype Int64:
+3-element view(::Matrix{Int64}, 1, :) with eltype Int64:
  1
  2
+ 3
+
+julia> s isa RowSlices, s[1] isa SubArray
+(true, true)
+
+julia> eachrow(Any[pi, 2pi])  # reshapes vector to matrix before slicing
+2-element eachrow(::Matrix{Any}) of 1-element slices with eltype Any:
+ [π]
+ [6.283185307179586]
 ```
 """
 eachrow(A::AbstractMatrix) = _eachslice(A, (1,), true)
@@ -178,20 +194,31 @@ See also [`eachrow`](@ref), [`eachslice`](@ref) and [`mapslices`](@ref).
 # Example
 
 ```jldoctest
-julia> a = [1 2; 3 4]
-2×2 Matrix{Int64}:
- 1  2
- 3  4
+julia> a = [1 2 3; 40 50 60]
+2×3 Matrix{Int64}:
+  1   2   3
+ 40  50  60
 
 julia> s = eachcol(a)
-2-element ColumnSlices{Matrix{Int64}, Tuple{Base.OneTo{Int64}}, SubArray{Int64, 1, Matrix{Int64}, Tuple{Base.Slice{Base.OneTo{Int64}}, Int64}, true}}:
- [1, 3]
- [2, 4]
+3-element eachcol(::Matrix{Int64}) of 2-element slices with eltype Int64:
+ [1, 40]
+ [2, 50]
+ [3, 60]
 
-julia> s[1]
-2-element view(::Matrix{Int64}, :, 1) with eltype Int64:
- 1
- 3
+julia> s[3]
+2-element view(::Matrix{Int64}, :, 3) with eltype Int64:
+  3
+ 60
+
+julia> s isa ColumnSlices
+true
+
+julia> parent(s) === a
+true
+
+julia> eachcol('a':'c')  # accepts AbstractVector too, reshapes to 1-colum matrix:
+1-element eachcol(reshape(::StepRange{Char, Int64}, 3, 1)) of 3-element slices with eltype Char:
+ ['a', 'b', 'c']
 ```
 """
 eachcol(A::AbstractMatrix) = _eachslice(A, (2,), true)